@yemi33/minions 0.1.2390 → 0.1.2392

package/docs/slim-ux/concepts.md

@@ -1,448 +1,507 @@
 # Minions Concept Dictionary
 
 > Plain-English definitions for every first-class noun in the Minions system. This is the team's
-> shared language before we redesign the UI; it is intentionally factual — design opinions live in
+> shared language before we redesign the UI; it is intentionally factual -- design opinions live in
 > [`architecture-suggestions.md`](./architecture-suggestions.md).
 >
-> Every backing claim is anchored to a file path and line number. If you change the code, please
-> update the line numbers here too.
+> Backing claims use stable `path#symbol` references instead of exact source-line anchors. Search
+> for the named symbol when the implementation moves.
 
 ---
 
 ## How the system fits together (one paragraph)
 
-A **human** types something into the **Command Center** chat. CC turns that into a **Work Item**
-(or a **Plan**, **Note**, **Schedule**, **Watch**, etc.) by emitting an `===ACTIONS===` JSON block.
-The **Engine** wakes up on its 60-second tick, looks at the pending **Dispatch Queue**, picks an
-**Agent** (a Minion / Team Member) by consulting **Routing**, spawns a CLI process for that agent
-(Claude or Copilot), and waits. The agent reads its **Charter**, the **Playbook** for the work
-type, the project's **CLAUDE.md**, the **Pinned Context**, the team's **Notes** and
-**Knowledge Base**, then does the work — usually opening a **Pull Request**. When the agent exits,
-it writes a **Completion** report; the engine syncs the PR back, marks the Work Item done, and
-runs the **Inbox** through the **KB Sweep** so the team's memory grows. **Watches**, **Schedules**,
-and **Pipelines** are the three ways things happen without a human typing.
+A **human** asks the **Command Center** to inspect or change the system. CC uses the dashboard's
+existing `/api/*` routes, most often to create a **Work Item**, **Plan**, **Note**, **Schedule**, or
+**Watch**. On its default 10-second tick, the **Engine** considers the pending **Dispatch Queue**,
+consults **Routing**, selects an **Agent**, and invokes the configured runtime adapter (Claude,
+Copilot, or Codex). The agent receives its **Charter**, the work-type **Playbook**, project
+instructions, and bounded team memory, then does the work -- often opening a **Pull Request**.
+Before exit it writes a trusted **Completion** JSON report; lifecycle code uses that report to
+finish the Work Item and attach durable artifacts. **Watches**, **Schedules**, and **Pipelines**
+provide persistent automation without a new human chat turn.
 
 ---
 
 ## 1. Command Center (CC)
 
-**What it is.** The chat box on the dashboard's home page. It's a Claude (or Copilot) instance
-running with a beefy system prompt that knows about your projects, agents, work items, and the
-JSON action grammar. You talk to CC; CC dispatches Work Items, creates Plans, files Notes, opens
-Watches, etc. It is the primary human-to-fleet interface.
+**What it is.** The conversational control surface on the dashboard home page. CC runs through the
+runtime adapter selected by `resolveCcCli`, with a system prompt that describes the live API. It can
+answer questions and use direct localhost `/api/*` calls to change Minions state.
+
+CC actions are direct API writes correlated to the current turn through `X-CC-Turn-Id`; the
+dashboard then builds synthetic action results for the UI.
 
 **Where it lives.**
+
 - System prompt: `prompts/cc-system.md`
-- Per-tab and global session state: `engine/state.db` (`cc_sessions`).
-- Direct CLI invocation: `engine/llm.js` `callLLM({ direct: true })` — bypasses
-  `spawn-agent.js` and runs the runtime CLI itself.
-
-**Backing classes / functions.**
-- Streaming endpoint handler: `dashboard.js` line 7194 (`/api/command-center/stream` → `handleCommandCenterStream`).
-- Non-streaming handler: `dashboard.js` line 7193 (`/api/command-center` → `handleCommandCenter`).
-- Action parser: `parseCCActions` / `executeCCActions` (search `dashboard.js` for `parseCCActions`).
-- Tab session bookkeeping: dashboard.js around line 1185 (`/api/cc-sessions/:id`).
-
-**How the existing dashboard surfaces it.** `dashboard/pages/home.html` — the Command Center is
-the top-of-page input box. There is also a "past commands" / history modal.
-
-**Endpoints (`dashboard.js` line refs from the `ROUTES` table starting at line 6807).**
-
-| Method | Path | Line | Purpose |
-|--------|------|------|---------|
-| POST | `/api/command-center` | 7193 | Single-shot CC turn |
-| POST | `/api/command-center/stream` | 7194 | SSE-streaming CC turn |
-| POST | `/api/command-center/new-session` | 7191 | Clear active CC session |
-| POST | `/api/command-center/abort` | 7192 | Cancel an in-flight stream |
-| GET  | `/api/cc-sessions` | 7195 | List per-tab sessions |
-| DELETE | `/api/cc-sessions/:id` | (see line 1185) | Close a tab |
-
-**Relationships.** CC is the *creator* of almost every other concept on this page (Work Item,
-Plan, Note, Schedule, Watch, Knowledge entry, Pinned note). Per-call cap is
-`ENGINE_DEFAULTS.ccMaxTurns` (50, `engine/shared.js` line 860+); sessions themselves never expire.
+- Session records: `engine/state.db` table `cc_sessions`
+- Shared invocation path: `dashboard.js#ccCall` and `engine/llm.js#callLLM`
+- Runtime selection: `engine/shared.js#resolveCcCli` and `engine/runtimes/index.js#resolveRuntime`
+
+**Backing symbols.**
+
+- Request handlers: `dashboard.js#handleCommandCenter` and
+  `dashboard.js#handleCommandCenterStream`
+- Turn/action correlation: `dashboard.js#_ccTurnCreations` and
+  `dashboard.js#_buildSyntheticActionResultsForTurn`
+- Session persistence: `engine/small-state-store.js` CC-session helpers
+- Per-response tool-turn cap: `engine/shared.js#ENGINE_DEFAULTS.ccMaxTurns` (default 50)
+
+**Existing dashboard.** `dashboard/pages/home.html` contains the classic CC surface; the Slim home
+surface uses the same server handlers and sessions.
+
+**Endpoints.**
+
+| Method | Path | Purpose |
+|---|---|---|
+| POST | `/api/command-center` | Non-streaming CC turn |
+| POST | `/api/command-center/stream` | SSE-streaming CC turn |
+| POST | `/api/command-center/triage` | Isolated, watch-driven headless turn |
+| POST | `/api/command-center/new-session` | Clear the active CC session |
+| POST | `/api/command-center/abort` | Abort an in-flight turn |
+| GET | `/api/cc-sessions` | List per-tab session metadata |
+| POST | `/api/cc-sessions/warm` | Pre-warm a compatible worker pool |
+| DELETE | `/api/cc-sessions/:id` | Delete a tab's persisted session |
+
+**Relationships.** CC is a human-facing client of the same APIs used by the rest of the dashboard.
+It creates and updates other concepts; it is not a second state store or a privileged orchestration
+path.
 
 ---
 
 ## 2. Work Item
 
-**What it is.** A unit of work the engine can dispatch to an agent. Has a title, type
-(`implement`, `fix`, `review`, …), priority, optional project, and lifecycle state. Most things on
-the home page eventually reduce to a Work Item.
+**What it is.** A unit of work the engine can dispatch to an agent. It has a title, canonical work
+type (`implement`, `fix`, `review`, and so on), priority, optional project and agent hints,
+dependencies, and lifecycle state.
 
 **Where it lives.**
-- Durable records: `engine/state.db` `work_items`, keyed by central/project scope.
-- In-flight dispatch rows: `engine/state.db` `dispatches`.
-
-**Backing classes / functions.**
-- Status constants: `engine/shared.js` line 1348 (`WI_STATUS`).
-- Type constants: `engine/shared.js` line 1359 (`WORK_TYPE`).
-- `addToDispatch`: `engine/dispatch.js` line 128.
-- `updateWorkItemStatus`: `engine/lifecycle.js` line 484 (validates against `WI_STATUS`).
-- `isItemCompleted`: `engine/lifecycle.js` line 477.
-- Lifecycle: pending → dispatched → done | failed; failed auto-retries up to
-  `ENGINE_DEFAULTS.maxRetries`.
-
-**Existing dashboard.** `dashboard/pages/work.html` — the side-panel "Work Items" tab with
-pending / active / completed columns.
-
-**Endpoints (all under `/api/work-items*`, `dashboard.js` lines 6852–6888).**
-- `POST /api/work-items` (6852) — create
-- `POST /api/work-items/update` (6853) — edit
-- `POST /api/work-items/retry` (6854) — back to pending
-- `POST /api/work-items/delete` (6855) — kill + remove
-- `POST /api/work-items/cancel` (6856) — cancel with reason
-- `POST /api/work-items/archive` (6857) — move to archive
-- `GET  /api/work-items/archive` (6858) — list archive
-- `POST /api/work-items/reopen` (6859) — done/failed → pending
-- `POST /api/work-items/feedback` (6860) — 👍 / 👎 → inbox note
-
-**Relationships.** A Work Item is the *body* the **Dispatch Queue** carries. It points to a
-**Project**, an **Agent** (post-dispatch), and a **Pull Request** (post-completion). Materialized
-from a **PRD Item** via the plan-to-prd flow. **Pipelines** can declare Work Items as stages.
+
+- Durable records: `engine/state.db` table `work_items`
+- In-flight execution records: `engine/state.db` table `dispatches`
+- Read/write facade: `engine/work-items-store.js`
+
+**Backing symbols.**
+
+- Statuses: `engine/shared.js#WI_STATUS`
+- Work types: `engine/shared.js#WORK_TYPE`
+- Queue admission: `engine/dispatch.js#addToDispatch`
+- Lifecycle updates: `engine/lifecycle.js#updateWorkItemStatus`
+- Completion predicate: `engine/lifecycle.js#isItemCompleted`
+
+The common path is `pending` (or `queued`) -> `dispatched` -> `done` or `failed`. `paused`,
+`decomposed`, and `cancelled` are also canonical states. Failures can retry up to
+`ENGINE_DEFAULTS.maxRetries`, with per-agent reassignment governed separately.
+
+**Existing dashboard.** `dashboard/pages/work.html` is the classic Work Items screen. Slim embeds
+that same screen for queued-work details rather than maintaining a second renderer.
+
+**Endpoints.**
+
+- `GET /api/work-items` -- list enriched, size-bounded records
+- `GET /api/work-items/<id>` -- fetch one full record for detail/edit
+- `POST /api/work-items` -- create
+- `POST /api/work-items/update` -- edit
+- `POST /api/work-items/retry` -- return a failed/dispatched item to pending
+- `POST /api/work-items/cancel` and `/delete` -- stop and remove/cancel
+- `POST /api/work-items/archive` and `GET /api/work-items/archive`
+- `POST /api/work-items/reopen`
+- `POST /api/work-items/feedback`
+
+**Relationships.** A Work Item is the durable intent carried by a **Dispatch**. It may point to a
+**Project**, depend on other Work Items, be materialized from a **PRD Item**, and acquire one or more
+associated **Pull Request** records over its lifecycle.
 
 ---
 
 ## 3. Plan
 
-**What it is.** A markdown document in `plans/` describing what should be built and why. The plan
-flow is: human (or agent) writes plan → human approves → `plan-to-prd` agent converts it to a
-**PRD** JSON → materializer creates **Work Items** with `depends_on` edges → engine executes them
-→ verify task auto-runs → human archives.
+**What it is.** A human-readable Markdown proposal that is approved before execution. The normal
+flow is:
+
+```
+Plan Markdown -> plan-to-prd Work Item -> PRD rows -> Work Items -> verify Work Item(s)
+```
+
+The `plan-to-prd` agent writes `agents/<id>/prd-result.json`. On successful completion,
+`engine/lifecycle.js` validates that sidecar against the expected plan and imports it into the SQL
+PRD store before the plan-to-PRD Work Item can finish.
 
 **Where it lives.**
-- Drafts: `plans/*.md`.
-- Archived: `plans/archive/*.md`.
-- Status field is on the PRD JSON twin (see PRD).
-
-**Backing classes / functions.**
-- Status constants: `engine/shared.js` line 1365 (`PLAN_STATUS = { ACTIVE, AWAITING_APPROVAL,
-  APPROVED, PAUSED, REJECTED, COMPLETED, REVISION_REQUESTED }`).
-- Atomic dispatch: `queuePlanToPrd` (used by every plan-to-prd path).
-- Plan completion / archival: `engine/lifecycle.js`
-  - `checkPlanCompletion` line 22
-  - `archivePlan` line 355
-  - `cleanupPlanWorktrees` line 415.
-- Plan dirs: `engine/pipeline.js` line 23 (`PLANS_DIR`).
-
-**Existing dashboard.** `dashboard/pages/plans.html` — plan browser, approve / reject / archive
-buttons.
-
-**Slim dashboard.** A **Plans** cockpit tile (`data-tile="plans"` in `dashboard/slim/body.html`)
-opens `#slim-plans-modal` — a two-tab control panel (**Plans** / **PRD**) rendered lazily by
-`dashboard/slim/js/plans.js` into `#slim-plans-body`. The **Plans** tab lists the `.md` drafts with
-their status and wires the lifecycle actions (approve / execute / archive at minimum, plus reject /
-pause / regenerate / delete / unarchive) to the **existing** `GET /api/plans`, `GET /api/plans/:file`,
-and the `POST /api/plans/*` endpoints — **no new server routes** are added. The tile's count is
-fetched lazily via `GET /api/plans` (`loadPlansCounts`), *not* from `/api/status` (the status
-snapshot carries no plans/PRD count). The whole surface lives under `dashboard/slim/` and is gated
-solely by the **`slim-ux`** feature flag — there is **no new `engine.*` flag or Settings-parity
-toggle**; Slim itself is the gate. The renderer exposes `openPlansModal` / `renderPlansTab` /
-`renderPlansTile` / `loadPlansCounts` in the shared Slim IIFE scope; tile→modal/tab binding is wired
-by `modals-tiles.js` + `status.js`.
-
-**Endpoints (`dashboard.js` lines 6952–6963).**
-- `GET  /api/plans` (6952) — list .md drafts + .json PRDs
-- `POST /api/plans/trigger-verify` (6953)
-- `POST /api/plans/approve` (6954) — kicks off plan-to-prd
-- `POST /api/plans/pause` (6955)
-- `POST /api/plans/execute` (6956)
-- `POST /api/plans/reject` (6957)
-- `POST /api/plans/regenerate` (6958)
-- `POST /api/plans/delete` (6959)
-- `POST /api/plans/archive` (6960) — manual archive
-- `POST /api/plans/unarchive` (6961)
-- `POST /api/plans/revise` (6962)
-- `POST /api/plans/discuss` (6963)
-- `POST /api/plans/create` (7055)
-
-**Relationships.** Plan ↔ **PRD** ↔ **Work Items** is a one-to-one-to-many chain. **Pipelines**
-can include `plan` stages. **Verification** is owned by the plan: when all work items finish, a
-verify Work Item auto-spawns.
+
+- Live source documents: `plans/*.md`
+- Archived source documents: `plans/archive/*.md`
+- Executable lifecycle/status: the corresponding SQL-backed **PRD**
+
+Executable lifecycle state is SQL-backed. Manual archive moves the Markdown source to
+`plans/archive/` and marks the authoritative PRD archived in place.
+
+**Backing symbols.**
+
+- Plan statuses: `engine/shared.js#PLAN_STATUS`
+- Atomic conversion enqueue: `engine/shared.js#queuePlanToPrd`
+- Completion gate: `engine/lifecycle.js#checkPlanCompletion`
+- Manual archive: `engine/lifecycle.js#archivePlan`
+- Plan worktree cleanup: `engine/lifecycle.js#cleanupPlanWorktrees`
+- PRD sidecar import: `engine/lifecycle.js#runPostCompletionHooks`
+
+**Existing dashboard.** `dashboard/pages/plans.html` owns the classic Plans and PRD tabs and all
+lifecycle actions.
+
+**Slim dashboard.** The Plans cockpit tile lazily gets its active count from `GET /api/plans`
+through `dashboard/slim/js/plans.js#loadPlansCounts`. Opening the tile embeds the literal classic
+`/plans?embed=1` screen via `dashboard/slim/js/modals-tiles.js#renderPlansBody`; Slim does not carry
+a parallel Plans/PRD renderer.
+
+**Endpoints.**
+
+- `GET /api/plans` -- list Markdown plans plus SQL-backed PRD summaries
+- `POST /api/plans/create`
+- `POST /api/plans/approve`, `/execute`, `/pause`, `/reject`, `/revise`
+- `POST /api/plans/regenerate`
+- `POST /api/plans/trigger-verify`
+- `POST /api/plans/archive`, `/unarchive`, `/delete`
+- `POST /api/plans/discuss`
+
+**Relationships.** A Plan has one executable PRD and many materialized Work Items. A cross-repo
+plan can fan items into multiple projects and create one verify Work Item per touched project.
+Archiving remains an explicit human action after verification.
 
 ---
 
 ## 4. PRD (Product Requirements Document)
 
-**What it is.** The structured JSON twin of a Plan. Where the Plan markdown is for humans, the
-PRD JSON is what the engine reads to materialize work items. Each PRD has an `items` array; each
-item has acceptance criteria, complexity, dependencies, and a status (`missing | updated | done`).
+**What it is.** The structured, machine-executable representation of a Plan. Its full document
+shape remains JSON-compatible, but the authoritative records are SQL rows: a parent in `prds` and
+children in `prd_items`. The compatibility filename still ends in `.json`; it is an identifier,
+not a live file under `prd/`.
 
-**Where it lives.** `prd/*.json`, archived to `prd/archive/*.json`. The materializer treats
-`missing` and `updated` items as work to do (`PRD_MATERIALIZABLE`, `engine/shared.js` line 1370).
+The current document shape uses `missing_features[]`. Each feature can carry acceptance criteria,
+complexity, dependencies, project, type, and a status of `missing`, `updated`, or `done`.
 
-**Backing classes / functions.**
-- Status constants: `engine/shared.js` line 1370 (`PRD_ITEM_STATUS`, `PRD_MATERIALIZABLE`).
-- Sync from Work Items: `syncPrdItemStatus`, `reconcilePrdStatuses` (`engine/lifecycle.js`
-  lines 564, 597).
-- Plan-to-PRD agent: `playbooks/plan-to-prd.md`, dispatched via `queuePlanToPrd`.
-- PRD dir: `engine/pipeline.js` line 24 (`PRD_DIR`).
+**Where it lives.**
 
-**Existing dashboard.** `dashboard/pages/plans.html` — same page as Plan, with a graph view of
-PRD items and their states. Recent feature: PRD graph view at parity with list view (commit
-`b4767d2d`).
+- Parent records: `engine/state.db` table `prds`
+- Item records: `engine/state.db` table `prd_items`
+- Verify-PR links: `engine/state.db` table `prd_verify_prs`
+- Read/write facade: `engine/prd-store.js`
 
-**Slim dashboard.** The same `#slim-plans-modal` (opened from the Plans cockpit tile) carries a
-**PRD** tab rendered by `dashboard/slim/js/plans.js`, mirroring the classic PRD view: it lists
-materialized PRDs with their work items, the verify task, and linked PRs. Reads use the **existing**
-`GET /api/prd`, `GET /api/plans` (the `.json` entries, for per-PRD lifecycle status), and
-`GET /api/work-items` (the verify row) — no new routes. See **§3 Plan → Slim dashboard** for the
-shared tile/modal, lazy-count source, and `slim-ux`-only gating (no new `engine.*` flag).
+Archived PRDs remain in SQL. Current manual archive sets the PRD's archive metadata in place.
 
-**Endpoints (`dashboard.js`).**
-- `POST /api/prd-items` (6968) — create PRD item
-- `POST /api/prd-items/update` (6969)
-- `POST /api/prd-items/remove` (6970) — also cancels matching Work Item
+**Backing symbols.**
+
+- Item statuses: `engine/shared.js#PRD_ITEM_STATUS`
+- Materializable statuses: `engine/shared.js#PRD_MATERIALIZABLE`
+- SQL writes and item upserts: `engine/prd-store.js#writePrd` and `#_upsertPrd`
+- Reads: `engine/prd-store.js#readPrd` and `#listPrdRows`
+- Work Item -> PRD status sync: `engine/lifecycle.js#syncPrdItemStatus`
+- Reconciliation sweep: `engine/lifecycle.js#reconcilePrdStatuses`
+- Stable Work Item join: `work_items.prd_item_id -> prd_items.id`
+
+**Existing dashboard.** `dashboard/pages/plans.html` renders the PRD graph/list. The Slim Plans tile
+embeds the same screen.
+
+**Endpoints.**
 
-**Relationships.** PRD is the bridge between **Plan** (human-readable) and the **Work Item**
-queue (machine-executable). When a plan's PRD items are all `done`, the plan completes; archive
-is still manual.
+- `GET /api/prd` -- SQL-derived progress, Work Item, and PR state
+- `POST /api/prd-items` -- add an item
+- `POST /api/prd-items/update` -- edit an item
+- `POST /api/prd-items/remove` -- remove an item and cancel its materialized Work Item
+
+**Relationships.** PRD is the bridge between a human Plan and executable Work Items. Its parent row,
+item rows, Work Item foreign keys, and verify PR associations form one SQL-backed lifecycle.
 
 ---
 
 ## 5. Note
 
-**What it is.** A small markdown file written by an agent (after a task) or a human (via "+
-Note") capturing what was learned. Notes are *raw*; the consolidation engine reads them and
-either merges them into `notes.md` or promotes them into a **Knowledge Base** category.
+**What it is.** A small Markdown artifact written by a human, agent, or engine process to capture
+an outcome, warning, or reusable finding. A Note is raw input; consolidation decides whether its
+information belongs in team `notes.md`, the Knowledge Base, or both.
+
+**Where it lives.**
 
-**Where it lives.** `notes/inbox/*.md` while raw, `notes/archive/<category>/*.md` after KB sweep,
-and merged content lives in `notes.md`.
+- New notes: `notes/inbox/*.md`
+- Processed source artifacts: `notes/archive/*.md`
+- Consolidated team digest: `notes.md`
+- Classified durable knowledge: `knowledge/<category>/*.md`
 
-**Backing classes / functions.**
-- Inbox writer: `writeToInbox` — `engine/shared.js` line 648 (re-exported line 2959).
-- ID parser: `parseNoteId` (same module).
-- Consolidation orchestration: `engine/consolidation.js`
-  - `consolidateInbox` line 24
-  - `consolidateWithLLM` line 116
-  - `classifyToKnowledgeBase` line 389
-  - `archiveInboxFiles` line 444.
+**Backing symbols.**
 
-**Existing dashboard.** `dashboard/pages/inbox.html` — the inbox tab. A "+ Note" quick-action
-exists in the top bar of `home.html`.
+- Writer and ID parser: `engine/shared.js#writeToInbox` and `#parseNoteId`
+- Consolidation entry point: `engine/consolidation.js#consolidateInbox`
+- LLM merge: `engine/consolidation.js#consolidateWithLLM`
+- Classification: `engine/consolidation.js#classifyToKnowledgeBase`
+- Source archival: `engine/consolidation.js#archiveInboxFiles`
 
-**Endpoints (`dashboard.js`).**
-- `POST /api/notes` (6946) — write to inbox
-- `GET  /api/notes-full` (6947) — read consolidated `notes.md`
-- `POST /api/notes-save` (6948) — save edited `notes.md`
+**Existing dashboard.** `dashboard/pages/inbox.html` surfaces Notes, the inbox, and KB controls.
+
+**Endpoints.**
 
-**Relationships.** Notes feed **Inbox** → **Consolidation** → **Knowledge Base** (or
-`notes.md`). Agents are *required* to drop a note in the inbox at the end of every successful
-task; failure cases must NOT write a note.
+- `POST /api/notes`
+- `GET /api/notes-full`
+- `POST /api/notes-save`
+
+**Relationships.** Notes enter the **Notes Inbox**, are consolidated into team memory, and can
+produce **Knowledge Base** entries. Successful agent tasks write the requested findings note;
+failed or partial tasks do not create a success artifact.
 
 ---
 
 ## 6. Knowledge Base (KB)
 
-**What it is.** The team's long-term memory. After consolidation, notes get classified into one of
-five categories and archived. Agents read the KB before researching outside.
+**What it is.** The team's categorized long-term memory. The five canonical categories in
+`KB_CATEGORIES` are `architecture`, `conventions`, `project-notes`, `build-reports`, and `reviews`.
+The consolidation pipeline can also use supporting categories such as `general`, while personal
+agent memory is kept separately under `knowledge/agents/`.
 
 **Where it lives.**
-- `notes/archive/architecture/*.md`
-- `notes/archive/conventions/*.md`
-- `notes/archive/project-notes/*.md`
-- `notes/archive/build-reports/*.md`
-- `notes/archive/reviews/*.md`
 
-**Backing classes / functions.**
-- Categories: `engine/shared.js` line 840 (`KB_CATEGORIES`).
-- Pin store: `engine/shared.js` line 15 (`PINNED_ITEMS_PATH = engine/kb-pins.json`).
-- Sweep / classification: `engine/kb-sweep.js`, `engine/consolidation.js`
-  `classifyToKnowledgeBase` line 389.
+- Shared entries: `knowledge/<category>/*.md`
+- Per-agent memory: `knowledge/agents/<agent-id>.md`
+- Sweep recovery archive: `knowledge/_swept/`
+
+**Backing symbols.**
+
+- Canonical categories: `engine/shared.js#KB_CATEGORIES`
+- Query/read layer: `engine/queries.js#KNOWLEDGE_DIR` and KB readers
+- Classification: `engine/consolidation.js#classifyToKnowledgeBase`
+- Compaction and TTL sweep: `engine/kb-sweep.js`
+
+**Existing dashboard.** `dashboard/pages/inbox.html` contains the KB browser and sweep controls.
 
-**Existing dashboard.** `dashboard/pages/inbox.html` — same tab as Notes. KB browser by category.
+**Endpoints.**
 
-**Endpoints (`dashboard.js`).**
-- `GET  /api/knowledge` (7146) — list KB grouped by category
-- `POST /api/knowledge` (7147) — create entry directly
-- `POST /api/knowledge/sweep` (7163) — async sweep
-- `GET  /api/knowledge/sweep/status` (7164) — poll sweep
+- `GET /api/knowledge`
+- `POST /api/knowledge`
+- `POST /api/knowledge/sweep`
+- `GET /api/knowledge/sweep/status`
 
-**Relationships.** Inbox → KB → agent prompt context. Pinned notes (next entry) are a *subset* of
-the KB.
+**Relationships.** KB entries feed bounded memory retrieval for agent prompts. An entry may be
+pinned, but **Pinned Context** is a separate prompt layer and storage surface rather than a subset
+of the KB.
 
 ---
 
 ## 7. Pinned Context (`pinned.md`)
 
-**What it is.** Critical context the human flagged as "READ FIRST." Prepended to every agent
-prompt regardless of work type. Use sparingly — pinned notes pollute every dispatch.
+**What it is.** Critical human-curated context that is always included in agent prompt context.
+Pinned content is intentionally small and high priority.
+
+**Where it lives.**
 
-**Where it lives.** `pinned.md` (root). Index file: `engine/kb-pins.json` (`PINNED_ITEMS_PATH`,
-`engine/shared.js` line 15).
+- Content: `<MINIONS_DIR>/pinned.md`
+- KB pin index: `<MINIONS_DIR>/engine/kb-pins.json`
 
-**Backing classes / functions.**
-- Add / remove handlers: `dashboard.js` lines 6891, 6895, 6908.
-- Parser: `parsePinnedEntries` (referenced at line 6893).
-- Slow-state cache invalidation explicitly on edits (`includeSlow: true`, line 6905).
+The Markdown content and KB pin index serve different purposes: `pinned.md` is the global prompt
+layer, while `kb-pins.json` protects selected KB entries from sweep removal.
 
-**Existing dashboard.** `dashboard/pages/home.html` — "Pinned Context" widget. Pin / unpin
-buttons appear in the KB browser.
+**Backing symbols.**
 
-**Endpoints (`dashboard.js`).**
-- `GET  /api/pinned` (6891)
-- `POST /api/pinned` (6895) — add
-- `POST /api/pinned/remove` (6908)
+- Pin-index path: `engine/shared.js#PINNED_ITEMS_PATH`
+- Pin-index reader: `engine/shared.js#getPinnedItems`
+- Markdown parser: `dashboard.js#parsePinnedEntries`
+- Prompt injection and untrusted-input fencing: `engine/playbook.js`
 
-**Relationships.** Pinned ⊂ KB. Pinned content shows up in *every* agent prompt (even short
-ones), so it's also coupled to **Charter** and **Routing** in terms of "what gets read first."
+**Existing dashboard.** The home and Knowledge surfaces expose pinned context and pin/unpin
+controls.
+
+**Endpoints.**
+
+- `GET /api/pinned`
+- `POST /api/pinned`
+- `POST /api/pinned/update`
+- `POST /api/pinned/remove`
+
+**Relationships.** Pinned Context is independent of **Routing** and **Charters** but appears in the
+same final prompt context. Because every dispatch sees it, stale or oversized content has
+fleet-wide impact.
 
 ---
 
 ## 8. Notes Inbox
 
-**What it is.** The waiting room for raw notes before consolidation. Files dropped into
-`notes/inbox/` are the engine's signal that an agent succeeded; they get consolidated into
-`notes.md` or promoted into the **KB** on a schedule.
+**What it is.** The staging area for raw notes before consolidation. Files can come from humans,
+agents, and engine alerts.
 
-**Where it lives.** `notes/inbox/*.md` (filename convention:
-`<agent>-<work-item-id>-<date>-<time>.md`, with YAML frontmatter `id:`, `agent:`, `date:`).
+**Where it lives.** `<MINIONS_DIR>/notes/inbox/*.md`. Agent findings conventionally use
+`<agent>-<work-item-id>-<date>-<time>.md` plus YAML frontmatter containing `id`, `agent`, and
+`date`.
 
-**Backing classes / functions.**
-- Inbox dir constant: `INBOX_DIR` in `engine/queries.js` (used at line 526).
-- Consolidation tick path: `engine/consolidation.js` `consolidateInbox` line 24.
-- Promote / delete API handlers: `handleInboxPersist`, `handleInboxPromoteKb`,
-  `handleInboxOpen`, `handleInboxDelete`.
+**Backing symbols.**
 
-**Existing dashboard.** `dashboard/pages/inbox.html` — note list, promote-to-KB buttons,
-consolidate-now button.
+- Directory: `engine/queries.js#INBOX_DIR`
+- Writer: `engine/shared.js#writeToInbox`
+- Consolidation: `engine/consolidation.js#consolidateInbox`
+- Manual handlers: `dashboard.js#handleInboxPersist`, `#handleInboxPromoteKb`,
+  `#handleInboxOpen`, and `#handleInboxDelete`
 
-**Endpoints (`dashboard.js`).**
-- `POST /api/inbox/persist` (7172) — promote to `notes.md`
-- `POST /api/inbox/promote-kb` (7173) — promote to KB category
-- `POST /api/inbox/open` (7174) — reveal in OS file manager
-- `POST /api/inbox/delete` (7175)
+**Existing dashboard.** `dashboard/pages/inbox.html` lists pending notes and manual disposition
+actions.
+
+**Endpoints.**
 
-**Relationships.** Inbox is the staging area between **Notes** (the act of writing) and the
-**KB** / `notes.md` (the durable store). Failure inboxes are explicitly forbidden by team rules.
+- `POST /api/inbox/persist`
+- `POST /api/inbox/promote-kb`
+- `POST /api/inbox/open`
+- `POST /api/inbox/delete`
+
+**Relationships.** Inbox is the boundary between raw **Notes** and durable `notes.md` / **KB**
+memory. Consolidation archives processed source files so the original evidence remains
+recoverable.
 
 ---
 
 ## 9. Schedule (cron)
 
-**What it is.** A recurring trigger that creates a Work Item on a cron pattern. The engine ticks
-every 10 s; if a schedule's last-run was ≥ its interval ago and the cron pattern matches, the
-engine drops a Work Item into the queue.
+**What it is.** A recurring trigger that creates a Work Item when a three-field cron expression
+(`minute hour day-of-week`) matches. Schedule-time template variables are resolved before the Work
+Item enters the queue, including nested string fields.
 
 **Where it lives.**
-- Definitions: `config.json` `schedules: []` (3-field cron `min hour dow`).
-- Last-run history: `engine/state.db` `schedule_runs`.
-
-**Backing classes / functions.**
-- Cron parser: `engine/scheduler.js`
-  - `parseCronField` line 63
-  - `parseCronExpr` line 106
-  - `shouldRunNow` line 145.
-- Variable substitution: `resolveScheduleTemplateVars` line 46 (handles `{{date}}`, etc., before
-  the work item lands in the queue).
-- Work-item factory: `createScheduledWorkItem` line 168.
-- Tick path: `discoverScheduledWork` line 209.
-
-**Existing dashboard.** `dashboard/pages/schedule.html` — schedule list, natural-language → cron
-helper.
-
-**Endpoints (`dashboard.js`).**
-- `GET  /api/schedules` (7200)
-- `POST /api/schedules` (7201) — create
-- `POST /api/schedules/update` (7202)
-- `POST /api/schedules/delete` (7203)
-- `POST /api/schedules/run-now` (7204)
-- `POST /api/schedules/parse-natural` (7199) — natural-language → cron
-
-**Relationships.** Schedule → emits Work Items into the **Dispatch Queue** on a cron. Closely
-analogous to **Watch** (event-driven instead of time-driven).
+
+- Definitions: `config.json` under `schedules[]`
+- Run history: `engine/state.db` table `schedule_runs`
+
+**Backing symbols.**
+
+- Cron parsing: `engine/scheduler.js#parseCronField` and `#parseCronExpr`
+- Match decision: `engine/scheduler.js#shouldRunNow`
+- Variable map: `engine/scheduler.js#buildScheduleTemplateVars`
+- Recursive substitution: `engine/scheduler.js#applyScheduleTemplateVarsRecursive`
+- Work Item factory: `engine/scheduler.js#createScheduledWorkItem`
+- Discovery: `engine/scheduler.js#discoverScheduledWork`
+
+**Existing dashboard.** `dashboard/pages/schedule.html` provides definition CRUD, run-now, and
+natural-language-to-cron assistance.
+
+**Endpoints.**
+
+- `GET /api/schedules`
+- `POST /api/schedules`
+- `POST /api/schedules/update`
+- `POST /api/schedules/delete`
+- `POST /api/schedules/run-now`
+- `POST /api/schedules/parse-natural`
+
+**Relationships.** A Schedule is time-driven and emits **Work Items**. A **Watch** is state-driven
+and can run a broader action registry.
 
 ---
 
 ## 10. Watch
 
-**What it is.** A persistent monitor on a PR or Work Item that fires when a condition is met
-(merged, build passes, build fails, status changes, new comments, vote changes). Watches are
-event-driven, schedules are time-driven.
+**What it is.** A persistent monitor that evaluates a registered target type and condition, then
+notifies or runs a configured follow-up action. The eight built-in target types are:
 
-**Where it lives.** `engine/state.db` `watches`.
+`pr`, `work-item`, `meeting`, `plan`, `schedule`, `pipeline`, `dispatch`, and `agent`.
 
-**Backing classes / functions.**
-- Status constants: `engine/shared.js` line 1380 (`WATCH_STATUS`).
-- Condition constants: `WATCH_CONDITION` (same file, near 1380); fire-once set
-  `WATCH_ABSOLUTE_CONDITIONS`.
-- CRUD: `engine/watches.js` `createWatch` line 44, `updateWatch` line 88, `deleteWatch`
-  line 116.
-- Tick path: `evaluateWatch` line 138, `checkWatches` line 214 (runs every 3 ticks).
-- State diff store: `_captureState` line 297 (`_lastState` per watch).
+Additional target types can be loaded from `<MINIONS_DIR>/watches.d/*.js`.
 
-**Existing dashboard.** `dashboard/pages/watches.html` — watch list, condition picker.
+**Where it lives.** `engine/state.db` table `watches`.
 
-**Endpoints (`dashboard.js`).**
-- `GET  /api/watches` (7207)
-- `POST /api/watches` (7208) — create
-- `POST /api/watches/update` (7209) — pause / resume / modify
-- `POST /api/watches/delete` (7210)
+**Backing symbols.**
 
-**Relationships.** Watch ⇒ optionally re-fires (notify, dispatch, etc.) when its condition flips.
-A merged-PR watch is the canonical "tell me when X ships" primitive.
+- Statuses and built-in target names: `engine/shared.js#WATCH_STATUS` and
+  `#WATCH_TARGET_TYPE`
+- Conditions: `engine/shared.js#WATCH_CONDITION`
+- Fire-once fallback set: `engine/shared.js#WATCH_ABSOLUTE_CONDITIONS`
+- Target registry: `engine/watches.js#TARGET_TYPES` and `#registerTargetType`
+- CRUD: `engine/watches.js#createWatch`, `#updateWatch`, and `#deleteWatch`
+- Evaluation: `engine/watches.js#evaluateWatch` and `#checkWatches`
+- Plugin loader: `engine/watches.js#_loadPluginTargetTypes`
+- Follow-up action registry: `engine/watch-actions.js`
+
+The engine schedules `checkWatches` every `ENGINE_DEFAULTS.watchPollEvery` ticks. The default is 18
+ticks, approximately three minutes at the default 10-second engine tick. Each watch can impose a
+longer minimum `interval`.
+
+**Existing dashboard.** `dashboard/pages/watches.html` lists watches and gets live target/action
+registries from the server.
+
+**Endpoints.**
+
+- `GET /api/watches`
+- `GET /api/watches/target-types`
+- `GET /api/watches/action-types`
+- `POST /api/watches`
+- `POST /api/watches/update`
+- `POST /api/watches/delete`
+
+**Relationships.** A Watch can write an inbox notification or run actions such as
+`dispatch-work-item`, `run-skill`, `webhook`, `minions-api`, `cc-triage`,
+`cancel-work-item`, `trigger-pipeline`, `archive-plan`, and `resume-plan`.
 
 ---
 
 ## 11. Pipeline
 
-**What it is.** A multi-stage workflow. Stages can be a Work Item (`task`), a `meeting`, or a
-`plan`. Stages can declare dependencies on previous stages. Pipelines run via triggers (manual,
-schedule, watch) and persist run state in SQLite.
+**What it is.** A reusable multi-stage workflow with dependency tracking. Shipped stage types are
+`task`, `meeting`, `plan`, `api`, `merge-prs`, `schedule`, `wait`, `parallel`, and `condition`.
+Pipelines can be triggered manually or through automation such as a schedule or watch action.
 
 **Where it lives.**
-- Definitions: `pipelines/*.json` (one file per pipeline).
-- Run state: `engine/state.db` `pipeline_runs`.
-
-**Backing classes / functions.**
-- Dirs: `engine/pipeline.js` lines 19–24 (`PIPELINES_DIR`, `PIPELINE_RUNS_PATH`, `PLANS_DIR`,
-  `PRD_DIR`).
-- CRUD: `getPipelines` line 35, `getPipeline` line 53, `savePipeline` line 58, `deletePipeline`
-  line 63.
-- Run lifecycle: `getActiveRun` line 80, `startRun` line 86, `updateRunStage` line 116,
-  `completeRun` line 127.
-
-**Existing dashboard.** `dashboard/pages/pipelines.html` — pipeline editor, run history, stage
-state.
-
-**Endpoints (`dashboard.js`).**
-- `GET  /api/pipelines` (7213)
-- `POST /api/pipelines` (7220) — create
-- `POST /api/pipelines/update` (7232)
-- `POST /api/pipelines/delete` (7248)
-- `POST /api/pipelines/trigger` (7256)
-- `POST /api/pipelines/continue` (7268) — past wait stage
-- `POST /api/pipelines/abort` (7280)
-- `POST /api/pipelines/retrigger` (7307)
-
-**Relationships.** Pipeline = composer of Work Items / Meetings / Plans. Confusion vector:
-unrelated to ADO/GitHub Actions pipelines, even though the word collides.
+
+- Definitions: `pipelines/*.json`
+- Run state: `engine/state.db` table `pipeline_runs`
+
+Definitions intentionally remain file-backed; run history is SQL-backed.
+
+**Backing symbols.**
+
+- Definition directory and CRUD: `engine/pipeline.js#PIPELINES_DIR`, `#getPipelines`,
+  `#getPipeline`, `#savePipeline`, and `#deletePipeline`
+- Stage/status enums: `engine/shared.js#STAGE_TYPE` and `#PIPELINE_STATUS`
+- Run reads: `engine/pipeline.js#getPipelineRuns` ->
+  `engine/small-state-store.js#readPipelineRuns`
+- Run mutations: `engine/shared.js#mutatePipelineRuns`
+- Lifecycle: `engine/pipeline.js#startRun`, `#updateRunStage`, `#upsertRunStage`, and
+  `#completeRun`
+
+**Existing dashboard.** `dashboard/pages/pipelines.html` provides definition editing, triggering,
+run history, and wait-stage continuation.
+
+**Endpoints.**
+
+- `GET /api/pipelines`
+- `POST /api/pipelines`
+- `POST /api/pipelines/update`
+- `POST /api/pipelines/delete`
+- `POST /api/pipelines/trigger`
+- `POST /api/pipelines/continue`
+- `POST /api/pipelines/abort`
+- `POST /api/pipelines/retrigger`
+
+**Relationships.** A Pipeline composes Work Items, Meetings, Plans, API calls, and control-flow
+stages. It is unrelated to a GitHub Actions or Azure DevOps build pipeline despite the shared word.
 
 ---
 
 ## 12. Dispatch
 
-**What it is.** The act of taking a pending Work Item and spawning an agent process for it. A
-dispatch holds the agent's PID, prompt sidecar path, worktree path, and current status until the
-process exits.
+**What it is.** One execution attempt for a Work Item. A dispatch records the selected agent,
+runtime, prompt sidecar, process/session metadata, worktree, branch/PR locks, and result.
 
-**Where it lives.** Active rows in `engine/state.db` `dispatches`.
+**Where it lives.** `engine/state.db` table `dispatches`.
 
-**Backing classes / functions.**
-- `mutateDispatch`: `engine/dispatch.js` line 60 (the only safe RMW path).
-- `addToDispatch`: line 128.
-- `findActivePrOrBranchLock`: line 112 (dedupe).
-- `completeDispatch`: line 327.
-- `cancelPendingDispatchesForPr`: line 550.
-- Result codes: `engine/shared.js` line 1433 (`DISPATCH_RESULT`).
+**Backing symbols.**
 
-**Existing dashboard.** `dashboard/pages/engine.html` — dispatch log; `home.html` — "Dispatch
-Queue" widget.
+- Transactional mutation: `engine/dispatch.js#mutateDispatch`
+- Queue insertion and dedupe: `engine/dispatch.js#addToDispatch`
+- PR/branch lock detection: `engine/dispatch.js#findActivePrOrBranchLock`
+- Completion: `engine/dispatch.js#completeDispatch`
+- Result enum: `engine/shared.js#DISPATCH_RESULT`
+- Store implementation: `engine/dispatch-store.js`
 
-**Endpoints.** No public CRUD — dispatch is a side effect of `/api/work-items` and the engine
-tick. Read shape via `/api/status` (line 6838).
+**Existing dashboard.** `dashboard/pages/engine.html` shows dispatch history and logs; home/work
+surfaces show active execution context.
 
-**Relationships.** Dispatch wraps a **Work Item** + an **Agent** + a **Project** worktree. A
-**Completion** is dispatch's exit signal.
+**Endpoints.** Dispatch is mostly a side effect of Work Item creation and engine discovery. Its
+read shape appears through `/api/status`, `/api/agents`, and Work Item APIs.
+
+**Relationships.** A Dispatch combines one Work Item, one Agent, one selected runtime, and one
+execution workspace. A **Completion** report is its trusted exit contract.
 
 ---
 
@@ -450,393 +509,487 @@ tick. Read shape via `/api/status` (line 6838).
 
 **What it is.** The sectioned view reconstructed from SQL dispatch rows:
 
-- `pending[]` — admitted Work Items waiting on agent / dependency / cooldown / budget.
-- `active[]` — currently spawned.
-- `completed[]` — finished (success or failure), kept for audit until cleaned.
+- `pending[]` -- admitted work waiting on capacity, dependencies, cooldowns, or an agent
+- `active[]` -- currently executing dispatches
+- `completed[]` -- terminal attempts retained for audit/cleanup
+- `review[]` -- candidates rejected by the optional pre-dispatch acceptance gate
 
-The queue's invariants are: max concurrent (default 5), per-PR / per-branch lock to avoid two
-agents fighting on the same branch, dependency-aware spawning (`depends_on` IDs must be done
-first), retry on failure up to `ENGINE_DEFAULTS.maxRetries`.
+**Where it lives.** `engine/state.db` table `dispatches`, reconstructed by
+`engine/dispatch-store.js#readDispatchSectioned`.
 
-**Where it lives.** `engine/state.db` `dispatches`.
+**Backing symbols.**
 
-**Backing classes / functions.** All in `engine/dispatch.js`. Mutation only via `mutateDispatch`
-line 60. Queue dedupe keys: `getDispatchProjectKey` line 80, `getPrDispatchTargetKey` line 85,
-`getPrDispatchDedupeKey` line 95, `getBranchDispatchLockKey` line 103.
+- Dashboard/query view: `engine/queries.js#getDispatchQueue`
+- Queue mutation: `engine/dispatch.js#mutateDispatch`
+- Acceptance-review routing: `engine/dispatch.js#_routeToReviewQueue`
+- Concurrency default: `engine/shared.js#ENGINE_DEFAULTS.maxConcurrent` (default 5)
 
-**Existing dashboard.** `dashboard/pages/home.html` ("Dispatch Queue" section) and
-`engine.html` (full log).
+The queue enforces Work Item and dispatch-key dedupe, fix-target and branch locks, dependency
+readiness, concurrency, retry policy, and budget/cooldown gates.
 
-**Endpoints.** Read-only via `/api/status` (line 6838).
+**Existing dashboard.** Home, Work Items, and Engine screens expose different projections of the
+same SQL-backed queue.
 
-**Relationships.** Queue ⊃ Dispatches ⊃ Work Items. The queue is the engine's state of mind.
+**Relationships.** Queue contains **Dispatches**; each Dispatch attempts a **Work Item**. Pending
+reasons explain why intent has not yet become an active process.
 
 ---
 
 ## 14. Completion
 
-**What it is.** The structured report an agent writes before exit. JSON shape lives at the path
-the engine puts in `MINIONS_COMPLETION_REPORT`. Fields: `status`, `summary`, `verdict`, `pr`,
-`failure_class`, `retryable`, `needs_rerun`, `artifacts[]`. Fenced ` ```completion ` blocks in
-stdout are also accepted as a fallback.
+**What it is.** The JSON report an agent writes to the exact path supplied in
+`MINIONS_COMPLETION_REPORT`. It is the sole structured completion source. A zero process exit code
+is only a transport signal; mutating work without a valid required report fails with
+`completion-report-missing`.
+
+Each spawn also receives `MINIONS_COMPLETION_NONCE`. The agent copies it verbatim into the report;
+a mismatch invalidates every reported signal and fails the dispatch as
+`completion-nonce-mismatch`.
 
 **Where it lives.**
-- File path: `engine/completions/<dispatchId>.json` (built by `dispatchCompletionReportPath`,
-  `engine/shared.js` line 351).
-- Field constants: `COMPLETION_FIELDS` (`engine/shared.js` line 1474–1475).
 
-**Backing classes / functions.** Parsing happens during `completeDispatch` (`engine/dispatch.js`
-line 327) and `engine/lifecycle.js`'s post-completion path (`syncPrsFromOutput` line 644).
+- `<MINIONS_DIR>/engine/completions/<dispatch-id>.json`
+- Canonical schema: [`docs/completion-reports.md`](../completion-reports.md)
 
-**Existing dashboard.** `dashboard/pages/work.html` — completion details when an item is
-expanded; `home.html` "Recent Completions" widget.
+**Backing symbols.**
 
-**Endpoints.** Read-only via `/api/status` and `/api/work-items/archive`.
+- Path builder: `engine/shared.js#dispatchCompletionReportPath`
+- Recognized core fields: `engine/shared.js#COMPLETION_FIELDS`
+- File parsing: `engine/lifecycle.js#parseCompletionReportFile`
+- Required-report gate: `engine/lifecycle.js#requiredCompletionReportFailure`
+- Dispatch terminalization: `engine/dispatch.js#completeDispatch`
 
-**Relationships.** Completion sits between **Dispatch** (the run) and **Work Item** (the long-term
-record). It also feeds **Pull Request** sync (`pr` field).
+Core fields include `status`, `summary`, `files_changed`, `tests`, `pr`, `not_changed`,
+`failure_class`, `retryable`, `needs_rerun`, `verdict`, `artifacts`, `nonce`, and
+`securityFlags`. The canonical schema documents additional optional fields and exact semantics.
+
+**Existing dashboard.** Work Item detail and recent-completion surfaces display the persisted
+summary, artifacts, tests, PR, and failure metadata.
+
+**Relationships.** Completion turns a process exit into a trustworthy lifecycle decision. It can
+attach a PR, publish artifacts, request a retry/rerun, carry a review verdict, flag prompt
+injection, and invalidate superseded Work Items.
 
 ---
 
-## 15. Pull Request (as tracked in minions)
+## 15. Pull Request (as tracked in Minions)
 
-**What it is.** A project-scoped row in the SQL PR store. Tracks status, vote tally, build
-state, review verdict, and the work item that created it. *Not* the GitHub/ADO PR itself —
-minions polls the host and writes a sanitized snapshot here.
+**What it is.** A project-scoped SQL record that mirrors the useful state of an external GitHub or
+Azure DevOps PR: host identity, source branch, lifecycle status, build state, human feedback,
+review verdict, and Minions linkage. It is not the host PR itself.
 
-**Where it lives.** `engine/state.db` `pull_requests`; cross-project links use `pr_links`.
+**Where it lives.**
 
-**Backing classes / functions.**
-- Status / pollable constants: `engine/shared.js` line 1372 (`PR_STATUS`,
-  `PR_POLLABLE_STATUSES`).
-- GitHub poller: `engine/github.js`.
-- ADO poller: `engine/ado.js`.
-- Parallel comment poller for human comments only (filters bots).
-- Sync from agent output: `syncPrsFromOutput` (`engine/lifecycle.js` line 644).
-- PR-attachment requirement check: `isPrAttachmentRequired` (line 875).
+- PR records: `engine/state.db` table `pull_requests`
+- Cross-record links: `engine/state.db` table `pr_links`
+- Store facade: `engine/pull-requests-store.js`
 
-**Existing dashboard.** `dashboard/pages/prs.html` — the "Pull Requests" tab.
+**Backing symbols.**
 
-**Endpoints (`dashboard.js`).**
-- `POST /api/pull-requests/link` (6974) — manually link external PR
-- `POST /api/pull-requests/delete` (7030)
+- Statuses and polling eligibility: `engine/shared.js#PR_STATUS` and
+  `#PR_POLLABLE_STATUSES`
+- GitHub integration: `engine/github.js`
+- Azure DevOps integration: `engine/ado.js`
+- Agent-output/report sync: `engine/lifecycle.js#syncPrsFromOutput`
+- Required-attachment gate: `engine/lifecycle.js#isPrAttachmentRequired`
 
-**Relationships.** PR ↔ Work Item is one-to-one in normal flow (review / fix work items can
-re-attach to the same PR). PR ↔ Watch is one-to-many (you can watch the same PR with multiple
-conditions).
+**Existing dashboard.** `dashboard/pages/prs.html` is the classic PR screen; Slim embeds that same
+screen for PR details.
+
+**Endpoints.**
+
+- `GET /api/pull-requests`
+- `POST /api/pull-requests/link`
+- `POST /api/pull-requests/observe`
+- `POST /api/pull-requests/delete`
+- Targeted resume/clear endpoints under `/api/pull-requests/clear-*`
+
+**Relationships.** An implementation Work Item commonly creates the first PR association. Review,
+fix, test, and follow-up Work Items can all attach to the same PR, and multiple Watches can observe
+it independently.
 
 ---
 
 ## 16. Agent / Minion / Team Member
 
-**What it is.** A named role with a charter, a skill list, a default CLI runtime, and metrics.
-Examples: Ripley (architect / explorer), Dallas (engineer), Lambert (analyst), Rebecca
-(architect), Ralph (engineer). Sometimes called "Minions" (the project's name), "Team Members"
-(in the dashboard), or just "Agents" (in the code).
+**What it is.** A named role with a charter, descriptive `expertise` tags, runtime/model
+configuration, and execution metrics. "Minion", "Team Member", and "Agent" refer to the same
+concept in different UI/code contexts.
+
+`expertise` is not the executable **Skill** system. It appears in the identity prompt and provides
+a soft preference to `pickReReviewAgentHints` for reviewer selection; it is not a hard routing
+constraint. The legacy config key `skills` is accepted only as a compatibility fallback.
 
 **Where it lives.**
-- Default roster: `engine/shared.js` line 1486 (`DEFAULT_AGENTS`).
-- Charter: `agents/<id>/charter.md` — read by `getAgentCharter` (`engine/queries.js` line 505).
-- Per-agent config (cli, model, budget, skills): `config.json` `agents.<id>`.
-- Metrics: `engine/state.db` `metrics` (per-agent token / cost / quality / runtime).
 
-**Backing classes / functions.**
-- Charter loader: `engine/queries.js` line 505.
-- Roster builder: `getAgents` line 509.
-- Spawn entry: `engine/spawn-agent.js`.
-- Charter injection into prompt: `engine/playbook.js` line 517.
+- Default roster: `engine/shared.js#DEFAULT_AGENTS`
+- Per-agent config: `config.json` under `agents.<id>`
+- Charter: `agents/<id>/charter.md`
+- Metrics and dispatch history: SQL-backed runtime state
+
+**Backing symbols.**
 
-**Existing dashboard.** `dashboard/pages/home.html` — "Minions Members" / agent cards.
+- Roster/status projection: `engine/queries.js#getAgents`
+- Detail projection: `engine/queries.js#getAgentDetail`
+- Identity/charter prompt: `engine/playbook.js#buildSystemPrompt`
+- Soft re-review preference: `engine/lifecycle.js#pickReReviewAgentHints`
+- Runtime selection: `engine/shared.js#resolveAgentCli`
+- Bundled adapters: `engine/runtimes/index.js` (`claude`, `copilot`, `codex`)
+
+**Existing dashboard.** Agent cards and detail views show status, runtime/model, charter, output,
+inbox, and recent dispatches.
 
 **Endpoints.**
-- `POST /api/agent-kill/:id` (line 3847)
-- `GET  /api/agent/:id/live-stream` (SSE — search for `/live-stream`)
-- `GET  /api/agent-detail/:id` (line 6686)
 
-**Relationships.** Agent ↔ Charter (1:1), Agent ↔ Skill (1:N), Agent ↔ runtime (Claude or
-Copilot via `resolveAgentCli`), Agent ↔ Work Item (N:N over history). Routing decides which agent
-gets which work type.
+- `GET /api/agents`
+- `GET /api/agent/:id`
+- `POST /api/agent/:id/kill`
+- `GET /api/agent/:id/live-stream`
+- `GET /api/agent/:id/live` and `/live-output`
+- `GET /api/agent/:id/output`
+- `POST /api/agents/steer`
+- `POST /api/agents/cancel`
+- `POST /api/agents/charter`
+
+**Relationships.** Routing and optional hints choose an Agent for a Work Item. The selected runtime
+adapter determines CLI behavior; the Charter and expertise tags shape identity; executable Skills
+remain runtime/harness assets.
 
 ---
 
 ## 17. Project
 
-**What it is.** A repository the engine knows about. Has a name, local path, repo host
-(`github` or `ado`), repository ID, main branch, and per-source toggles (`workSources`).
+**What it is.** A repository Minions knows how to operate on. A project definition carries its
+name, local operator checkout, repository identity/host, main branch, checkout mode, and enabled
+work sources.
 
 **Where it lives.**
-- Definitions: `config.json` `projects: []`.
-- Runtime records: project-scoped rows in `engine/state.db`.
-- Removal artifact: `projects/.archived/<name>-YYYYMMDD/`.
-
-**Backing classes / functions.**
-- Helpers: `engine/shared.js`
-  - `getProjects`
-  - `stateScope`, `readWorkItems`, `readPullRequests`
-  - `projectStateDir` for file-backed project definitions/artifacts.
-- Removal: `engine/projects.js` `removeProject` (canonical teardown — never edit `config.json`
-  directly).
-
-**Existing dashboard.** `dashboard/pages/settings.html` — Projects section.
-
-**Endpoints (`dashboard.js`).**
-- `POST /api/projects/browse` (7181)
-- `POST /api/projects/scan` (7182)
-- `POST /api/projects/confirm-token` (7183) — SEC-05 single-use token
-- `POST /api/projects/add` (7184)
-- `POST /api/projects/remove` (7185)
-
-**Relationships.** Project ⊃ Work Items, Pull Requests, Schedules (via `project` field), and
-Pipelines that target it. The minions repo is special: it's the home of the engine itself.
+
+- Definitions: `config.json` under `projects[]`
+- Runtime records: project-scoped rows in `engine/state.db`
+- Project definitions/artifacts: `projects/<name>/`
+- Removal archive: `projects/.archived/<name>-YYYYMMDD/`
+
+**Backing symbols.**
+
+- Config projection: `engine/shared.js#getProjects`
+- Scope helpers: `engine/shared.js#stateScope`, `#readWorkItems`, and
+  `#readPullRequests`
+- Checkout mode: `engine/shared.js#resolveCheckoutMode`
+- Canonical removal: `engine/projects.js#removeProject`
+
+`checkoutMode: "worktree"` is the default isolated execution model.
+`checkoutMode: "live"` opts a project into guarded in-place execution.
+
+**Existing dashboard.** `dashboard/pages/settings.html` owns project onboarding and removal.
+
+**Endpoints.**
+
+- `POST /api/projects/browse`
+- `POST /api/projects/scan`
+- `POST /api/projects/confirm-token`
+- `POST /api/projects/add`
+- `POST /api/projects/remove`
+
+**Relationships.** Projects scope Work Items, PRs, worktrees, and project-targeted automation.
+Project removal is a coordinated lifecycle operation, never a direct `config.json` edit.
 
 ---
 
 ## 18. Skill
 
-**What it is.** A reusable prompt / workflow snippet under `.claude/skills/<name>/SKILL.md`.
-Skills can be `scope: minions` (installed personally to the runtime's user dir) or
-`scope: project` (PR'd into the project repo). Agents auto-extract skills from their output via
-` ```skill ` fenced blocks.
+**What it is.** An executable prompt/workflow asset stored as `SKILL.md`. Agents can emit a
+fenced `skill` artifact with `scope: minions` (personal runtime-native installation) or
+`scope: project` (queued for a PR into the project-native skill root).
 
-**Where it lives.**
-- User skills: `~/.claude/skills/`, `~/.copilot/skills/`, etc. (runtime-specific).
-- Project skills: `<project>/.claude/skills/`, `<project>/.github/skills/`.
-- Frontmatter parser: `parseSkillFrontmatter` (`engine/shared.js`, exported line 14 of
-  `engine/queries.js`).
+This concept is distinct from `agents.<id>.expertise`, which is descriptive agent metadata.
 
-**Backing classes / functions.**
-- Discovery: `engine/queries.js` `collectSkillFiles` line 789, `getSkills` line 891,
-  `getSkillIndex` line 916.
-- Per-runtime roots: adapter `getSkillRoots()` / `getSkillWriteTargets()` (engine/runtimes/).
+**Where it lives.** Runtime adapters own discovery and write targets:
 
-**Existing dashboard.** `dashboard/pages/tools.html` — skill browser.
+- Claude: personal `.claude/skills`, project `.claude/skills`
+- Copilot: personal `.copilot/skills`, project `.github/skills`
+- Codex: personal and project `.agents/skills`
+- Portable discovery: `.agents/skills` is visible across bundled adapters
 
-**Endpoints.**
-- `GET /api/skill` (line 7178) — read a single skill file.
+Adapters may discover additional compatible roots without changing orchestration code.
+
+**Backing symbols.**
 
-**Relationships.** Skill ↔ Runtime adapter (storage paths differ). Skills ↔ Agent prompts
-(skills can be invoked mid-task).
+- Frontmatter parser: `engine/shared.js#parseSkillFrontmatter`
+- Discovery: `engine/queries.js#collectSkillFiles`
+- Dashboard projections: `engine/queries.js#getSkills` and `#getSkillIndex`
+- Extraction: `engine/lifecycle.js#extractSkillsFromOutput`
+- Adapter contract: `getSkillRoots()` and `getSkillWriteTargets()` in
+  `engine/runtimes/{claude,copilot,codex}.js`
+
+**Existing dashboard.** `dashboard/pages/tools.html` contains the skill browser.
+
+**Endpoints.** `GET /api/skill` reads a selected skill; the broader index is included in dashboard
+status data.
+
+**Relationships.** Skills are runtime/harness assets that an Agent can invoke. The runtime adapter
+owns their paths, while Minions lifecycle code owns extraction and project-scope PR dispatch.
 
 ---
 
 ## 19. MCP Server
 
-**What it is.** A Model Context Protocol server the runtime CLI can call. Examples: GitHub MCP,
-Azure DevOps MCP, custom tool servers. Configured per-fleet and per-runtime; agents see them as
-extra tools.
+**What it is.** A Model Context Protocol tool server discovered by the selected CLI runtime. MCP
+configuration is runtime-native; repository/user harness files are not merged into Minions
+`config.json`.
 
 **Where it lives.**
-- Configuration: `config.json` `mcpServers: { … }`.
-- Aggregator: `getMcpServers` in `dashboard.js` line 759 (also re-reads runtime-specific
-  configs at lines 750–787, e.g. `~/.copilot/mcp-config.json`, `~/.claude/mcp-config.json`).
 
-**Backing classes / functions.**
-- Loader: `dashboard.js` line 759 (`getMcpServers`).
-- Engine status integration: `getStatusJson` includes `mcpServers` (line 905).
-- Per-runtime adapter knobs: `engine.copilotDisableBuiltinMcps` (default true) strips the
-  built-in `github-mcp-server` because it would mutate state behind the engine's back.
+- Claude user registrations: `~/.claude.json` (`mcpServers`)
+- Copilot user registrations: `~/.copilot/mcp-config.json`
+- Workspace registrations surfaced by the dashboard: `<project>/.mcp.json`
+- Other runtime-native locations: owned by the corresponding CLI/adapter contract
+
+**Backing symbols.**
 
-**Existing dashboard.** `dashboard/pages/tools.html` — MCP server list with status.
+- Dashboard inventory: `dashboard.js#getMcpServers`
+- Watched config paths: `engine/queries.js` slow-state dependency collector
+- Runtime preparation/discovery: `engine/runtimes/*`
+- Copilot built-in suppression: `engine.copilotDisableBuiltinMcps`
 
-**Endpoints.** Read-only via `/api/status`. There is no dedicated MCP CRUD endpoint —
-configuration is via `/api/settings` (config.json edits).
+The dashboard reads configuration files to inventory registrations; it does not claim live
+connection health. Agent spawning relies on native runtime discovery from the assigned working
+directory rather than copying repository harness configuration into Minions settings.
 
-**Relationships.** MCP ↔ Runtime (Copilot has built-in MCPs that we explicitly disable). MCP ↔
-Skill is unrelated; skills are prompt-level, MCPs are tool-level.
+**Existing dashboard.** `dashboard/pages/tools.html` lists discovered MCP registrations.
+
+**Endpoints.** MCP inventory appears in `/api/status`; there is no dedicated MCP CRUD API.
+
+**Relationships.** MCP servers provide tools. **Skills** provide reusable prompt workflows. Both
+are runtime-visible assets, but they have separate discovery and execution contracts.
 
 ---
 
 ## 20. Engine
 
-**What it is.** The orchestrator daemon. One Node process; runs a 10 s tick that drains the
-**Dispatch Queue**, polls **PRs**, evaluates **Watches** every 3 ticks, runs **Schedules**,
-consolidates the **Inbox**, and so on. It's also the gatekeeper for control state
-(`paused | running | stopping`).
+**What it is.** The orchestration daemon. Its default tick is 10 seconds. Tick phases handle
+timeouts/steering, inbox consolidation, cleanup, watch evaluation, PR polling/reconciliation,
+dispatch, work discovery, snapshots, and diagnostics.
 
 **Where it lives.**
-- Process: `engine.js` (root).
-- State: `engine/state.db` (logs, metrics, queues, watches, schedules, PRDs) plus
-  `engine/control.json` for process coordination.
 
-**Backing classes / functions.**
-- Tick: `engine.js` (top-level `tick()`).
-- Defaults: `engine/shared.js` line 860 (`ENGINE_DEFAULTS`).
-- Concurrency: SQLite transactions for runtime records; file locks only for intentionally
-  file-backed definitions and coordination sidecars.
-- Restart re-attach: PID files in `engine/tmp/pid-<id>.pid` + `live-output.log` mtimes,
-  20-min grace.
+- Process entry: `engine.js`
+- Authoritative runtime state: `engine/state.db`
+- Process coordination: `engine/control.json`, PID/stop-intent files, and bounded sidecars
+
+**Backing symbols.**
+
+- Tick: `engine.js#tick` / `#tickInner`
+- Defaults: `engine/shared.js#ENGINE_DEFAULTS`
+- Watch cadence: `ENGINE_DEFAULTS.watchPollEvery` (18 ticks by default)
+- Cold-process reattachment: `engine/cli.js` startup reattachment path
+- Stale-orphan grace: `engine/timeout.js` with `ENGINE_DEFAULTS.heartbeatTimeout`
+
+Tracked live agents are not killed merely for output silence. Cold agents can be reattached after
+an engine restart through persisted PID/session data and `agents/<id>/live-output.log`; pooled ACP
+leases intentionally follow a different lifecycle.
 
-**Existing dashboard.** `dashboard/pages/engine.html` — engine timeline, log, controls.
+**Existing dashboard.** `dashboard/pages/engine.html` exposes engine state, dispatch history, logs,
+and controls.
 
 **Endpoints.**
-- `POST /api/engine/wakeup` (7406) — set `_wakeupAt` so the tick fires now.
-- `POST /api/engine/restart` (7410) — graceful restart.
-- `GET  /api/status` (6838), `/api/health` (6844), `/api/status-stream` (6839, SSE).
 
-**Relationships.** Engine = the verb. Every other concept on this page is the engine's data.
+- `GET /api/status`
+- `GET /api/status-stream`
+- `GET /api/health`
+- `POST /api/engine/wakeup`
+- `POST /api/engine/restart`
+- PR polling/auto-fix controls under `/api/engine/*`
+
+**Relationships.** Engine is the coordinator over every other concept. SQLite stores durable
+runtime records; files remain for definitions, human documents, caches, artifacts, and process
+coordination.
 
 ---
 
 ## 21. Settings
 
-**What it is.** `config.json`. Holds projects, agents, engine defaults, schedules, features, and
-runtime knobs. Merged with `.claude/settings.local.json` for user-only overrides.
+**What it is.** Minions configuration stored in `config.json`: projects, agents, engine defaults,
+schedules, features, and runtime selection/options.
+
+Repository and user harness settings are not merged into this object. Files such as runtime-native
+MCP/skill configuration remain owned and discovered by the selected CLI.
+
+**Where it lives.**
+
+- Minions settings: `<MINIONS_DIR>/config.json`
+- Routing table: `<MINIONS_DIR>/routing.md` (separate, intentionally file-backed)
+- Runtime-native harness configuration: runtime-owned user/repository paths
+
+**Backing symbols.**
 
-**Where it lives.** `config.json` (root); `.claude/settings.local.json` (gitignored).
+- Loader: `engine/queries.js#getConfig`
+- Defaults: `engine/shared.js#ENGINE_DEFAULTS`
+- Settings handlers: `dashboard.js#handleSettingsRead`, `#handleSettingsUpdate`,
+  `#handleSettingsReset`, and `#handleSettingsRouting`
 
-**Backing classes / functions.**
-- Loader: `engine/queries.js` `getConfig` (around line 86–166, includes migrations like
-  `applyLegacyCcModelMigration`).
-- Defaults: `engine/shared.js` line 860 (`ENGINE_DEFAULTS`).
-- Routing knob: `routing.md` (separate file).
+**Existing dashboard.** `dashboard/pages/settings.html` is the canonical settings surface.
 
-**Existing dashboard.** `dashboard/pages/settings.html` — multi-tab editor for engine, projects,
-agents, runtimes.
+**Endpoints.**
 
-**Endpoints (`dashboard.js`).**
-- Settings reads / writes are via the `/api/settings*` family (search for them in the ROUTES
-  table around 6249–6599 in earlier dashboard.js layouts; the agent-driven version uses the
-  ROUTES registry).
-- `POST /api/settings/reset` — restore defaults.
-- `POST /api/settings/routing` — read `routing.md`.
+- `GET /api/settings`
+- `POST /api/settings`
+- `POST /api/settings/reset`
+- `POST /api/settings/routing`
 
-**Relationships.** Settings is the *write target* for almost every config-changing action in CC
-and the dashboard. Two locations to know about: per-fleet (`engine.*`) and per-agent
-(`agents.<id>.*`). They don't fall through to each other for runtime selection.
+**Relationships.** Fleet defaults live under `engine.*`; agent overrides live under
+`agents.<id>.*`; project behavior lives under `projects[]`. Agent and Command Center runtime/model
+resolution are intentionally independent.
 
 ---
 
 ## 22. Feature Flag
 
-**What it is.** A temporary gate registered in `engine/features.js`. Resolved per request:
-env var (`MINIONS_FEATURE_<UPPER_SNAKE>`) → `config.features[id]` → registry default. Throws if
-asked for an unknown id. The slim UX itself is gated behind `slim-ux`.
+**What it is.** A temporary product/UX gate registered in `engine/features.js`. Resolution order
+is environment override (`MINIONS_FEATURE_<ID>`) -> `config.features[id]` -> registry default.
+Unknown flag IDs fail loudly.
 
-**Where it lives.** `engine/features.js` lines 1–62 (registry + `isFeatureOn`).
+Feature flags are not a substitute for permanent `engine.*` configuration. The `slim-ux` flag gates
+the redesigned dashboard.
 
-**Backing classes / functions.**
-- Registry: `FEATURES` (top of `engine/features.js`).
-- Resolver: `isFeatureOn(id, config)`.
-- Env override: any `MINIONS_FEATURE_*` translates id `slim-ux` ↔ `MINIONS_FEATURE_SLIM_UX`.
+**Where it lives.** `engine/features.js#FEATURES`.
 
-**Existing dashboard.** `dashboard/pages/settings.html` — "Show experimental flags" disclosure.
-Slim UX also has its own minimal flags-only settings dialog (`dashboard/slim.html` line ~445).
+**Backing symbols.**
 
-**Endpoints (`dashboard.js`).**
-- `GET  /api/features` (7457)
-- `POST /api/features/toggle` (7458)
+- Resolver: `engine/features.js#isFeatureOn`
+- Listing: `engine/features.js#listFeatures`
+- Registry check: `engine/features.js#hasFeature`
 
-**Relationships.** Feature flag ↔ everything that gets ramped behind one. When the feature
-ships, *delete the registry entry and the gate* — stale entries past `expires` surface in
-preflight.
+**Existing dashboard.** Settings exposes registered experimental flags and their current values.
+
+**Endpoints.**
+
+- `GET /api/features`
+- `POST /api/features/toggle`
+
+**Relationships.** A flag gates code/UI behavior until rollout is complete. Registry metadata
+includes defaults and expiry dates so stale experiments are visible to operators.
 
 ---
 
 ## 23. Routing (`routing.md`)
 
-**What it is.** A markdown table mapping work types to agents (e.g. `implement → dallas`,
-`review → ripley`, `fix → _author_`). The engine parses it on every tick.
+**What it is.** A global Markdown table mapping work types to preferred and fallback agents. The
+engine reads it through an mtime-based cache during agent resolution.
 
-**Where it lives.** `routing.md` (root).
+**Where it lives.** `<MINIONS_DIR>/routing.md`.
 
-**Backing classes / functions.**
-- Parser: `engine/routing.js` `parseRoutingTable` line 31.
-- Path constant: line 15.
-- Cache: line 59 (`_routingCache`).
-- Re-export: line 301.
+There is no project-local routing override. Project-local **playbook** overrides exist, but routing
+uses the single global `ROUTING_PATH`.
 
-**Existing dashboard.** `dashboard/pages/settings.html` — Routing panel (read-only with an edit
-modal).
+**Backing symbols.**
 
-**Endpoints.**
-- `POST /api/settings/routing` — read `routing.md`.
+- Path and reader: `engine/routing.js#ROUTING_PATH` and `#getRouting`
+- Parser: `engine/routing.js#parseRoutingTable`
+- Cache: `engine/routing.js#getRoutingTableCached`
+- Work-type lookup: `engine/routing.js#routeForWorkType`
+- Final resolution: `engine/routing.js#resolveAgent`
+
+**Existing dashboard.** Settings exposes the routing table editor.
 
-**Relationships.** Routing decides which **Agent** receives which **Work Type**. The CC action
-parser pre-flights routing to surface "no agent available" warnings before enqueue. Per-project
-overrides are possible via `projects/<name>/routing.md`.
+**Endpoints.** `POST /api/settings/routing` updates `routing.md`; `GET /api/settings` includes the
+current routing content.
+
+**Relationships.** Routing supplies preferred/fallback candidates for a Work Item type. Explicit
+hard pins, author routing, availability, budget, retry reassignment, and temporary-agent policy
+still participate in final selection.
 
 ---
 
 ## 24. Charter (Agent Charter)
 
-**What it is.** A short markdown file describing an agent's role, voice, and rules of engagement.
-Loaded into the agent's system prompt at every dispatch.
+**What it is.** A Markdown file describing one Agent's role, voice, expertise boundary, and rules
+of engagement. It is loaded into that Agent's system prompt for each dispatch.
+
+**Where it lives.** `agents/<id>/charter.md`.
+
+**Backing symbols.**
 
-**Where it lives.** `agents/<id>/charter.md`. Examples: `agents/dallas/charter.md`,
-`agents/ripley/charter.md`, …
+- Prompt loading/injection: `engine/playbook.js#buildSystemPrompt`
+- Dashboard detail read: `engine/queries.js#getAgentDetail`
+- Dashboard write handler: the `/api/agents/charter` route in `dashboard.js`
 
-**Backing classes / functions.**
-- Loader: `engine/queries.js` `getAgentCharter` line 505.
-- Injection into prompt: `engine/playbook.js` line 517 (`prompt += '## Your Charter\n\n' +
-  charter`).
+The prompt and detail surfaces each read the charter at their respective system-prompt/detail
+boundaries.
 
-**Existing dashboard.** Agent detail modal on `home.html` shows the charter.
+**Existing dashboard.** Agent detail shows the charter; Settings can edit agent identity metadata.
+
+**Endpoints.**
 
-**Endpoints.** Read-only via `/api/agent-detail/:id` (line 6686).
+- `GET /api/agent/:id` -- detail including charter
+- `POST /api/agents/charter` -- save charter content
 
-**Relationships.** Charter ↔ Agent (1:1). Distinct from Skills (skills are reusable work
-recipes; charter is identity).
+**Relationships.** A Charter is one-to-one with an Agent. It is identity/context, whereas a Skill
+is a reusable executable workflow.
 
 ---
 
 ## 25. Meeting
 
-**What it is.** A multi-agent debate workflow. Three rounds: investigate → debate → conclude.
-Participants are explicitly listed; each round writes a structured findings file before the
-engine advances. The engine times out / advances rounds automatically.
-
-**Where it lives.** `meetings/*.json` (definitions + transcripts). Per-agent artifact notes
-land in `notes/inbox/`.
-
-**Backing classes / functions.**
-- Dirs / status: `engine/meeting.js`
-  - lines 21–24 (`MEETINGS_DIR`, `MEETING_NOTE_ARTIFACT_ROOT`, `TERMINAL_MEETING_STATUSES`,
-    `ROUND_STATUS_BY_NAME`).
-  - line 29 (`ROUND_NUMBER_BY_NAME`).
-- Round bookkeeping: `roundKeyFor` line 40, `getRoundFailures` line 46, `hasRoundFailure`
-  line 59, `hasRoundSuccess` line 63, `hasRoundTerminalOutcome` line 69,
-  `allParticipantsFinishedRound` line 73.
-- Advance / fail handling: `advanceMeetingIfRoundComplete` line 93,
-  `buildFailedMeetingConclusion` line 87.
-- Empty-output detection: `EMPTY_OUTPUT_PATTERNS` line 15, `isEmptyMeetingContent` line 124.
-
-**Existing dashboard.** `dashboard/pages/meetings.html` — meeting browser, round status, notes.
-
-**Endpoints (`dashboard.js`).**
-- `POST /api/meetings` (7322) — create
-- `GET  /api/meetings` (7337)
-- `POST /api/meetings/note` (7349)
-- `POST /api/meetings/advance` (7359)
-- `POST /api/meetings/end` (7369)
-- `POST /api/meetings/archive` (7378)
-- `POST /api/meetings/unarchive` (7387)
-- `POST /api/meetings/delete` (7396)
-
-**Relationships.** Meeting → emits Notes into the inbox. Each meeting round dispatches one Work
-Item per participant. Pipelines may include `meeting` stages.
+**What it is.** A multi-agent debate workflow with three rounds: investigate, debate, and conclude.
+Participants produce round artifacts; the meeting advances when the current round reaches terminal
+outcomes or the operator explicitly intervenes.
 
----
+**Where it lives.**
 
-## Cross-cutting relationship cheatsheet
+- Meeting definitions/state/transcript: `meetings/<id>.json`
+- Participant note artifacts: `notes/inbox/`
 
-```
-Human ──► Command Center ──► [Work Item | Plan | Note | Schedule | Watch | Pinned | Knowledge]
-                              │
-                              └─► Dispatch Queue ──► Dispatch ──► Agent (CLI)
-                                                                   │
-                                                                   ├─► Pull Request (synced from output)
-                                                                   ├─► Completion (JSON report)
-                                                                   └─► Notes Inbox  ──► Consolidation ──► KB / notes.md
-                                                                                                            │
-                                                                                                            └─► Pinned (manual subset)
+**Backing symbols.**
 
-Plan ──► PRD ──► Work Items (depends_on edges) ──► … ──► Verify Work Item ──► Manual Archive
+- Paths/status maps: `engine/meeting.js#MEETINGS_DIR`,
+  `#MEETING_NOTE_ARTIFACT_ROOT`, `#ROUND_STATUS_BY_NAME`, and
+  `#ROUND_NUMBER_BY_NAME`
+- Round outcome helpers: `#getRoundFailures` and `#allParticipantsFinishedRound`
+- Advancement: `#advanceMeetingIfRoundComplete`
+- Empty-output guard: `#EMPTY_OUTPUT_PATTERNS` and `#isEmptyMeetingContent`
 
-Pipeline (stages: task / meeting / plan) ──► spawns Work Items / Meetings / Plans
+**Existing dashboard.** `dashboard/pages/meetings.html` shows meetings, rounds, participant
+artifacts, and controls.
 
-Schedule (cron) ──► spawns Work Items
-Watch (event)   ──► spawns notifications / Work Items / pipeline-continuations
+**Endpoints.**
+
+- `POST /api/meetings`
+- `GET /api/meetings`
+- `POST /api/meetings/note`
+- `POST /api/meetings/advance`
+- `POST /api/meetings/end`
+- `POST /api/meetings/archive`
+- `POST /api/meetings/unarchive`
+- `POST /api/meetings/delete`
+
+**Relationships.** A Meeting dispatches one participant Work Item per round, writes durable Notes,
+and can itself be a Pipeline stage.
+
+---
+
+## Cross-cutting relationship cheatsheet
 
-Engine reads:  routing.md, config.json, definitions, engine/state.db
-Engine writes: control.json, artifacts, engine/state.db
+```
+Human ---> Command Center ---> dashboard /api/* ---> [Work Item | Plan | Note | Schedule | Watch]
+                                                |
+                                                +--> Dispatch Queue ---> Dispatch ---> Agent
+                                                                                       |
+                                                                                       +--> Pull Request
+                                                                                       +--> Completion JSON
+                                                                                       +--> Notes Inbox
+                                                                                                |
+                                                                                                +--> notes.md
+                                                                                                +--> Knowledge Base
+
+Plan Markdown ---> plan-to-prd sidecar ---> SQL PRD + PRD Items ---> Work Items ---> Verify
+
+Pipeline definition ---> SQL pipeline run ---> stages (task / meeting / plan / API / control flow)
+
+Schedule (time) ---> Work Item
+Watch (state)  ---> notification or registered follow-up action
+
+Engine reads:  config.json, routing.md, definitions, human docs, engine/state.db
+Runtime reads: runtime-native harness assets from the assigned working directory
+Engine writes: engine/state.db, control/process sidecars, artifacts, and requested human docs
 ```