@voybio/ace-swarm 2.4.4 → 2.4.6

package/README.md

@@ -4,9 +4,9 @@ Autonomous Coding Entity (ACE) is a local MCP server and CLI for agent-assisted
 
 `ace-swarm` provides Claude Code, Codex, Cursor, GitHub Copilot CLI, VS Code, and provider-backed workflows with a shared runtime: durable workspace state, typed handoffs, scheduler support, change intelligence, and operator tooling. All state lives in a single binary file — `agent-state/ace-state.ace` — with `.agents/ACE/ace-state.ace` kept only as a legacy fallback for older workspaces.
 
-Modern coding agents can already read files, write code, run commands, and call tools. The missing layer is coordination that survives restarts, model switches, and multi-agent work. ACE keeps the workflow in the store and projects only the files external clients still need. For provider-backed runs, ACE provides task context, tool surfaces, status events, evidence trails, and resumable state.
+Modern coding agents can already read files, write code, run commands, and call tools. The missing layer is coordination that survives restarts, model switches, and multi-agent work. ACE keeps the workflow in the store and projects only the files external clients still need. For provider-backed runs, ACE supplies task context, tool surfaces, status events, evidence trails, and resumable state.
 
-The full MCP surface spans **~70 registered tools** across 12 domain modules — handoffs, scheduler, file ops, drift detection, git, memory, discovery, skills, lifecycle events, vericify, tracker, and framework orchestration — plus resources and prompts.
+The full MCP surface spans **119 registered tools** across 13 domain modules — handoffs, scheduler, goals, file ops, drift detection, git, memory, discovery, skills, lifecycle events, vericify, tracker, and framework orchestration — plus resources and prompts. For premium hosts (Claude Code, Codex) a curated **`ace mcp --profile host-min`** exposes 22 high-value tools; the rest remain reachable via `run_orchestrator` delegation or `--profile full`. See the [MCP Tool Reference](docs/mcp-tool-reference.md) for the full catalog.
 
 ## ACE Manifesto
 
@@ -22,12 +22,12 @@ The full MCP surface spans **~70 registered tools** across 12 domain modules —
 ACE provides model providers with the context they cannot infer on their own: task state, tool surfaces, status events, evidence trails, and the next move in the loop.
 
 - `ace init --llm <provider>` records the selected runtime profile in the store.
-- `ace connect` records an explicit runtime profile from a user-chosen local runtime endpoint or hosted provider without inventing a local model preset.
-- `ace doctor` validates local or hosted runtime wiring, checks the selected model when the provider exposes listings, and keeps the runtime honest.
+- `ace connect` records an explicit runtime profile from a user-chosen local runtime endpoint or hosted provider.
+- `ace doctor` validates local or hosted runtime wiring and checks the selected model when the provider exposes listings.
 - `ace doctor --scan` probes common Ollama and llama.cpp endpoints and writes the selected profile back into the store.
 - `ace tui` is provider-aware for `ollama`, `llama.cpp`, `codex`, `claude`, `gemini`, and `copilot` when credentials or base URLs are configured.
 - `ace mcp` and `ace tui` expose the same workspace truth to the host, the terminal, and the model.
-- `ace mcp-shadow --tools <csv>` starts a filtered stdio server that exposes only the listed tools — used internally by the Hermes bridge so the local model sees a scoped, safe subset of the surface.
+- `ace mcp-shadow --tools <csv>` starts a filtered stdio server that exposes only the listed tools — used by the Hermes bridge so a local model sees a scoped, safe subset of the surface.
 
 ## Why This Exists Now
 
@@ -38,66 +38,29 @@ Frontier models are getting more capable and more restricted at the same time. P
 - Ollama and llama.cpp keep local runtimes in play.
 - MCP remains the common protocol surface across clients and runtimes.
 
-ACE sits underneath that stack. It does not compete with the host you already use. It provides that host with a durable local runtime.
-
-ACE also provides scheduler primitives for queued work, dependency gates, leases, and resource locks so multi-agent runs stay coordinated.
+ACE sits underneath that stack. It does not compete with the host you already use — it provides that host with a durable local runtime, plus scheduler primitives for queued work, dependency gates, leases, and resource locks so multi-agent runs stay coordinated.
 
 ## ACEPACK State Model
 
-ACE uses a custom binary format called ACEPACK to present `agent-state/ace-state.ace` as a structured single-file store. Existing workspaces that still carry `.agents/ACE/ace-state.ace` are read through the legacy fallback path. The file has three regions:
-
-```
-ace-state.ace
-├── Header (128 bytes)
-│     magic · version · flags
-│     kv_index_offset · kv_index_length · kv_chunk_end
-│     evt_offset · evt_length · evt_count · evt_base_id
-├── KV Chunk Region  (append-only, random-access)
-│     knowledge/agents/{name}/{file}  →  agent instruction text
-│     knowledge/skills/{name}/{file}  →  skill content
-│     topology/{kind}                 →  swarm registry, route tables
-│     state/{...}                     →  handoffs, todo, ledger, scheduler
-│     meta/{...}                      →  schema version, project name
-│     Each chunk: [uint32 length][bytes]
-└── Columnar Event Section  (rewritten on commit)
-      uint32    event count
-      int64[N]  timestamps      (epoch ms, big-endian)
-      uint8[N]  kinds           (EntityKind enum)
-      uint8[N]  sources         (ContentSource enum)
-      uint8[N]  flags           (0x01 = deleted)
-      uint32[N] payload offsets (→ payload pool)
-      uint32[N] payload lengths
-      uint32    pool length
-      bytes[M]  payload pool    (UTF-8 JSON blobs)
-```
-
-### KV region — random-access blob cache
-
-All persistent state — agent instructions, skills, topology, task indexes, scheduler queues — lives in the KV region. Each key maps to an immutable chunk appended at write time. `commit()` rewrites the KV index (a small JSON map at the file tail) to reflect the live keys. `compact()` rewrites the KV region to remove dead space from overwritten keys, atomically via tmp-rename.
-
-Write cost: O(1) append + O(index_size) index rewrite.
-Read cost: O(1) seek + O(chunk_length) read.
-
-### Columnar event section — typed handoff log
+Most agent frameworks scatter runtime state across dozens of generated files — status logs, handoff records, todo lists, indexes — that drift apart and get re-parsed on every read. ACEPACK closes that gap: it is a custom binary format that presents all workspace state as one structured, single-file store at `agent-state/ace-state.ace`.
 
-Every `appendEntry()` call — handoffs, status events, ledger entries, session events — lands in an in-memory buffer and is flushed to the columnar section on `commit()`. The columnar layout stores fixed-width fields (timestamp, kind, source, flags) separately from payloads. This means:
+- A **random-access KV region** holds agent instructions, skills, topology, task indexes, and scheduler queues as append-only chunks.
+- A **columnar event section** stores the typed handoff and status log so time/kind scans read a few bytes per event instead of parsing full JSON.
+- **Store-backed projections** mean external tools read the same truth through a single authority instead of divergent files.
 
-- Scanning "all handoffs in the last hour" reads only `timestamps[]` + `kinds[]` — 9 bytes per event, never touching the payload pool.
-- Per-event overhead is ~19 bytes fixed vs ~150 bytes for equivalent JSON.
-- At 100,000 events, the fixed columns are ~1.9 MB; a full JSON log would be ~15 MB.
+The result is one coherent source of truth that survives restarts, compacts to reclaim space, and keeps a full replayable event history. For the on-disk byte layout, KV mechanics, and columnar details, see the [ACEPACK State Model reference](docs/state-model.md).
 
-Events accumulate for the workspace lifetime and survive `compact()`. Full historical replay is always available.
+### Reading hidden state
 
-### Why one state file
+Generated state is store-only by default — the workspace stays clean and agents read
+through MCP tools. Humans stay in the loop through the CLI:
 
-| One `.ace` authority | What it avoids |
-|---|---|
-| Single append-only file | Hundreds of generated state files drifting apart |
-| KV region with typed keys | Hand-rolled file sprawl for runtime state, instructions, indexes |
-| Columnar event log | Repeated full-JSON parsing for timestamp and kind scanning |
-| Store-backed projections | External tools reading the same truth through different paths |
+    ace ls agent-state              # list hidden artifacts by logical path
+    ace read agent-state/kanban.json
+    ace read agent-state/STORE_AUTHORITY_AUDIT.md --out /tmp/audit.md
 
-The store holds runtime state, agent instructions, skills, topology, schemas, and the complete event history. Materialized files exist only when an external client still needs a path on disk.
+`ace read` is exact-length by construction: it returns the complete stored block or
+fails loudly — never a truncated or delimiter-clipped view.
 
 ## Quick Start
 
@@ -108,6 +71,8 @@ npx -y @voybio/ace-swarm turnkey --project "My Project"
 ace mcp
 ```
 
+The bare `ace` commands throughout the docs assume a global install (`npm install -g @voybio/ace-swarm`); without one, prefix each with `npx -y @voybio/ace-swarm`.
+
 Then, in your MCP host:
 
 ```text
@@ -117,10 +82,10 @@ initiate ACE
 Local-model path with Ollama:
 
 ```bash
-npx -y @voybio/ace-swarm turnkey --project "My Project" --llm ollama --model llama3.1:8b --base-url http://localhost:11434
+npx -y @voybio/ace-swarm turnkey --project "My Project" --llm ollama --model qwen3:8b --base-url http://localhost:11434
 ollama serve
-ollama pull llama3.1:8b
-ace doctor --llm ollama --model llama3.1:8b --base-url http://localhost:11434
+ollama pull qwen3:8b
+ace doctor --llm ollama --model qwen3:8b --base-url http://localhost:11434
 ace mcp
 ```
 
@@ -133,20 +98,6 @@ ace doctor --llm llama.cpp --model local-model --base-url http://localhost:8080
 ace mcp
 ```
 
-Optional local-model path with the Hermes execution engine:
-
-```bash
-ace init --project "My Project" --llm llama.cpp --base-url http://localhost:8080
-llama-server -m /path/to/model.gguf --port 8080
-ace doctor --scan          # auto-detect endpoint and model
-ACE_HERMES_ROOT=/path/to/hermes-agent HERMES_PYTHON=/path/to/python \
-  ace doctor --llm llama.cpp --base-url http://127.0.0.1:8080/v1 --model <model> --hermes
-ACE_HERMES_ROOT=/path/to/hermes-agent HERMES_PYTHON=/path/to/python \
-  ace tui --provider llama.cpp --base-url http://127.0.0.1:8080/v1 --model <model> --hermes
-```
-
-If you already have a local runtime running, `ace doctor --scan` will probe common Ollama and llama.cpp endpoints and write the selected profile back into the store.
-
 Hosted provider path with Codex:
 
 ```bash
@@ -156,6 +107,8 @@ ace doctor --llm codex --model gpt-5
 ace mcp
 ```
 
+If you already have a local runtime running, `ace doctor --scan` will probe common Ollama and llama.cpp endpoints and write the selected profile back into the store. For the optional Hermes engine path, see [Local Models & Hermes](#local-models--hermes) and the [Hermes reference](docs/hermes.md). The full command list lives in the [CLI Reference](docs/cli-reference.md).
+
 ## What Bootstrap Writes
 
 ACE bootstrap is intentionally contained. The store is authoritative at `agent-state/ace-state.ace`; only a few host-facing files land in the workspace when requested.
@@ -183,7 +136,7 @@ Developer or MCP host
   │       ├── ace-state.ace              (ACEPACK binary store)
   │       └── STATUS.md / kanban.html / HANDOFF.json projections
   │
-  ├── ace mcp                            (full surface, ~70 tools)
+  ├── ace mcp [--profile host-min|full]  (full surface 119 tools; host-min 22)
   │       │
   │       ├── tools, prompts, resources
   │       ├── typed handoff validation
@@ -215,20 +168,27 @@ Developer or MCP host
 +----------------------+--------------------------------------------------------------+
 | Runtime roles        | ACE-Orchestrator, Coders, QA, Spec, Docs, Research, Ops,     |
 |                      | Security, Memory, Release, Eval, Skeptic, astgrep, Builder   |
-| MCP server           | ~70 tools across 12 domain modules (stdio transport)          |
+| MCP server           | 119 tools across 13 domain modules (stdio); host-min         |
+|                      | profile exposes 22 curated tools                             |
 | Durable state        | Single `agent-state/ace-state.ace` authority for handoffs,   |
-|                      | status events, todos, run ledger, job queue, and discovery    |
-| Projections          | Hook context, todo surface, and host config bundles           |
-| Coordination         | Scheduler queues, dependency gates, leases, resource locks    |
-| Change intelligence  | Delta scan, semantic snapshots, drift reports, rewrite hints  |
-| Structural editing   | ast-grep query, locate, rewrite, compile, patch               |
-| Hermes bridge        | Optional, user-supplied subprocess engine selected only with  |
-|                      | `--hermes`; scoped shadow MCP tools, evidence tracking        |
-| Terminal UI          | Provider-aware TUI with chat, tabs, telemetry, and agent UI   |
-| Local models         | Ollama and llama.cpp bootstrap, doctor checks, and bridges    |
-| Tracker integration  | GitHub Issues, Linear adapter layer with snapshot cache       |
-| Vericify             | Test evidence log, process post trail (incl. blocker routing), bridge snapshot |
-| Skills               | Packaged skills with catalog, audit, and triage               |
+|                      | status events, todos, run ledger, job queue, and discovery   |
+| Projections          | Hook context, todo surface, and host config bundles          |
+| Coordination         | Scheduler queues, dependency gates, leases, resource locks,  |
+|                      | in-process job worker, heartbeat watchdog, circuit breakers  |
+| Goal engine          | `ace goal` self-paced objective loop with evidence-gated     |
+|                      | completion, tick/replan budgets, and operator stop           |
+| Change intelligence  | Delta scan, semantic snapshots, drift reports, rewrite hints |
+| Structural editing   | ast-grep query, locate, rewrite, compile, patch              |
+| Hermes bridge        | Optional, user-supplied subprocess engine selected only with |
+|                      | `--hermes`; scoped shadow MCP tools, evidence tracking       |
+| Terminal UI          | Provider-aware TUI with chat, tabs, telemetry, and agent UI  |
+| Local models         | Ollama and llama.cpp bootstrap, doctor checks, and bridges   |
+| Tracker integration  | GitHub Issues, Linear adapter layer with snapshot cache      |
+| Vericify             | Test evidence log, process post trail (incl. blocker         |
+|                      | routing), bridge snapshot                                    |
+| Skills               | Packaged skills with catalog, audit, and triage              |
+| Experience playbook  | Evidence-gated lessons store (experimental, injection off by |
+|                      | default; `ace playbook` / `ace eval --adapt`)                |
 +----------------------+--------------------------------------------------------------+
 ```
 
@@ -243,360 +203,28 @@ ACE is for teams and solo operators who already like their coding host and want
 
 In that setup, the host remains the interface. ACE becomes the state contract underneath it.
 
-## Local Models & Hermes Companion Engine
-
-Local models are good at generating text. They usually need help seeing the workspace, hearing the handoff trail, and remembering what changed two turns ago. ACE closes that gap.
-
-### What Hermes is
-
-Hermes is an optional, user-supplied companion execution substrate. ACE does not install Hermes, clone it, or make it a package dependency. When the operator explicitly passes `--hermes` or `--engine hermes_local`, Hermes handles local provider quirks, streaming delivery, and robust tool-call framing. The local model provider is still Ollama or llama.cpp. ACE remains the system of record — state, evidence, verification, scheduler — and exports a **scoped shadow MCP tool surface** to Hermes so the local model only sees the tools it needs for a given task scope.
-
-```
-ACE TUI  (ace tui --hermes / --engine hermes_local)
-        │  user input → ChatSession.sendMessage();
-        │  ACE owns session identity, policy, state
-        ▼
-runLocalModelTask()                    ← src/local-model-runtime.ts
-        │  ACE dispatches, ACE controls the turn
-        ▼
-HermesSubprocessExecutor               ← Node.js class, src/hermes/session-manager.ts
-        │  spawns Python worker; ACE controls lifecycle
-        ├── writes hermesHome/config.yaml (provider, model, user-supplied Hermes path, shadow MCP entry)
-        ├── pipes ace mcp-shadow --tools <csv>  ← scoped tools-only shadow server (stdio)
-        │         (ACE-owned; local model sees only allowed tools, not public prompts/resources)
-        ▼
-hermes_bridge_worker.py                ← Python subprocess
-        │  reads config.yaml; calls shadow MCP & local model
-        ├── streams framed NDJSON events → HermesBridgeFrameDecoder
-        └── calls local model (ollama / llama.cpp)
-        │
-        ▼  bridge frames validated and applied by ACE
-ACE store (ace-state.ace)              ← authoritative output; ACE-owned
-        evidence, continuity, run ledger persisted here
-```
-
-### Bridge protocol
-
-The Node ↔ Hermes channel is a strictly typed newline-delimited JSON frame stream. Each frame carries a `type` field:
-
-| Frame type | Direction | Purpose |
-|---|---|---|
-| `session_open` | N→H | start session with config |
-| `turn_run` | N→H | submit a task turn |
-| `interrupt` | N→H | cancel in-flight turn |
-| `session_close` | N→H | shut down the worker |
-| `status` | H→N | heartbeat / progress |
-| `delta` | H→N | streaming token chunk |
-| `reasoning` | H→N | chain-of-thought (optional) |
-| `assistant_interim` | H→N | partial assistant message |
-| `tool_start` | H→N | tool call initiated |
-| `tool_progress` | H→N | tool call in flight |
-| `tool_complete` | H→N | tool call result |
-| `final` | H→N | complete assistant response |
-| `error` | H→N | fatal bridge error |
+For hosted Codex, Claude, Gemini, and Copilot backends, use the [hosted provider quick setup](docs/provider-security.md#hosted-provider-quick-setup) to configure credentials, endpoints, current default models, and a provider-specific doctor preflight.
 
-Frame decoding is handled by `HermesBridgeFrameDecoder` in `src/hermes/bridge-protocol.ts`. The decoder strips control bytes, sanitizes the line, and validates against the event schema before handing frames to the session manager.
+## Local Models & Hermes
 
-### Running with Hermes
+Local models are good at generating text. They usually need help seeing the workspace, hearing the handoff trail, and remembering what changed two turns ago. ACE closes that gap by giving any OpenAI-compatible local runtime — Ollama or llama.cpp — the same shared context, tool surfaces, evidence trails, and resumable state that hosted providers get. The direct provider path works out of the box; no extra runtime is required.
 
-```bash
-# User owns Hermes/Python setup. ACE only discovers and launches it when asked.
-ACE_HERMES_ROOT=/path/to/hermes-agent \
-HERMES_PYTHON=/path/to/python \
-ace doctor --llm llama.cpp --base-url http://127.0.0.1:8080/v1 --model <model> --hermes
-
-ACE_HERMES_ROOT=/path/to/hermes-agent \
-HERMES_PYTHON=/path/to/python \
-ace tui --provider llama.cpp --base-url http://127.0.0.1:8080/v1 --model <model> --hermes
-
-# Optional uv-managed Hermes project, still operator supplied.
-ACE_HERMES_ROOT=/path/to/hermes-agent \
-ACE_HERMES_UV_PROJECT=/path/to/hermes-agent \
-ace tui --provider llama.cpp --base-url http://127.0.0.1:8080/v1 --model <model> --hermes
-```
+**Hermes** is an optional layer on top of that. Local providers vary in how they stream tokens, frame tool calls, and handle interrupts. Rather than special-case every quirk in ACE, the operator can point ACE at Hermes — a user-supplied companion execution engine — to handle streaming delivery and robust tool-call framing. ACE does not install Hermes or bundle it; it discovers and launches the operator's own Hermes/Python setup only when `--hermes` (or `--engine hermes_local`) is passed. ACE stays the system of record — state, evidence, verification, scheduler — and exposes only a scoped shadow MCP tool surface to Hermes, so the local model sees just the tools its task scope needs.
 
-Or use the TUI with explicit engine selection:
+Hermes-local is opt-in. The local model provider is still Ollama or llama.cpp; Hermes is only the optional execution bridge around that provider.
 
 ```bash
-ace tui --provider llama.cpp --base-url http://localhost:8080 --engine hermes_local
-# shorthand
-ace tui --provider ollama --model llama3.1:8b --hermes
-```
-
-Note: Hermes-local is opt-in. Without `--hermes` or `--engine hermes_local`, the TUI uses the direct provider path and does not require Python, uv, or Hermes. When Hermes is selected, ACE launches the user-supplied Hermes/Python setup for that session and exposes only the scoped shadow MCP tool surface. Tool evidence, not model prose, determines executable mutation.
+# Direct path (no Python, no Hermes) — just a local model
+ace tui --provider ollama --model qwen3:8b
 
-### Doctor checks for Hermes
-
-`ace doctor` surfaces Hermes-local readiness gates only when `--hermes` is passed:
-
-```bash
+# Optional Hermes engine, operator-supplied
 ACE_HERMES_ROOT=/path/to/hermes-agent HERMES_PYTHON=/path/to/python \
-  ace doctor --llm llama.cpp --model gemma-4 --base-url http://localhost:8080 --hermes
-```
-
-Checks performed:
-
-- Hermes bridge worker packaged (`scripts/hermes_bridge_worker.py` present)
-- Hermes checkout supplied by the operator (`ACE_HERMES_ROOT` or `--hermes-root`)
-- Python supplied by the operator (`HERMES_PYTHON` or `--hermes-python`)
-- Optional uv project supplied by the operator (`ACE_HERMES_UV_PROJECT` or `--hermes-uv-project`)
-- Shadow MCP command available for scoped tools-only transport
-- Local runtime reachable and model available
-
-```bash
-# Auto-scan common Ollama + llama.cpp endpoints
-ace doctor --scan
-```
-
-### Evidence model
-
-ACE persists tool evidence only when the model invokes `write_workspace_file` successfully through the shadow MCP surface. If Hermes returns a complete artifact in its final response but never called the write tool, the live driver materializes the artifact for inspection and records `materialized_from_hermes_final` — diagnostic only, not counted as `tool_write_done`.
-
-Operator-restricted models (e.g. `deepseek-r1:8b`) are blocked in `local-model-policy.ts` before a session even starts.
-
-## MCP Tool Surface
-
-ACE exposes tools through a domain-modular registration system (`src/tools.ts` delegates to 12 domain modules). Tools can be allow-listed at startup; `ace mcp-shadow` uses this to give Hermes a scoped tools-only subset. Public `ace mcp` still exposes the full tools, prompts, and resources surface.
-
-### Agent & Runtime
-
-| Tool | Purpose |
-|---|---|
-| `get_agent_instructions` | Read instruction content for any ACE agent role |
-| `get_agent_manifest` | Read the manifest for a given agent role |
-| `get_all_agents_summary` | List all registered agents with role metadata |
-| `get_kernel_artifact` | Read a named kernel artifact from the store |
-| `get_runtime_profile` | Read the active runtime profile (provider, model, base URL) |
-| `validate_runtime_profile` | Schema-validate the stored runtime profile |
-| `get_transition_log` | Read recent agent state-transition history |
-| `get_capability_snapshot` | Summarize current capability coverage across agents |
-| `get_runtime_tool_specs` | Read the tool-spec registry for the active runtime |
-| `validate_runtime_tool_specs` | Schema-validate the tool-spec registry |
-| `list_runtime_tool_specs` | List all registered tool specs |
-| `execute_runtime_tool` | Execute a named runtime tool by spec |
-
-### Orchestration & Planning
-
-| Tool | Purpose |
-|---|---|
-| `propose_plan` | Generate a multi-step task plan proposal |
-| `validate_plan` | Validate a plan proposal against acceptance contracts |
-| `run_local_model` | Dispatch a task to the configured local model runtime |
-| `run_orchestrator` | Run an ACE orchestrator session for a given task |
-| `route_task` | Route an incoming task to the appropriate agent role |
-| `bootstrap_state` | Seed or repair the ACE store for the current workspace |
-| `get_framework_status` | Read aggregate framework health and readiness |
-| `validate_framework` | Run the full framework validation gate suite |
-| `audit_public_surface` | Audit schema-bound tools, resources, and prompts |
-| `audit_store_authority` | Verify store authority and projection consistency |
-| `execute_gates` | Run named gate conditions (dependency, handoff, time) |
-
-### Handoffs
-
-| Tool | Purpose |
-|---|---|
-| `create_handoff` | Create a typed, validated handoff record |
-| `validate_handoff` | Validate a handoff payload against the schema |
-| `get_handoff_template` | Retrieve the handoff template for a given role pair |
-| `get_handoff_status` | Read the status of a specific handoff |
-| `ack_handoff` | Acknowledge a handoff as received and accepted |
-
-Example — creating a handoff from orchestrator to qa:
-
-```bash
-# via any MCP client
-create_handoff {
-  "from_role": "orchestrator",
-  "to_role": "qa",
-  "summary": "Auth module implementation complete, ready for test coverage review",
-  "evidence": ["src/auth.ts", "src/auth.test.ts"],
-  "priority": "P1"
-}
-```
-
-### Scheduler
-
-| Tool | Purpose |
-|---|---|
-| `enqueue_job` | Add a job to the queue with priority, deps, and resource locks |
-| `dispatch_jobs` | Tick the scheduler and dispatch ready jobs |
-| `acknowledge_job` | Mark a job as accepted by a worker |
-| `complete_job` | Mark a job done or failed |
-| `get_job_queue` | Read the current job queue |
-| `get_job_lock_table` | Read active resource locks |
-| `get_scheduler_lease` | Read the current scheduler lease |
-
-Example — queuing a blocked job:
-
-```bash
-enqueue_job {
-  "kind": "handoff.lifecycle",
-  "priority": "P1",
-  "dependencies": [{ "kind": "handoff", "ref": "HNDOFF-abc123", "expected": "ack" }],
-  "resource_requirements": ["agent-state/handoff-registry.json"],
-  "run_after": "2026-05-08T18:00:00Z"
-}
-```
-
-### Files & Structural Editing
-
-| Tool | Purpose |
-|---|---|
-| `read_workspace_file` | Read any file in the workspace |
-| `write_workspace_file` | Write or overwrite a file (evidence-tracked) |
-| `list_workspace` | Directory listing with optional glob filter |
-| `safe_edit_file` | Edit a file with collision-safe write semantics |
-| `diff_files` | Produce a unified diff between two workspace paths |
-| `read_file_lines` | Read a line range from a file |
-| `outline_file` | Extract structural outline (symbols, headings) from a file |
-| `astgrep_query` | Run an ast-grep query pattern against the workspace index |
-| `astgrep_locate` | Locate a specific symbol or construct with ast-grep |
-| `compile_structural_edit` | Compile an ast-grep rewrite to a patch |
-| `preview_structural_edit` | Preview a structural edit without applying |
-| `astgrep_rewrite` | Apply an ast-grep rewrite rule across matched files |
-| `apply_patch` | Apply a unified diff patch to the workspace |
-
-### Change Intelligence & Drift
-
-| Tool | Purpose |
-|---|---|
-| `snapshot_state` | Take a semantic snapshot of the current workspace state |
-| `semantic_diff` | Diff two semantic snapshots |
-| `drift_report` | Produce a drift report between baseline and current state |
-| `list_snapshots` | List available workspace snapshots |
-| `rewrite_targets` | Identify files that are candidates for rewrite based on drift |
-
-### Discovery & Indexing
-
-| Tool | Purpose |
-|---|---|
-| `refresh_astgrep_index` | Rebuild the ast-grep structural index |
-| `scan_workspace_delta` | Scan for file changes since the last index pass |
-| `web_research_packet` | Package a web research context for agent consumption |
-| `mcp_ingestion_probe` | Probe an MCP server and ingest its tool/resource surface |
-| `codemunch_snapshot` | Take a full codemunch snapshot of the workspace |
-| `codemunch_index` | Index a codemunch snapshot for search |
-
-### Git
-
-| Tool | Purpose |
-|---|---|
-| `git_status` | Read working-tree status |
-| `git_commit` | Stage and commit changes with a message |
-| `git_diff` | Diff staged, unstaged, or between refs |
-| `git_log` | Read recent commit history |
-
-### Memory & Continuity
-
-| Tool | Purpose |
-|---|---|
-| `context_snapshot` | Capture a structured context snapshot for the current session |
-| `build_continuity_packet` | Build a continuity packet for cross-session handoff |
-| `recall_context` | Recall a previous context snapshot by ID or recency |
-
-Example — before switching models mid-task:
-
-```bash
-build_continuity_packet {
-  "session_summary": "Implemented auth module, blocked on integration test setup",
-  "next_step": "Write integration tests for /api/auth endpoints"
-}
-```
-
-### Lifecycle & Status Events
-
-| Tool | Purpose |
-|---|---|
-| `emit_status_event` | Append a typed lifecycle event to `STATUS_EVENTS.ndjson` |
-| `get_framework_status` | Read aggregate status across all modules |
-| `refresh_kanban` | Rebuild the kanban board from current state |
-
-Example:
-
-```bash
-emit_status_event {
-  "source_module": "capability-ops",
-  "event_type": "TASK_COMPLETE",
-  "status": "pass",
-  "summary": "Auth integration tests green across all providers"
-}
+  ace tui --provider llama.cpp --base-url http://127.0.0.1:8080/v1 --model gemma-3-4b-it --hermes
 ```
 
-### Todo & Run Ledger
-
-| Tool | Purpose |
-|---|---|
-| `get_todo` | Read the current todo surface |
-| `get_todo_state` | Read structured todo state from the store |
-| `update_todo` | Update one or more todo items |
-| `get_run_ledger` | Read the run ledger (history of major tool invocations) |
-
-### Vericify (Verification)
-
-| Tool | Purpose |
-|---|---|
-| `get_vericify_context` | Get the current verification context packet |
-| `get_vericify_delta` | Get the incremental verification delta |
-| `get_vericify_bridge` | Read the vericify bridge snapshot |
-| `refresh_vericify_bridge` | Refresh the bridge snapshot from test runner output |
-| `validate_vericify_bridge` | Schema-validate the bridge snapshot |
-| `get_vericify_process_posts` | Read the vericify process post log |
-| `append_vericify_process_post` | Append a test result post to the process log |
-| `validate_vericify_process_post_log` | Schema-validate the process post log |
-
-### Tracker Integration
-
-| Tool | Purpose |
-|---|---|
-| `get_tracker_snapshot` | Read the cached tracker snapshot (GitHub Issues, Linear, etc.) |
-| `validate_tracker_snapshot` | Schema-validate the tracker snapshot |
-| `list_tracker_adapter_kinds` | List available tracker adapters |
-| `get_tracker_adapter_health` | Check health of the active tracker adapter |
-| `list_tracker_items` | List items from the tracker |
-| `create_tracker_comment` | Post a comment to a tracker item |
-| `update_tracker_item_state` | Update the state of a tracker item |
-| `refresh_tracker_snapshot` | Pull fresh data from the tracker into the snapshot |
-
-### Skills & Tasks
-
-| Tool | Purpose |
-|---|---|
-| `skill_catalog_summary` | List all available skills with brief descriptions |
-| `skill_audit` | Audit skill freshness and coverage |
-| `problem_triage` | Triage a problem description against known skills |
-| `list_skills` | List skills in the store |
-| `get_skill_instructions` | Read full instructions for a named skill |
-| `get_task_pack` | Read a named task pack |
-| `get_lessons` | Read the lessons log |
-| `add_lesson` | Append a lesson to the log |
-
-### Workspace Sessions
-
-| Tool | Purpose |
-|---|---|
-| `list_workspace_sessions` | List managed workspace sessions |
-| `create_workspace_session` | Create a new managed workspace session |
-| `remove_workspace_session` | Remove a workspace session |
-| `validate_managed_workspace_path` | Validate a workspace path against the session registry |
-
-### Unattended Sessions
+Hermes launch configuration can be supplied with `--hermes-root`, `--hermes-python`, and `--hermes-uv-project`, or with the matching environment variables `ACE_HERMES_ROOT`, `HERMES_PYTHON`, and `ACE_HERMES_UV_PROJECT`.
 
-| Tool | Purpose |
-|---|---|
-| `list_unattended_sessions` | List registered unattended agent sessions |
-| `get_unattended_session` | Read details of a specific unattended session |
-| `start_unattended_session` | Launch an unattended agent session |
-| `stop_unattended_session` | Stop a running unattended session |
-| `wait_for_unattended_session` | Block until a session reaches a terminal state |
-| `validate_unattended_session_registry` | Schema-validate the session registry |
-
-### Framework & Config
-
-| Tool | Purpose |
-|---|---|
-| `get_mcp_config` | Read the baked MCP config for a named client |
-| `run_tests` | Run the ACE test suite |
-| `get_cli_split` | Read the CLI split configuration |
+Tool evidence, not model prose, authorizes completion: a `completed` claim from a mutation-intent run is demoted to `blocked` unless the declared artifacts and evidence actually exist. For the bridge architecture, frame protocol, doctor checks, and evidence model, see the [Hermes reference](docs/hermes.md).
 
 ## Compatible Surfaces
 
@@ -612,110 +240,22 @@ emit_status_event {
 +-------------------+------------------------------------------------------------------+
 ```
 
-## CLI
-
-```text
-+-----------------------------------------------+---------------------------------------------------+
-| Command                                       | Purpose                                           |
-+-----------------------------------------------+---------------------------------------------------+
-| `ace mcp` / `ace serve`                       | Start MCP server over stdio                       |
-| `ace mcp-shadow --tools <csv>`                | Start filtered shadow MCP server (Hermes use)     |
-| `ace tui [options]`                           | Open the terminal operator surface                |
-| `ace init [options]`                          | Seed the ACE store and optional host stubs        |
-| `ace connect [provider] [options]`            | Register a live local runtime or hosted provider  |
-| `ace turnkey [options]`                       | Project store-backed host surface stubs           |
-| `ace doctor [options]`                        | Validate ACE runtime + Hermes readiness           |
-| `ace cache [options]`                         | Cache ACE artifacts into ace-state.ace            |
-| `ace mcp-config [--client <name>|--all]`      | Print baked client snippets for optional install  |
-| `ace preconfig`                               | Write .mcp-config/ bundle for all clients         |
-| `ace paths`                                   | Show resolved package and workspace paths         |
-| `ace help`                                    | Show help                                         |
-+-----------------------------------------------+---------------------------------------------------+
-```
-
-### CLI examples
-
-```bash
-# Bootstrap a workspace with a hosted provider
-ace init --project "My App" --llm claude --client-config-bundle
-
-# Bootstrap with local Ollama model and write VS Code MCP config
-ace init --project "My App" --llm ollama --model llama3.1:8b \
-  --base-url http://localhost:11434 --mcp-config
-
-# Connect to a running llama.cpp server from a Hugging Face model
-ace connect llama-server --hf bartowski/gemma-3-4b-it-GGUF \
-  --base-url http://localhost:8080
-
-# Run doctor checks with auto-scan of common local endpoints
-ace doctor --scan
-
-# Run doctor checks for a specific provider + model
-ace doctor --llm ollama --model llama3.1:8b --base-url http://localhost:11434
-
-# Run optional Hermes checks with user-supplied Hermes/Python
-ACE_HERMES_ROOT=/path/to/hermes-agent HERMES_PYTHON=/path/to/python \
-  ace doctor --llm llama.cpp --model gemma-4 --base-url http://localhost:8080 --hermes
-
-# Repair a missing Ollama model found during doctor
-ace doctor --llm ollama --model llama3.1:8b --repair-ollama
-
-# Print VS Code MCP config snippet to stdout
-ace mcp-config --client vscode
-
-# Write config bundles for every supported client at workspace root
-ace preconfig
-
-# Launch TUI with optional Hermes engine against a local llama.cpp server
-ACE_HERMES_ROOT=/path/to/hermes-agent HERMES_PYTHON=/path/to/python \
-  ace tui --provider llama.cpp --base-url http://localhost:8080 --model gemma-4 --hermes
-
-# Cache all ACE artifacts into ace-state.ace (dry run first)
-ace cache --dry-run
-ace cache
-```
-
-## Development
-
-```bash
-cd ace-mcp-server
-npm install
-npm run build
-npm test
-npm run start
-```
-
-Run the Hermes live driver against your workspace:
-
-```bash
-npm run build
-# with a local llama.cpp or Ollama runtime running:
-ACE_WORKSPACE_ROOT=$PWD \
-  ACE_LIVE_PROVIDERS=llama.cpp \
-  ACE_LIVE_LLAMA_CPP_BASE_URL=http://127.0.0.1:8080/v1 \
-  ACE_LIVE_LLAMA_CPP_MODEL=gemma-4-it \
-  ACE_LIVE_HERMES_MAX_TURNS=3 \
-  ACE_LIVE_OUTPUT_ONLY=1 \
-  node scripts/dev/run_hermes_crispr_live.mjs
-```
-
-Key source files:
+## Documentation
 
-| File | Role |
+| Reference | Contents |
 |---|---|
-| `src/index.ts` | Package entry point |
-| `src/cli.ts` | CLI command dispatch |
-| `src/server.ts` | MCP server setup and stdio transport |
-| `src/tools.ts` | Tool registration hub (delegates to domain modules) |
-| `src/hermes/session-manager.ts` | `HermesSubprocessExecutor` — Hermes subprocess lifecycle |
-| `src/hermes/bridge-protocol.ts` | Frame decoder for the Hermes bridge protocol |
-| `src/model-bridge.ts` | Model bridge interface and process orchestration |
-| `src/public-surface.ts` | Public surface audit and schema-bound entry map |
-| `src/store/ace-packed-store.ts` | ACEPACK binary store read/write |
-| `src/local-model-policy.ts` | Operator allow/block policy for local models |
-| `scripts/hermes_bridge_worker.py` | Packaged Python worker for the Hermes bridge |
-
-See [CHANGELOG.md](./CHANGELOG.md) for release history.
+| [CLI Reference](docs/cli-reference.md) | Every `ace` command and worked examples |
+| [MCP Tool Reference](docs/mcp-tool-reference.md) | The full 119-tool surface across 13 domain modules |
+| [ACEPACK State Model](docs/state-model.md) | On-disk binary format, KV region, columnar event log |
+| [Hermes Companion Engine](docs/hermes.md) | Bridge architecture, frame protocol, doctor checks, evidence model |
+| [TUI Operator Guide](docs/tui-operator-guide.md) | Provider setup, navigation, interrupt behavior, and recovery |
+| [Provider Security](docs/provider-security.md) | Hosted/local credentials, endpoint setup, and trust boundaries |
+| [Evaluation Safety](docs/evaluation-safety.md) | Disposable eval roots, fixtures, provenance, and reproducibility |
+| [Troubleshooting](docs/troubleshooting.md) | Symptom-driven diagnostics and recovery commands |
+| [Library API](docs/library-api.md) | Supported programmatic entry points and stability boundaries |
+| [Experience Playbook](docs/experience-playbook.md) | Experimental evidence-gated lessons store |
+| [Development](docs/development.md) | Build, test, live driver, and key source files |
+| [CHANGELOG](./CHANGELOG.md) | Release history |
 
 ## References