docs: add OpenGrimoire clarification queue documentation and enhance existing files

Introduced `OPENGRIMOIRE_CLARIFICATION_BRIDGE.md` to document the integration of OpenGrimoire with OpenHarness for async agent-human interactions. Updated `AGENT_ENTRY.md` to reference this new documentation and clarify UUID usage. Enhanced `CHEATSHEET.md` with additional context for the `build_brain_map.py` script, indicating its minimal harness copy usage and alternative paths. Added a portfolio index reference in the GUI audit documentation for better navigation.

Author: ManintheCrowds

docs/AGENT_ENTRY.md

@@ -35,6 +35,10 @@
 
 ---
 
+## 3b. OpenGrimoire clarification queue (optional)
+
+If you use **OpenGrimoire** (OpenAtlas) for async agent→human questions, stable UUIDs and handoff conventions live in **[`OPENGRIMOIRE_CLARIFICATION_BRIDGE.md`](./OPENGRIMOIRE_CLARIFICATION_BRIDGE.md)**. OpenHarness does not host this API; it is the join key between harness runs and Grimoire.
+
 ## 4. State on disk
 
 **[`state/`](../state/)** — Schema and files agents and humans share: `handoff_latest.md`, `decision-log.md`, `continue_prompt.txt`, `daily/`, etc. Read **[`state/README.md`](../state/README.md)** for layout. After a handoff, load **handoff** → **preferences** → **rejection_log** as in CHEATSHEET **Memory load order**.

docs/CHEATSHEET.md

@@ -38,7 +38,7 @@ Use this table for **action parity** with humans (same script, agent via `run_te
 | `copy_continue_prompt.ps1` / `copy_continue_prompt.sh` / `copy_continue_prompt.cmd` | Copy continue prompt to clipboard | `.\scripts\copy_continue_prompt.ps1` (Windows), `./scripts/copy_continue_prompt.sh`, or `scripts\copy_continue_prompt.cmd` |
 | `validate_handoff_scp.py` | Validate `handoff_latest` against SCP rules | `python scripts/validate_handoff_scp.py` |
 | `sanitize_input.py` | Sanitize handoff/state before commit | Usually via pre-commit; `python scripts/sanitize_input.py` |
-| `build_brain_map.py` | Build brain-map JSON from cursor state | `python scripts/build_brain_map.py` (set `CURSOR_STATE_DIR` / `CURSOR_STATE_DIRS` as in README) |
+| `build_brain_map.py` | Build brain-map JSON from cursor state (minimal harness copy) | `python scripts/build_brain_map.py` (set `CURSOR_STATE_DIR` / `CURSOR_STATE_DIRS` as in README). **OpenGrimoire / multi-root / vaults:** use sibling **MiscRepos** [`../../MiscRepos/.cursor/scripts/build_brain_map.py`](../../MiscRepos/.cursor/scripts/build_brain_map.py) instead. |
 | `verify_canonical_bundle.ps1` | Verify pinned bundle hashes | `.\scripts\verify_canonical_bundle.ps1` |
 | `update_canonical_bundle_hashes.ps1` | Regenerate `docs/canonical-bundle.sha256` after bundle edits | `.\scripts\update_canonical_bundle_hashes.ps1` |
 | `check_docs_portfolio_links.py` | Verify `docs/**/*.md` links to sibling `portfolio-harness` | `python scripts/check_docs_portfolio_links.py` |

docs/OPENGRIMOIRE_CLARIFICATION_BRIDGE.md

@@ -0,0 +1,40 @@
+# OpenGrimoire clarification queue ↔ OpenHarness
+
+**Purpose:** Correlate **async human answers** to **agent runs** using stable UUIDs from OpenGrimoire (OpenAtlas app).
+
+## Stable identifier
+
+When an agent creates a clarification request via `POST /api/clarification-requests`, the response includes `item.id` (UUID). Treat this as the canonical join key.
+
+## Handoff convention
+
+In `.cursor/state/handoff_latest.md` or session notes (reference only — not executable):
+
+```text
+OPENGRIMOIRE_CLARIFICATION_ID=<uuid>
+OPENGRIMOIRE_BASE_URL=https://your-host (default local: http://localhost:3001)
+```
+
+Poll until `item.status` is `answered` or `superseded`:
+
+`GET /api/clarification-requests/<uuid>` with:
+
+- **`x-clarification-queue-key`** when OpenGrimoire has **`CLARIFICATION_QUEUE_API_SECRET`** set (recommended for production harnesses that only poll clarification — smaller blast radius than the alignment key), or
+- **`x-alignment-context-key`** when using **`ALIGNMENT_CONTEXT_API_SECRET`** and no dedicated clarification secret (same key gates alignment + clarification).
+
+## Optional script
+
+If the OpenGrimoire repo is checked out, use:
+
+`node scripts/poll-clarification.mjs <uuid>`
+
+(from the OpenAtlas/OpenGrimoire repo root; set **`CLARIFICATION_QUEUE_API_SECRET`** in the environment for the script to send **`x-clarification-queue-key`**, else **`ALIGNMENT_CONTEXT_API_SECRET`** for **`x-alignment-context-key`** — see script header).
+
+## Normative API doc
+
+In your OpenGrimoire (OpenAtlas) clone: `docs/agent/CLARIFICATION_QUEUE_API.md`.
+
+## Distinction
+
+- **OpenHarness:** patterns, state schema, handoff — no clarification HTTP API.
+- **OpenGrimoire:** persistence and operator UI for the queue (`/admin/clarification-queue`).

docs/audit/gui-2026-03-26.md

@@ -1,5 +1,7 @@
 # GUI audit — OpenHarness
 
+**Portfolio index (sibling repo audits):** [MiscRepos `GUI_AUDIT_PORTFOLIO_INDEX.md`](../../MiscRepos/docs/audit/GUI_AUDIT_PORTFOLIO_INDEX.md).
+
 **Date:** 2026-03-26  
 **Mode:** Read-only audit  
 

scripts/build_brain_map.py

@@ -6,6 +6,11 @@
 """
 Build brain-map-graph.json from Harness state sources.
 
+**Portfolio / OpenGrimoire:** A richer sibling script lives at
+``MiscRepos/.cursor/scripts/build_brain_map.py`` (multi-root ``CURSOR_STATE_DIRS``,
+vault roots, SCP, default output to ``OpenAtlas/public/brain-map-graph.local.json``).
+Use this file only for minimal OpenHarness-only trees.
+
 Sources:
 - state/daily/YYYY-MM-DD.md (or .cursor/state/daily/)
 - state/handoff_latest.md