@yemi33/minions 0.1.1883 → 0.1.1885

package/README.md

@@ -6,6 +6,8 @@ Zero dependencies — uses only Node.js built-in modules.
 
 Inspired by and initially scaffolded from [Brady Gaster's Squad](https://bradygaster.github.io/squad/).
 
+📚 **Documentation:** see [docs/README.md](docs/README.md) for the full audience-grouped docs index.
+
 ## Prerequisites
 
 - **Node.js** 18+ (LTS recommended)
@@ -40,6 +42,41 @@ git clone https://github.com/yemi33/minions.git ~/.minions
 node ~/.minions/minions.js init
 ```
 
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `minions init` | Bootstrap `~/.minions/` with default agents and config |
+| `minions update` | Update to latest version (npm update + apply) |
+| `minions version` | Show installed vs package version |
+| `minions doctor` | Check prerequisites and runtime health |
+| `minions scan [dir] [depth]` | Scan for git repos and multi-select to add (default: ~, depth 3) |
+| `minions add <dir>` | Link a single project (auto-detects settings from git, prompts to confirm) |
+| `minions remove <dir-or-name> [--keep-data \| --purge --force]` | Unlink a project: cancels pending work items, drains dispatch + kills active agents, cleans worktrees, disables linked schedules, archives `projects/<name>/` to `projects/.archived/<name>-YYYYMMDD/`. Use `--keep-data` to leave the data dir in place, or `--purge --force` to delete it. |
+| `minions list` | List all linked projects with descriptions |
+| `minions restart` | Start engine and dashboard together (recommended after reboot) |
+| `minions start` | Start engine daemon (ticks every 60s, auto-syncs MCP servers) |
+| `minions stop` | Stop the engine |
+| `minions status` | Show agents, projects, dispatch queue, quality metrics |
+| `minions pause` / `resume` | Pause/resume dispatching |
+| `minions dispatch` | Force a dispatch cycle |
+| `minions discover` | Dry-run work discovery |
+| `minions queue` | Show dispatch queue (pending, active, completed) |
+| `minions sources` | Show work source status per project |
+| `minions work <title> [opts]` | Add to central work queue |
+| `minions spawn <agent> <prompt>` | Manually spawn an agent |
+| `minions plan <file\|text> [proj]` | Run a plan |
+| `minions kill` | Kill all active agents and reset their dispatches to pending |
+| `minions complete <dispatch-id>` | Manually mark a dispatch as completed |
+| `minions config set-cli <R> [--model M]` | Persist the default runtime/model without starting the engine |
+| `minions mcp-sync` | Sync MCP servers from `~/.claude.json` |
+| `minions cleanup` | Run cleanup manually (temp files, worktrees, zombies) |
+| `minions dash` | Open dashboard (starts if not already running, port 7331) |
+| `minions nuke --confirm` | Factory reset runtime state and reset config to defaults |
+| `minions uninstall --confirm` | Remove Minions state and uninstall the npm package |
+
+You can also run scripts directly: `node ~/.minions/engine.js start`, `node ~/.minions/dashboard.js`, etc.
+
 ## Upgrading
 
 ```bash
@@ -64,6 +101,8 @@ minions init --force
 
 ## Quick Start
 
+> **New contributor?** Walk through [docs/onboarding.md](docs/onboarding.md) first — an 8-step, first-30-minutes guide from clone → doctor → init → add → dashboard tour → first dispatch → first plan → first PR review, with debugging pointers.
+
 ```bash
 # 1. Init + scan — finds all git repos on your machine, multi-select to add
 minions init
@@ -120,41 +159,6 @@ To give the minions its first task, open the dashboard Command Center and add a
 minions work "Explore the codebase and document the architecture"
 ```
 
-## CLI Reference
-
-| Command | Description |
-|---------|-------------|
-| `minions init` | Bootstrap `~/.minions/` with default agents and config |
-| `minions update` | Update to latest version (npm update + apply) |
-| `minions version` | Show installed vs package version |
-| `minions doctor` | Check prerequisites and runtime health |
-| `minions scan [dir] [depth]` | Scan for git repos and multi-select to add (default: ~, depth 3) |
-| `minions add <dir>` | Link a single project (auto-detects settings from git, prompts to confirm) |
-| `minions remove <dir-or-name> [--keep-data \| --purge --force]` | Unlink a project: cancels pending work items, drains dispatch + kills active agents, cleans worktrees, disables linked schedules, archives `projects/<name>/` to `projects/.archived/<name>-YYYYMMDD/`. Use `--keep-data` to leave the data dir in place, or `--purge --force` to delete it. |
-| `minions list` | List all linked projects with descriptions |
-| `minions restart` | Start engine and dashboard together (recommended after reboot) |
-| `minions start` | Start engine daemon (ticks every 60s, auto-syncs MCP servers) |
-| `minions stop` | Stop the engine |
-| `minions status` | Show agents, projects, dispatch queue, quality metrics |
-| `minions pause` / `resume` | Pause/resume dispatching |
-| `minions dispatch` | Force a dispatch cycle |
-| `minions discover` | Dry-run work discovery |
-| `minions queue` | Show dispatch queue (pending, active, completed) |
-| `minions sources` | Show work source status per project |
-| `minions work <title> [opts]` | Add to central work queue |
-| `minions spawn <agent> <prompt>` | Manually spawn an agent |
-| `minions plan <file\|text> [proj]` | Run a plan |
-| `minions kill` | Kill all active agents and reset their dispatches to pending |
-| `minions complete <dispatch-id>` | Manually mark a dispatch as completed |
-| `minions config set-cli <R> [--model M]` | Persist the default runtime/model without starting the engine |
-| `minions mcp-sync` | Sync MCP servers from `~/.claude.json` |
-| `minions cleanup` | Run cleanup manually (temp files, worktrees, zombies) |
-| `minions dash` | Open dashboard (starts if not already running, port 7331) |
-| `minions nuke --confirm` | Factory reset runtime state and reset config to defaults |
-| `minions uninstall --confirm` | Remove Minions state and uninstall the npm package |
-
-You can also run scripts directly: `node ~/.minions/engine.js start`, `node ~/.minions/dashboard.js`, etc.
-
 ## Architecture
 
 ```
@@ -214,7 +218,7 @@ You can also run scripts directly: `node ~/.minions/engine.js start`, `node ~/.m
 
 - **Auto-discovers work** from plans (`plans/*.json`), pull requests, and work queues across all linked projects
 - **Plan pipeline** — `/plan` spawns a plan agent, chains to plan-to-prd, produces `plans/{project}-{date}.json` with `status: "awaiting-approval"`. Supports shared-branch and parallel strategies.
-- **Human approval gate** — plans require approval before materializing as work items. Dashboard provides Approve / Discuss & Revise / Reject. Discussion launches an interactive Claude Code session.
+- **Human approval gate** — plans require approval before materializing as work items. Dashboard provides Approve / Discuss & Revise / Reject. Discussion launches an interactive Command Center session via the configured runtime CLI (`config.engine.ccCli`).
 - **Dispatches AI agents** (Claude CLI) with full project context, git worktrees, and MCP server access
 - **Routes intelligently** — fixes first, then reviews, then implementation, matched to agent strengths
 - **LLM-powered consolidation** — Claude Haiku summarizes notes (threshold: 5 files). Regex fallback. Source references required.
@@ -649,34 +653,43 @@ To move to a new machine: `npm install -g @yemi33/minions && minions init --forc
     minions.js             <- Unified CLI entry point (npm package)
   minions.js               <- Project management: init, add, remove, list
   engine.js              <- Engine daemon + orchestrator
-  engine/
-    shared.js            <- Shared utilities: IO, process spawning, config helpers
-    queries.js           <- Read-only state queries (used by engine + dashboard)
-    cli.js               <- CLI command handlers (start, stop, status, plan, etc.)
-    lifecycle.js          <- Post-completion hooks, plan chaining, PR sync, metrics
-    consolidation.js     <- Haiku-powered inbox consolidation, knowledge base
-    ado.js               <- ADO token management, PR polling, PR reconciliation
-    llm.js               <- callLLM() with session resume, trackEngineUsage()
-    spawn-agent.js       <- Agent spawn wrapper (resolves claude cli.js)
-    preflight.js         <- Prerequisite checks (Node, Git, Claude CLI, API key)
-    scheduler.js         <- Cron-style scheduled task discovery
-    pipeline.js          <- Multi-stage pipeline orchestration
-    meeting.js           <- Meeting creation, rounds, conclusion
-    cleanup.js           <- Worktree + temp file cleanup
-    timeout.js           <- Agent timeout and orphan detection
-    cooldown.js          <- Dispatch cooldown with exponential backoff
-    github.js            <- GitHub PR polling, comment polling, reconciliation
-    routing.js           <- Agent routing and temp agent management
-    dispatch.js          <- Dispatch queue mutations (add, complete, retry)
-    ado-mcp-wrapper.js   <- ADO MCP authentication wrapper
-    check-status.js      <- Quick status check without full engine load
-    control.json         <- running/paused/stopped (runtime, generated)
-    dispatch.json        <- pending/active/completed queue (runtime, generated)
-    log.json             <- Audit trail, capped at 2500 (runtime, generated)
-    metrics.json         <- Per-agent quality metrics (runtime, generated)
-    cooldowns.json       <- Dispatch cooldown tracking (runtime, generated)
-    schedule-runs.json   <- Last-run timestamps for scheduled tasks (runtime, generated)
-    pipeline-runs.json   <- Pipeline run history per pipeline (runtime, generated)
+  engine/                <- See CLAUDE.md "Key Modules" table for per-file roles
+    # Core orchestration
+    shared.js            queries.js            cli.js
+    lifecycle.js         dispatch.js           cooldown.js
+    timeout.js           steering.js           recovery.js
+    pre-dispatch-eval.js
+    # Discovery, routing, playbooks
+    routing.js           playbook.js           cleanup.js
+    # Knowledge / consolidation
+    consolidation.js     kb-sweep.js
+    # LLM + runtime adapters
+    llm.js               model-discovery.js    spawn-agent.js
+    runtimes/            <- Per-runtime CLI adapters (claude, copilot, etc.)
+    # Lifecycle helpers
+    preflight.js         restart-health.js     scheduler.js
+    pipeline.js          meeting.js
+    # Project + feature management
+    projects.js          project-discovery.js  features.js
+    watches.js           watch-actions.js
+    # Repo-host integrations
+    github.js            issues.js
+    ado.js               ado-token.js          ado-mcp-wrapper.js
+    ado-status.js        check-status.js
+    # Notifications
+    teams.js             teams-cards.js
+    # Runtime state (generated, gitignored)
+    control.json         <- running/paused/stopped
+    dispatch.json        <- pending/active/completed queue
+    log.json             <- audit trail, capped at 2500
+    metrics.json         <- per-agent quality + runtime metrics
+    cooldowns.json       <- dispatch cooldown tracking
+    schedule-runs.json   <- last-run timestamps for scheduled tasks
+    pipeline-runs.json   <- pipeline run history per pipeline
+    watches.json         <- persistent watch jobs
+    completions/         <- per-dispatch agent completion JSON reports
+    <runtime>-caps.json  <- adapter capability cache (claude-caps.json, copilot-caps.json, …)
+    <runtime>-models.json <- adapter model catalog cache
   dashboard.js           <- Web dashboard server
   dashboard/
     layout.html          <- Page layout shell with sidebar navigation
@@ -730,6 +743,7 @@ To move to a new machine: `npm install -g @yemi33/minions && minions init --forc
     inbox/               <- Agent findings drop-box (generated)
     archive/             <- Processed inbox files (generated)
   docs/
+    README.md            <- Docs index (grouped by audience)
     auto-discovery.md    <- Auto-discovery pipeline docs
     self-improvement.md  <- Self-improvement loop docs
     plan-lifecycle.md    <- Full plan pipeline: plan → PRD → implement → verify

package/agents/lambert/charter.md

@@ -39,8 +39,7 @@
 
 ## How I Work
 
-- Read Ripley's exploration findings from `{{team_root}}/notes/inbox/ripley-findings-*.md`
-- Read Dallas's build summary from `{{team_root}}/notes/inbox/dallas-build-*.md`
+- Read recent teammate findings under `{{team_root}}/notes/inbox/` — filenames follow the engine-injected "Write Learnings" contract in each agent's dispatch prompt, so defer to that contract rather than matching ad-hoc filename globs here
 - Cross-reference against all `docs/`, agent `CLAUDE.md` files, and prototype instructions
 - Be exhaustive on missing features — better to over-document than under-document
 - Output the JSON to `{{team_root}}/prd/<plan-slug>.json` (the engine's `materializePlansAsWorkItems()` reads from that directory)

package/agents/ripley/charter.md

@@ -22,7 +22,7 @@
 - Always read `CLAUDE.md` files (root + per-agent) before anything else
 - Map the repo structure: `agents/`, `modules/`, `.devtools/`, `docs/`, `eval/`
 - Look for prototype instructions in: `docs/`, `agents/*/CLAUDE.md`, `README.md`, inline comments
-- Document findings in `notes/inbox/ripley-findings-{timestamp}.md` (relative to squad team root)
+- Document findings in the inbox file the dispatch prompt assigns under "Write Learnings" — that section is the single source of truth for the path and filename; do not re-derive it here
 - Never guess — if something is unclear, note it explicitly for human review
 
 ## Boundaries

package/docs/README.md

@@ -0,0 +1,36 @@
+# Minions Documentation Index
+
+A navigable index of every Markdown file under `docs/`. Entries are grouped by audience.
+
+## User-facing
+
+Hands-on stories and distribution guides for people running or evaluating Minions.
+
+- [blog-first-successful-dispatch.md](blog-first-successful-dispatch.md) — Narrative walkthrough of the first end-to-end agent dispatch and the seven failed spawn attempts that preceded it.
+- [distribution.md](distribution.md) — How Minions is published as the `@yemi33/minions` npm package and what the two-repo (origin / personal) sync strips.
+
+## Contributor-facing
+
+Architecture, design proposals, and lifecycle references for people working on the engine, dashboard, or playbooks.
+
+- [command-center.md](command-center.md) — Command Center (CC) chat panel: persistent Sonnet sessions, `--resume` semantics, system-prompt invalidation, and per-tab session storage.
+- [copilot-cli-schema.md](copilot-cli-schema.md) — Behavior and schema reference for the GitHub Copilot CLI adapter (capability flags, stdin vs `-p`, model discovery, effort levels).
+- [design-state-storage.md](design-state-storage.md) — Design proposal evaluating five database options for replacing Minions' file-based JSON state; recommends `node:sqlite` as the medium-term target.
+- [plan-lifecycle.md](plan-lifecycle.md) — Full plan pipeline from `/plan` through PRD materialization, dispatch with dependency gating, verify task, and human archive.
+- [pr-review-fix-loop.md](pr-review-fix-loop.md) — How the engine moves a PR from creation through review, fix dispatch, and re-review, including stale-status guards.
+- [rfc-completion-json.md](rfc-completion-json.md) — RFC for replacing stdout regex-scraping with a structured `completion.json` control-plane protocol.
+- [self-improvement.md](self-improvement.md) — The six self-improvement mechanisms (learnings inbox, per-agent history, review feedback, quality metrics, etc.) that form Minions' continuous feedback loop.
+
+## Operations
+
+Operational runbooks for engine operators, fleet maintainers, and Teams integrators.
+
+- [auto-discovery.md](auto-discovery.md) — Auto-discovery and execution pipeline: the per-tick orchestration loop and the four work-discovery sources.
+- [engine-restart.md](engine-restart.md) — How agents survive an engine restart: state persistence, the 20-minute startup grace period, and orphan reattachment via PID files and `live-output.log`.
+- [human-vs-automated.md](human-vs-automated.md) — Quick reference table of which features humans start, run, decide, and recover, and the two human approval gates.
+- [teams-production.md](teams-production.md) — Three deployment options (Azure App Service, Container Apps, self-hosted VM) for migrating the Teams bot from a Dev Tunnel to a stable HTTPS endpoint.
+- [teams-setup.md](teams-setup.md) — End-to-end guide for connecting Minions to Microsoft Teams via Azure Bot Framework and a Dev Tunnel.
+
+---
+
+**Adding a new doc?** Drop the file in `docs/` and add a one-line entry above under the right audience group. Keep entries alphabetical within each group.

package/docs/{distribution.md → archive/distribution.md}

@@ -1,5 +1,7 @@
 # Distribution & Publishing
 
+> **ARCHIVED 2026-05-12.** This document describes a defunct two-repo "personal vs. origin" architecture (`yemishin_microsoft/minions` → `yemi33/minions`) and a manual `/sync-to-personal` workflow that no longer exists. The current model is single-repo: `yemi33/minions` publishes itself to npm via `.github/workflows/publish.yml` on every push to `master`. The doc also incorrectly claims package contents are gated by a `files` field in `package.json` — they are actually gated by `.npmignore`. Kept for historical reference; do not follow these steps.
+
 Minions is distributed as an npm package (`@yemi33/minions`) from a sanitized copy of the main repo.
 
 ## Two-Repo Architecture

package/docs/auto-discovery.md

@@ -1,5 +1,7 @@
 # Auto-Discovery & Execution Pipeline
 
+> Last verified: 2026-05-12 against `engine.js` `tickInner()` (lines 4439-4750).
+
 How the minions engine finds work and dispatches agents automatically.
 
 ## The Tick Loop
@@ -8,16 +10,27 @@ The engine runs a tick every 60 seconds (configurable via `config.json` → `eng
 
 ```
 tick()
-  1. checkTimeouts()            Enforce runtime limits and stale-orphan cleanup
-  2. consolidateInbox()         Merge learnings into notes.md (Haiku-powered)
-  2.5 runCleanup()              Periodic cleanup (every 10 ticks ≈ 10min)
-  2.6 pollPrStatus()            Poll ADO + GitHub for build, review, merge status (wall-clock cadence from prPollStatusEvery × tickInterval, default ≈ 12min)
-  2.7 pollPrHumanComments()     Poll PR threads for human @minions comments (wall-clock cadence from prPollCommentsEvery × tickInterval, default ≈ 12min)
-  3. discoverWork()             Scan ALL linked projects for new tasks
-  4. updateSnapshot()           Write identity/now.md
-  5. dispatch                   Spawn agents for pending items (up to maxConcurrent)
+  1.  checkTimeouts()            Enforce runtime limits and stale-orphan cleanup
+  1a. checkSteering()            Drain steering messages queued by the dashboard
+  1b. checkIdleThreshold()       Notify on excessive agent idleness
+  1c. meetingTimeouts()          Advance round-based meetings whose timer fired
+  2.  consolidateInbox()         Merge learnings into notes.md (Haiku-powered)
+  2.5 runCleanup()               Periodic cleanup (every 10 ticks ≈ 10min)
+  2.55 checkWatches()            Persistent watch jobs (every 3 tick-equivalents)
+  2.6 pollPrStatus()             Poll ADO + GitHub for build, review, merge status (wall-clock cadence from prPollStatusEvery × tickInterval, default ≈ 12min)
+       processPendingRebases()   Run any rebase work queued from the previous tick
+       syncPrdFromPrs()          Backfill PRD item status from active PRs
+       checkPlanCompletion()     Mark plans completed when all features done/in-pr
+  2.7 pollPrHumanComments()      Poll PR threads for human @minions comments (wall-clock cadence from prPollCommentsEvery × tickInterval, default ≈ 12min)
+       reconcilePrs() (ADO+GH)   Reconciliation sweep (runs regardless of poll flags)
+  2.9 stallRecovery()            Auto-retry failed items blocking pending deps (every 20 ticks)
+  3.  discoverWork()             Scan ALL linked projects for new tasks
+  4.  updateSnapshot()           Write identity/now.md
+  5.  dispatch                   Spawn agents for pending items (up to maxConcurrent)
 ```
 
+> When `control.state === 'stopping'`, only steps 1–1c run; discovery and dispatch are skipped while live agents drain.
+
 ## Work Discovery
 
 `discoverWork()` iterates every project in `config.projects[]` and runs four core discovery sources: pull requests, per-project work items, central work items, and pipeline/scheduled tasks. Results are prioritized: fixes > reviews > implements > work-items.

package/docs/command-center.md

@@ -1,159 +1,7 @@
 # Command Center
 
-The Command Center (CC) is the minions's conversational AI brain. It powers the dashboard's chat panel, document editing modals, and plan steering — all through a single persistent Sonnet session with full minions awareness.
+The Command Center (CC) is the dashboard's conversational chat panel. It opens from the **CC** button in the top-right header and lets you drive the engine — dispatching work items, saving notes, approving plans, and asking questions about minions state — through a persistent Claude/Copilot session with full repo awareness.
 
-## Access
+CC is intentionally a thin wrapper around the runtime CLI: state changes happen via `Bash`-tool `curl` calls to the dashboard's own REST API, not via parsed delimiter blocks. The end-to-end flow is `dashboard/js/command-center.js` `_ccDoSend()` → `POST /api/command-center` (or `/api/command-center/stream`) in `dashboard.js` (`handleCommandCenter`) → `engine/llm.js` `callLLM({ direct: true })` → claude/copilot CLI session persisted in `engine/cc-sessions.json`. Per-turn API mutations are correlated via the `X-CC-Turn-Id` header and surfaced as standalone `role='action'` chips rendered outside the assistant bubble (`_ccActionResultLine` + `addMsg('action', ...)`).
 
-Click the **CC** button in the top-right header of the dashboard. A slide-out chat drawer opens on the right side.
-
-## Persistent Sessions
-
-CC maintains a true multi-turn session using Claude CLI's `--resume` flag. Unlike a typical stateless API call, each message resumes the same conversation — Claude retains full history including tool calls, intermediate reasoning, and file contents from prior turns.
-
-**Session lifecycle:**
-- **Created** on first message (or after the system prompt changes, or when you click **New Session**)
-- **Resumed** on subsequent messages via `--resume <sessionId>`
-- **Invalidated** only when the CC system prompt changes — detected by hashing `CC_STATIC_SYSTEM_PROMPT` into `_ccPromptHash` and comparing on each call. CC chat sessions do **not** auto-expire by TTL or turn count; `ENGINE_DEFAULTS.ccMaxTurns` (default 50) is a per-call tool-use cap inside the Claude CLI, not a session lifetime cap.
-- **Persisted** to `engine/cc-session.json` (legacy global session) and `engine/cc-sessions.json` (per-tab sessions) — both survive dashboard restarts and engine cleanup ticks
-- **Frontend messages** saved to `localStorage` — survive page refresh
-- **Removed** only when the user explicitly closes a tab via the **×** button on the tab strip — that fires `DELETE /api/cc-sessions/:id` to evict the persisted session
-
-Click **New Session** in the drawer header to start fresh; click the **×** on a tab to remove it permanently.
-
-### Fresh State Each Turn
-
-The system prompt is baked into the session at creation (persona, rules, action format, tool access). Dynamic minions state is injected as a preamble in each user message, so CC always sees current data even in a resumed session.
-
-```
-Turn 1: system prompt (static) + [Current Minions State] + user message
-Turn 2+: [Updated Minions State] + user message  (system prompt already in session)
-```
-
-## What It Knows
-
-Full minions context is injected every turn:
-
-| Context | Details |
-|---------|---------|
-| Agents | Statuses, current tasks, full charters (expertise/roles) |
-| Routing | Who's preferred/fallback for each work type |
-| Config | Tick interval, max concurrent, timeouts, max turns |
-| Work items | Active, pending, failed across all projects with failure reasons |
-| Pull requests | Status, review status, build status, branch, URL |
-| Plans | Full `.md` plan contents + PRD JSON summaries + archived plans |
-| PRD items | All items with status, priority, dependencies |
-| Dispatch | Active agents + last 15 completions with result summaries |
-| Skills | All reusable agent workflows with triggers |
-| Knowledge base | Recent entries (architecture, conventions, build reports, reviews) |
-| Team notes | Recent consolidated notes |
-
-## Tool Access
-
-CC can use tools to look beyond the pre-loaded context:
-
-- **Bash** — Run shell commands (git, build tools, scripts)
-- **Read** — Open any file (agent output logs, code, config, plans)
-- **Write** — Create or overwrite files
-- **Edit** — Make targeted edits to existing files
-- **Glob** — Find files by pattern (e.g., `agents/*/output.log`)
-- **Grep** — Search file contents (find functions, search agent outputs)
-- **WebFetch/WebSearch** — Look up external resources
-
-## Unified Brain
-
-All LLM-powered features in the dashboard route through the same CC session:
-
-| Feature | Endpoint | How It Works |
-|---------|----------|-------------|
-| **CC chat panel** | `POST /api/command-center` | Direct CC interaction |
-| **Doc chat modal** | `POST /api/doc-chat` | Routes through CC via `ccDocCall()` |
-| **Doc steer** | `POST /api/steer-document` | Routes through CC via `ccDocCall()` |
-| **Plan revision** | `POST /api/plans/revise` | Routes through CC via `ccDocCall()` |
-
-This means:
-- A question in the doc chat modal shares context with the CC panel
-- CC remembers what you discussed in a document editing session
-- Doc modals can cross-reference other minions knowledge, PRs, work items
-- All turns accumulate in the same session
-
-## Actions
-
-When you ask CC to *do* something, it includes structured action blocks in its response.
-
-| Action | What It Does | Example Prompt |
-|--------|-------------|----------------|
-| `dispatch` | Create a work item | "Have dallas fix the login bug" |
-| `note` | Save a decision/reminder | "Remember we need to migrate to v3" |
-| `plan` | Create an implementation plan | "Plan the GitHub integration feature" |
-| `cancel` | Stop a running agent | "Cancel whatever ripley is doing" |
-| `retry` | Retry failed work items | "Retry the three failed tasks" |
-| `pause-plan` | Pause a PRD | "Pause the officeagent PRD" |
-| `approve-plan` | Approve a PRD | "Approve the new plan" |
-| `edit-prd-item` | Edit a PRD item | "Change P003's priority to high" |
-| `remove-prd-item` | Remove a PRD item | "Remove P011 from the plan" |
-| `delete-work-item` | Delete a work item | "Delete work item W025" |
-
-For endpoints without a named action, CC may emit a local API fallback action with `endpoint`, `method`, and `params`. The server only invokes safe local `/api/...` paths, validates the requested method against the route index when available, sends GET params as query strings, and rejects streaming/recursive CC/doc-chat endpoints.
-
-## Error Handling
-
-- **Frontend timeout**: 10-minute `AbortSignal` on the fetch — prevents infinite "thinking" spinner
-- **Backend timeout**: 5-minute kill timer on the claude process
-- **Resume failure**: If `--resume` fails (corrupted/deleted session), automatically retries with a fresh session
-- **Concurrency guard**: Only one CC call at a time — concurrent requests get a 429 "CC is busy" response
-- **Phase indicators**: Thinking indicator shows progressive phases ("Thinking..." → "Analyzing..." → "Timing out soon...")
-
-## Architecture
-
-```
-User message (CC panel, doc modal, or steer)
-    │
-    ▼
-POST /api/command-center  (or /api/doc-chat, /api/steer-document)
-    │
-    ├── Validate session (prompt-hash check — invalidate if `_ccPromptHash` drifted)
-    ├── Build dynamic state preamble (buildCCStatePreamble)
-    ├── callLLM() with sessionId (resume) or without (new)
-    │     model: sonnet
-    │     maxTurns: 25 (CC) or 10 (doc-plan) or 1 (doc-other)
-    │     allowedTools: Bash, Read, Write, Edit, Glob, Grep, WebFetch, WebSearch
-    │     timeout: 600s (CC) or 300s (doc-plan) or 60s (doc-other)
-    │
-    ▼
-engine/llm.js callLLM({ direct: true })  (bypasses engine/spawn-agent.js — CC + doc-chat only)
-    │
-    ├── Resolves claude CLI binary path from engine/claude-caps.json
-    ├── If --resume: pass -p --resume <id> (no system prompt file)
-    ├── If new: pass -p --system-prompt-file <file>
-    │
-    ▼
-claude CLI (persistent session on disk)
-    │
-    ▼
-Parse response
-    ├── Extract sessionId from stream-json result
-    ├── Extract ===ACTIONS=== block (CC)
-    ├── Extract ---DOCUMENT--- block (doc chat/steer)
-    ├── Update cc-session.json
-    │
-    ▼
-Frontend
-    ├── Render chat message
-    ├── Execute actions / apply doc edits
-    ├── Save sessionId + messages to localStorage
-```
-
-## Key Files
-
-| File | Role |
-|------|------|
-| `engine/llm.js` | `callLLM()` / `callLLMStreaming()` — single LLM function with optional `sessionId` for resume; `direct: true` spawns claude CLI directly (used by CC + doc-chat) |
-| `engine/spawn-agent.js` | Agent dispatch wrapper — resolves claude CLI path and invokes it. **Not used by CC/doc-chat** (direct spawn path). |
-| `engine/shared.js` | `parseStreamJsonOutput()` extracts `sessionId` from result |
-| `engine/cc-session.json` | Persisted session state (sessionId, turnCount, timestamps) |
-| `dashboard.js` | CC endpoint, `buildCCStatePreamble()`, `ccDocCall()`, `parseCCActions()` |
-| `dashboard/js/` | Frontend: localStorage persistence, session indicator, New Session button |
-
-## Command Bar
-
-The command bar at the top of the dashboard routes all input to the CC panel. Typing in the command bar opens the CC drawer and sends the message as a CC turn.
+For canonical detail (system prompt, session lifecycle, turn-ID surfacing pipeline, doc-chat integration, and CC API contract), read [`CLAUDE.md`](../CLAUDE.md) — see the **CC API Contract** and **Sessions** sections — and the source in [`dashboard/js/command-center.js`](../dashboard/js/command-center.js), [`dashboard.js`](../dashboard.js) (`handleCommandCenter`), and [`prompts/cc-system.md`](../prompts/cc-system.md). This pointer file exists so the docs index has an entry for "Command Center"; the implementation details are deliberately not duplicated here because they drift.