@voybio/ace-swarm 2.4.1 → 2.4.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [2.4.1] - 2026-05-08
+
+### Changed
+
+- Added the local-model execution-engine seam for Hermes-local remediation while preserving provider identity.
+- Added filtered ACE shadow-server registration support for Hermes-local tool allowlists.
+- Added strict Hermes bridge frame decoding tests for fragmented UTF-8, malformed JSON, and control-byte rejection.
+
 ## [2.4.0] - 2026-05-02
 
 ### Changed

package/README.md

@@ -6,6 +6,8 @@ Autonomous Coding Entity (ACE) is a local MCP server and CLI for agent-assisted
 
 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.
 
+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.
+
 ## ACE Manifesto
 
 - Agent work should survive restarts, handoffs, and review.
@@ -25,6 +27,7 @@ ACE provides model providers with the context they cannot infer on their own: ta
 - `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.
 
 ## Why This Exists Now
 
@@ -130,6 +133,18 @@ 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:
@@ -158,35 +173,38 @@ That containment matters. ACE is meant to structure the workflow, not contaminat
 
 ```text
 Developer or MCP host
-  |
-  +-- Claude Code / Codex / Cursor / VS Code / Antigravity
-  |       |
-  |       `-- calls ace-swarm over MCP
-  |
-  +-- agent-state/
-  |       |
-  |       +-- ace-state.ace
-  |       +-- STATUS.md / TASK.md / HANDOFF.json projections
-  |
-  +-- ace mcp
-  |       |
-  |       +-- tools, prompts, resources
-  |       +-- typed handoff validation
-  |       +-- scheduler and resource locks
-  |       `-- state-aware workflow tools
-  |
-  +-- .agents/ACE/
-  |       |
-  |       +-- ace-hook-context.json
-  |       +-- tasks/todo.md
-  |       `-- host config bundles
-  |
-  `-- ace tui
-          |
-          +-- chat
-          +-- agent tabs
-          +-- telemetry
-          `-- provider-aware runtime
+  │
+  ├── Claude Code / Codex / Cursor / VS Code / Antigravity
+  │       │
+  │       └── calls ace-swarm over MCP
+  │
+  ├── agent-state/
+  │       │
+  │       ├── ace-state.ace              (ACEPACK binary store)
+  │       └── STATUS.md / kanban.html / HANDOFF.json projections
+  │
+  ├── ace mcp                            (full surface, ~70 tools)
+  │       │
+  │       ├── tools, prompts, resources
+  │       ├── typed handoff validation
+  │       ├── scheduler and resource locks
+  │       └── state-aware workflow tools
+  │
+  ├── ace tui
+  │       │
+  │       ├── chat, agent tabs, telemetry
+  │       └── provider-aware runtime (direct | optional hermes_local)
+  │               │
+  │               └── [hermes_local] HermesSubprocessExecutor
+  │                       │  spawns Python worker per turn
+  │                       ├── ace mcp-shadow --tools <csv>  (scoped surface for Hermes)
+  │                       └── hermes_bridge_worker.py → local model (Ollama / llama.cpp)
+  │
+  ├── .agents/ACE/
+  │       │
+  │       ├── ace-hook-context.json
+  │       ├── tasks/todo.md
+  │       └── host config bundles
 ```
 
 ## What Ships Today
@@ -195,16 +213,22 @@ Developer or MCP host
 +----------------------+--------------------------------------------------------------+
 | Surface              | Current scope                                                |
 +----------------------+--------------------------------------------------------------+
-| Runtime roles        | swarm and composable runtime roles                           |
-| Skills               | packaged skills                                              |
-| MCP server           | stdio surface for tools, prompts, resources, and workflows   |
-| 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, and resource locks |
-| Change intelligence  | delta scan, semantic snapshots, drift reports, rewrite hints |
-| Terminal UI          | provider-aware TUI with chat, tabs, telemetry, and agent UI  |
-| Local models         | Ollama and llama.cpp bootstrap, doctor checks, and bridges   |
-| Verification         | automated test suite and regression coverage                 |
+| 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)          |
+| 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               |
 +----------------------+--------------------------------------------------------------+
 ```
 
@@ -219,16 +243,360 @@ 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
+## 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.
 
-- `ace init --llm <provider>` seeds the profile inside `agent-state/ace-state.ace`.
-- `ace doctor` verifies that the selected runtime is configured and, when possible, reachable.
-- `ace tui` can talk to either local runtime and surface the same workspace state the MCP server sees.
-- The ACE model bridge gives local runs tool selection, execution flow, and persisted state instead of a fragile one-shot chat loop.
+### 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 |
+
+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.
+
+### Running with Hermes
+
+```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
+```
+
+Or use the TUI with explicit engine selection:
+
+```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.
+
+### Doctor checks for Hermes
+
+`ace doctor` surfaces Hermes-local readiness gates only when `--hermes` is passed:
+
+```bash
+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 |
 
-If you want local agents with memory, evidence, and handoff discipline, this is the point of the package.
+### 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"
+}
+```
+
+### 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
+
+| 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 |
 
 ## Compatible Surfaces
 
@@ -247,17 +615,64 @@ If you want local agents with memory, evidence, and handoff discipline, this is
 ## CLI
 
 ```text
-+---------------------------------------------+---------------------------------------------------+
-| Command                                     | Purpose                                           |
-+---------------------------------------------+---------------------------------------------------+
-| `ace init [options]`                        | seed the ACE store and optional host stubs        |
-| `ace turnkey [options]`                     | project the store-backed host surface              |
-| `ace mcp` / `ace serve`                     | start the MCP server over stdio                   |
-| `ace tui [options]`                         | open the terminal operator surface                |
-| `ace doctor [options]`                      | validate ACE runtime readiness                    |
-| `ace mcp-config [--client <name>|--all]`    | print baked client snippets for optional install  |
-| `ace paths`                                 | show resolved package and workspace paths         |
-+---------------------------------------------+---------------------------------------------------+
++-----------------------------------------------+---------------------------------------------------+
+| 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
@@ -270,6 +685,36 @@ 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:
+
+| File | Role |
+|---|---|
+| `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.
 
 ## References