Merge origin/master: adopt the DeepSeek Harness SDK product name

Reconciliations beyond textual conflicts: - product rename (DeepSeek Code -> DeepSeek Harness SDK) applied to the PR-added assertion in system-prompt.spec.ts that master's rename commit could not reach - architecture.md: master's rewrite kept; this PR's prompt-assembly semantics re-added in the new doc's voice (Turn Flow footnote + service-spine row), within the 1630-word ceiling - cordis catalog regenerated into master's split events.md/services.md (events-and-services.md deleted); module graph and doc graphs regenerated to pick up this PR's new events and dependency edges
2026-08-15 21:04:50 +00:00 · 2026-07-05 20:54:48 +08:00
parent 00cf8b693a d5cb3297ad
commit 2304f7a245
61 changed files with 3582 additions and 706 deletions
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -49,10 +49,10 @@ jobs:

      # Doc-sync gates (doc-sync-enforcement RFC). doc-typecheck compiles the
      # fenced ts blocks against the root project-reference graph. The cordis
-      # catalog freshness check, type-equiv check, and markdown wrap/link checks
-      # only read source. Same `doc-sync` script the pre-push hook runs
+      # catalog freshness check, type-equiv check, Mermaid syntax check, and
+      # markdown wrap/link checks only read source. Same `doc-sync` script the pre-push hook runs
      # (quality-gates RFC: one source of truth).
-      - name: Doc-sync gates (doc code blocks + cordis catalog + type-equiv + markdown wrap/links)
+      - name: Doc-sync gates (doc code blocks + catalogs + mermaid + markdown)
        run: pnpm run doc-sync

      # Module-graph freshness: regenerate docs/module-graph.md from the
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,6 @@
 # AGENTS.md

-This is the monorepo of the DeepSeek Harness group; it hosts **DeepSeek Code**, DeepSeek's coding agent product. The codebase is built on the vendored Cordis framework, microkernel-style: **everything is a plugin**. Read [docs/architecture.md](docs/architecture.md) before changing anything under `packages/` — the service map, event taxonomy, loop lifecycle, and extension seams. The documentation standard is [docs/AGENTS.md](docs/AGENTS.md). Design context: [Coding Harness MVP 需求分析](https://trtgsjkv6r.feishu.cn/wiki/ZwK6wfBE9i91V6kzMGYcgRGanxg), [微内核Harness实现思路](https://trtgsjkv6r.feishu.cn/wiki/VS9Lw1kQki6mDJk2UHocyuphnsc).
+This is the monorepo of the DeepSeek Harness group; it hosts **DeepSeek Harness SDK**, a plugin-based SDK for building agent harnesses. The codebase is built on the vendored Cordis framework, microkernel-style: **everything is a plugin**. Read [docs/architecture.md](docs/architecture.md) before changing anything under `packages/` — the service map, event surface, loop lifecycle, and extension seams. The documentation standard is [docs/AGENTS.md](docs/AGENTS.md).

 ## Pre-release stance: foundation over blast radius

@@ -83,9 +83,9 @@ Real-API tests and demos read `DEEPSEEK_API_KEY` (and optional `DEEPSEEK_BASE_UR
 - Every npm package is `@deepseek-ai/dsh-<name>`; vendored packages keep upstream names and are `private: true`. `cordis` is a peerDependency (+ dev) of every harness package.
 - ESM everywhere (`"type": "module"`). Cross-package imports use package names, never relative paths; in-package relative imports use explicit `.ts` extensions. Dev/test/demo run unbuilt via tsx + the root tsconfig `paths` map; building is only for consumers outside the repo.
 - **Registrations are effects**: every contribution goes through `ctx.effect()` / `ctx.on()`; a registry's `register()` returns the disposer.
- **Typed events via declaration merging**; extensible unions use the merge-extensible-map pattern (`ContentBlockMap`, `SessionEventMap`, …). Every new event's JSDoc carries an `@mode` tag and a `@param` per payload parameter (`this`/trailing `next` exempt); every public service-class method documents each parameter and non-void return (`@param`/`@returns`) — the catalog generator hard-errors otherwise ([completeness RFC](docs/rfc/implemented/process/2026-07-04-cordis-jsdoc-completeness-gate.md)); mode semantics are in the [generated catalog](docs/cordis-catalog/events-and-services.md) header and [the catalog RFC](docs/rfc/implemented/process/2026-06-20-generated-cordis-catalog.md).
+- **Typed events via declaration merging**; extensible unions use the merge-extensible-map pattern (`ContentBlockMap`, `SessionEventMap`, …). Every new event's JSDoc carries an `@mode` tag and a `@param` per payload parameter (`this`/trailing `next` exempt); every public service-class method documents each parameter and non-void return (`@param`/`@returns`) — the catalog generator hard-errors otherwise ([completeness RFC](docs/rfc/implemented/process/2026-07-04-cordis-jsdoc-completeness-gate.md)); mode semantics are in the [generated events catalog](docs/cordis-catalog/events.md) header and [the catalog RFC](docs/rfc/implemented/process/2026-06-20-generated-cordis-catalog.md).
 - **Discriminated unions: `switch` on the tag**, not if-chains. Closed unions end with `default: assertNever(...)`; merge-extensible unions must NOT — handle known cases and fall through `default` with a comment.
- **Waterfall listeners MUST call `next()`** to delegate; returning without it is the veto ([semantics](docs/architecture.md#cordis-waterfall-semantics-important)).
+- **Waterfall listeners MUST call `next()`** to delegate; returning without it is the veto ([semantics](docs/cordis-primer.md#cordis-waterfall-semantics)).
 - **Plugins, not loop changes**: new behavior goes on the documented extension seams; changing `agent-loop` requires updating docs/architecture.md.
 - **Capability seams are three packages** — interface / implementation / consumer ([capability seams](docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)); don't split preemptively.
 - **Explicit > implicit at package seams**: no optional field silently filled by a hidden `?? default` inside `run()`; defaulting is an explicit `resolve(request): Spec` step in the owning implementation (the `dsh-bash` request/spec split is the template).
--- a/README.i18n.yaml
+++ b/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-README.md: 7ddf68bab06ecf891856e6d1393ccdefd9eeba38
-README.zh.md: 59a0419164f2dfee6f66903cc93d7b35da1d9063
+README.md: 53dd3896eb15800125673e7c44f7de02daca9376
+README.zh.md: 5de4c5b6804648f061647d9e315c08a32b42b39b
--- a/README.md
+++ b/README.md
@@ -15,6 +15,6 @@ pnpm run demo:repl     # REPL agent demo (needs DEEPSEEK_API_KEY)
 pnpm run demo:acp      # ACP server agent demo (needs DEEPSEEK_API_KEY)
 ```

-For humans, start with the [development guide](docs/development.md) for local setup, hooks, environment variables, and quality gates, then read the [architecture design](docs/architecture.md) before package work. Local context lives in [packages/](packages/) and [vendor/](vendor/).
+For humans, start with the [development guide](docs/development.md) for local setup, hooks, environment variables, and quality gates, then read the [architecture design](docs/architecture.md) and [documentation graph index](docs/graph-atlas.md) before package work. Local context lives in [packages/](packages/) and [vendor/](vendor/).

 For agents, follow [AGENTS.md](AGENTS.md).
--- a/README.zh.md
+++ b/README.zh.md
@@ -15,6 +15,6 @@ pnpm run demo:repl     # REPL agent demo (needs DEEPSEEK_API_KEY)
 pnpm run demo:acp      # ACP server agent demo (needs DEEPSEEK_API_KEY)
 ```

-面向人类读者：先读[开发指南](docs/development.md)了解本地环境搭建、钩子、环境变量与质量门禁，动手改 package 之前再读[架构设计](docs/architecture.md)。局部上下文见 [packages/](packages/) 与 [vendor/](vendor/)。
+面向人类读者：先读[开发指南](docs/development.md)了解本地环境搭建、钩子、环境变量与质量门禁，动手改 package 之前再读[架构设计](docs/architecture.md)和[文档关系图索引](docs/graph-atlas.md)。局部上下文见 [packages/](packages/) 与 [vendor/](vendor/)。

 面向 agent：遵循 [AGENTS.md](AGENTS.md)。
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -10,14 +10,14 @@ Every fact has exactly one home — the tier whose job it is — and every other
 |---|---|---|
 | Root `AGENTS.md` | Standing orders: rules an agent needs in context in every session, one to three lines each, linking its home | Stories, worked examples, situational procedures, anything restated from a linked home |
 | Subtree `AGENTS.md` (`packages/`, `examples/`, `docs/`) | Orders specific to that subtree | Repo-wide rules the root file already carries |
-| [architecture.md](architecture.md) | The system map: layering, services, the loop, extension seams — read before changing `packages/` | Type shapes (→ core-data-structures), per-package detail (→ package READMEs), decision rationale (→ RFCs), implementation-status annotations |
+| [architecture.md](architecture.md) | The system map: services, the loop, extension seams — read before changing `packages/` | Type shapes (→ core-data-structures), per-package detail (→ package READMEs), decision rationale (→ RFCs), implementation-status annotations |
 | [core-data-structures/](core-data-structures/core.md) | The type catalog: literal shapes and semantics of the spine and seam vocabulary | Behavior narration (→ architecture.md) |
 | [rfc/](rfc/README.md) | Decision records: the why and the what-was-given-up; `implemented/` RFCs describe shipped reality in present tense | Migration plans, test checklists, and spec-speak ("should…") once the decision has shipped |
 | [postmortem/](postmortem/README.md) | Incident stories — the only tier where war-story narrative belongs | — |
 | [cookbook/](cookbook/adding-a-package.md) | Step-by-step how-tos with numbered verify steps | Design rationale (→ the RFC each guide links) |
 | Package README | The per-package contract: config, semantics, limitations, extension points | JSDoc restatement, generated-catalog restatement (event/tool tables), other packages' concerns |
 | [development.md](development.md) | Human-facing setup and daily workflow; a bilingual pair under the [i18n contract](i18n/README.md) | Gate-by-gate enumerations that drift from `package.json` scripts |
-| Generated catalogs: [cordis-catalog](cordis-catalog/events-and-services.md), [tool-catalog](tool-catalog/tools.md), [persistence-catalog](persistence-catalog/log-events.md), [module-graph.md](module-graph.md) | Exhaustive enumerations regenerated from source, freshness-gated | Hand edits of any kind |
+| Generated catalogs: [cordis events](cordis-catalog/events.md), [cordis services](cordis-catalog/services.md), [tool-catalog](tool-catalog/tools.md), [persistence-catalog](persistence-catalog/log-events.md), [module-graph.md](module-graph.md) | Exhaustive enumerations regenerated from source, freshness-gated | Hand edits of any kind |
 | Skills (`.agents/skills/`) | Workflows: how to carry out a recurring task against the contracts | The contracts themselves (→ docs) |

 Placement test: a story about a bug → postmortem. Why we chose X → RFC. How to do task Y → cookbook. What type Z looks like → core-data-structures. What package P promises → its README. A rule every agent must always obey → root AGENTS.md, one line, linking the home that holds the why.
--- a/docs/acp/snapshot-replay.md
+++ b/docs/acp/snapshot-replay.md
@@ -0,0 +1,27 @@
+<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
+     Run `pnpm run gen-doc-graphs` to regenerate. -->
+
+# ACP Snapshot Replay
+
+This graph explains what a snapshot scenario proves: recorded real-model session logs are replayed keylessly, ACP stdout is normalized and diffed, and scenario workspaces preserve tool side effects that the UI stream alone cannot prove.
+
+```mermaid
+sequenceDiagram
+  participant Recorder as Real API recording
+  participant Fixture as snapshot fixture
+  participant Workspace
+  participant Replay as llm-replay adapter
+  participant ACP as acp-agent subprocess
+  participant Golden as stdout golden
+  Recorder->>Fixture: session.jsonl + workspace inputs
+  Fixture->>Workspace: seed files and hook configs
+  Fixture->>Replay: recorded StreamChunk script
+  Replay->>ACP: deterministic <code>llm/stream</code> chunks
+  ACP->>Workspace: bash, fs, and hook side effects
+  ACP->>Golden: normalized sessionUpdate stream
+  Golden-->>ACP: diff must be empty
+```
+
+The fs and hook snapshot matrix is valuable because it proves world state, hook decisions, and failed tool-card rendering, not just that replay returns text.
+
+Maintenance mode: curated Mermaid sequence based on the snapshot test harness.
--- a/docs/agent-lifecycle.md
+++ b/docs/agent-lifecycle.md
@@ -0,0 +1,49 @@
+<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
+     Run `pnpm run gen-doc-graphs` to regenerate. -->
+
+# Agent Turn And Step Lifecycle
+
+This sequence is the visual companion to [architecture.md](architecture.md#loop-lifecycle-session--turn--step). It keeps durable replay facts on `session/event` and live control/status on `agent/*`.
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant Agent
+  participant Driver
+  participant Hooks as hook listeners
+  participant Prompt as ctx.systemPrompt
+  participant LLM as ctx.llm
+  participant Tools as ctx.tools
+  participant Session
+  participant Persistence
+  participant SDK as UI or SDK listener
+  User->>Agent: send(content)
+  Agent-->>SDK: <code>agent/queued</code>
+  Agent->>Driver: queued work wakes driver
+  Driver-->>SDK: <code>agent/status</code> running
+  Driver->>Session: <code>turn/start</code>
+  Driver->>Hooks: <code>agent/prompt-submit</code> waterfall
+  Hooks-->>Driver: allow, block, or add context
+  Driver->>Session: <code>user/message</code> or rejected <code>turn/end</code>
+  Driver->>Prompt: <code>system-prompt/assemble</code> waterfall
+  Driver-->>Driver: <code>agent/pre-step</code> serial checkpoint
+  Driver->>Session: <code>step/start</code>
+  Driver->>LLM: <code>agent/request</code> waterfall, then <code>llm/stream</code> waterfall
+  LLM-->>Driver: StreamChunk*
+  Driver->>Session: <code>assistant/chunk</code>*
+  Session-->>SDK: <code>session/event</code> <code>assistant/chunk</code>*
+  Driver->>Hooks: <code>agent/step-result</code> waterfall
+  Driver->>Session: <code>assistant/message</code>
+  Driver->>Session: <code>tool/call</code>
+  Driver->>Tools: execute through pre and post waterfalls
+  Tools-->>Session: tool-owned events when applicable
+  Driver->>Session: <code>tool/result</code> and <code>step/end</code>
+  Driver->>Hooks: <code>agent/turn-continuation</code> waterfall
+  Driver->>Session: <code>turn/end</code>
+  Driver->>Persistence: <code>session/flush</code> parallel checkpoint
+  Driver-->>SDK: <code>agent/status</code> idle
+```
+
+SDK users that need replayable transcript data should consume `session/event`; `agent/*` is the live coordination surface for queue/status, prompt interception, request shaping, steering, continuation, and errors.
+
+Maintenance mode: curated Mermaid sequence; exact event signatures live in the generated Cordis catalog.
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -1,162 +1,145 @@
 # DeepSeek Harness Architecture

-This document describes the architecture of the DeepSeek Harness — the foundation of **DeepSeek Code**. The governing principle, from the [microkernel design discussion][microkernel-doc]: **everything is a plugin**. The core is deliberately tiny — a handful of abstract services plus one concrete loop plugin (`dsh-agent-loop`) — and every product feature is a plugin against the extension surface described here, without modifying the loop.
+The **DeepSeek Harness SDK** is an SDK for building agent harnesses using the Cordis framework. The governing principle is simple: **everything is a plugin**. For example, the shipped agent loop is just one plugin in the default bundle, not a privileged kernel.

-This document covers **behavior**; type shapes live in [core-data-structures/](core-data-structures/core.md), the per-event/service reference in the [generated catalog](cordis-catalog/events-and-services.md), per-package contracts in the package READMEs ([map](../packages/README.md)). Requirement context: [Coding Harness MVP 需求分析][mvp-doc].
+Read this page as the system map before changing `packages/`. It explains how the runtime is shaped, how the default loop moves work, where state lives, and where extensions attach. Type shapes live in [core-data-structures/](core-data-structures/core.md); exact event and service signatures live in the generated [events](cordis-catalog/events.md) and [services](cordis-catalog/services.md) catalogs; package contracts live in the [package map](../packages/README.md); rationale lives in the [RFCs](rfc/README.md). If Cordis itself is new to you, start with the [Cordis primer](cordis-primer.md).

-[microkernel-doc]: https://trtgsjkv6r.feishu.cn/wiki/VS9Lw1kQki6mDJk2UHocyuphnsc
-[mvp-doc]: https://trtgsjkv6r.feishu.cn/wiki/ZwK6wfBE9i91V6kzMGYcgRGanxg
+## System Shape

-## Layering
+A running harness is one Cordis context. Packages contribute service keys, typed events, and disposable registrations to that context. Services are the stable call surfaces (`ctx.llm`, `ctx.tools`, `ctx.sessions`); events are interception and notification points (`agent/request`, `tools/pre-execute`, `session/event`); registrations install prompt sections, tool schemas, providers, adapters, and listeners.

-```
-┌────────────────────────────────────────────────────────────────┐
-│  extension + implementation plugins                            │
-│    dsh-agent-loop — THE concrete loop plugin                   │
-│    LLM adapters · executors/backends · model-facing tools      │
-│    subagent providers · hook bridges · UI bridges              │
-├────────────────────────────────────────────────────────────────┤
-│  interface/service packages (each owns a ctx key + vocabulary) │
-│    dsh-agent · dsh-tools · dsh-system-prompt · dsh-session     │
-│    dsh-llm · dsh-bash · dsh-fs · dsh-web · dsh-compact         │
-│    dsh-subagent · dsh-session-persistence                      │
-├────────────────────────────────────────────────────────────────┤
-│  vendor/: pinned Cordis framework source (cordis, loader, …)   │
-└────────────────────────────────────────────────────────────────┘
-```
+The default distribution is a composition, not a hierarchy. `packages/core/` is a repository grouping for the default agent spine; capability seams around it are equally first-class plugins from a Cordis perspective.

-Dependency rule: extension plugins depend on interfaces, never on `dsh-agent-loop` (the loop is swappable); the sanctioned exception is the composition bundle `dsh-agent-core`, whose job is assembling the concrete spine ([full rule + generated graph](../packages/README.md#dependencies)).
-
-## Service map
+### Default Service Spine

 | ctx key | Package | Role |
 |---|---|---|
-| `ctx.llm` | dsh-llm | adapter registry; `stream()` |
-| `ctx.sessions` | dsh-session | creates/holds event-sourced `Session`s |
-| `ctx.sessionPersistence` | dsh-session-persistence | durable persistence: create/append/load/list |
-| `ctx.systemPrompt` | dsh-system-prompt | ordered sections + tool schemas → `assemble()` |
-| `ctx.tools` | dsh-tools | tool definitions; `execute()` through waterfall |
-| `ctx.agents` | dsh-agent | live `Agent` handles + create/resume factory (returns `AgentHandle { agent, dispose() }`) |
-| `ctx.agentLoop` | dsh-agent-loop | creates and drives `ReactLoopAgent`s |
-| `ctx.bash` | dsh-bash | bash execution: foreground runs + background tasks |
-| `ctx.fs` | dsh-fs | filesystem provider: read/stream, atomic writes/edits; owns the `fs/*` policy events |
-| `ctx.compact` | dsh-compact | compaction: detect pressure, summarize an older range |
-| `ctx.web` | dsh-web | search/fetch provider registries + `WebError` taxonomy |
-| `ctx.subagents` | dsh-subagent | named provider registry for delegating to child agents |
+| `ctx.sessions` | `dsh-session` | in-memory event-sourced sessions |
+| `ctx.systemPrompt` | `dsh-system-prompt` | ordered prompt sections, tool schemas, and prompt variables |
+| `ctx.tools` | `dsh-tools` | tool registry and [execution pipeline](tool-execution-pipeline.md) |
+| `ctx.agents` | `dsh-agent` | live agent registry, public `Agent` handle, `agent/*` vocabulary |
+| `ctx.agentLoop` | `dsh-agent-loop` | shipped `ReactLoopAgent` driver |

-All registrations go through `ctx.effect()` and return disposers, so hot-reload and fiber disposal clean up automatically (full service interfaces: the [generated catalog](cordis-catalog/events-and-services.md) `## Services` section).
+### Capability Services

-## Capability seams: interface / implementation / consumer
+| ctx key | Package family | Role |
+|---|---|---|
+| `ctx.llm` | [`llm/`](../packages/llm/README.md) | adapter registry and streaming model calls |
+| `ctx.bash` | [`bash/`](../packages/bash/README.md) | foreground/background command execution |
+| `ctx.fs` | [`fs/`](../packages/fs/README.md) | filesystem provider primitives and policy events |
+| `ctx.web` | [`web/`](../packages/web/README.md) | search/fetch provider registries |
+| `ctx.compact` | [`compact/`](../packages/compact/README.md) | session-surface compaction |
+| `ctx.subagents` | [`subagent/`](../packages/subagent/README.md) | named delegation providers |
+| `ctx.sessionPersistence` | [`session-persistence/`](../packages/session-persistence/README.md) | durable storage for session logs |

-Swappable capabilities split into three packages — **interface** (abstract service + vocabulary, owns the ctx key), **implementation** (a concrete subclass loaded as a plugin), **consumer** (what the model and plugins program against) — so each evolves independently; the bash trio is the template ([capability seams RFC](rfc/implemented/architecture/2026-06-13-capability-seams.md)). Keep interface + consumer together when they are one concern (the LLM seam: `dsh-llm` carries both, adapters implement); don't split preemptively.
+## Event Surface

-Two seams bend the template deliberately:
+Events are the harness extension API. Each service owns the vocabulary for the behavior it controls, and the generated [events catalog](cordis-catalog/events.md) is the exhaustive reference. The [producer/consumer map](event-producer-consumer.md) shows which packages emit or listen to each event.

- **Filesystem** adds a policy layer as an **event gate**, not a method service: `dsh-tool-fs` (the `read`/`write`/`edit` tools AND executor) dispatches `fs/*` intent events that `dsh-fs-policy` decides, so dropping the policy plugin degrades to the bare provider instead of breaking an injection ([event-gate RFC](rfc/implemented/architecture/2026-06-26-file-context-as-event-gate.md)). Paths resolve against the caller's session cwd, matching bash ([per-session cwd RFC](rfc/implemented/architecture/2026-07-02-fs-per-session-cwd.md)).
- **Web** folds search and fetch onto one seam: `ctx.web` is a provider REGISTRY (`registerSearchProvider`/`registerFetchProvider`, registration-order-independent selection); providers register like LLM adapters, and `dsh-tool-web` is the single consumer owning the tool schemas ([web seam RFC](rfc/implemented/architecture/2026-06-24-web-capability-seam.md)).
+### Event Domains

-> The seam pattern is plain Cordis services + `inject` (a consumer's fiber stays pending until the service exists). Despite the name, `@cordisjs/plugin-capability` is unrelated — a permission-security service (a candidate for the deferred permissions work), not a mechanism for swapping implementations.
+Use the event domain to decide where new behavior belongs:

-## The vocabulary (dsh-llm)
+- **Session events** are durable, replayable facts. Turn and step boundaries, user input, assistant output, tool calls, tool results, steering, compaction records, and tool-owned durable facts append to the session log and flow through `session/event`.
+- **Agent events** are live runtime surfaces. They carry the live `Agent` handle for status, diagnostics, prompt admission, request mutation, result validation, and continuation policy.
+- **Capability events** belong to the seam that owns the action. `tools/*`, `llm/*`, `system-prompt/*`, `fs/*`, and `subagent/*` let policy and adapters attach without importing the loop.

-Messages are arrays of typed **content blocks** (`text`, `reasoning`, `tool-call`, `tool-result`); the union derives from the merge-extensible `ContentBlockMap`; the same pattern types `MessageSource`, `FinishReason`, `TurnTrigger`, `TurnEndReason`. The core set is limited to blocks every shipping path honors — multimodal content (images, audio, …) has no core block type; a feature that needs one adds it via the map in the same coordinated change that maps it in the adapters, surfaces it in the UI bridges, and prices it in compaction ([the drop-image RFC](rfc/implemented/simplification/2026-07-04-drop-image-content-block.md)). Streaming is a raw chunk protocol (`block-start` … `finish`) with `BlockAssembler` as the single shared chunk→block assembler; the loop logs raw chunks (replay fidelity) while assembling them. `LlmAdapter` is the provider seam: subclass, implement `stream()`, register via `ctx.llm.registerAdapter(models, adapter)`; `dsh-llm-deepseek` and `dsh-llm-pi-ai` implement the one contract as deliberate design twins ([twin RFC](rfc/implemented/architecture/2026-06-13-twin-llm-adapters.md)). The StreamChunk conventions (usage/finish ordering, raw-string tool arguments, the two sanctioned error paths) are pinned in `dsh-llm/src/types.ts` and [llm-streaming.md](core-data-structures/llm-streaming.md).
+### Interception Semantics

-## Event-sourced sessions (dsh-session)
+Waterfall events behave like around-middleware: a listener delegates by calling `next()` and vetoes or takes over by returning without it. The full rule lives in [Cordis waterfall semantics](cordis-primer.md#cordis-waterfall-semantics).

-A `Session` is an append-only log of typed `SessionEvent`s — the single source of truth. The LLM message history is *derived* (`deriveMessages()`): user/assistant messages, tool results, and envelope-tagged context/steering messages come from their events in chronological order (raw `assistant/chunk` events are replay/UI data, skipped; the per-event mapping is in [session.md](core-data-structures/session.md)). Replay/fork = `ctx.sessions.create(id, { seed })`; trace/telemetry = listen to `session/event` ([event-sourcing RFC](rfc/implemented/architecture/2026-06-11-event-sourced-sessions.md)).
+## Default Loop Lifecycle

-**Durability**: `session/event` is a synchronous notification; persistence backends buffer write-behind and drain at the awaited `session/flush` checkpoint at every turn end. The abstract `SessionPersistence` seam defines create/append/load/list over `SessionEvent` (no parallel persisted type); metadata travels as `SessionHeader`; crash recovery preserves an interrupted turn by closing it with a synthetic `turn/end {interrupted}`. Two backends (JSONL, SQLite) pass one shared contract suite ([persistence RFC](rfc/implemented/architecture/2026-06-14-session-persistence.md), [write coordinator RFC](rfc/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md)). Resume = `ctx.agents.resume({ resumeSessionId })`.
+The shipped loop drains queued work, assembles a request, streams a model answer, executes tools, decides whether to continue, and checkpoints durable state. The important architecture is where it pauses: each pause is a documented service call or event seam that another plugin can program against.

-## Prompt assembly (dsh-system-prompt)
+A **session** is one agent's append-only event log. A **turn** drains one queued batch and runs until the model stops asking for tools and no plugin requests continuation. A **step** is one model request plus the tool executions caused by that response. In the flow below ([sequence companion](agent-lifecycle.md)), quoted names are durable session events and event names are extension seams.

-Plugins contribute `PromptSection`s (named, ordered, static or computed from the per-call `AssembleContext`), tool-schema providers, and named **prompt variables** interpolated as `{{name}}` at render (strict: an unknown or valueless reference throws). `renderPrompt(assemble({ agent }))` IS the full prompt: the loop's `harness:identity` (−100) and `agent:persona` (0) sections plus its `model`/`cwd` variables carry the harness and per-agent facts — no second composition path. Tool schemas are deliberately part of the assembly ([RFC](rfc/implemented/architecture/2026-06-11-tool-schemas-in-prompt-assembly.md)); prompt-fact ownership (persona vs description vs section vs variable) is pinned by [the prompt-variables RFC](rfc/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md).
+### Turn Flow

-## Tool pipeline (dsh-tools)
-
-`ToolRegistry.register()` takes schema + `execute()`; schemas flow into the assembly automatically. `execute()` runs through a two-waterfall pipeline — `tools/pre-execute` (a `PreToolDecision`: allow/deny/ask) → core dispatch → `tools/post-execute` (a `PostToolDecision`: accept/block, replace content, attach context) — the seams where sandbox, permission, hook, and plan-mode plugins live. A thrown tool still reaches `post-execute` as an `isError` result.
-
-## Agents (dsh-agent) and the loop (dsh-agent-loop)
-
-`Agent` is the handle every plugin programs against: `send()` (queued), `steer()` (mid-turn injection, drained between steps), `inject()` (in-session context; a one-shot `injection` turn when idle), `cancel()` (the single public stop primitive: clears queued + steering work, aborts the in-flight step, drops a turn about to start), `whenIdle()` (quiescence observation, not teardown), plus `session`/`status`/`options`. A lifecycle owner tears down via `await AgentHandle.dispose()` — stop, await exit, unregister. Full semantics: [core.md](core-data-structures/core.md), [lifecycle RFC](rfc/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md).
-
-**Subagents** are a seam, not a method on `Agent`: `ctx.subagents` is a named-provider registry (`spawn` starts fresh, `fork` seeds the child with the parent's completed-turn prefix, ACP drives an out-of-process child); children are ordinary `Agent`s. See [subagent.md](core-data-structures/subagent.md), [subagent RFC](rfc/implemented/feature/2026-06-21-subagent-capability-seam.md).
-
-### Loop lifecycle (session / turn / step)
-
- **Session**: the whole event log of one agent.
- **Turn**: ≥1 queued message; steps run until the model stops requesting tools and no plugin requests continuation.
- **Step**: one model request + its tool executions.
-
-```
-create agent → emit agent/session-start(source)       ⟵ once, before turn 1 (startup|resume)
+```text
+create agent -> emit agent/session-start(source)
 forever:
-  wait for queued messages (idle)
+  wait for queued messages
  emit agent/status(running)
-  TURN (error-contained — a throwing plugin ends the turn, never the loop):
-    'turn/start'                                        ⟵ durable turn boundary (no agent/* mirror)
-    each queued msg: waterfall agent/prompt-submit      ⟵ allow (rewrite/+context) | block
-      allow → session('user/message'…); inject additionalContext
-    every prompt blocked → 'turn/end'(rejected), 0 steps ⟵ zero-step turn, model never called
+  TURN:
+    'turn/start'
+    each queued message -> agent/prompt-submit
+      allowed prompt -> 'user/message' plus injected context
+    every prompt blocked -> 'turn/end'(rejected)
    STEP loop:
-      drain steering (late steering from previous step's listeners)
-      assembly = ctx.systemPrompt.assemble({agent})   ⟵ waterfall system-prompt/assemble; renderPrompt
-                                                         (persona section + {{variables}}) IS the prompt
-      await ctx.serial('agent/pre-step')              ⟵ surface mutation (compaction) OUTSIDE the step
-      session('step/start')                           ⟵ durable step boundary (no agent/* mirror)
-      req = {model, system, tools, messages: session.deriveMessages(), signal}
-      req = waterfall agent/request                   ⟵ hooks, model switch
-      stream ctx.llm.stream(req)                      ⟵ waterfall llm/stream (raw chunks)
-        session('assistant/chunk')
-      if assembler.finish is error/aborted: throw      ⟵ adapter's in-band error path →
-                                                         step error (turn ends error/aborted,
-                                                         not a normal completed message)
-      msg = waterfall agent/step-result               ⟵ runs BEFORE the log append, so the
-      session('assistant/message' {content, usage?})     log records what tool dispatch uses
-      each tool-call (sequential, abort-checked between calls):
-        session('tool/call'); ctx.tools.execute()     ⟵ waterfall tools/pre-execute (allow/
-          deny/ask gate) → dispatch → tools/post-execute (accept/block, replace, +context)
-          tool execution may append tool-owned session events, e.g. `todo/write`
-        session('tool/result')
-      append buffered post-execute additionalContext → session('context/message')(s)
-                                                         ⟵ after ALL tool/results (adjacency)
-      drain steering → session('steering/message')
-      session('step/end')                             ⟵ durable step boundary (no agent/* mirror)
-      cont = waterfall agent/turn-continuation(default = {action: hadToolCalls||steered
-        ? 'continue' : 'stop'}) → ContinuationDecision
-      a continue's reason is recorded as next-step steering (same turn); steering pending
-        also forces continue (continuation OR step/end listeners — the /goal pattern)
-      if action==stop: break
-  session('turn/end')                                 ⟵ durable turn boundary (no agent/* mirror)
-  await ctx.parallel('session/flush', session)        ⟵ durability checkpoint (failure
-                                                         reported via agent/error, not fatal)
-  leftover steering re-enqueued as queued messages    ⟵ steering is never stranded
-  emit agent/status(idle) unless more queued
+      drain steering
+      assemble system prompt and tool schemas
+      agent/pre-step
+      'step/start'
+      derive messages from the session log
+      agent/request -> llm/stream
+        'assistant/chunk'
+      agent/step-result
+      'assistant/message'
+      each tool call:
+        'tool/call'
+        tools/pre-execute -> dispatch -> tools/post-execute
+        'tool/result'
+      append post-tool context and steering
+      'step/end'
+      agent/turn-continuation
+      stop unless tools or continuation policy ask for another step
+    'turn/end'
+    checkpoint persistence and notify idle/running status
 ```

-Error containment: a throwing listener or broken step ends the **turn** (`turn/end { reason: { kind: 'error', step, … } }`), never the driver loop; live diagnostics fire via `agent/error`; an adapter's in-band error/aborted finish chunk becomes a step error. `cancel()` is honored mid-stream and between tool calls; disposal mid-turn ends the turn `disposed`. A post-`turn/end` failure (a rejecting `session/flush`) is reported via `agent/error` only — the turn stays balanced, the backend keeps its buffer.
+Prompt assembly is single-path: `renderPrompt(assemble({ agent }))` IS the system prompt sent to the model. Plugins contribute ordered sections (static or computed from the per-call `AssembleContext`), tool schemas, and named variables interpolated as `{{name}}` at render — strictly, so an unknown or valueless reference fails the turn instead of shipping a hole. The loop itself registers the `harness:identity` (order −100) and `agent:persona` (order 0) sections and the `model`/`cwd` variables; prompt-fact ownership is pinned by the [prompt-variables RFC](rfc/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md).

-A turn ends with one `TurnEndReason` — `completed`, `aborted`, `error`, `disposed`, `max-tokens`, `rejected`, or `interrupted`; per-variant semantics (and the max-tokens-wins rule) are in [session.md § TurnEndReasonMap](core-data-structures/session.md#why-a-turn-ended-turnendreasonmap).
+Post-tool context lands after all tool results so tool-call/result adjacency stays stable. Steering drains between steps; leftover steering after a turn is re-queued as ordinary input.

-**Turn-enclosure invariant**: every session event lives inside a turn, making the turn the single durability/replay boundary — anything after the last `turn/end` is an interrupted-crash tail. `dsh-invariants` enforces it in dev ([invariant RFC](rfc/implemented/architecture/2026-06-15-turn-enclosure-invariant.md)).
+### Failure Boundaries

-### Event taxonomy
+The turn is the containment boundary. A throwing listener, adapter error finish, or failed step ends the current turn with an error reason and reports live diagnostics through `agent/error`; it does not kill the driver loop. `cancel()` clears queued and steering work, aborts the active model/tool boundary when possible, and records the appropriate turn end. Disposal stops the loop, awaits quiescence, unregisters the agent, and lets service disposers drain.

-The `agent/*` events are declared in `dsh-agent` (so nothing depends on the loop package); each other service declares its own (`tools/*`, `llm/*`, `system-prompt/*`, `session/*`). The full catalog — signatures, dispatch modes, prose — is generated from source and freshness-gated: [cordis-catalog/events-and-services.md](cordis-catalog/events-and-services.md). Domain semantics (session = the fact log, agent = the live surface): [the event-domain RFC](rfc/implemented/architecture/2026-06-30-event-domain-semantics.md).
+Every session event is turn-enclosed. Reloading a crashed session preserves the interrupted tail and closes it with a synthetic `interrupted` turn end. A failure after the durable turn has closed reports through `agent/error` only because no safe in-turn position remains. A turn ends with one `TurnEndReason` (`completed`, `aborted`, `error`, `disposed`, `max-tokens`, `rejected`, or `interrupted`); per-variant semantics are in [session.md § TurnEndReasonMap](core-data-structures/session.md#why-a-turn-ended-turnendreasonmap).

-### Cordis waterfall semantics (important)
+### Agent Handles

-`ctx.waterfall` is **around-middleware**, not a value reducer. Each listener receives `(...args, next)`:
+`ctx.agents` owns live agents and returns an `AgentHandle { agent, dispose() }`. `Agent` is the surface other plugins drive: `send()` queues work, `steer()` injects mid-turn content, `inject()` appends context and opens a one-shot injection turn when idle, `cancel()` is the public stop primitive, and `whenIdle()` observes quiescence. Lifecycle owners tear down with `await dispose()`.

- call `next()` to delegate to later listeners (and ultimately the core behavior), possibly wrapping it;
- return a value **without** calling `next()` to short-circuit (veto);
- listeners run in registration order; `prepend: true` jumps the queue.
+## State And Model Surface

-Composition caveat: values propagate through `next()`'s **return value** — a listener that returns a *new* object makes earlier listeners' mutations invisible downstream. Prefer mutate-then-`next()` for cooperative middleware; return a replacement only to take over the result.
+### Session Log

-## Extension guide
+The session log is the source of truth. `deriveMessages()` projects session events into the `Message[]` sent to the model; raw `assistant/chunk` events stay in the log for replay and UI fidelity. Replay, fork, resume, transcript rendering, telemetry, and persistence all derive from the same event stream.

-Plugin skeletons (tool, hook/permission gate, UI, protocol bridge) and the feature→mechanism map — which extension seam implements each product feature — live in [the extension cookbook](cookbook/extension-cookbook.md); step-by-step guides: [adding a package](cookbook/adding-a-package.md), [a tool](cookbook/adding-a-tool.md), [an LLM adapter](cookbook/adding-an-llm-adapter.md), [a vendored package](cookbook/adding-a-vendored-package.md).
+Durability is a plugin concern. Persistence backends buffer synchronous `session/event` notifications and the loop awaits a turn-end checkpoint before moving on. The `SessionPersistence` seam stores `SessionEvent` directly, with metadata in `SessionHeader`; JSONL and SQLite share one contract suite.

-## Deferred work (TODO)
+### Model Content

-Designed-for but not implemented: inter-agent channels beyond delegation (shared state, streaming output); the model-facing `/compact` consumer tool over `ctx.compact` ([compaction RFC](rfc/implemented/feature/2026-06-18-compaction-capability-seam.md)); parallel tool execution (concurrency-safety hints on `ToolDefinition`); session branching/tree if seed-based forking proves insufficient.
+Messages are arrays of typed content blocks (`text`, `reasoning`, `tool-call`, `tool-result`). The union derives from the merge-extensible `ContentBlockMap`; the same pattern types `MessageSource`, `FinishReason`, `TurnTrigger`, and `TurnEndReason`. New block types are coordinated across adapters, UI bridges, compaction pricing, and persistence, so block vocabulary remains a repo-wide contract.
+
+Streaming is a raw chunk protocol (`block-start` through `finish`) with `BlockAssembler` as the shared chunk-to-block assembler. The loop logs raw chunks while assembling them for dispatch. `LlmAdapter` is the provider seam: subclass, implement `stream()`, and register with `ctx.llm.registerAdapter(models, adapter)`. StreamChunk conventions live in [llm-streaming.md](core-data-structures/llm-streaming.md).
+
+## Extension And Composition
+
+### Capability Pattern
+
+A swappable capability usually splits into **interface / implementation / consumer**: the interface owns the `ctx` key and vocabulary; an implementation registers a backend; a consumer exposes model-facing behavior through `ctx.tools` or prompt assembly. The bash trio is the reference shape, and the [capability seam graph](capability-seams.md) shows the current package families.
+
+Some seams bend the template deliberately. LLM keeps interface and consumer vocabulary together because adapters are the implementations. Filesystem adds policy as event gates around provider primitives. Web is one service with search and fetch provider registries, so provider swaps do not rename model tools. Subagents use a named provider registry because multiple delegation backends can coexist; `spawn` starts fresh, `fork` seeds from the parent's completed-turn prefix, and ACP can drive an out-of-process child ([subagent.md](core-data-structures/subagent.md)).
+
+### Bundles And Apps
+
+`dsh-agent-core` is the default composition bundle: one plugin loading the providerless spine as code ([README](../packages/core/agent-core/README.md)). App packages compose it with a front door and own the boot `bin`: `dsh-stdio-agent` for the terminal REPL, and `dsh-acp-agent` for ACP over JSON-RPC stdio with no stdout logger ([ui/](../packages/ui/README.md)). A deployment is a thin `cordis.yml` leaf: swappable backends, one app entry, and optional product tools ([examples/](../examples/AGENTS.md), [runnable wirings](cookbook/extension-cookbook.md#runnable-wirings), [graph atlas](graph-atlas.md)).
+
+### Where New Behavior Goes
+
+New behavior should attach to a documented seam; changing the shipped loop requires updating this map.
+
+| Goal | Mechanism |
+|---|---|
+| Add a model provider | register an adapter on `ctx.llm` |
+| Add a model-facing capability | register a tool on `ctx.tools`; schemas flow into prompt assembly |
+| Add command execution | implement and register a `ctx.bash` backend |
+| Add filesystem access or policy | implement a `ctx.fs` provider or listen on `fs/*` policy events |
+| Intercept prompts, requests, tool use, or continuation | listen on the relevant `agent/*` or `tools/*` waterfall |
+| Add UI or editor integration | drive `ctx.agents` and render from `session/event` |
+| Add durable session state | add a `SessionEventMap` member and render/replay from the log |
+
+The [extension cookbook](cookbook/extension-cookbook.md) carries plugin skeletons and the feature-to-seam map; step-by-step guides cover [packages](cookbook/adding-a-package.md), [tools](cookbook/adding-a-tool.md), [LLM adapters](cookbook/adding-an-llm-adapter.md), and [vendored packages](cookbook/adding-a-vendored-package.md).
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -0,0 +1,142 @@
+<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
+     Run `pnpm run gen-doc-graphs` to regenerate. -->
+
+# Capability Seams And Core Services
+
+A service can be a core spine service, a swappable capability seam, or a bundle/composition point. The graph shows the package that owns the service declaration, known implementation packages, and packages that consume the service directly.
+
+```mermaid
+flowchart LR
+  pkg_llm["llm"]
+  svc_llm["ctx.llm<br/>LLM adapter registry"]
+  pkg_llm_deepseek["llm-deepseek"]
+  pkg_llm_pi_ai["llm-pi-ai"]
+  pkg_llm_replay["llm-replay"]
+  pkg_agent_loop["agent-loop"]
+  pkg_compact_basic["compact-basic"]
+  pkg_session["session"]
+  svc_sessions["ctx.sessions<br/>In-memory session store"]
+  pkg_agent["agent"]
+  pkg_session_persistence["session-persistence"]
+  pkg_subagent_inprocess["subagent-inprocess"]
+  pkg_invariants["invariants"]
+  svc_sessionPersistence["ctx.sessionPersistence<br/>Durable session persistence seam"]
+  pkg_session_persistence_jsonl["session-persistence-jsonl"]
+  pkg_session_persistence_sqlite["session-persistence-sqlite"]
+  pkg_acp["acp"]
+  pkg_system_prompt["system-prompt"]
+  svc_systemPrompt["ctx.systemPrompt<br/>System prompt assembly registry"]
+  pkg_tools["tools"]
+  pkg_tool_fs["tool-fs"]
+  pkg_tool_web["tool-web"]
+  svc_tools["ctx.tools<br/>Tool registry and execution waterfall"]
+  pkg_tool_bash["tool-bash"]
+  pkg_tool_subagent["tool-subagent"]
+  pkg_tool_todo["tool-todo"]
+  svc_agents["ctx.agents<br/>Agent registry"]
+  pkg_stdio_agent["stdio-agent"]
+  svc_agentLoop["ctx.agentLoop<br/>Concrete loop driver"]
+  pkg_agent_core["agent-core"]
+  pkg_bash["bash"]
+  svc_bash["ctx.bash<br/>Bash executor seam"]
+  pkg_bash_local["bash-local"]
+  pkg_hooks_claude["hooks-claude"]
+  pkg_hooks_codex["hooks-codex"]
+  pkg_fs["fs"]
+  svc_fs["ctx.fs<br/>Filesystem provider seam"]
+  pkg_fs_local["fs-local"]
+  pkg_fs_policy["fs-policy"]
+  pkg_compact["compact"]
+  svc_compact["ctx.compact<br/>Compaction seam"]
+  pkg_subagent["subagent"]
+  svc_subagents["ctx.subagents<br/>Subagent provider registry"]
+  pkg_subagent_spawn["subagent-spawn"]
+  pkg_subagent_fork["subagent-fork"]
+  pkg_subagent_acp["subagent-acp"]
+  pkg_subagent_mock["subagent-mock"]
+  pkg_web["web"]
+  svc_web["ctx.web<br/>Web access provider registry"]
+  pkg_web_search_exa["web-search-exa"]
+  pkg_web_search_perplexity["web-search-perplexity"]
+  pkg_web_search_deepseek["web-search-deepseek"]
+  pkg_web_fetch_local["web-fetch-local"]
+  pkg_agent --> svc_agents
+  pkg_agent_loop --> svc_agentLoop
+  pkg_bash --> svc_bash
+  pkg_bash_local --> svc_bash
+  pkg_compact --> svc_compact
+  pkg_compact_basic --> svc_compact
+  pkg_fs --> svc_fs
+  pkg_fs_local --> svc_fs
+  pkg_llm --> svc_llm
+  pkg_llm_deepseek --> svc_llm
+  pkg_llm_pi_ai --> svc_llm
+  pkg_llm_replay --> svc_llm
+  pkg_session --> svc_sessions
+  pkg_session_persistence --> svc_sessionPersistence
+  pkg_session_persistence_jsonl --> svc_sessionPersistence
+  pkg_session_persistence_sqlite --> svc_sessionPersistence
+  pkg_subagent --> svc_subagents
+  pkg_subagent_acp --> svc_subagents
+  pkg_subagent_fork --> svc_subagents
+  pkg_subagent_mock --> svc_subagents
+  pkg_subagent_spawn --> svc_subagents
+  pkg_system_prompt --> svc_systemPrompt
+  pkg_tools --> svc_tools
+  pkg_web --> svc_web
+  pkg_web_fetch_local --> svc_web
+  pkg_web_search_deepseek --> svc_web
+  pkg_web_search_exa --> svc_web
+  pkg_web_search_perplexity --> svc_web
+  svc_agentLoop --> pkg_agent_core
+  svc_agents --> pkg_acp
+  svc_agents --> pkg_agent_loop
+  svc_agents --> pkg_invariants
+  svc_agents --> pkg_stdio_agent
+  svc_agents --> pkg_subagent_inprocess
+  svc_bash --> pkg_hooks_claude
+  svc_bash --> pkg_hooks_codex
+  svc_bash --> pkg_tool_bash
+  svc_compact --> pkg_compact_basic
+  svc_fs --> pkg_tool_fs
+  svc_llm --> pkg_agent_loop
+  svc_llm --> pkg_compact_basic
+  svc_sessionPersistence --> pkg_acp
+  svc_sessionPersistence --> pkg_agent_loop
+  svc_sessions --> pkg_agent
+  svc_sessions --> pkg_agent_loop
+  svc_sessions --> pkg_invariants
+  svc_sessions --> pkg_session_persistence
+  svc_sessions --> pkg_subagent_inprocess
+  svc_subagents --> pkg_tool_subagent
+  svc_systemPrompt --> pkg_agent_loop
+  svc_systemPrompt --> pkg_tool_fs
+  svc_systemPrompt --> pkg_tool_web
+  svc_systemPrompt --> pkg_tools
+  svc_tools --> pkg_acp
+  svc_tools --> pkg_agent_loop
+  svc_tools --> pkg_tool_bash
+  svc_tools --> pkg_tool_fs
+  svc_tools --> pkg_tool_subagent
+  svc_tools --> pkg_tool_todo
+  svc_tools --> pkg_tool_web
+  svc_web --> pkg_tool_web
+  svc_fs -. event gate .-> pkg_fs_policy
+```
+
+| ctx key | Role | Owner | Implementations | Direct consumers | Companion plugins | Note |
+| --- | --- | --- | --- | --- | --- | --- |
+| `ctx.llm` | `seam` | [`llm`](../packages/llm/llm) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), [`llm-replay`](../packages/support/llm-replay) | [`agent-loop`](../packages/core/agent-loop), [`compact-basic`](../packages/compact/compact-basic) | - | Adapters register provider implementations; the loop and compaction call the provider-neutral stream service. |
+| `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`session-persistence`](../packages/session-persistence/session-persistence), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`invariants`](../packages/support/invariants) | - | Owns append-only Session instances and emits the durable session event feed. |
+| `ctx.sessionPersistence` | `seam` | [`session-persistence`](../packages/session-persistence/session-persistence) | [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/ui/acp) | - | Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time. |
+| `ctx.systemPrompt` | `core` | [`system-prompt`](../packages/core/system-prompt) | - | [`agent-loop`](../packages/core/agent-loop), [`tools`](../packages/core/tools), [`tool-fs`](../packages/fs/tool-fs), [`tool-web`](../packages/web/tool-web) | - | Collects prompt sections and model-facing tool schemas for each step. |
+| `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-bash`](../packages/bash/tool-bash), [`tool-fs`](../packages/fs/tool-fs), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web), [`acp`](../packages/ui/acp) | - | Registers tool definitions, exposes schemas to the prompt, and routes calls through tools/pre-execute and tools/post-execute. |
+| `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/ui/acp), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`stdio-agent`](../packages/ui/stdio-agent), [`invariants`](../packages/support/invariants) | - | Owns live Agent handles and the create/resume factory seam. |
+| `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-core`](../packages/core/agent-core) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. |
+| `ctx.bash` | `seam` | [`bash`](../packages/bash/bash) | [`bash-local`](../packages/bash/bash-local) | [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | - | The model-facing bash tools and hook bridges consume this seam; sandboxed or remote executors can replace bash-local. |
+| `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-policy`](../packages/fs/fs-policy) | tool-fs executes read/write/edit through ctx.fs; fs-policy contributes observed-state checks through the fs/* event gate. |
+| `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | The basic backend currently consumes the pre-step event directly; a model-facing compact tool remains deferred. |
+| `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn), [`subagent-fork`](../packages/subagent/subagent-fork), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-mock`](../packages/support/subagent-mock) | [`tool-subagent`](../packages/subagent/tool-subagent) | - | Providers implement transports; tool-subagent exposes one configured provider as a model-facing tool name. |
+| `ctx.web` | `seam` | [`web`](../packages/web/web) | [`web-search-exa`](../packages/web/web-search-exa), [`web-search-perplexity`](../packages/web/web-search-perplexity), [`web-search-deepseek`](../packages/web/web-search-deepseek), [`web-fetch-local`](../packages/web/web-fetch-local) | [`tool-web`](../packages/web/tool-web) | - | Search and fetch providers register into one ctx.web seam; tool-web owns the stable model-facing names. |
+
+Maintenance mode: hybrid: services are discovered from Cordis declarations; interface/implementation/consumer roles are classified in `scripts/gen-doc-graphs.ts` with a completeness guard.
--- a/docs/cordis-catalog/events-and-services.md
+++ b/docs/cordis-catalog/events-and-services.md
@@ -1,21 +1,19 @@
 <!-- Generated by scripts/gen-cordis-catalog.ts — do not edit by hand.
     Run `pnpm run gen-cordis-catalog` to regenerate. -->

-# Cordis Events & Services Catalog
+# Cordis Events Catalog

-An index reference to the **wiring** a plugin author works against: every cordis event you can listen to (exact signature + dispatch mode) and every `ctx.<key>` service you can call (exact public interface). It complements [core-data-structures/](../core-data-structures/core.md), which catalogs the *data structures* these signatures move around — this page is the verbs, that page is the nouns.
+Every cordis event a plugin can listen to: exact signature, dispatch mode, and the declaration's JSDoc. This is one axis of the **wiring** reference a plugin author works against — the callable `ctx.<key>` surface is the sibling [services catalog](services.md), and [core-data-structures/](../core-data-structures/core.md) catalogs the *data structures* these signatures move around.

 This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence (skipped by doc-typecheck, since a bare signature is not standalone-compilable). Type names in a signature link to the page that documents them.

-The **harness tier** below (the `@deepseek-ai/dsh-*` packages) is the vocabulary this repo owns. The **inherited tier** at the end is the cordis-core + loader/hmr/timer surface a plugin also sees — pinned vendor source, summarized tersely.
+The **harness tier** below (the `@deepseek-ai/dsh-*` packages) is the vocabulary this repo owns, grouped by scope. The **inherited tier** at the end is the cordis-core + loader/hmr/timer event surface a plugin also sees — pinned vendor source, summarized tersely.

-## Events
+Dispatch modes: **emit** (fire-and-forget), **waterfall** (each listener gets `next()` and may transform or veto — see [waterfall semantics](../cordis-primer.md#cordis-waterfall-semantics)), **parallel** (awaited fan-out; all listeners run), **serial** (awaited in registration order until one returns a bail value — anything other than `null`, `false`, or `undefined`).

-Dispatch modes: **emit** (fire-and-forget), **waterfall** (each listener gets `next()` and may transform or veto — see [waterfall semantics](../architecture.md#cordis-waterfall-semantics-important)), **parallel** (awaited fan-out; all listeners run), **serial** (awaited in registration order until one returns a bail value — anything other than `null`, `false`, or `undefined`).
+## `agent/*`

-### `agent/*`
-
-#### `agent/created` — emit
+### `agent/created` — emit

 An agent was registered in the AgentRegistry and is ready to receive messages.

@@ -27,7 +25,7 @@ Types: [Agent](../core-data-structures/core.md)

 Source: [`packages/core/agent/src/types.ts:258`](../../packages/core/agent/src/types.ts)

-#### `agent/disposed` — emit
+### `agent/disposed` — emit

 An agent was disposed and removed from the registry; its fiber and any in-flight turn have been torn down.

@@ -39,7 +37,7 @@ Types: [Agent](../core-data-structures/core.md)

 Source: [`packages/core/agent/src/types.ts:265`](../../packages/core/agent/src/types.ts)

-#### `agent/error` — emit
+### `agent/error` — emit

 A step or turn errored. The loop reports a failure here (plus the logger) even when the error has no in-turn position for a session `error` event.

@@ -51,7 +49,7 @@ Types: [Agent](../core-data-structures/core.md)

 Source: [`packages/core/agent/src/types.ts:404`](../../packages/core/agent/src/types.ts)

-#### `agent/pre-step` — serial
+### `agent/pre-step` — serial

 Awaited pre-step surface-mutation checkpoint, fired once per step AFTER `turn/start` (and after the prior step closed) but BEFORE this step's `step/start` — so anything a listener appends lands OUTSIDE the step, between `turn/start`/`step/end` and the upcoming `step/start`. `step` is the number of the step about to start. The loop awaits `ctx.serial('agent/pre-step', …)` after assembling the system prompt, then opens the step and derives the request history ONCE from whatever the surface now holds. This is where compaction belongs: it mutates the session surface in place (shadowing an older range with a summary node) with its log-only `compact/*` records cleanly outside any step, and the single subsequent derive reflects the mutation — so there is no double-derive and no listener can see (or be expected to act on) an assembled `messages` array that does not exist yet.

@@ -65,7 +63,7 @@ Types: [Agent](../core-data-structures/core.md)

 Source: [`packages/core/agent/src/types.ts:343`](../../packages/core/agent/src/types.ts)

-#### `agent/prompt-submit` — waterfall
+### `agent/prompt-submit` — waterfall

 Waterfall: decide what happens to ONE drained queued message before it becomes a `user/message` — allow (optionally rewriting the prompt bytes or attaching `additionalContext`) or block it. Fires inside the already-open turn, per drained message. Maps onto Claude Code's `UserPromptSubmit` hook. Call `next()` to delegate to the default (allow unchanged), or return a PromptDecision without calling `next()` to short-circuit.

@@ -77,7 +75,7 @@ Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-s

 Source: [`packages/core/agent/src/types.ts:356`](../../packages/core/agent/src/types.ts)

-#### `agent/queued` — emit
+### `agent/queued` — emit

 A message entered the agent's inbox (queued or steering). `source` is the resolved source (defaults applied), not the caller's raw options.

@@ -89,7 +87,7 @@ Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-s

 Source: [`packages/core/agent/src/types.ts:283`](../../packages/core/agent/src/types.ts)

-#### `agent/request` — waterfall
+### `agent/request` — waterfall

 Waterfall: mutate the fully-assembled GenerateOptions before the model call (hooks, model switching, tool filtering, …). Call `next()` to delegate, or return without it to short-circuit. For surface mutation that must precede history derivation (compaction), use agent/pre-step instead — by the time this fires, `options.messages` is already derived.

@@ -101,7 +99,7 @@ Types: [Agent](../core-data-structures/core.md) · [GenerateOptions](../core-dat

 Source: [`packages/core/agent/src/types.ts:369`](../../packages/core/agent/src/types.ts)

-#### `agent/session-start` — emit
+### `agent/session-start` — emit

 The agent's session lifecycle began, fired once before its first turn. `source` says why (SessionStartSource: fresh startup, a resumed persisted session, …). A pure NOTIFICATION (emit, not waterfall): it carries no veto — a session-start listener that wants to seed context does so via `agent.inject()` (a `context/message` the first request sees), not by returning a decision. Cannot block the session from starting; that gap is deliberate (a bridge logs/injects, it does not gate startup).

@@ -113,7 +111,7 @@ Types: [Agent](../core-data-structures/core.md)

 Source: [`packages/core/agent/src/types.ts:298`](../../packages/core/agent/src/types.ts)

-#### `agent/status` — emit
+### `agent/status` — emit

 Agent status changed (`idle` ⇄ `running`, or → `disposed`). Drive lifecycle off this transition, never off a status you just requested — `send()` does not flip status to `running` before it returns.

@@ -125,7 +123,7 @@ Types: [Agent](../core-data-structures/core.md)

 Source: [`packages/core/agent/src/types.ts:274`](../../packages/core/agent/src/types.ts)

-#### `agent/step-result` — waterfall
+### `agent/step-result` — waterfall

 Waterfall: post-process the assembled assistant Message before tool dispatch (validation, content rewriting, …).

@@ -137,7 +135,7 @@ Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-struct

 Source: [`packages/core/agent/src/types.ts:379`](../../packages/core/agent/src/types.ts)

-#### `agent/turn-continuation` — waterfall
+### `agent/turn-continuation` — waterfall

 Waterfall: override the turn-continuation decision via a typed ContinuationDecision. The loop's `defaultDecision` is `continue` when the step had tool calls or steering was injected, else `stop`. Listeners force-continue (`/goal`, `/loop` — optionally attaching a `reason` recorded as next-step steering) or force-stop (budget guards). Call `next()` to delegate to the default, or return a decision to override.

@@ -149,9 +147,9 @@ Types: [Agent](../core-data-structures/core.md)

 Source: [`packages/core/agent/src/types.ts:392`](../../packages/core/agent/src/types.ts)

-### `fs/*`
+## `fs/*`

-#### `fs/edit-intent` — waterfall
+### `fs/edit-intent` — waterfall

 Single-slot decision: produce the optional version guard for the next FileSystem.editText. The tool dispatches this as an unbound waterfall and supplies a default thunk returning `undefined` (unconditional edit of the current content — the bare provider; no `stat`). The `@deepseek-ai/dsh-fs-policy` policy listener returns `{ version: vObserved }`, or throws `FS_NOT_OBSERVED` if the actor is unset or has not observed the target. Does NOT call `next()`: one decision, first-wins (see Events.'fs/write-intent').

@@ -163,7 +161,7 @@ Types: [FsTarget](../core-data-structures/filesystem.md) · [FsVersion](../core-

 Source: [`packages/fs/fs/src/index.ts:123`](../../packages/fs/fs/src/index.ts)

-#### `fs/observed` — emit
+### `fs/observed` — emit

 Record that an actor observed a target at a version, after a successful read/write/edit. Fire-and-forget (plain `emit`). A listener MUST be a synchronous, side-effect-only recorder (`@deepseek-ai/dsh-fs-policy`'s is a `WeakMap.set`): the tool does not guard the emit, so a listener that throws surfaces as the tool's `isError` result, and cordis `emit` does not await listener promises — async or fallible audit/telemetry does not belong here. No listener ⇒ nothing recorded. `actor` is the opaque tool-execution context.

@@ -175,7 +173,7 @@ Types: [FsTarget](../core-data-structures/filesystem.md) · [FsVersion](../core-

 Source: [`packages/fs/fs/src/index.ts:138`](../../packages/fs/fs/src/index.ts)

-#### `fs/write-intent` — waterfall
+### `fs/write-intent` — waterfall

 Single-slot decision: produce the write intent for the next FileSystem.writeText. The tool dispatches this as an unbound waterfall (no `this`) and supplies a default thunk returning `undefined` (unconditional create-or-overwrite — the bare provider). The `@deepseek-ai/dsh-fs-policy` policy listener returns `createIfAbsent` (unobserved actor) or `{ kind: 'replaceIfVersion', version: vObserved }` (observed) and does NOT call `next()` — one decision, not a composable chain. The slot is first-wins: the first non-`next()` decider (registration order, or `prepend`) occupies it; a second decider is a misconfiguration, not layering. `actor` is the opaque tool-execution context, never read here.

@@ -187,9 +185,9 @@ Types: [FsTarget](../core-data-structures/filesystem.md) · [FsWriteIntent](../c

 Source: [`packages/fs/fs/src/index.ts:109`](../../packages/fs/fs/src/index.ts)

-### `llm/*`
+## `llm/*`

-#### `llm/stream` — waterfall
+### `llm/stream` — waterfall

 Waterfall around every streaming model call (retry, caching, routing). Bound to the LlmService; call `next()` to reach the resolved adapter's stream, or yield your own chunks to short-circuit.

@@ -201,9 +199,9 @@ Types: [GenerateOptions](../core-data-structures/core.md) · [StreamChunk](../co

 Source: [`packages/llm/llm/src/index.ts:33`](../../packages/llm/llm/src/index.ts)

-### `session/*`
+## `session/*`

-#### `session/created` — emit
+### `session/created` — emit

 A session was created in the store.

@@ -213,7 +211,7 @@ A session was created in the store.

 Source: [`packages/core/session/src/index.ts:36`](../../packages/core/session/src/index.ts)

-#### `session/event` — emit
+### `session/event` — emit

 An event was appended to a session log (sync, fire-and-forget). This is the per-append feed a UI or invariant plugin tails.

@@ -225,7 +223,7 @@ Types: [SessionEvent](../core-data-structures/core.md)

 Source: [`packages/core/session/src/index.ts:44`](../../packages/core/session/src/index.ts)

-#### `session/flush` — parallel
+### `session/flush` — parallel

 Awaited durability checkpoint. The agent loop awaits `ctx.parallel('session/flush', session)` at every turn end; persistence plugins (JSONL, SQLite) drain their write-behind buffers here and on fiber dispose. Awaited (parallel), not a waterfall: every listener runs and the loop waits for all of them, but none can veto.

@@ -235,9 +233,9 @@ Awaited durability checkpoint. The agent loop awaits `ctx.parallel('session/flus

 Source: [`packages/core/session/src/index.ts:54`](../../packages/core/session/src/index.ts)

-### `subagent/*`
+## `subagent/*`

-#### `subagent/end` — emit
+### `subagent/end` — emit

 A subagent run settled — emitted when SubagentRun.result resolves (any stop reason). Paired with Events['subagent/start'].

@@ -247,7 +245,7 @@ A subagent run settled — emitted when SubagentRun.result resolves (any stop re

 Source: [`packages/subagent/subagent/src/index.ts:96`](../../packages/subagent/subagent/src/index.ts)

-#### `subagent/provider-added` — emit
+### `subagent/provider-added` — emit

 A provider became resolvable in the SubagentService registry. Consumers that derive state from a named provider (e.g. the model-facing tool wording in `dsh-tool-subagent`) react HERE instead of assuming load order — the cordis Loader starts sibling plugins concurrently, so "listed earlier in cordis.yml" does not mean "registered earlier".

@@ -257,7 +255,7 @@ A provider became resolvable in the SubagentService registry. Consumers that der

 Source: [`packages/subagent/subagent/src/index.ts:72`](../../packages/subagent/subagent/src/index.ts)

-#### `subagent/provider-removed` — emit
+### `subagent/provider-removed` — emit

 A provider left the registry (its plugin's fiber was disposed — an unload or an HMR reload). Consumers holding provider-derived state drop it here; a reload re-fires `subagent/provider-added` with the fresh provider.

@@ -267,7 +265,7 @@ A provider left the registry (its plugin's fiber was disposed — an unload or a

 Source: [`packages/subagent/subagent/src/index.ts:81`](../../packages/subagent/subagent/src/index.ts)

-#### `subagent/start` — emit
+### `subagent/start` — emit

 A subagent run started — emitted after the provider is resolved and its capabilities validated, as the child run begins. Paired with Events['subagent/end'].

@@ -277,9 +275,9 @@ A subagent run started — emitted after the provider is resolved and its capabi

 Source: [`packages/subagent/subagent/src/index.ts:89`](../../packages/subagent/subagent/src/index.ts)

-### `system-prompt/*`
+## `system-prompt/*`

-#### `system-prompt/assemble` — waterfall
+### `system-prompt/assemble` — waterfall

 Waterfall around prompt assembly — mutate or extend the PromptAssembly (sections + tools + variables) before it is rendered. Bound to the SystemPrompt service; call `next()` to delegate.

@@ -289,7 +287,7 @@ Waterfall around prompt assembly — mutate or extend the PromptAssembly (sectio

 Source: [`packages/core/system-prompt/src/index.ts:32`](../../packages/core/system-prompt/src/index.ts)

-#### `system-prompt/change` — emit
+### `system-prompt/change` — emit

 A section, tool provider, or variable provider was registered or unregistered (the assembly inputs changed).

@@ -299,9 +297,9 @@ A section, tool provider, or variable provider was registered or unregistered (t

 Source: [`packages/core/system-prompt/src/index.ts:38`](../../packages/core/system-prompt/src/index.ts)

-### `tools/*`
+## `tools/*`

-#### `tools/change` — emit
+### `tools/change` — emit

 A tool was registered or unregistered (the available tool set changed).

@@ -311,7 +309,7 @@ A tool was registered or unregistered (the available tool set changed).

 Source: [`packages/core/tools/src/index.ts:87`](../../packages/core/tools/src/index.ts)

-#### `tools/post-execute` — waterfall
+### `tools/post-execute` — waterfall

 Waterfall AFTER a tool runs — where hook plugins inspect the result and accept it (optionally REPLACING the model-facing content, and/or attaching `additionalContext` for the next request) or block it with corrective `feedback` (Claude Code's `PostToolUse`). Listeners receive `(exec, result, next)`: call `next()` to delegate to the default (accept unchanged), or return a PostToolDecision to override. The core tool dispatch sits between the two waterfalls as plain code, all inside `execute`'s outer try/catch (and the tool body keeps its own inner try/catch, so a thrown tool still reaches `post-execute` as an `isError` result).

@@ -323,7 +321,7 @@ Types: [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult

 Source: [`packages/core/tools/src/index.ts:82`](../../packages/core/tools/src/index.ts)

-#### `tools/pre-execute` — waterfall
+### `tools/pre-execute` — waterfall

 Waterfall BEFORE a tool runs — the gate where sandbox, permission, and hook plugins allow or deny a call (Claude Code's `PreToolUse`). Listeners receive `(exec, next)`: call `next()` to delegate to the default (allow), or return a PreToolDecision without calling `next()` to short-circuit. A `deny` skips dispatch and yields an `isError` result; the tool body never runs. Input rewrite is deliberately NOT offered here (see PreToolDecision); `ask` degrades to deny until the permission system lands (`FIXME(permissions)`).

@@ -335,234 +333,9 @@ Types: [ToolExecution](../core-data-structures/tools.md)

 Source: [`packages/core/tools/src/index.ts:66`](../../packages/core/tools/src/index.ts)

-## Services
+## Inherited events (cordis core + loader/hmr/timer)

-The `ctx.<key>` services the harness provides. An abstract seam (e.g. `ctx.bash`) is implemented by a separate package; the interface is what consumers code against.
-
-### `ctx.agentLoop` — `AgentLoop`
-
-The agent-loop plugin (`ctx.agentLoop`): creates ReactLoopAgents, runs their loops, and registers them in `ctx.agents`. Also implements the AgentFactory seam, so plugins create/resume agents through `ctx.agents` (the interface) without depending on this concrete package.
-
-The loop itself is deliberately thin — every behavior beyond "call the model, run the tools, repeat" belongs to plugins listening on the event taxonomy declared in @deepseek-ai/dsh-agent.
-
-```ts cordis-catalog
-create(id: AgentId, options: AgentOptions = {}): ReactLoopAgent
-createAgent(options: CreateAgentOptions): AgentHandle
-async resume(options: ResumeAgentOptions): Promise<AgentHandle>
-```
-
-Source: [`packages/core/agent-loop/src/index.ts:63`](../../packages/core/agent-loop/src/index.ts)
-
-### `ctx.agents` — `AgentRegistry`
-
-Agent registry (`ctx.agents`): tracks live agents so UI, hook, and orchestrator plugins can find them without depending on the concrete loop package. Agent *creation* is provided by whichever plugin implements the AgentFactory (phase 1: `@deepseek-ai/dsh-agent-loop`), registered via setFactory.
-
-```ts cordis-catalog
-setFactory(factory: AgentFactory): () => void
-create(options: CreateAgentOptions): AgentHandle
-async resume(options: ResumeAgentOptions): Promise<AgentHandle>
-register(agent: Agent): () => void
-get(id: AgentId): Agent | undefined
-list(): Agent[]
-```
-
-Types: [Agent](../core-data-structures/core.md)
-
-Source: [`packages/core/agent/src/index.ts:117`](../../packages/core/agent/src/index.ts)
-
-### `ctx.bash` — `BashExecutor` (abstract seam)
-
-Abstract bash execution service. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.bash` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
-
-Semantics every implementation must honor:
-
- run REJECTS only for infrastructure failures (unusable workdir, missing shell, pre-aborted signal). Nonzero exits, timeout kills, and abort kills RESOLVE with a descriptive BashRunResult — reporting a failed command is the tool layer's job, not an exception.
- start returns immediately; no timeout applies to background tasks (callers stop them via kill or the spec's AbortSignal). Completion must fire the onTaskDone listeners exactly once per task, and must NOT fire after the service is disposed.
- readOutput is incremental: consecutive reads never re-deliver output. Implementations bound their buffers; reads that lost data flag `lossy` and point at full-stream spill files when available.
- Disposal kills every running task and awaits their exit (no orphan processes survive `fiber.dispose()`).
-
-```ts cordis-catalog
-abstract resolve(request: BashExecRequest): BashExecSpec
-abstract run(spec: BashExecSpec): Promise<BashRunResult>
-abstract start(spec: BashExecSpec): BashTask
-abstract get(id: BashTaskId): BashTask | undefined
-abstract ownerOf(id: BashTaskId): OwnerToken | undefined
-abstract list(): BashTask[]
-abstract readOutput(id: BashTaskId): BashTaskRead
-abstract kill(id: BashTaskId): boolean
-onTaskDone(listener: BashTaskListener): () => void
-```
-
-Types: [BashExecRequest](../core-data-structures/bash.md) · [BashExecSpec](../core-data-structures/bash.md) · [BashRunResult](../core-data-structures/bash.md) · [BashTask](../core-data-structures/bash.md) · [BashTaskRead](../core-data-structures/bash.md)
-
-Source: [`packages/bash/bash/src/index.ts:59`](../../packages/bash/bash/src/index.ts)
-
-### `ctx.compact` — `CompactService` (abstract seam)
-
-Abstract compaction service. Subclass implement the two abstract methods, and load the subclass as a plugin — it registers as `ctx.compact` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
-
-Both core methods are abstract: the contract states WHAT compaction does, while the entire strategy — token estimation, retention policy, event sequencing, summarization — is a HOW decision owned by the implementation.
-
-Implementations MUST honor:
-
- **Surface contract**: a successful compaction shadows the compacted surface nodes with a SINGLE replacement node carrying the summary. Because `SurfaceEventType` is a closed union, that node is a `user/message` with `surfaceOp: { op:'replace', start, end }`; the `compact/*` events are log-only (lock + provenance).
- **Blocking**: no compaction begins while another is in progress for the same session. The recommended mechanism is the log-recorded lock — append `compact/start` before the slow work and `compact/end` after (even on failure) — so the lock is visible to replay and crash recovery.
-
-```ts cordis-catalog
-abstract compactIfNeeded( agent: CompactAgentContext, turn: number, step: number, fullSystemPrompt: string, signal: AbortSignal, ): Promise<CompactionResult | null>
-abstract compactRegion( session: Session, start: number, end: number, agent: CompactAgentContext, turn: number, step: number, signal?: AbortSignal, ): Promise<CompactionResult>
-```
-
-Source: [`packages/compact/compact/src/index.ts:63`](../../packages/compact/compact/src/index.ts)
-
-### `ctx.fs` — `FileSystem` (abstract seam)
-
-Abstract filesystem provider service. Subclass, implement the seven storage primitives, and load the subclass as a plugin — it registers as `ctx.fs` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior).
-
-Semantics every backend must honor:
-
- resolve returns a stable FsTarget; the same underlying file reached by different input paths must yield the same `targetKey` so stale guards and target lookup agree across paths (e.g. through symlinks).
- stat returns FsInfo metadata (never content) or `undefined` when the target is absent.
- readText/streamText read the whole regular text file (the stream for large files); both own regular-file checks, UTF-8 decoding, binary/NUL rejection, and `FS_NOT_TEXT`.
- listDir returns direct children of a directory in stable name order with resolved child targets and cheap metadata only. It never reads file contents. Missing targets throw `FS_NOT_FOUND`, non-directories throw `FS_NOT_DIRECTORY`, permission failures throw `FS_PERMISSION_DENIED`, and other backend I/O failures throw `FS_IO_ERROR`.
- writeText is atomic temp-file + rename. `expected` is OPTIONAL: omit it for an unconditional create-or-overwrite (the bare-provider default), or supply a FsWriteIntent to guard the write.
- editText verifies `expected.version` BEFORE literal matching (so a stale edit reports `FS_STALE_VERSION`, not `FS_EDIT_NOT_FOUND`/ `FS_AMBIGUOUS_EDIT` against newer content), then applies literal replacement and writes atomically — all inside one mutation critical section. `expected` is OPTIONAL: omit it for an unconditional edit of the current content (a missing target still reports `FS_STALE_VERSION`).
-
-```ts cordis-catalog
-abstract resolve(path: string, opts?: { cwd?: string }): Promise<FsTarget>
-abstract stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>
-abstract readText(target: FsTarget, signal?: AbortSignal): Promise<string>
-abstract streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>
-abstract listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>
-abstract writeText(target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal): Promise<FsWriteOutcome>
-abstract editText(target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal): Promise<FsEditOutcome>
-```
-
-Types: [FsEditOutcome](../core-data-structures/filesystem.md) · [FsEditRequest](../core-data-structures/filesystem.md) · [FsInfo](../core-data-structures/filesystem.md) · [FsTarget](../core-data-structures/filesystem.md) · [FsVersion](../core-data-structures/filesystem.md) · [FsWriteIntent](../core-data-structures/filesystem.md) · [FsWriteOutcome](../core-data-structures/filesystem.md)
-
-Source: [`packages/fs/fs/src/index.ts:172`](../../packages/fs/fs/src/index.ts)
-
-### `ctx.llm` — `LlmService`
-
-The abstract `llm` service: an adapter registry plus a streaming model-call surface, interceptable via the `llm/stream` waterfall.
-
-```ts cordis-catalog
-registerAdapter(models: string[], adapter: LlmAdapter): () => void
-models(): string[]
-stream(options: GenerateOptions): AsyncIterable<StreamChunk>
-```
-
-Types: [GenerateOptions](../core-data-structures/core.md) · [StreamChunk](../core-data-structures/llm-streaming.md)
-
-Source: [`packages/llm/llm/src/index.ts:78`](../../packages/llm/llm/src/index.ts)
-
-### `ctx.sessionPersistence` — `SessionPersistence` (abstract seam)
-
-Abstract durable session-persistence service. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.sessionPersistence` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior).
-
-Contracts every implementation MUST honor (a DB backend asserts them inside a transaction; a file backend appends at EOF):
-
- **Append-only; a crashed turn is closed, not truncated.** Committed events — those at or below a flushed `turn/end` — are never rewritten. A crash can leave an unclosed final turn whose events are real (and possibly large); load preserves them and closes the orphaned turn with synthetic boundary events (see load). Only a never-fully-written torn tail fragment is discarded.
- **Contiguous seq.** A persisted log is contiguous: `events[i].seq === i`. load rejects a parse error or a `seq` gap in the COMMITTED region (unloadable); append's first event `seq` MUST equal the backend's stored next-seq (after `load` has balanced any interrupted turn).
- **JSON-serializable data.** `SessionEventMap` is merge-extensible and `event.data` is typed only as `SessionEventMap[K]`, so append REJECTS non-JSON-serializable data with an error naming the offending event type. A backend snapshots (serializes/clones) each event when it buffers, since `session.events` hands out the live mutable object.
- **Durability.** append returns only once the batch is durable (the file backend fsyncs; a DB commits). create MAY defer the physical write until the first append (lazy materialization).
-
-```ts cordis-catalog
-abstract create(meta: SessionHeader): Promise<void>
-abstract append(id: SessionId, events: readonly SessionEvent[]): Promise<void>
-abstract load(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }>
-abstract list(): Promise<SessionHeader[]>
-```
-
-Types: [SessionEvent](../core-data-structures/core.md)
-
-Source: [`packages/session-persistence/session-persistence/src/index.ts:98`](../../packages/session-persistence/session-persistence/src/index.ts)
-
-### `ctx.sessions` — `SessionStore`
-
-In-memory session store (`ctx.sessions`).
-
-Persistence is intentionally not implemented here — persistence plugins subscribe to `session/event` and flush on `session/flush` / dispose.
-
-```ts cordis-catalog
-create(id?: SessionId, options?: CreateSessionOptions): Session
-prepare(id?: SessionId, options?: CreateSessionOptions): Session
-enter(session: Session): () => void
-announce(session: Session): void
-get(id: SessionId): Session | undefined
-list(): Session[]
-```
-
-Source: [`packages/core/session/src/index.ts:327`](../../packages/core/session/src/index.ts)
-
-### `ctx.subagents` — `SubagentService`
-
-The `subagents` service: a registry of named SubagentProviders and a capability-checked start surface.
-
-```ts cordis-catalog
-registerProvider(provider: SubagentProvider): () => void
-getProvider(name: string): SubagentProvider | undefined
-list(): string[]
-start(name: string, request: SubagentStartRequest): SubagentRun
-```
-
-Source: [`packages/subagent/subagent/src/index.ts:142`](../../packages/subagent/subagent/src/index.ts)
-
-### `ctx.systemPrompt` — `SystemPrompt`
-
-Registry service (`ctx.systemPrompt`): plugins contribute ordered text sections, tool-schema providers, and named prompt variables; the agent loop calls `assemble(context)` once per step.
-
-```ts cordis-catalog
-section(section: PromptSection): () => void
-tools(provider: () => ToolSchema[]): () => void
-variable(name: string, provider: (context: AssembleContext) => string | undefined): () => void
-assemble(context: AssembleContext = {}): Promise<PromptAssembly>
-```
-
-Source: [`packages/core/system-prompt/src/index.ts:174`](../../packages/core/system-prompt/src/index.ts)
-
-### `ctx.tools` — `ToolRegistry`
-
-Tool registry (`ctx.tools`): tool plugins register definitions; the agent loop executes calls through the `tools/pre-execute` → dispatch → `tools/post-execute` pipeline. The registry contributes its schemas into the system-prompt assembly.
-
-```ts cordis-catalog
-register(definition: ToolDefinition): () => void
-get(name: string): ToolDefinition | undefined
-schemas(): ToolSchema[]
-async execute(exec: ToolExecution): Promise<ToolExecutionResult>
-```
-
-Types: [ToolDefinition](../core-data-structures/tools.md) · [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md)
-
-Source: [`packages/core/tools/src/index.ts:268`](../../packages/core/tools/src/index.ts)
-
-### `ctx.web` — `WebService`
-
-The web access service. Registered as `ctx.web` (one instance per context).
-
-Selection semantics (resolved at execution time, never order-dependent):
-
- A configured id that is registered and `status().available` → that provider.
- A configured id not registered → `WEB_PROVIDER_CONFIGURED_MISSING`.
- A configured id registered but unavailable → `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`.
- No id configured, exactly one registered usable provider → that provider.
- No id configured, multiple usable providers → `WEB_PROVIDER_AMBIGUOUS`.
- No id configured, no usable provider → `WEB_PROVIDER_UNAVAILABLE`.
-
-```ts cordis-catalog
-registerSearchProvider(provider: WebSearchProvider): () => void
-registerFetchProvider(provider: WebFetchProvider): () => void
-async search(request: WebSearchRequest, exec?: WebExecContext): Promise<WebSearchResult>
-async fetch(request: WebFetchRequest, exec?: WebExecContext): Promise<WebFetchResult>
-```
-
-Source: [`packages/web/web/src/index.ts:87`](../../packages/web/web/src/index.ts)
-
-## Inherited tier (cordis core + loader/hmr/timer)
-
-The framework surface every plugin inherits, beyond the harness vocabulary above. This is pinned vendor source ([vendoring policy](../../vendor/README.md)); it is summarized here so the catalog is a complete picture of what `ctx` and the event bus offer, without elevating framework internals to the harness tier's prominence.
-
-### Inherited events
+The framework events every plugin also sees, beyond the harness vocabulary above. This is pinned vendor source ([vendoring policy](../../vendor/README.md)); it is summarized here so the page is a complete picture of the event bus, without elevating framework internals to the harness tier's prominence.

 - `internal/plugin` — A plugin fiber was created. ([`vendor/cordis/src/events.ts:197`](../../vendor/cordis/src/events.ts))
 - `internal/status` — A fiber changed lifecycle state. ([`vendor/cordis/src/events.ts:198`](../../vendor/cordis/src/events.ts))
@@ -579,16 +352,3 @@ The framework surface every plugin inherits, beyond the harness vocabulary above
 - `loader/entry-init` — A config entry is being initialized. ([`vendor/loader/src/index.ts:25`](../../vendor/loader/src/index.ts))
 - `loader/partial-dispose` — An entry is being partially disposed on reload. ([`vendor/loader/src/index.ts:26`](../../vendor/loader/src/index.ts))
 - `loader/patch-context` — A context is being patched during a reload. ([`vendor/loader/src/index.ts:27`](../../vendor/loader/src/index.ts))
-
-### Inherited `ctx` members
-
- `ctx.on / ctx.once` — Register an event listener (disposable). ([`vendor/cordis/src/events.ts:29`](../../vendor/cordis/src/events.ts))
- `ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall` — Dispatch an event (sync / awaited / first-bail / veto-chain). ([`vendor/cordis/src/events.ts:29`](../../vendor/cordis/src/events.ts))
- `ctx.plugin / ctx.inject` — Load a plugin / declare required services. ([`vendor/cordis/src/registry.ts:144`](../../vendor/cordis/src/registry.ts))
- `ctx.effect` — Register a disposable side effect tied to the fiber. ([`vendor/cordis/src/fiber.ts:9`](../../vendor/cordis/src/fiber.ts))
- `ctx.get / ctx.set / ctx.provide / ctx.accessor / ctx.mixin` — Low-level service-store access and binding. ([`vendor/cordis/src/reflect.ts:7`](../../vendor/cordis/src/reflect.ts))
- `ctx.extend / ctx.isolate / ctx.intercept` — Derive a child context (scoped services / isolation / interception). ([`vendor/cordis/src/context.ts:35`](../../vendor/cordis/src/context.ts))
- `ctx.root / ctx.scope / ctx.fiber / ctx.registry / ctx.reflect / ctx.events / ctx.logger` — Ambient handles onto the running context graph. ([`vendor/cordis/src/context.ts:16`](../../vendor/cordis/src/context.ts))
- `ctx.timer (+ interval / timeout / throttle / debounce / setTimeout / setInterval)` — Disposable timer helpers. The `timer` key is provided at runtime; the six helpers are mixed onto ctx directly (declared via Pick). ([`vendor/timer/src/index.ts:4`](../../vendor/timer/src/index.ts))
- `ctx.loader` — The config Loader that booted the app (present under the loader). ([`vendor/loader/src/index.ts:30`](../../vendor/loader/src/index.ts))
- `ctx.hmr` — The hot-module-reload watcher (present under the hmr plugin). ([`vendor/hmr/src/index.ts:15`](../../vendor/hmr/src/index.ts))
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -0,0 +1,244 @@
+<!-- Generated by scripts/gen-cordis-catalog.ts — do not edit by hand.
+     Run `pnpm run gen-cordis-catalog` to regenerate. -->
+
+# Cordis Services Catalog
+
+Every `ctx.<key>` service a plugin can call: the exact public interface plus the class JSDoc. This is one axis of the **wiring** reference a plugin author works against — the events a plugin listens to are the sibling [events catalog](events.md), and [core-data-structures/](../core-data-structures/core.md) catalogs the *data structures* these signatures move around. An abstract seam (e.g. `ctx.bash`) is implemented by a separate package; the interface is what consumers code against.
+
+This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence (skipped by doc-typecheck, since a bare signature is not standalone-compilable). Type names in a signature link to the page that documents them.
+
+The **harness tier** below (the `@deepseek-ai/dsh-*` packages) is the vocabulary this repo owns. The **inherited tier** at the end is the cordis-core + loader/hmr/timer `ctx` surface a plugin also sees — pinned vendor source, summarized tersely.
+
+## `ctx.agentLoop` — `AgentLoop`
+
+The agent-loop plugin (`ctx.agentLoop`): creates ReactLoopAgents, runs their loops, and registers them in `ctx.agents`. Also implements the AgentFactory seam, so plugins create/resume agents through `ctx.agents` (the interface) without depending on this concrete package.
+
+The loop itself is deliberately thin — every behavior beyond "call the model, run the tools, repeat" belongs to plugins listening on the event taxonomy declared in @deepseek-ai/dsh-agent.
+
+```ts cordis-catalog
+create(id: AgentId, options: AgentOptions = {}): ReactLoopAgent
+createAgent(options: CreateAgentOptions): AgentHandle
+async resume(options: ResumeAgentOptions): Promise<AgentHandle>
+```
+
+Source: [`packages/core/agent-loop/src/index.ts:63`](../../packages/core/agent-loop/src/index.ts)
+
+## `ctx.agents` — `AgentRegistry`
+
+Agent registry (`ctx.agents`): tracks live agents so UI, hook, and orchestrator plugins can find them without depending on the concrete loop package. Agent *creation* is provided by whichever plugin implements the AgentFactory (phase 1: `@deepseek-ai/dsh-agent-loop`), registered via setFactory.
+
+```ts cordis-catalog
+setFactory(factory: AgentFactory): () => void
+create(options: CreateAgentOptions): AgentHandle
+async resume(options: ResumeAgentOptions): Promise<AgentHandle>
+register(agent: Agent): () => void
+get(id: AgentId): Agent | undefined
+list(): Agent[]
+```
+
+Types: [Agent](../core-data-structures/core.md)
+
+Source: [`packages/core/agent/src/index.ts:117`](../../packages/core/agent/src/index.ts)
+
+## `ctx.bash` — `BashExecutor` (abstract seam)
+
+Abstract bash execution service. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.bash` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
+
+Semantics every implementation must honor:
+
+- run REJECTS only for infrastructure failures (unusable workdir, missing shell, pre-aborted signal). Nonzero exits, timeout kills, and abort kills RESOLVE with a descriptive BashRunResult — reporting a failed command is the tool layer's job, not an exception.
+- start returns immediately; no timeout applies to background tasks (callers stop them via kill or the spec's AbortSignal). Completion must fire the onTaskDone listeners exactly once per task, and must NOT fire after the service is disposed.
+- readOutput is incremental: consecutive reads never re-deliver output. Implementations bound their buffers; reads that lost data flag `lossy` and point at full-stream spill files when available.
+- Disposal kills every running task and awaits their exit (no orphan processes survive `fiber.dispose()`).
+
+```ts cordis-catalog
+abstract resolve(request: BashExecRequest): BashExecSpec
+abstract run(spec: BashExecSpec): Promise<BashRunResult>
+abstract start(spec: BashExecSpec): BashTask
+abstract get(id: BashTaskId): BashTask | undefined
+abstract ownerOf(id: BashTaskId): OwnerToken | undefined
+abstract list(): BashTask[]
+abstract readOutput(id: BashTaskId): BashTaskRead
+abstract kill(id: BashTaskId): boolean
+onTaskDone(listener: BashTaskListener): () => void
+```
+
+Types: [BashExecRequest](../core-data-structures/bash.md) · [BashExecSpec](../core-data-structures/bash.md) · [BashRunResult](../core-data-structures/bash.md) · [BashTask](../core-data-structures/bash.md) · [BashTaskRead](../core-data-structures/bash.md)
+
+Source: [`packages/bash/bash/src/index.ts:59`](../../packages/bash/bash/src/index.ts)
+
+## `ctx.compact` — `CompactService` (abstract seam)
+
+Abstract compaction service. Subclass implement the two abstract methods, and load the subclass as a plugin — it registers as `ctx.compact` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
+
+Both core methods are abstract: the contract states WHAT compaction does, while the entire strategy — token estimation, retention policy, event sequencing, summarization — is a HOW decision owned by the implementation.
+
+Implementations MUST honor:
+
+- **Surface contract**: a successful compaction shadows the compacted surface nodes with a SINGLE replacement node carrying the summary. Because `SurfaceEventType` is a closed union, that node is a `user/message` with `surfaceOp: { op:'replace', start, end }`; the `compact/*` events are log-only (lock + provenance).
+- **Blocking**: no compaction begins while another is in progress for the same session. The recommended mechanism is the log-recorded lock — append `compact/start` before the slow work and `compact/end` after (even on failure) — so the lock is visible to replay and crash recovery.
+
+```ts cordis-catalog
+abstract compactIfNeeded( agent: CompactAgentContext, turn: number, step: number, fullSystemPrompt: string, signal: AbortSignal, ): Promise<CompactionResult | null>
+abstract compactRegion( session: Session, start: number, end: number, agent: CompactAgentContext, turn: number, step: number, signal?: AbortSignal, ): Promise<CompactionResult>
+```
+
+Source: [`packages/compact/compact/src/index.ts:63`](../../packages/compact/compact/src/index.ts)
+
+## `ctx.fs` — `FileSystem` (abstract seam)
+
+Abstract filesystem provider service. Subclass, implement the seven storage primitives, and load the subclass as a plugin — it registers as `ctx.fs` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior).
+
+Semantics every backend must honor:
+
+- resolve returns a stable FsTarget; the same underlying file reached by different input paths must yield the same `targetKey` so stale guards and target lookup agree across paths (e.g. through symlinks).
+- stat returns FsInfo metadata (never content) or `undefined` when the target is absent.
+- readText/streamText read the whole regular text file (the stream for large files); both own regular-file checks, UTF-8 decoding, binary/NUL rejection, and `FS_NOT_TEXT`.
+- listDir returns direct children of a directory in stable name order with resolved child targets and cheap metadata only. It never reads file contents. Missing targets throw `FS_NOT_FOUND`, non-directories throw `FS_NOT_DIRECTORY`, permission failures throw `FS_PERMISSION_DENIED`, and other backend I/O failures throw `FS_IO_ERROR`.
+- writeText is atomic temp-file + rename. `expected` is OPTIONAL: omit it for an unconditional create-or-overwrite (the bare-provider default), or supply a FsWriteIntent to guard the write.
+- editText verifies `expected.version` BEFORE literal matching (so a stale edit reports `FS_STALE_VERSION`, not `FS_EDIT_NOT_FOUND`/ `FS_AMBIGUOUS_EDIT` against newer content), then applies literal replacement and writes atomically — all inside one mutation critical section. `expected` is OPTIONAL: omit it for an unconditional edit of the current content (a missing target still reports `FS_STALE_VERSION`).
+
+```ts cordis-catalog
+abstract resolve(path: string, opts?: { cwd?: string }): Promise<FsTarget>
+abstract stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>
+abstract readText(target: FsTarget, signal?: AbortSignal): Promise<string>
+abstract streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>
+abstract listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>
+abstract writeText(target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal): Promise<FsWriteOutcome>
+abstract editText(target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal): Promise<FsEditOutcome>
+```
+
+Types: [FsEditOutcome](../core-data-structures/filesystem.md) · [FsEditRequest](../core-data-structures/filesystem.md) · [FsInfo](../core-data-structures/filesystem.md) · [FsTarget](../core-data-structures/filesystem.md) · [FsVersion](../core-data-structures/filesystem.md) · [FsWriteIntent](../core-data-structures/filesystem.md) · [FsWriteOutcome](../core-data-structures/filesystem.md)
+
+Source: [`packages/fs/fs/src/index.ts:172`](../../packages/fs/fs/src/index.ts)
+
+## `ctx.llm` — `LlmService`
+
+The abstract `llm` service: an adapter registry plus a streaming model-call surface, interceptable via the `llm/stream` waterfall.
+
+```ts cordis-catalog
+registerAdapter(models: string[], adapter: LlmAdapter): () => void
+models(): string[]
+stream(options: GenerateOptions): AsyncIterable<StreamChunk>
+```
+
+Types: [GenerateOptions](../core-data-structures/core.md) · [StreamChunk](../core-data-structures/llm-streaming.md)
+
+Source: [`packages/llm/llm/src/index.ts:78`](../../packages/llm/llm/src/index.ts)
+
+## `ctx.sessionPersistence` — `SessionPersistence` (abstract seam)
+
+Abstract durable session-persistence service. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.sessionPersistence` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior).
+
+Contracts every implementation MUST honor (a DB backend asserts them inside a transaction; a file backend appends at EOF):
+
+- **Append-only; a crashed turn is closed, not truncated.** Committed events — those at or below a flushed `turn/end` — are never rewritten. A crash can leave an unclosed final turn whose events are real (and possibly large); load preserves them and closes the orphaned turn with synthetic boundary events (see load). Only a never-fully-written torn tail fragment is discarded.
+- **Contiguous seq.** A persisted log is contiguous: `events[i].seq === i`. load rejects a parse error or a `seq` gap in the COMMITTED region (unloadable); append's first event `seq` MUST equal the backend's stored next-seq (after `load` has balanced any interrupted turn).
+- **JSON-serializable data.** `SessionEventMap` is merge-extensible and `event.data` is typed only as `SessionEventMap[K]`, so append REJECTS non-JSON-serializable data with an error naming the offending event type. A backend snapshots (serializes/clones) each event when it buffers, since `session.events` hands out the live mutable object.
+- **Durability.** append returns only once the batch is durable (the file backend fsyncs; a DB commits). create MAY defer the physical write until the first append (lazy materialization).
+
+```ts cordis-catalog
+abstract create(meta: SessionHeader): Promise<void>
+abstract append(id: SessionId, events: readonly SessionEvent[]): Promise<void>
+abstract load(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }>
+abstract list(): Promise<SessionHeader[]>
+```
+
+Types: [SessionEvent](../core-data-structures/core.md)
+
+Source: [`packages/session-persistence/session-persistence/src/index.ts:98`](../../packages/session-persistence/session-persistence/src/index.ts)
+
+## `ctx.sessions` — `SessionStore`
+
+In-memory session store (`ctx.sessions`).
+
+Persistence is intentionally not implemented here — persistence plugins subscribe to `session/event` and flush on `session/flush` / dispose.
+
+```ts cordis-catalog
+create(id?: SessionId, options?: CreateSessionOptions): Session
+prepare(id?: SessionId, options?: CreateSessionOptions): Session
+enter(session: Session): () => void
+announce(session: Session): void
+get(id: SessionId): Session | undefined
+list(): Session[]
+```
+
+Source: [`packages/core/session/src/index.ts:327`](../../packages/core/session/src/index.ts)
+
+## `ctx.subagents` — `SubagentService`
+
+The `subagents` service: a registry of named SubagentProviders and a capability-checked start surface.
+
+```ts cordis-catalog
+registerProvider(provider: SubagentProvider): () => void
+getProvider(name: string): SubagentProvider | undefined
+list(): string[]
+start(name: string, request: SubagentStartRequest): SubagentRun
+```
+
+Source: [`packages/subagent/subagent/src/index.ts:142`](../../packages/subagent/subagent/src/index.ts)
+
+## `ctx.systemPrompt` — `SystemPrompt`
+
+Registry service (`ctx.systemPrompt`): plugins contribute ordered text sections, tool-schema providers, and named prompt variables; the agent loop calls `assemble(context)` once per step.
+
+```ts cordis-catalog
+section(section: PromptSection): () => void
+tools(provider: () => ToolSchema[]): () => void
+variable(name: string, provider: (context: AssembleContext) => string | undefined): () => void
+assemble(context: AssembleContext = {}): Promise<PromptAssembly>
+```
+
+Source: [`packages/core/system-prompt/src/index.ts:174`](../../packages/core/system-prompt/src/index.ts)
+
+## `ctx.tools` — `ToolRegistry`
+
+Tool registry (`ctx.tools`): tool plugins register definitions; the agent loop executes calls through the `tools/pre-execute` → dispatch → `tools/post-execute` pipeline. The registry contributes its schemas into the system-prompt assembly.
+
+```ts cordis-catalog
+register(definition: ToolDefinition): () => void
+get(name: string): ToolDefinition | undefined
+schemas(): ToolSchema[]
+async execute(exec: ToolExecution): Promise<ToolExecutionResult>
+```
+
+Types: [ToolDefinition](../core-data-structures/tools.md) · [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md)
+
+Source: [`packages/core/tools/src/index.ts:268`](../../packages/core/tools/src/index.ts)
+
+## `ctx.web` — `WebService`
+
+The web access service. Registered as `ctx.web` (one instance per context).
+
+Selection semantics (resolved at execution time, never order-dependent):
+
+- A configured id that is registered and `status().available` → that provider.
+- A configured id not registered → `WEB_PROVIDER_CONFIGURED_MISSING`.
+- A configured id registered but unavailable → `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`.
+- No id configured, exactly one registered usable provider → that provider.
+- No id configured, multiple usable providers → `WEB_PROVIDER_AMBIGUOUS`.
+- No id configured, no usable provider → `WEB_PROVIDER_UNAVAILABLE`.
+
+```ts cordis-catalog
+registerSearchProvider(provider: WebSearchProvider): () => void
+registerFetchProvider(provider: WebFetchProvider): () => void
+async search(request: WebSearchRequest, exec?: WebExecContext): Promise<WebSearchResult>
+async fetch(request: WebFetchRequest, exec?: WebExecContext): Promise<WebFetchResult>
+```
+
+Source: [`packages/web/web/src/index.ts:87`](../../packages/web/web/src/index.ts)
+
+## Inherited `ctx` members (cordis core + loader/hmr/timer)
+
+The framework `ctx` surface every plugin also sees, beyond the harness services above. This is pinned vendor source ([vendoring policy](../../vendor/README.md)); it is summarized here so the page is a complete picture of what `ctx` offers, without elevating framework internals to the harness tier's prominence.
+
+- `ctx.on / ctx.once` — Register an event listener (disposable). ([`vendor/cordis/src/events.ts:29`](../../vendor/cordis/src/events.ts))
+- `ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall` — Dispatch an event (sync / awaited / first-bail / veto-chain). ([`vendor/cordis/src/events.ts:29`](../../vendor/cordis/src/events.ts))
+- `ctx.plugin / ctx.inject` — Load a plugin / declare required services. ([`vendor/cordis/src/registry.ts:144`](../../vendor/cordis/src/registry.ts))
+- `ctx.effect` — Register a disposable side effect tied to the fiber. ([`vendor/cordis/src/fiber.ts:9`](../../vendor/cordis/src/fiber.ts))
+- `ctx.get / ctx.set / ctx.provide / ctx.accessor / ctx.mixin` — Low-level service-store access and binding. ([`vendor/cordis/src/reflect.ts:7`](../../vendor/cordis/src/reflect.ts))
+- `ctx.extend / ctx.isolate / ctx.intercept` — Derive a child context (scoped services / isolation / interception). ([`vendor/cordis/src/context.ts:35`](../../vendor/cordis/src/context.ts))
+- `ctx.root / ctx.scope / ctx.fiber / ctx.registry / ctx.reflect / ctx.events / ctx.logger` — Ambient handles onto the running context graph. ([`vendor/cordis/src/context.ts:16`](../../vendor/cordis/src/context.ts))
+- `ctx.timer (+ interval / timeout / throttle / debounce / setTimeout / setInterval)` — Disposable timer helpers. The `timer` key is provided at runtime; the six helpers are mixed onto ctx directly (declared via Pick). ([`vendor/timer/src/index.ts:4`](../../vendor/timer/src/index.ts))
+- `ctx.loader` — The config Loader that booted the app (present under the loader). ([`vendor/loader/src/index.ts:30`](../../vendor/loader/src/index.ts))
+- `ctx.hmr` — The hot-module-reload watcher (present under the hmr plugin). ([`vendor/hmr/src/index.ts:15`](../../vendor/hmr/src/index.ts))
--- a/docs/cordis-primer.md
+++ b/docs/cordis-primer.md
@@ -0,0 +1,38 @@
+# Cordis Primer
+
+Cordis is the vendored plugin framework underneath the DeepSeek Harness SDK. This primer teaches the Cordis ideas a harness plugin author needs before reading the generated [events](cordis-catalog/events.md) and [services](cordis-catalog/services.md) catalogs. The vendored source and sync procedure live in [vendor/README.md](../vendor/README.md).
+
+## Cordis In Five Ideas
+
+- **A plugin is a unit of behavior.** It can be a function with optional `inject` and `apply(ctx)` fields, or a `Service` subclass whose lifecycle Cordis mounts into the current context.
+- **A context is the service container.** A service claims a stable `ctx.<key>` such as `ctx.tools`, `ctx.llm`, or `ctx.sessions`; other plugins program against that key instead of importing a concrete implementation.
+- **`inject` is the dependency gate.** A plugin that names required services waits until those services exist, so load order is expressed through service requirements rather than manual boot sequencing.
+- **Events are typed extension seams.** Services declare event names through TypeScript declaration merging, then dispatch them as `emit`, `waterfall`, `parallel`, or `serial` depending on whether listeners observe, wrap, fan out, or run in order.
+- **Registrations are disposable effects.** Prompt sections, tool schemas, adapters, providers, and listeners are installed through `ctx.effect()` or `ctx.on()` so reload and teardown unwind them predictably.
+
+## Dispatch Modes
+
+Use the mode to understand what a listener can do:
+
+| Mode | Shape |
+|---|---|
+| `emit` | synchronous notification; listeners observe but do not shape the result |
+| `waterfall` | around-middleware; each listener receives `next()` and may wrap, rewrite, or veto |
+| `parallel` | awaited fan-out; all listeners run and the dispatcher waits for them |
+| `serial` | awaited in registration order; a non-void bail value stops the chain |
+
+The mode is part of the event's public contract. New harness events document it with an `@mode` tag so the generated catalog can check declarations against dispatch sites.
+
+## Cordis Waterfall Semantics
+
+`ctx.waterfall` is around-middleware, not a reducer. A listener receives `(...args, next)`. Call `next()` to delegate, optionally wrapping the result; return without `next()` to short-circuit. Values propagate through `next()`'s return value.
+
+Cooperative listeners usually mutate a shared request or decision object and then delegate. Returning a replacement is a takeover: downstream listeners see the replacement, and earlier mutations on the original object do not carry forward. Use `prepend: true` only when the listener must run before ordinary registrations.
+
+For single-decision events, short-circuiting is the design. A policy listener can return without `next()` when it owns the decision, while a listener that only annotates or observes must delegate.
+
+## Practical Rules
+
+Own vocabulary where the behavior lives: a tool pipeline event belongs to `ctx.tools`, model streaming belongs to `ctx.llm`, and live agent coordination belongs to `ctx.agents`. Prefer events for interception and policy; prefer service methods for direct capability calls.
+
+Every registration should have a disposer, either by returning one from `ctx.effect()` or using a Cordis helper that does it for you. If teardown order matters, keep the related work in one effect so disposal unwinds in the intended sequence.
--- a/docs/core-data-structures/filesystem.md
+++ b/docs/core-data-structures/filesystem.md
@@ -90,7 +90,7 @@ interface FsEditOutcome {

 `dsh-fs` owns three events the tool dispatches and the policy plugin listens for, so the emitter (`dsh-tool-fs`) and the listener (`dsh-fs-policy`) share a vocabulary without the emitter depending on the policy plugin. They carry only `dsh-fs` vocabulary plus an opaque `object` actor — no model-facing concepts and no agent/session owner structure.

-`fs/write-intent` and `fs/edit-intent` are **single-slot decision waterfalls**: the tool dispatches each with a default thunk returning `undefined` (the bare provider), and a listener fully decides without calling `next()`. The slot is first-wins by registration order — the policy plugin owning it is a deployment convention, not an enforced invariant. `fs/observed` is a fire-and-forget recording event dispatched with a plain `ctx.emit`; its listener MUST be synchronous and side-effect-only, because the tool does NOT guard the emit — a throwing listener would surface as the tool's `isError` result for a mutation that already succeeded. The generated catalog shows the exact signatures on [events-and-services.md](../cordis-catalog/events-and-services.md).
+`fs/write-intent` and `fs/edit-intent` are **single-slot decision waterfalls**: the tool dispatches each with a default thunk returning `undefined` (the bare provider), and a listener fully decides without calling `next()`. The slot is first-wins by registration order — the policy plugin owning it is a deployment convention, not an enforced invariant. `fs/observed` is a fire-and-forget recording event dispatched with a plain `ctx.emit`; its listener MUST be synchronous and side-effect-only, because the tool does NOT guard the emit — a throwing listener would surface as the tool's `isError` result for a mutation that already succeeded. The generated catalog shows the exact signatures on [events.md](../cordis-catalog/events.md).

 ## Execution context (policy plugin)

@@ -144,4 +144,4 @@ type FsErrorCode =

 ## The service and the plugin

-`FileSystem` (`ctx.fs`, abstract) owns the provider primitives: `resolve`, `stat`, `readText`, `streamText`, `listDir`, `writeText`, and `editText`. `dsh-fs-policy` registers **no service** — it is a plugin that adds policy through the `fs/*` event gate: it decides the write/edit intent waterfalls (supplying `createIfAbsent`/`replaceIfVersion`/`{ version }` or throwing `FS_NOT_OBSERVED`) and records on `fs/observed`. The executor is `dsh-tool-fs`: it reads/writes/edits through `ctx.fs`, dispatches the waterfalls, and emits the recording event. The generated wiring catalog shows the exact `ctx.fs` signatures on [events-and-services.md](../cordis-catalog/events-and-services.md#ctxfs--filesystem-abstract-seam).
+`FileSystem` (`ctx.fs`, abstract) owns the provider primitives: `resolve`, `stat`, `readText`, `streamText`, `listDir`, `writeText`, and `editText`. `dsh-fs-policy` registers **no service** — it is a plugin that adds policy through the `fs/*` event gate: it decides the write/edit intent waterfalls (supplying `createIfAbsent`/`replaceIfVersion`/`{ version }` or throwing `FS_NOT_OBSERVED`) and records on `fs/observed`. The executor is `dsh-tool-fs`: it reads/writes/edits through `ctx.fs`, dispatches the waterfalls, and emits the recording event. The generated wiring catalog shows the exact `ctx.fs` signatures on [services.md](../cordis-catalog/services.md#ctxfs--filesystem-abstract-seam).
--- a/docs/core-data-structures/llm-streaming.md
+++ b/docs/core-data-structures/llm-streaming.md
@@ -62,7 +62,7 @@ interface TokenUsage {

 ## The seam

-`LlmAdapter` is the provider seam: subclass, implement `stream()`, register with `ctx.llm.registerAdapter(models, adapter)`. The `block-start` / `block-end` `index` correlation and the assembler together mean an adapter only has to emit well-formed chunks — block reassembly is not each adapter's problem. The consumer surface (`ctx.llm.stream()`) and the `llm/stream` waterfall are described in [architecture.md § The vocabulary](../architecture.md#the-vocabulary-dsh-llm).
+`LlmAdapter` is the provider seam: subclass, implement `stream()`, register with `ctx.llm.registerAdapter(models, adapter)`. The `block-start` / `block-end` `index` correlation and the assembler together mean an adapter only has to emit well-formed chunks — block reassembly is not each adapter's problem. The consumer surface (`ctx.llm.stream()`) and the `llm/stream` waterfall are described in [architecture.md § Content blocks and streaming](../architecture.md#content-blocks-and-streaming-dsh-llm).

 `ContentBlockType` (the key set the `index`-correlated blocks carry) derives from `ContentBlockMap`:

--- a/docs/core-data-structures/subagent.md
+++ b/docs/core-data-structures/subagent.md
@@ -86,7 +86,7 @@ interface SubagentProvider {
 }
 ```

-The service (`ctx.subagents`) emits `subagent/start` when a run begins and `subagent/end` when it settles (see the [events catalog](../cordis-catalog/events-and-services.md)). `subagent/end` carries `lastAssistantMessage` (the child's final `output`) on the settle path, so an observer sees WHAT the subagent produced without holding the run (absent when the run rejected at the infrastructure level — no result was produced). These are **observe-only** events: both are plain `emit`s (the `subagent/end` fires from a detached `.then` after the result settles and awaits no listener), so a subscriber observes but cannot change the run. Both emits contain a thrown listener **per listener** (logged, never propagated): one bad subscriber can neither strand a live run, surface as an unhandled rejection on the detached settle hook, nor starve the listeners registered after it.
+The service (`ctx.subagents`) emits `subagent/start` when a run begins and `subagent/end` when it settles (see the [events catalog](../cordis-catalog/events.md)). `subagent/end` carries `lastAssistantMessage` (the child's final `output`) on the settle path, so an observer sees WHAT the subagent produced without holding the run (absent when the run rejected at the infrastructure level — no result was produced). These are **observe-only** events: both are plain `emit`s (the `subagent/end` fires from a detached `.then` after the result settles and awaits no listener), so a subscriber observes but cannot change the run. Both emits contain a thrown listener **per listener** (logged, never propagated): one bad subscriber can neither strand a live run, surface as an unhandled rejection on the detached settle hook, nor starve the listeners registered after it.

 ## In-process backends: depth and seed

--- a/docs/development.i18n.yaml
+++ b/docs/development.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-development.md: c57ccd4a393bdf54a13c5786b70b6b665904aedd
-development.zh.md: 198b7651e6937b3f5280a6104a5b43b35f40262b
+development.md: f032764fff29baaca007211db8b69d9a5129078f
+development.zh.md: 3a650d03ce7cafd0e34290ae918e5a303c2ad8a9
--- a/docs/development.md
+++ b/docs/development.md
@@ -96,10 +96,13 @@ pnpm run typecheck      # build package/vendor outputs, then typecheck examples,
 pnpm run lint           # eslint .
 pnpm run lint:fix       # eslint . --fix
 pnpm run doc-typecheck  # compile checked TypeScript snippets in Markdown docs
-pnpm run gen-cordis-catalog     # regenerate docs/cordis-catalog/events-and-services.md from source
-pnpm run verify-cordis-catalog  # fail if the cordis events/services catalog is stale
+pnpm run gen-cordis-catalog     # regenerate docs/cordis-catalog/events.md + services.md from source
+pnpm run verify-cordis-catalog  # fail if either cordis catalog is stale
+pnpm run gen-doc-graphs     # regenerate generated relationship docs from source and curated graph definitions
+pnpm run verify-doc-graphs  # fail if generated relationship docs are stale
 pnpm run gen-rfc-index          # regenerate the docs/rfc/README.md index tables from the RFC tree
 pnpm run verify-md-wrap  # fail on hard-wrapped prose paragraphs in docs/README markdown
+pnpm run verify-mermaid  # fail if a ```mermaid diagram has invalid Mermaid syntax
 pnpm run verify-type-equiv  # fail if a ```ts type-equiv doc block drifts from its source type
 pnpm run verify-doc-budgets  # fail if a budgeted standing doc exceeds its word ceiling
 pnpm run doc-sync       # all Markdown/doc gates; see the doc-sync script in package.json for the full list
@@ -110,7 +113,7 @@ pnpm run verify-node-next-types  # fail if built declarations are not NodeNext-c
 pnpm run hygiene        # knip, publint, workspace constraints, and NodeNext declaration check
 ```

-When changing package public behavior, update the relevant README or JSDoc in the same change. `pnpm run doc-sync` catches checked TypeScript snippets, cordis events/services catalog drift, and hard-wrapped markdown prose, but broader prose/API sync still needs review.
+When changing package public behavior, update the relevant README or JSDoc in the same change. `pnpm run doc-sync` catches checked TypeScript snippets, generated doc freshness, markdown wrap/link drift, type equivalence, translation pairing, Mermaid syntax, and doc budgets, but broader prose/API sync still needs review.

 ## Demos

--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -96,10 +96,13 @@ pnpm run typecheck      # build package/vendor outputs, then typecheck examples,
 pnpm run lint           # eslint .
 pnpm run lint:fix       # eslint . --fix
 pnpm run doc-typecheck  # compile checked TypeScript snippets in Markdown docs
-pnpm run gen-cordis-catalog     # regenerate docs/cordis-catalog/events-and-services.md from source
-pnpm run verify-cordis-catalog  # fail if the cordis events/services catalog is stale
+pnpm run gen-cordis-catalog     # regenerate docs/cordis-catalog/events.md + services.md from source
+pnpm run verify-cordis-catalog  # fail if either cordis catalog is stale
+pnpm run gen-doc-graphs     # regenerate generated relationship docs from source and curated graph definitions
+pnpm run verify-doc-graphs  # fail if generated relationship docs are stale
 pnpm run gen-rfc-index          # regenerate the docs/rfc/README.md index tables from the RFC tree
 pnpm run verify-md-wrap  # fail on hard-wrapped prose paragraphs in docs/README markdown
+pnpm run verify-mermaid  # fail if a ```mermaid diagram has invalid Mermaid syntax
 pnpm run verify-type-equiv  # fail if a ```ts type-equiv doc block drifts from its source type
 pnpm run verify-doc-budgets  # fail if a budgeted standing doc exceeds its word ceiling
 pnpm run doc-sync       # all Markdown/doc gates; see the doc-sync script in package.json for the full list
@@ -110,7 +113,7 @@ pnpm run verify-node-next-types  # fail if built declarations are not NodeNext-c
 pnpm run hygiene        # knip, publint, workspace constraints, and NodeNext declaration check
 ```

-改动 package 的公开行为时，在同一个变更里更新相关 README 或 JSDoc。`pnpm run doc-sync` 能抓住被检查的 TypeScript 片段、cordis 事件/服务目录漂移和硬折行的 markdown 段落，但更广泛的行文/API 同步仍需评审把关。
+改动 package 的公开行为时，在同一个变更里更新相关 README 或 JSDoc。`pnpm run doc-sync` 能抓住被检查的 TypeScript 片段、生成文档新鲜度、markdown 换行/链接漂移、type-equiv、翻译配对、Mermaid 语法和文档预算，但更广泛的行文/API 同步仍需评审把关。

 ## 演示

--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -0,0 +1,38 @@
+<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
+     Run `pnpm run gen-doc-graphs` to regenerate. -->
+
+# Event Producer And Consumer Matrix
+
+This matrix shows which packages dispatch each harness-owned event and which packages listen to it. It is intentionally a table rather than one large graph: events are many-to-many, and dense relation data is easier to review in rows. Dynamic dispatch overrides cover sites that deliberately bypass `ctx.emit`, such as subagent lifecycle containment.
+
+| Event | Mode | Declared in | Dispatchers | Listeners |
+| --- | --- | --- | --- | --- |
+| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:258`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) |
+| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:265`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) |
+| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:404`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - |
+| `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:343`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic) |
+| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:356`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+| `agent/queued` | `emit` | [`packages/core/agent/src/types.ts:283`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - |
+| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:369`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`), [`compact-basic`](../packages/compact/compact-basic) (`waterfall`) | - |
+| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:298`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:274`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`stdio-agent`](../packages/ui/stdio-agent) |
+| `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:379`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - |
+| `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:392`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+| `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:123`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
+| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:138`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`) | [`fs-policy`](../packages/fs/fs-policy) |
+| `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:109`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
+| `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:33`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`llm-replay`](../packages/support/llm-replay) |
+| `session/created` | `emit` | [`packages/core/session/src/index.ts:36`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`emit`) | [`invariants`](../packages/support/invariants), [`session-persistence`](../packages/session-persistence/session-persistence) |
+| `session/event` | `emit` | [`packages/core/session/src/index.ts:44`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`emit`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`session-persistence`](../packages/session-persistence/session-persistence), [`stdio-agent`](../packages/ui/stdio-agent) |
+| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:54`](../packages/core/session/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`parallel`) | [`session-persistence`](../packages/session-persistence/session-persistence) |
+| `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:96`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude) |
+| `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:72`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`tool-subagent`](../packages/subagent/tool-subagent) |
+| `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:81`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`tool-subagent`](../packages/subagent/tool-subagent) |
+| `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:89`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude) |
+| `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:32`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | - |
+| `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:38`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - |
+| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:87`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - |
+| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:82`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:66`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+
+Maintenance mode: hybrid generated: Cordis event declarations and most producer/listener edges are AST-scanned; dynamic dispatch sites are classified in `scripts/gen-doc-graphs.ts`.
--- a/docs/graph-atlas.md
+++ b/docs/graph-atlas.md
@@ -0,0 +1,25 @@
+<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
+     Run `pnpm run gen-doc-graphs` to regenerate. -->
+
+# Documentation Graph Index
+
+These diagrams are the relationship layer above the generated catalogs. Use them to navigate package topology, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type shapes still live in the generated [events](cordis-catalog/events.md) / [services](cordis-catalog/services.md) catalogs, [tool-catalog/](tool-catalog/tools.md), and [core-data-structures/](core-data-structures/core.md).
+
+The process decision behind this index is recorded in [the documentation graph RFC](rfc/implemented/process/2026-07-03-documentation-graph-atlas.md).
+
+| Graph | Mode |
+| --- | --- |
+| [module dependency graph](module-graph.md) | `generated` |
+| [tool schema catalog and package map](tool-catalog/tools.md) | `generated` |
+| [capability seams and core services](capability-seams.md) | `hybrid generated` |
+| [echo-agent app composition](../examples/echo-agent/composition.md) | `hybrid generated` |
+| [coding-agent app composition](../examples/coding-agent/composition.md) | `hybrid generated` |
+| [acp-agent app composition](../examples/acp-agent/composition.md) | `hybrid generated` |
+| [event producer/consumer matrix](event-producer-consumer.md) | `hybrid generated` |
+| [agent turn and step lifecycle](agent-lifecycle.md) | `curated` |
+| [tool execution pipeline](tool-execution-pipeline.md) | `curated` |
+| [ACP snapshot replay](acp/snapshot-replay.md) | `curated` |
+
+Regenerate with `pnpm run gen-doc-graphs`; verify freshness with `pnpm run verify-doc-graphs`.
+
+Maintenance mode: mixed: each linked page declares generated, hybrid, or curated mode.
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -3,178 +3,249 @@

 # Module dependency graph

-Inter-package dependencies among the `@deepseek-ai/dsh-*` harness packages, derived from each package's `peerDependencies` (the canonical runtime-dependency signal). An edge `a --> b` means package `a` depends on package `b`. Names have the `@deepseek-ai/dsh-` prefix stripped.
+Inter-package dependencies among the `@deepseek-ai/dsh-*` harness packages, derived from each package's `peerDependencies` (the canonical runtime-dependency signal) and grouped by the `packages/<group>/<pkg>` hierarchy. An edge `a --> b` means package `a` depends on package `b`. Names have the `@deepseek-ai/dsh-` prefix stripped.

 ```mermaid
-graph TD
-  bash --> brand
-  llm --> brand
-  bash-local --> bash
-  fs --> brand
-  fs --> llm
-  llm-deepseek --> llm
-  llm-pi-ai --> llm
-  session --> brand
-  session --> llm
-  system-prompt --> llm
-  web --> llm
-  agent --> brand
-  agent --> llm
-  agent --> session
-  agent --> system-prompt
-  compact --> llm
-  compact --> session
-  fs-local --> fs
-  fs-policy --> fs
-  hook-protocol --> bash
-  hook-protocol --> session
-  llm-replay --> llm
-  llm-replay --> session
-  session-persistence --> session
-  web-fetch-local --> web
-  web-search-deepseek --> web
-  web-search-exa --> web
-  web-search-perplexity --> web
-  compact-basic --> agent
-  compact-basic --> compact
-  compact-basic --> llm
-  compact-basic --> session
-  invariants --> agent
-  invariants --> llm
-  invariants --> session
-  session-persistence-jsonl --> session
-  session-persistence-jsonl --> session-persistence
-  session-persistence-sqlite --> session
-  session-persistence-sqlite --> session-persistence
-  tools --> agent
-  tools --> llm
-  tools --> system-prompt
-  acp --> agent
-  acp --> llm
-  acp --> session
-  acp --> session-persistence
-  acp --> tools
-  agent-loop --> agent
-  agent-loop --> llm
-  agent-loop --> session
-  agent-loop --> session-persistence
-  agent-loop --> system-prompt
-  agent-loop --> tools
-  hooks-codex --> agent
-  hooks-codex --> hook-protocol
-  hooks-codex --> llm
-  hooks-codex --> session
-  hooks-codex --> tools
-  subagent --> agent
-  subagent --> llm
-  subagent --> tools
-  tool-bash --> agent
-  tool-bash --> bash
-  tool-bash --> llm
-  tool-bash --> system-prompt
-  tool-bash --> tools
-  tool-fs --> fs
-  tool-fs --> llm
-  tool-fs --> session
-  tool-fs --> system-prompt
-  tool-fs --> tools
-  tool-todo --> agent
-  tool-todo --> session
-  tool-todo --> tools
-  tool-web --> llm
-  tool-web --> system-prompt
-  tool-web --> tools
-  tool-web --> web
-  agent-core --> agent
-  agent-core --> agent-loop
-  agent-core --> invariants
-  agent-core --> llm
-  agent-core --> session
-  agent-core --> system-prompt
-  agent-core --> tool-bash
-  agent-core --> tools
-  hooks-claude --> agent
-  hooks-claude --> hook-protocol
-  hooks-claude --> llm
-  hooks-claude --> session
-  hooks-claude --> subagent
-  hooks-claude --> tools
-  subagent-acp --> agent
-  subagent-acp --> llm
-  subagent-acp --> subagent
-  subagent-inprocess --> agent
-  subagent-inprocess --> llm
-  subagent-inprocess --> session
-  subagent-inprocess --> subagent
-  subagent-mock --> agent
-  subagent-mock --> llm
-  subagent-mock --> subagent
-  tool-subagent --> agent
-  tool-subagent --> llm
-  tool-subagent --> subagent
-  tool-subagent --> tools
-  acp-agent --> acp
-  acp-agent --> agent-core
-  acp-agent --> app-boot
-  acp-agent --> session-persistence-jsonl
-  stdio-agent --> agent
-  stdio-agent --> agent-core
-  stdio-agent --> app-boot
-  stdio-agent --> llm
-  stdio-agent --> session
-  stdio-agent --> session-persistence-jsonl
-  subagent-fork --> agent
-  subagent-fork --> session
-  subagent-fork --> subagent
-  subagent-fork --> subagent-inprocess
-  subagent-spawn --> subagent
-  subagent-spawn --> subagent-inprocess
+flowchart TD
+  subgraph group_util["packages/util"]
+    pkg_brand["brand"]
+  end
+  subgraph group_llm["packages/llm"]
+    pkg_llm["llm"]
+    pkg_llm_deepseek["llm-deepseek"]
+    pkg_llm_pi_ai["llm-pi-ai"]
+  end
+  subgraph group_core["packages/core"]
+    pkg_agent["agent"]
+    pkg_agent_core["agent-core"]
+    pkg_agent_loop["agent-loop"]
+    pkg_session["session"]
+    pkg_system_prompt["system-prompt"]
+    pkg_tools["tools"]
+  end
+  subgraph group_bash["packages/bash"]
+    pkg_bash["bash"]
+    pkg_bash_local["bash-local"]
+    pkg_tool_bash["tool-bash"]
+  end
+  subgraph group_fs["packages/fs"]
+    pkg_fs["fs"]
+    pkg_fs_local["fs-local"]
+    pkg_fs_policy["fs-policy"]
+    pkg_tool_fs["tool-fs"]
+  end
+  subgraph group_compact["packages/compact"]
+    pkg_compact["compact"]
+    pkg_compact_basic["compact-basic"]
+  end
+  subgraph group_subagent["packages/subagent"]
+    pkg_subagent["subagent"]
+    pkg_subagent_acp["subagent-acp"]
+    pkg_subagent_fork["subagent-fork"]
+    pkg_subagent_inprocess["subagent-inprocess"]
+    pkg_subagent_spawn["subagent-spawn"]
+    pkg_tool_subagent["tool-subagent"]
+  end
+  subgraph group_web["packages/web"]
+    pkg_tool_web["tool-web"]
+    pkg_web["web"]
+    pkg_web_fetch_local["web-fetch-local"]
+    pkg_web_search_deepseek["web-search-deepseek"]
+    pkg_web_search_exa["web-search-exa"]
+    pkg_web_search_perplexity["web-search-perplexity"]
+  end
+  subgraph group_todo["packages/todo"]
+    pkg_tool_todo["tool-todo"]
+  end
+  subgraph group_hooks["packages/hooks"]
+    pkg_hook_protocol["hook-protocol"]
+    pkg_hooks_claude["hooks-claude"]
+    pkg_hooks_codex["hooks-codex"]
+  end
+  subgraph group_session_persistence["packages/session-persistence"]
+    pkg_session_persistence["session-persistence"]
+    pkg_session_persistence_jsonl["session-persistence-jsonl"]
+    pkg_session_persistence_sqlite["session-persistence-sqlite"]
+  end
+  subgraph group_support["packages/support"]
+    pkg_invariants["invariants"]
+    pkg_llm_replay["llm-replay"]
+    pkg_subagent_mock["subagent-mock"]
+  end
+  subgraph group_ui["packages/ui"]
+    pkg_acp["acp"]
+    pkg_acp_agent["acp-agent"]
+    pkg_app_boot["app-boot"]
+    pkg_stdio_agent["stdio-agent"]
+  end
+  pkg_llm --> pkg_brand
+  pkg_bash --> pkg_brand
+  pkg_llm_deepseek --> pkg_llm
+  pkg_llm_pi_ai --> pkg_llm
+  pkg_session --> pkg_brand
+  pkg_session --> pkg_llm
+  pkg_system_prompt --> pkg_llm
+  pkg_bash_local --> pkg_bash
+  pkg_fs --> pkg_brand
+  pkg_fs --> pkg_llm
+  pkg_web --> pkg_llm
+  pkg_agent --> pkg_brand
+  pkg_agent --> pkg_llm
+  pkg_agent --> pkg_session
+  pkg_agent --> pkg_system_prompt
+  pkg_fs_local --> pkg_fs
+  pkg_fs_policy --> pkg_fs
+  pkg_compact --> pkg_llm
+  pkg_compact --> pkg_session
+  pkg_web_fetch_local --> pkg_web
+  pkg_web_search_deepseek --> pkg_web
+  pkg_web_search_exa --> pkg_web
+  pkg_web_search_perplexity --> pkg_web
+  pkg_hook_protocol --> pkg_bash
+  pkg_hook_protocol --> pkg_session
+  pkg_session_persistence --> pkg_session
+  pkg_llm_replay --> pkg_llm
+  pkg_llm_replay --> pkg_session
+  pkg_tools --> pkg_agent
+  pkg_tools --> pkg_llm
+  pkg_tools --> pkg_system_prompt
+  pkg_compact_basic --> pkg_agent
+  pkg_compact_basic --> pkg_compact
+  pkg_compact_basic --> pkg_llm
+  pkg_compact_basic --> pkg_session
+  pkg_session_persistence_jsonl --> pkg_session
+  pkg_session_persistence_jsonl --> pkg_session_persistence
+  pkg_session_persistence_sqlite --> pkg_session
+  pkg_session_persistence_sqlite --> pkg_session_persistence
+  pkg_invariants --> pkg_agent
+  pkg_invariants --> pkg_llm
+  pkg_invariants --> pkg_session
+  pkg_agent_loop --> pkg_agent
+  pkg_agent_loop --> pkg_llm
+  pkg_agent_loop --> pkg_session
+  pkg_agent_loop --> pkg_session_persistence
+  pkg_agent_loop --> pkg_system_prompt
+  pkg_agent_loop --> pkg_tools
+  pkg_tool_bash --> pkg_agent
+  pkg_tool_bash --> pkg_bash
+  pkg_tool_bash --> pkg_llm
+  pkg_tool_bash --> pkg_system_prompt
+  pkg_tool_bash --> pkg_tools
+  pkg_tool_fs --> pkg_fs
+  pkg_tool_fs --> pkg_llm
+  pkg_tool_fs --> pkg_session
+  pkg_tool_fs --> pkg_system_prompt
+  pkg_tool_fs --> pkg_tools
+  pkg_subagent --> pkg_agent
+  pkg_subagent --> pkg_llm
+  pkg_subagent --> pkg_tools
+  pkg_tool_web --> pkg_llm
+  pkg_tool_web --> pkg_system_prompt
+  pkg_tool_web --> pkg_tools
+  pkg_tool_web --> pkg_web
+  pkg_tool_todo --> pkg_agent
+  pkg_tool_todo --> pkg_session
+  pkg_tool_todo --> pkg_tools
+  pkg_hooks_codex --> pkg_agent
+  pkg_hooks_codex --> pkg_hook_protocol
+  pkg_hooks_codex --> pkg_llm
+  pkg_hooks_codex --> pkg_session
+  pkg_hooks_codex --> pkg_tools
+  pkg_acp --> pkg_agent
+  pkg_acp --> pkg_llm
+  pkg_acp --> pkg_session
+  pkg_acp --> pkg_session_persistence
+  pkg_acp --> pkg_tools
+  pkg_agent_core --> pkg_agent
+  pkg_agent_core --> pkg_agent_loop
+  pkg_agent_core --> pkg_invariants
+  pkg_agent_core --> pkg_llm
+  pkg_agent_core --> pkg_session
+  pkg_agent_core --> pkg_system_prompt
+  pkg_agent_core --> pkg_tool_bash
+  pkg_agent_core --> pkg_tools
+  pkg_subagent_acp --> pkg_agent
+  pkg_subagent_acp --> pkg_llm
+  pkg_subagent_acp --> pkg_subagent
+  pkg_subagent_inprocess --> pkg_agent
+  pkg_subagent_inprocess --> pkg_llm
+  pkg_subagent_inprocess --> pkg_session
+  pkg_subagent_inprocess --> pkg_subagent
+  pkg_tool_subagent --> pkg_agent
+  pkg_tool_subagent --> pkg_llm
+  pkg_tool_subagent --> pkg_subagent
+  pkg_tool_subagent --> pkg_tools
+  pkg_hooks_claude --> pkg_agent
+  pkg_hooks_claude --> pkg_hook_protocol
+  pkg_hooks_claude --> pkg_llm
+  pkg_hooks_claude --> pkg_session
+  pkg_hooks_claude --> pkg_subagent
+  pkg_hooks_claude --> pkg_tools
+  pkg_subagent_mock --> pkg_agent
+  pkg_subagent_mock --> pkg_llm
+  pkg_subagent_mock --> pkg_subagent
+  pkg_subagent_fork --> pkg_agent
+  pkg_subagent_fork --> pkg_session
+  pkg_subagent_fork --> pkg_subagent
+  pkg_subagent_fork --> pkg_subagent_inprocess
+  pkg_subagent_spawn --> pkg_subagent
+  pkg_subagent_spawn --> pkg_subagent_inprocess
+  pkg_acp_agent --> pkg_acp
+  pkg_acp_agent --> pkg_agent_core
+  pkg_acp_agent --> pkg_app_boot
+  pkg_acp_agent --> pkg_session_persistence_jsonl
+  pkg_stdio_agent --> pkg_agent
+  pkg_stdio_agent --> pkg_agent_core
+  pkg_stdio_agent --> pkg_app_boot
+  pkg_stdio_agent --> pkg_llm
+  pkg_stdio_agent --> pkg_session
+  pkg_stdio_agent --> pkg_session_persistence_jsonl
 ```

-| Package | Depends on |
-| --- | --- |
-| `app-boot` | — |
-| `brand` | — |
-| `bash` | `brand` |
-| `llm` | `brand` |
-| `bash-local` | `bash` |
-| `fs` | `brand`, `llm` |
-| `llm-deepseek` | `llm` |
-| `llm-pi-ai` | `llm` |
-| `session` | `brand`, `llm` |
-| `system-prompt` | `llm` |
-| `web` | `llm` |
-| `agent` | `brand`, `llm`, `session`, `system-prompt` |
-| `compact` | `llm`, `session` |
-| `fs-local` | `fs` |
-| `fs-policy` | `fs` |
-| `hook-protocol` | `bash`, `session` |
-| `llm-replay` | `llm`, `session` |
-| `session-persistence` | `session` |
-| `web-fetch-local` | `web` |
-| `web-search-deepseek` | `web` |
-| `web-search-exa` | `web` |
-| `web-search-perplexity` | `web` |
-| `compact-basic` | `agent`, `compact`, `llm`, `session` |
-| `invariants` | `agent`, `llm`, `session` |
-| `session-persistence-jsonl` | `session`, `session-persistence` |
-| `session-persistence-sqlite` | `session`, `session-persistence` |
-| `tools` | `agent`, `llm`, `system-prompt` |
-| `acp` | `agent`, `llm`, `session`, `session-persistence`, `tools` |
-| `agent-loop` | `agent`, `llm`, `session`, `session-persistence`, `system-prompt`, `tools` |
-| `hooks-codex` | `agent`, `hook-protocol`, `llm`, `session`, `tools` |
-| `subagent` | `agent`, `llm`, `tools` |
-| `tool-bash` | `agent`, `bash`, `llm`, `system-prompt`, `tools` |
-| `tool-fs` | `fs`, `llm`, `session`, `system-prompt`, `tools` |
-| `tool-todo` | `agent`, `session`, `tools` |
-| `tool-web` | `llm`, `system-prompt`, `tools`, `web` |
-| `agent-core` | `agent`, `agent-loop`, `invariants`, `llm`, `session`, `system-prompt`, `tool-bash`, `tools` |
-| `hooks-claude` | `agent`, `hook-protocol`, `llm`, `session`, `subagent`, `tools` |
-| `subagent-acp` | `agent`, `llm`, `subagent` |
-| `subagent-inprocess` | `agent`, `llm`, `session`, `subagent` |
-| `subagent-mock` | `agent`, `llm`, `subagent` |
-| `tool-subagent` | `agent`, `llm`, `subagent`, `tools` |
-| `acp-agent` | `acp`, `agent-core`, `app-boot`, `session-persistence-jsonl` |
-| `stdio-agent` | `agent`, `agent-core`, `app-boot`, `llm`, `session`, `session-persistence-jsonl` |
-| `subagent-fork` | `agent`, `session`, `subagent`, `subagent-inprocess` |
-| `subagent-spawn` | `subagent`, `subagent-inprocess` |
+| Package | Group | Depends on |
+| --- | --- | --- |
+| [`brand`](../packages/util/brand) | `util` | — |
+| [`app-boot`](../packages/ui/app-boot) | `ui` | — |
+| [`llm`](../packages/llm/llm) | `llm` | [`brand`](../packages/util/brand) |
+| [`bash`](../packages/bash/bash) | `bash` | [`brand`](../packages/util/brand) |
+| [`llm-deepseek`](../packages/llm/llm-deepseek) | `llm` | [`llm`](../packages/llm/llm) |
+| [`llm-pi-ai`](../packages/llm/llm-pi-ai) | `llm` | [`llm`](../packages/llm/llm) |
+| [`session`](../packages/core/session) | `core` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm) |
+| [`system-prompt`](../packages/core/system-prompt) | `core` | [`llm`](../packages/llm/llm) |
+| [`bash-local`](../packages/bash/bash-local) | `bash` | [`bash`](../packages/bash/bash) |
+| [`fs`](../packages/fs/fs) | `fs` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm) |
+| [`web`](../packages/web/web) | `web` | [`llm`](../packages/llm/llm) |
+| [`agent`](../packages/core/agent) | `core` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
+| [`fs-local`](../packages/fs/fs-local) | `fs` | [`fs`](../packages/fs/fs) |
+| [`fs-policy`](../packages/fs/fs-policy) | `fs` | [`fs`](../packages/fs/fs) |
+| [`compact`](../packages/compact/compact) | `compact` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
+| [`web-fetch-local`](../packages/web/web-fetch-local) | `web` | [`web`](../packages/web/web) |
+| [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`web`](../packages/web/web) |
+| [`web-search-exa`](../packages/web/web-search-exa) | `web` | [`web`](../packages/web/web) |
+| [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`web`](../packages/web/web) |
+| [`hook-protocol`](../packages/hooks/hook-protocol) | `hooks` | [`bash`](../packages/bash/bash), [`session`](../packages/core/session) |
+| [`session-persistence`](../packages/session-persistence/session-persistence) | `session-persistence` | [`session`](../packages/core/session) |
+| [`llm-replay`](../packages/support/llm-replay) | `support` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
+| [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt) |
+| [`compact-basic`](../packages/compact/compact-basic) | `compact` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
+| [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl) | `session-persistence` | [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) |
+| [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | `session-persistence` | [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) |
+| [`invariants`](../packages/support/invariants) | `support` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
+| [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
+| [`tool-bash`](../packages/bash/tool-bash) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
+| [`tool-fs`](../packages/fs/tool-fs) | `fs` | [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
+| [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`tools`](../packages/core/tools) |
+| [`tool-web`](../packages/web/tool-web) | `web` | [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`web`](../packages/web/web) |
+| [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
+| [`hooks-codex`](../packages/hooks/hooks-codex) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
+| [`acp`](../packages/ui/acp) | `ui` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`tools`](../packages/core/tools) |
+| [`agent-core`](../packages/core/agent-core) | `core` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tool-bash`](../packages/bash/tool-bash), [`tools`](../packages/core/tools) |
+| [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent) |
+| [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
+| [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
+| [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
+| [`subagent-mock`](../packages/support/subagent-mock) | `support` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent) |
+| [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
+| [`subagent-spawn`](../packages/subagent/subagent-spawn) | `subagent` | [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
+| [`acp-agent`](../packages/ui/acp-agent) | `ui` | [`acp`](../packages/ui/acp), [`agent-core`](../packages/core/agent-core), [`app-boot`](../packages/ui/app-boot), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl) |
+| [`stdio-agent`](../packages/ui/stdio-agent) | `ui` | [`agent`](../packages/core/agent), [`agent-core`](../packages/core/agent-core), [`app-boot`](../packages/ui/app-boot), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl) |
--- a/docs/persistence-catalog/log-events.md
+++ b/docs/persistence-catalog/log-events.md
@@ -3,7 +3,7 @@

 # Persistence Log Event Catalog

-Every event type that can appear in a session's durable event log: each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with the payload it carries, its surface badge, and the declaration it comes from. It complements [session.md](../core-data-structures/session.md) (the `SessionEvent` envelope, surface list, and `deriveMessages()` projection), [persistence.md](../core-data-structures/persistence.md) (how the log is made durable), and the [cordis catalog](../cordis-catalog/events-and-services.md) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).
+Every event type that can appear in a session's durable event log: each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with the payload it carries, its surface badge, and the declaration it comes from. It complements [session.md](../core-data-structures/session.md) (the `SessionEvent` envelope, surface list, and `deriveMessages()` projection), [persistence.md](../core-data-structures/persistence.md) (how the log is made durable), and the [cordis events catalog](../cordis-catalog/events.md) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).

 This file is GENERATED from source (`scripts/gen-persistence-catalog.ts`) and verified fresh by `pnpm run verify-persistence-catalog` (part of `doc-sync`) — do not edit it by hand. Payload blocks use a `ts persistence-catalog` fence (skipped by doc-typecheck, since a bare payload fragment is not standalone-compilable). Type names in a payload link to the page that documents them. See [the persistence-log-catalog RFC](../rfc/implemented/process/2026-07-04-persistence-log-catalog.md).

--- a/docs/rfc/README.md
+++ b/docs/rfc/README.md
@@ -170,6 +170,7 @@ Do NOT write one for a mechanical or local choice (a variable name, a one-file r
 | [Classify RFCs by kind via path-encoded subdirectories](implemented/process/2026-06-20-rfc-classification.md) | 2026-06-20 |
 | [Bilingual documentation via paired sibling files and a pairing gate](implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md) | 2026-07-02 |
 | [Generated tool-schema catalog (boot-and-harvest)](implemented/process/2026-07-02-tool-schema-catalog.md) | 2026-07-02 |
+| [Documentation graph index for maintainers and SDK users](implemented/process/2026-07-03-documentation-graph-atlas.md) | 2026-07-03 |
 | [JSDoc completeness gate for the cordis surface](implemented/process/2026-07-04-cordis-jsdoc-completeness-gate.md) | 2026-07-04 |
 | [Documentation tiers, budgets, and the ceiling gate](implemented/process/2026-07-04-doc-tiers-and-budgets.md) | 2026-07-04 |
 | [Generate the RFC index tables](implemented/process/2026-07-04-generate-rfc-index-tables.md) | 2026-07-04 |
--- a/docs/rfc/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md
+++ b/docs/rfc/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md
@@ -6,7 +6,7 @@ Status: implemented (accepted 2026-06-11)

 ## Context

-The product principle (see the 微内核Harness实现思路 design doc) is "everything is a plugin": hooks, /goal, /loop, dynamic workflows, compaction, sandboxing, permissions, UI, persistence, MCP, skills must all be writable as plugins without modifying the core. Candidate mechanisms considered: a purpose-built middleware stack (koa-compose style), an explicit phase state machine plugins can insert into, or Cordis's native event system.
+The product principle is "everything is a plugin": hooks, /goal, /loop, dynamic workflows, compaction, sandboxing, permissions, UI, persistence, MCP, skills must all be writable as plugins without modifying the core. Candidate mechanisms considered: a purpose-built middleware stack (koa-compose style), an explicit phase state machine plugins can insert into, or Cordis's native event system.

 ## Decision

--- a/docs/rfc/implemented/architecture/2026-06-20-extract-example-app-packages.md
+++ b/docs/rfc/implemented/architecture/2026-06-20-extract-example-app-packages.md
@@ -12,7 +12,7 @@ The deeper problem was a **coupled front-door cluster** that lived at the leaf w

 Each example is now **mostly an invocation of an app package**, splitting the wiring along the existing [interface / implementation / consumer seam](2026-06-13-capability-seams.md): the **app package owns the composition**, the leaf `cordis.yml` owns only the **swappable choices** (which LLM adapter, which bash executor, model, prompt, persistence root).

- **`@deepseek-ai/dsh-agent-core`** ([packages/core/agent-core](../../../../packages/core/agent-core)) — a Cordis bundle plugin for the providerless, executor-less, UI-less spine: `timer` + `llm` + sessions + system-prompt + tools + agents + invariants + `tool-bash` + `agent-loop`, mounted as child plugins inside its `apply(ctx)` via `ctx.plugin(...)`. This is the old `base-core.yml` **minus** `bash-local`, **plus** `timer` and the loop, as code instead of a YAML include. The bundle **forwards** `agent-loop`'s `agents` list as its own config (`export const Config = AgentLoop.Config`, default `[]`, the existing `AgentLoop.Config` shape in [packages/core/agent-loop/src/index.ts](../../../../packages/core/agent-loop/src/index.ts)) — so each app supplies its own pre-created agents. This is precisely the reason the old `base-core.yml` gave for keeping `agent-loop` *out* of the shared core ("the examples disagree — stdio needs a pre-created `main`, acp needs none"); forwarding the config dissolves that objection — the loop is shared, the agents list is per-app. The bundle children register into the root service store, so a leaf-mounted sibling (the adapter, the executor) sees them exactly as a nested `plugin-include` subtree's services were seen before. Depending on the CONCRETE `dsh-agent-loop` (not just the `dsh-agent` interface) is deliberate and is the sanctioned exception to the "extension plugins depend on interfaces, never on the concrete loop" rule (packages/README.md, docs/architecture.md § Layering): the rule constrains plugins that EXTEND the system, whereas this bundle's whole job is to COMPOSE the concrete spine. Swapping the loop means publishing a different bundle, not rewiring every extension.
+- **`@deepseek-ai/dsh-agent-core`** ([packages/core/agent-core](../../../../packages/core/agent-core)) — a Cordis bundle plugin for the providerless, executor-less, UI-less spine: `timer` + `llm` + sessions + system-prompt + tools + agents + invariants + `tool-bash` + `agent-loop`, mounted as child plugins inside its `apply(ctx)` via `ctx.plugin(...)`. This is the old `base-core.yml` **minus** `bash-local`, **plus** `timer` and the loop, as code instead of a YAML include. The bundle **forwards** `agent-loop`'s `agents` list as its own config (`export const Config = AgentLoop.Config`, default `[]`, the existing `AgentLoop.Config` shape in [packages/core/agent-loop/src/index.ts](../../../../packages/core/agent-loop/src/index.ts)) — so each app supplies its own pre-created agents. This is precisely the reason the old `base-core.yml` gave for keeping `agent-loop` *out* of the shared core ("the examples disagree — stdio needs a pre-created `main`, acp needs none"); forwarding the config dissolves that objection — the loop is shared, the agents list is per-app. The bundle children register into the root service store, so a leaf-mounted sibling (the adapter, the executor) sees them exactly as a nested `plugin-include` subtree's services were seen before. Depending on the CONCRETE `dsh-agent-loop` (not just the `dsh-agent` interface) is deliberate and is the sanctioned exception to the "extension plugins depend on interfaces, never on the concrete loop" rule (packages/README.md, docs/architecture.md § Service map): the rule constrains plugins that EXTEND the system, whereas this bundle's whole job is to COMPOSE the concrete spine. Swapping the loop means publishing a different bundle, not rewiring every extension.
 - **`@deepseek-ai/dsh-stdio-agent`** ([packages/ui/stdio-agent](../../../../packages/ui/stdio-agent)) and **`@deepseek-ai/dsh-acp-agent`** ([packages/ui/acp-agent](../../../../packages/ui/acp-agent)) — app packages, each consuming `dsh-agent-core` and **baking in its coupled front-door cluster**: stdio = `ui-stdio` + console logger + a pre-created `main`; acp = the `acp` bridge + JSONL persistence + **no stdout logger** + no pre-created agents. The leaf no longer carries the cluster, so it has no logger entry to copy wrong by default — the common stdout-purity mistake loses its foothold. (A leaf can still *add* a sibling logger entry — a package cannot forbid what a leaf author writes — so the rule "never add a stdout logger to an ACP leaf" stays documented at the leaf; what changed is that the default leaf has nothing to get wrong.) They land under the existing `ui` group alongside `acp`, so no new package group (and no `tsconfig`/`packages/README` group plumbing) was needed.
 - **`start.ts` is gone.** Each app package exposes a `bin` (`dsh-stdio-agent` / `dsh-acp-agent`); the `demo:*` scripts invoke it (e.g. `dsh-stdio-agent ./cordis.yml`). The Loader-boot tail, `.env` loading, and fail-loud guards live in the shared [`@deepseek-ai/dsh-app-boot`](../../../../packages/ui/app-boot) package (unit-tested under the per-file coverage gate — see [share the app bins' boot glue](../simplification/2026-07-04-share-app-bin-boot-glue.md)); each bin is a thin self-executing composition over those helpers plus its app-specific lifecycle (the ACP bin: snapshot-mode selection and stdin-dispose). The `bin.ts` files themselves stay coverage-excluded (self-executing CLI entries, like the old `start.ts`) and are driven by the keyless Loader-path tests.
 - **Each leaf `cordis.yml` collapses** to backends + config: the LLM adapter (`llm-deepseek` with apiKey/models, or `llm-replay`), the bash executor (`bash-local`), `hmr` for the stdio demos (see the amendment below), and one app entry carrying the app's config (model, system prompt, persistence root — surfaced as the app package's own `Config`, which routes each value to wherever the app wires it: stdio onto its pre-created agent, acp onto the bridge plugin).
--- a/docs/rfc/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
+++ b/docs/rfc/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
@@ -67,7 +67,7 @@ Endpoint detection is not part of this RFC because no endpoint-specific mapping

 **Config-only opt-in attribution.** Rejected. A default-off setting is exactly how adapters keep drifting. The policy is mandatory default attribution with overrideable public values, not optional attribution.

-**Product-named token (`deepseek-code`).** Considered for the `User-Agent` token, since the product's name is DeepSeek Code. `deepseek-harness` won on continuity: it is the identity providers already see from this codebase, it matches the org/repo and planned SDK-repo naming, and a public rename can change the product token deliberately later.
+**Product-named token (`deepseek-harness-sdk`).** Considered for the `User-Agent` token, since the product name is DeepSeek Harness SDK. `deepseek-harness` won on continuity: it is the identity providers already see from this codebase, it matches the org/repo identity and package scope, and it keeps wire attribution stable while display copy carries the product name.

 ## Risks / what we give up

--- a/docs/rfc/implemented/architecture/2026-06-30-event-domain-semantics.md
+++ b/docs/rfc/implemented/architecture/2026-06-30-event-domain-semantics.md
@@ -32,4 +32,4 @@ This is the foundational change in a stack that adds a Hooks subsystem; it estab
 - Tests that observed boundaries via the removed emits now observe the durable `turn/start`/`turn/end`/`step/start`/`step/end` session events — the behavior they pin (boundary ordering, step counting) is unchanged; only the feed they read moved to the canonical one. The tests that exercised a *throwing turn-boundary emit listener* were deleted, because that code path no longer exists (there is no emit to throw from). Per [AGENTS.md "tests document behavior, not golden truth"](../../../../AGENTS.md), the behavior and its test moved (or died) together.
 - The loop marks the step open (`stepOpen = true`) BEFORE appending `step/start`, because `Session.append` pushes the event to the log before notifying `session/event` listeners (validation throws happen earlier, before the push — see [the session append contract](../../../core-data-structures/session.md)). So a throwing `step/start` session-event listener runs with the step already open and the event already in the log: the loop's outer catch then calls `closeStep()`, which appends the balancing `step/end`, and the turn closes balanced with an error (`turn/start → step/start → step/end → turn/end` — verified by the invariants oracle in the regression test). Closing the open step is owed precisely because the marker is set first.
 - The full realization of this is [the simplification RFC "Stop mirroring durable boundaries as agent events"](../simplification/2026-06-20-remove-agent-boundary-mirror-events.md): all four boundary mirrors are removed and every consumer reads boundaries off `session/event`. `agent/steering` (not a boundary mirror) stayed outside that RFC's scope and was removed by its own follow-up, [Remove the `agent/steering` mirror emit](../simplification/2026-07-04-remove-agent-steering-mirror.md) — it mirrored the durable `steering/message`.
- The cordis catalog (`docs/cordis-catalog/events-and-services.md`) is regenerated to drop the mirror events.
+- The cordis events catalog (`docs/cordis-catalog/events.md`) is regenerated to drop the mirror events.
--- a/docs/rfc/implemented/process/2026-06-11-doc-sync-enforcement.md
+++ b/docs/rfc/implemented/process/2026-06-11-doc-sync-enforcement.md
@@ -13,7 +13,7 @@ AGENTS.md promises that docs and code stay strictly in sync, but the promise was
 Two gates, mirroring the existing `scripts/` style (tsx ESM, one job each):

 1. **`doc-typecheck`** extracts every fenced ` ```ts ` block from `README.md`, `docs/**`, and `packages/*/README.md`, writes them to a temp project extending the root `tsconfig.json`, and compiles it with `tsc -b`. The temp project reuses the source `paths` map and the root project references, so documentation examples see source while vendored code remains checked under its own tsconfig settings. A block that is a deliberate sketch opts out with an explicit ` ```ts ignore-check ` info string; the script reports the opt-out ratio and fails if it exceeds half, so the escape hatch can't quietly become the norm.
-2. **`verify-event-taxonomy`** extracts the event names from the `interface Events` blocks across `packages/*/src` and from the taxonomy table in `docs/architecture.md`, and asserts the two sets match exactly. Verify, don't generate: the table keeps its hand-written Mode/Purpose columns; only the set of names is checked. (Landing this surfaced three events the table had been missing — `tools/change`, `llm/adapter-change`, `system-prompt/change`.) **Superseded** by [the generated cordis catalog](2026-06-20-generated-cordis-catalog.md): this gate and its `architecture.md` table are retired in favor of a fully-generated `docs/cordis-catalog/events-and-services.md` and its `verify-cordis-catalog` freshness gate. The other gates here (`doc-typecheck`, and the `verify-md-wrap` amendment below) are unaffected.
+2. **`verify-event-taxonomy`** extracts the event names from the `interface Events` blocks across `packages/*/src` and from the taxonomy table in `docs/architecture.md`, and asserts the two sets match exactly. Verify, don't generate: the table keeps its hand-written Mode/Purpose columns; only the set of names is checked. (Landing this surfaced three events the table had been missing — `tools/change`, `llm/adapter-change`, `system-prompt/change`.) **Superseded** by [the generated cordis catalog](2026-06-20-generated-cordis-catalog.md): this gate and its `architecture.md` table are retired in favor of the fully-generated `docs/cordis-catalog/events.md` + `docs/cordis-catalog/services.md` and their `verify-cordis-catalog` freshness gate. The other gates here (`doc-typecheck`, and the `verify-md-wrap` amendment below) are unaffected.

 Both run via a shared `doc-sync` package.json script that the lefthook pre-push hook and CI both invoke ([mechanical quality gates](2026-06-11-quality-gates.md): hooks and CI call the same scripts, so the gate fires locally before a push — not only after it). They run after `pnpm run typecheck`, which validates the package/vendor build graph that doc-typecheck references. API-extractor golden reports ([the deferred API-extractor-reports proposal](../../proposed/process/2026-06-11-api-extractor-reports.md)) were deliberately **deferred** — low value for an internal monorepo where reviewers already see the source diff, and a heavy, finicky dependency.

--- a/docs/rfc/implemented/process/2026-06-11-vendor-cordis-as-source.md
+++ b/docs/rfc/implemented/process/2026-06-11-vendor-cordis-as-source.md
@@ -6,7 +6,7 @@ Status: implemented (accepted 2026-06-11)

 ## Context

-DeepSeek Code is built on the Cordis framework. Cordis core was at 4.0.0-rc.6 (a release candidate) when this repo started; the harness depends on framework internals (fiber lifecycle, effect disposal, waterfall dispatch) whose exact behavior matters to the agent loop's correctness guarantees.
+DeepSeek Harness SDK is built on the Cordis framework. Cordis core was at 4.0.0-rc.6 (a release candidate) when this repo started; the harness depends on framework internals (fiber lifecycle, effect disposal, waterfall dispatch) whose exact behavior matters to the agent loop's correctness guarantees.

 ## Decision

--- a/docs/rfc/implemented/process/2026-06-20-generated-cordis-catalog.md
+++ b/docs/rfc/implemented/process/2026-06-20-generated-cordis-catalog.md
@@ -14,7 +14,7 @@ This is the wiring-axis complement to the [core-data-structures catalog](../../.

 Generate the catalog from source instead of hand-maintaining a table and verifying a subset.

-`scripts/gen-cordis-catalog.ts` walks the `interface Events` and `interface Context` declarations (plus the service classes) with the TypeScript compiler API and emits `docs/cordis-catalog/events-and-services.md` — one `## Events` section (grouped by scope, each event rendered as signature + mode badge + its source JSDoc) and one `## Services` section (each `ctx.<key>` with its public method signatures + class JSDoc). It mirrors the `gen-module-graph` pattern exactly: `--write` regenerates, `--check` fails if the committed file is stale, output is deterministic (sorted), and the file is a build artifact that is never hand-edited. `verify-cordis-catalog` (the `--check`) runs inside `doc-sync`, so the freshness gate fires in the same lefthook pre-push and CI paths as every other doc gate.
+`scripts/gen-cordis-catalog.ts` walks the `interface Events` and `interface Context` declarations (plus the service classes) with the TypeScript compiler API and emits two sibling pages: `docs/cordis-catalog/events.md` (events grouped by scope, each rendered as signature + mode badge + its source JSDoc, plus the dispatch-mode legend) and `docs/cordis-catalog/services.md` (each `ctx.<key>` with its public method signatures + class JSDoc). The two axes are separate documents — a reader is either finding what to listen to or what to call, and each page scans and deep-links as its own reference instead of one long combined scroll. It mirrors the `gen-module-graph` pattern exactly: `--write` regenerates both, `--check` fails if either committed file is stale, output is deterministic (sorted), and the files are build artifacts that are never hand-edited. `verify-cordis-catalog` (the `--check`) runs inside `doc-sync`, so the freshness gate fires in the same lefthook pre-push and CI paths as every other doc gate.

 Pure generation is correct here because the codebase is disciplined enough that the AST is the whole truth: every event/service name is a string literal that round-trips to a static declaration — there are no dynamically-named events and no runtime-only services. So a generated doc cannot be wrong, and it closes the undocumented-event gap structurally (generation enumerates source rather than checking a hand-written subset).

--- a/docs/rfc/implemented/process/2026-06-20-rfc-classification.md
+++ b/docs/rfc/implemented/process/2026-06-20-rfc-classification.md
@@ -30,7 +30,7 @@ The `architecture` / `process` line: **architecture** is about the source we shi
 Both are `doc-sync` members, in the `verify-md-wrap` style (tsx ESM, verify-don't-generate, exit non-zero on the first violation):

 - **`scripts/verify-rfc-classification.ts`** — the closed set and index freshness. It asserts every file under a lifecycle folder lives in a class folder from the canonical set (a loose `.md` at a lifecycle root, or an unknown class folder, fails), and that the README's marker-delimited index regions byte-match a fresh render from the tree (see [generate the RFC index tables](2026-07-04-generate-rfc-index-tables.md)). The canonical class set lives as a `const` in `scripts/rfc-index.ts` — the machine source of truth shared with the generator — and [the index](../../README.md) documents it in prose; the README's class *descriptions* stay hand-written, its tables are generated.
- **`scripts/verify-doc-refs.ts`** — source comments that cite docs. RFC paths are referenced not only from Markdown but from TypeScript doc comments (root-relative prose like `docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md`). `verify-md-links` never saw those, so the reorg could have silently orphaned them. This gate scans repo-authored `.ts` under `packages/**` and `examples/**` (excluding built `lib/` and `vendor/`) for `docs/….md` tokens, resolves each root-relative, and asserts it exists. It requires the `.md` extension so extensionless prose (`docs/postmortem/0001`, `docs/architecture.md § plugin checklist`) is left alone.
+- **`scripts/verify-doc-refs.ts`** — source comments that cite docs. RFC paths are referenced not only from Markdown but from TypeScript doc comments (root-relative prose like `docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md`). `verify-md-links` never saw those, so the reorg could have silently orphaned them. This gate scans repo-authored `.ts` under `packages/**` and `examples/**` (excluding built `lib/` and `vendor/`) for `docs/….md` tokens, resolves each root-relative, and asserts it exists. It requires the `.md` extension so extensionless prose (`docs/postmortem/0001`, `docs/architecture.md § Extending The Harness`) is left alone.

 ### Rejected alternatives

--- a/docs/rfc/implemented/process/2026-07-02-tool-schema-catalog.md
+++ b/docs/rfc/implemented/process/2026-07-02-tool-schema-catalog.md
@@ -4,7 +4,7 @@ Status: implemented (accepted 2026-07-02)

 ## Context

-A reader — a plugin author, a prompt engineer, someone auditing what the agent can do — has no single place that lists the model-facing tools the harness ships. The `name` / `description` / JSON-Schema `parameters` a tool contributes are what the model actually receives (via `ctx.systemPrompt.tools()` off `ctx.tools.schemas()`), but they are scattered across each `defineTool` call in each `packages/*/tool-*` package, buried in string concatenation and runtime spreads. The [cordis events & services catalog](../../../cordis-catalog/events-and-services.md) ([its RFC](2026-06-20-generated-cordis-catalog.md)) documents the *wiring* a plugin works against and the [core-data-structures catalog](../../../core-data-structures/core.md) documents the *vocabulary* those signatures move — but neither documents the *tools* the agent is offered. This RFC adds that third reference surface, `docs/tool-catalog/tools.md`, and a freshness gate so it cannot drift.
+A reader — a plugin author, a prompt engineer, someone auditing what the agent can do — has no single place that lists the model-facing tools the harness ships. The `name` / `description` / JSON-Schema `parameters` a tool contributes are what the model actually receives (via `ctx.systemPrompt.tools()` off `ctx.tools.schemas()`), but they are scattered across each `defineTool` call in each `packages/*/tool-*` package, buried in string concatenation and runtime spreads. The cordis [events](../../../cordis-catalog/events.md) & [services](../../../cordis-catalog/services.md) catalogs ([their RFC](2026-06-20-generated-cordis-catalog.md)) document the *wiring* a plugin works against and the [core-data-structures catalog](../../../core-data-structures/core.md) documents the *vocabulary* those signatures move — but neither documents the *tools* the agent is offered. This RFC adds that third reference surface, `docs/tool-catalog/tools.md`, and a freshness gate so it cannot drift.

 ## Decision

--- a/docs/rfc/implemented/process/2026-07-03-documentation-graph-atlas.md
+++ b/docs/rfc/implemented/process/2026-07-03-documentation-graph-atlas.md
@@ -0,0 +1,67 @@
+# RFC: Documentation graph index for maintainers and SDK users
+
+Status: implemented (accepted 2026-07-03)
+
+## Context
+
+The repo already had several high-trust documentation surfaces, each on a different axis: [module-graph.md](../../../module-graph.md) is generated from package `peerDependencies`, the generated [Cordis events](../../../cordis-catalog/events.md) and [services](../../../cordis-catalog/services.md) catalogs are generated from Cordis `Events` and `Context` declarations, [tool-catalog/tools.md](../../../tool-catalog/tools.md) is generated by booting shipped tool plugins, and [core-data-structures/](../../../core-data-structures/core.md) uses `ts type-equiv` blocks to keep pasted type definitions synchronized with source.
+
+Those references are accurate, but they are mostly catalogs. A maintainer still has to synthesize the relationships: which packages form a capability seam, which app bundles a concrete spine, which event is durable vs live, where a hook or policy plugin can intercept work, and which model-facing tool depends on which service. An SDK user has the same problem from another angle: "Which package do I install or load for the behavior I want, and which event/service/tool do I extend?"
+
+The pressure is already visible in the open stacks even though this implementation is based on `origin/master`: the hooks stack through PR #129 makes event producer/consumer topology and interception points much more important, while the filesystem stack through PR #128 makes capability seams, policy vetoes, tool presentation, and SDK assembly paths much more important. Graphs based only on today's small bash/todo/subagent surface would become obsolete as soon as those stacks land.
+
+## Decision
+
+Add generated relationship graph docs, indexed at [docs/graph-atlas.md](../../../graph-atlas.md), produced by focused generators and verified by `pnpm run verify-doc-graphs` / existing catalog freshness checks as part of `doc-sync`.
+
+The index is a relationship layer above the existing catalogs. It does not replace exact references; instead, it links to them and explains how their pieces fit together.
+
+### Maintenance modes
+
+Every graph page declares one maintenance mode:
+
+- **Generated**: all nodes and edges are discovered from source; `--check` fails if the committed artifact is stale.
+- **Hybrid generated**: source discovers the inventory, a small manifest classifies irreducible policy, and a completeness guard fails if discovered items are unclassified.
+- **Curated**: the diagram explains design intent, temporal order, or ownership; it is emitted by the generator so the graph docs remain a regenerated unit, but the content is deliberately authored.
+
+### First shipped index
+
+The first index links ten relationship surfaces. Package topology and tool-package affordances live in the existing generated catalogs that already own those facts; the remaining focused diagrams are generated by `scripts/gen-doc-graphs.ts`.
+
+| Graph | Maintenance mode | Source of truth |
+|---|---|---|
+| [module dependency graph](../../../module-graph.md) | generated | `packages/*/*/package.json` peer dependencies plus package group paths |
+| [tool schema catalog and package map](../../../tool-catalog/tools.md) | generated | boot-harvested tool schemas plus tool-package service/effect metadata |
+| [capability seams and core services](../../../capability-seams.md) | hybrid generated | Cordis service declarations plus a role manifest in `gen-doc-graphs.ts` |
+| [echo-agent app composition](../../../../examples/echo-agent/composition.md) | hybrid generated | `examples/echo-agent/cordis.yml` plugin list plus curated app/bundle expansion |
+| [coding-agent app composition](../../../../examples/coding-agent/composition.md) | hybrid generated | `examples/coding-agent/cordis.yml` plugin list plus curated app/bundle expansion |
+| [acp-agent app composition](../../../../examples/acp-agent/composition.md) | hybrid generated | `examples/acp-agent/cordis.yml` plugin list plus curated app/bundle expansion |
+| [event producer/consumer matrix](../../../event-producer-consumer.md) | hybrid generated | Cordis event declarations, AST-scanned `ctx.on/emit/parallel/serial/waterfall` sites, and explicit dynamic dispatch overrides |
+| [agent turn and step lifecycle](../../../agent-lifecycle.md) | curated | architecture.md loop lifecycle, Cordis catalog links, and session event semantics |
+| [tool execution pipeline](../../../tool-execution-pipeline.md) | curated | tool pipeline semantics and the `tools/execute` waterfall |
+| [ACP snapshot replay](../../../acp/snapshot-replay.md) | curated | snapshot harness behavior |
+
+### Why generators own the docs
+
+Package topology stays in `gen-module-graph.ts`, and tool-package affordances stay in `gen-tool-catalog.ts`, because those generators already own the canonical facts and freshness gates. `gen-doc-graphs.ts` owns the remaining relationship pages and the index. The tradeoff is that curated diagrams are edited in TypeScript string blocks rather than directly in Markdown. That is acceptable for this first cut because the user-facing artifact is still plain Markdown/Mermaid, and a future change can split the curated pages out if authorship ergonomics matter more than regeneration.
+
+### Completeness guards
+
+The hybrid pages must fail loud when their manifests are stale:
+
+- The module graph reads every package's `peerDependencies` and groups each package by its `packages/<group>/<pkg>` path.
+- The tool catalog boot-harvests shipped tools and renders the package/service/effect map from the same manifest that its completeness guard already checks.
+- The capability seam graph imports the Cordis service collector and asserts every discovered harness `ctx.<key>` is classified in `SERVICE_ROLES`, and every classified key still exists.
+- The event producer/consumer matrix labels itself hybrid because subagent lifecycle events deliberately use `ctx.events.dispatch` for per-listener containment; those dynamic edges are explicit overrides rather than invisible omissions.
+- `verify-mermaid` parses every repo-authored ` ```mermaid ` fence with Mermaid's own parser, so syntax errors fail `doc-sync` locally and in CI instead of showing up as broken GitHub-rendered diagrams.
+
+## Format choices
+
+Use Mermaid for committed diagrams because GitHub renders it in Markdown and it adds no new docs build dependency. Use Markdown tables for dense many-to-many data such as event producer/consumer relationships. Do not adopt PlantUML, hosted diagram services, or generated SVGs until Mermaid becomes the limiting factor.
+
+## Consequences
+
+- Maintainers get visual entry points for topology, seams, event flow, lifecycle, app composition, and snapshot behavior.
+- SDK users get a path from use case to package composition instead of only bottom-up package references.
+- `doc-sync` now includes `verify-doc-graphs` and `verify-mermaid`, so graph drift and Mermaid syntax errors are caught with the other doc freshness gates.
+- Future fs and hooks work has a concrete place to land new complexity: fs should expand the capability docs and tool catalog, while hooks should expand the event matrix and tool execution pipeline.
--- a/docs/tool-catalog/tools.md
+++ b/docs/tool-catalog/tools.md
@@ -3,12 +3,24 @@

 # Tool Schema Catalog

-Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the [cordis events & services catalog](../cordis-catalog/events-and-services.md) (the wiring a plugin listens to and calls) and [core-data-structures/](../core-data-structures/core.md) (the types those signatures move) — this page is the *tools* the agent is offered.
+Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the cordis [events](../cordis-catalog/events.md) & [services](../cordis-catalog/services.md) catalogs (the wiring a plugin listens to and calls) and [core-data-structures/](../core-data-structures/core.md) (the types those signatures move) — this page is the *tools* the agent is offered.

 This file is GENERATED and verified fresh by `pnpm run verify-tool-catalog` (part of `doc-sync`) — do not edit it by hand. Unlike the cordis catalog (a pure source-AST pass), this generator BOOTS each tool plugin on a real context and reads `ctx.tools.schemas()`, because a tool schema is not statically knowable (runtime-spread enums, concatenated descriptions, config-driven names, raw-JSON-Schema MCP tools). A completeness guard globs `packages/*/tool-*` and fails if any package is missing from the generator's boot manifest, so a new tool cannot be silently undocumented. See [the tool-schema-catalog RFC](../rfc/implemented/process/2026-07-02-tool-schema-catalog.md).

 Scope: shipped product tools under `packages/*/tool-*`, each booted with its DEFAULT config. The registered tool NAME can be a load-time config (e.g. `tool-subagent`'s `toolName`), so a deployment may surface a package under a different or additional name — a per-package note records those shipped aliases where they exist. The `examples/` demo tools (e.g. `echo`) are excluded, matching the cordis catalog's packages-only scope.

+## Tool Package Map
+
+This table connects model-visible tool names to the plugin package and service seams behind them. Exact JSON Schemas follow in the package sections below.
+
+| Tool package | Model-visible names | Requires | Writes / affects | Shipped aliases | Deployment note |
+| --- | --- | --- | --- | --- | --- |
+| `@deepseek-ai/dsh-tool-bash` | `bash`, `bash_kill`, `bash_output` | `ctx.tools`, `ctx.bash` | `tool/call`, `tool/result`, `context/message via agent.inject() for background completion notices` | - | The bash/bash_output/bash_kill tools are model-facing consumers of the bash executor seam. |
+| `@deepseek-ai/dsh-tool-fs` | `edit`, `read`, `write` | `ctx.tools`, `ctx.fs`, `ctx.systemPrompt` | `tool/call`, `fs/write-intent or fs/edit-intent for mutations`, `fs/observed after successful file operations`, `tool/result` | - | The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-policy` (an `fs/*` event-gate plugin, no schema change); a deployment that loads these tools is expected to also load it. The tool schemas above are identical with or without the policy plugin. |
+| `@deepseek-ai/dsh-tool-subagent` | `subagent` | `ctx.tools`, `ctx.subagents` | `tool/call`, `tool/result`, `child session events through the chosen provider` | `subagent`, `subagent_fork` | The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `examples/coding-agent/cordis.yml` and `examples/acp-agent/cordis.yml`. |
+| `@deepseek-ai/dsh-tool-todo` | `todo_write` | `ctx.tools`, `owning Agent session` | `tool/call`, `todo/write`, `tool/result` | - | todo_write is session-owned state; UIs render the latest todo/write event as a checklist or ACP plan. |
+| `@deepseek-ai/dsh-tool-web` | `web_fetch`, `web_search` | `ctx.tools`, `ctx.web`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | web_search and web_fetch keep provider selection behind ctx.web so model-visible schemas stay stable across backend swaps. |
+
 ## `@deepseek-ai/dsh-tool-bash`

 ### `bash`
@@ -91,6 +103,8 @@ Read new output from a background bash task started with `bash` + `run_in_backgr

 Source: [`packages/bash/tool-bash/src/index.ts`](../../packages/bash/tool-bash/src/index.ts)

+The bash/bash_output/bash_kill tools are model-facing consumers of the bash executor seam.
+
 ## `@deepseek-ai/dsh-tool-fs`

 ### `edit`
@@ -260,6 +274,8 @@ Record and update a structured task list for the current work. Send the ENTIRE l

 Source: [`packages/todo/tool-todo/src/index.ts`](../../packages/todo/tool-todo/src/index.ts)

+todo_write is session-owned state; UIs render the latest todo/write event as a checklist or ACP plan.
+
 ## `@deepseek-ai/dsh-tool-web`

 ### `web_fetch`
@@ -307,3 +323,5 @@ Search the web for current information. Returns an optional summary answer and a
 ```

 Source: [`packages/web/tool-web/src/index.ts`](../../packages/web/tool-web/src/index.ts)
+
+web_search and web_fetch keep provider selection behind ctx.web so model-visible schemas stay stable across backend swaps.
--- a/docs/tool-execution-pipeline.md
+++ b/docs/tool-execution-pipeline.md
@@ -0,0 +1,39 @@
+<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
+     Run `pnpm run gen-doc-graphs` to regenerate. -->
+
+# Tool Execution Pipeline
+
+This graph shows where policy, hooks, sandboxing, filesystem guards, result rewriting, and UI rendering fit without changing the loop. The key extension points are the `tools/pre-execute` and `tools/post-execute` waterfalls.
+
+```mermaid
+flowchart TD
+  model["Assistant message contains tool-call block"]
+  toolCall["Session event: <code>tool/call</code><br/>logged before execution"]
+  presentCall["UI pending card<br/>presentCall(args)"]
+  pre["<code>tools/pre-execute</code> waterfall<br/>hooks, permission, sandbox"]
+  denied["deny or ask<br/>tool body skipped"]
+  toolBody["Registered tool execute() body"]
+  fsGate["<code>fs/write-intent</code> or <code>fs/edit-intent</code><br/>tool-fs mutations only"]
+  owned["Tool-owned session events<br/><code>todo/write</code>, <code>fs/observed</code>, <code>hook/invoked</code>, <code>hook/result</code>"]
+  post["<code>tools/post-execute</code> waterfall<br/>accept, block, replace, add context"]
+  context["Buffered additionalContext<br/>context/message after all tool results"]
+  toolResult["Session event: <code>tool/result</code><br/>single model-facing outcome"]
+  presentResult["UI completed card<br/>presentResult(args, result)"]
+  model --> toolCall
+  toolCall --> presentCall
+  toolCall --> pre
+  pre -->|allow| toolBody
+  pre -->|deny or ask| denied
+  denied --> post
+  toolBody --> fsGate
+  fsGate --> toolBody
+  toolBody --> owned
+  toolBody --> post
+  post --> context
+  post --> toolResult
+  toolResult --> presentResult
+```
+
+Filesystem read-before-edit checks live below `tool-fs` on the `fs/*` event gate, while hook bridges and future permission prompts live on the generic tool waterfalls. That split lets the same hooks observe bash, fs, web, todo, and subagent calls without coupling those tools to one policy service.
+
+Maintenance mode: curated Mermaid flow; exact tool schemas and event signatures live in generated catalogs.
--- a/examples/acp-agent/README.md
+++ b/examples/acp-agent/README.md
@@ -1,6 +1,6 @@
 # acp-agent example

-The DeepSeek Harness agent demo exposed as an **Agent Client Protocol (ACP)** server over JSON-RPC stdio — drive it from Zed or any other ACP client.
+The DeepSeek Harness SDK agent demo exposed as an **Agent Client Protocol (ACP)** server over JSON-RPC stdio — drive it from Zed or any other ACP client.

 ```sh
 pnpm run demo:acp          # needs DEEPSEEK_API_KEY (repo-root .env or env)
--- a/examples/acp-agent/composition.md
+++ b/examples/acp-agent/composition.md
@@ -0,0 +1,67 @@
+<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
+     Run `pnpm run gen-doc-graphs` to regenerate. -->
+
+# ACP Agent App Composition
+
+The ACP demo exposes the same agent spine over JSON-RPC stdio, with no stdout logger and no pre-created agent; clients create sessions through the ACP bridge.
+
+```mermaid
+flowchart LR
+  cfg["examples/acp-agent<br/>cordis.yml"]
+  plugin_acp_llm_deepseek["llm-deepseek<br/>@deepseek-ai/dsh-llm-deepseek"]
+  cfg --> plugin_acp_llm_deepseek
+  plugin_acp_bash["bash<br/>@deepseek-ai/dsh-bash-local"]
+  cfg --> plugin_acp_bash
+  plugin_acp_acp_agent["acp-agent<br/>@deepseek-ai/dsh-acp-agent"]
+  cfg --> plugin_acp_acp_agent
+  plugin_acp_acp_agent --> bundle_agent_core["@deepseek-ai/dsh-agent-core"]
+  plugin_acp_acp_agent --> bundle_jsonl["@deepseek-ai/dsh-session-persistence-jsonl"]
+  plugin_acp_acp_agent --> frontdoor_acp["@deepseek-ai/dsh-acp<br/>JSON-RPC stdio bridge<br/>sessions created by client"]
+  bundle_agent_core --> spine_llm["ctx.llm"]
+  bundle_agent_core --> spine_sessions["ctx.sessions"]
+  bundle_agent_core --> spine_tools["ctx.tools + tool-bash"]
+  bundle_agent_core --> spine_loop["ctx.agents + ctx.agentLoop"]
+  plugin_acp_subagent["subagent<br/>@deepseek-ai/dsh-subagent"]
+  cfg --> plugin_acp_subagent
+  plugin_acp_subagent_spawn["subagent-spawn<br/>@deepseek-ai/dsh-subagent-spawn"]
+  cfg --> plugin_acp_subagent_spawn
+  plugin_acp_subagent_fork["subagent-fork<br/>@deepseek-ai/dsh-subagent-fork"]
+  cfg --> plugin_acp_subagent_fork
+  plugin_acp_tool_subagent["tool-subagent<br/>@deepseek-ai/dsh-tool-subagent"]
+  cfg --> plugin_acp_tool_subagent
+  plugin_acp_tool_subagent_fork["tool-subagent-fork<br/>@deepseek-ai/dsh-tool-subagent"]
+  cfg --> plugin_acp_tool_subagent_fork
+  plugin_acp_tool_todo["tool-todo<br/>@deepseek-ai/dsh-tool-todo"]
+  cfg --> plugin_acp_tool_todo
+  plugin_acp_fs_local["fs-local<br/>@deepseek-ai/dsh-fs-local"]
+  cfg --> plugin_acp_fs_local
+  plugin_acp_fs_policy["fs-policy<br/>@deepseek-ai/dsh-fs-policy"]
+  cfg --> plugin_acp_fs_policy
+  plugin_acp_tool_fs["tool-fs<br/>@deepseek-ai/dsh-tool-fs"]
+  cfg --> plugin_acp_tool_fs
+  plugin_acp_hooks_claude["hooks-claude<br/>@deepseek-ai/dsh-hooks-claude"]
+  cfg --> plugin_acp_hooks_claude
+  plugin_acp_hooks_codex["hooks-codex<br/>@deepseek-ai/dsh-hooks-codex"]
+  cfg --> plugin_acp_hooks_codex
+```
+
+| Plugin id | Package / module |
+| --- | --- |
+| `llm-deepseek` | `@deepseek-ai/dsh-llm-deepseek` |
+| `bash` | `@deepseek-ai/dsh-bash-local` |
+| `acp-agent` | `@deepseek-ai/dsh-acp-agent` |
+| `subagent` | `@deepseek-ai/dsh-subagent` |
+| `subagent-spawn` | `@deepseek-ai/dsh-subagent-spawn` |
+| `subagent-fork` | `@deepseek-ai/dsh-subagent-fork` |
+| `tool-subagent` | `@deepseek-ai/dsh-tool-subagent` |
+| `tool-subagent-fork` | `@deepseek-ai/dsh-tool-subagent` |
+| `tool-todo` | `@deepseek-ai/dsh-tool-todo` |
+| `fs-local` | `@deepseek-ai/dsh-fs-local` |
+| `fs-policy` | `@deepseek-ai/dsh-fs-policy` |
+| `tool-fs` | `@deepseek-ai/dsh-tool-fs` |
+| `hooks-claude` | `@deepseek-ai/dsh-hooks-claude` |
+| `hooks-codex` | `@deepseek-ai/dsh-hooks-codex` |
+
+Source config: [`examples/acp-agent/cordis.yml`](cordis.yml).
+
+Maintenance mode: hybrid: the leaf plugin list is parsed from its `cordis.yml`; app package expansion is curated from package source.
--- a/examples/coding-agent/composition.md
+++ b/examples/coding-agent/composition.md
@@ -0,0 +1,67 @@
+<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
+     Run `pnpm run gen-doc-graphs` to regenerate. -->
+
+# Coding Agent App Composition
+
+The coding REPL demo adds the real DeepSeek adapter, filesystem tools, todo_write, compaction, and both subagent transports on top of the stdio app package.
+
+```mermaid
+flowchart LR
+  cfg["examples/coding-agent<br/>cordis.yml"]
+  plugin_coding_hmr["hmr<br/>@cordisjs/plugin-hmr"]
+  cfg --> plugin_coding_hmr
+  plugin_coding_llm_deepseek["llm-deepseek<br/>@deepseek-ai/dsh-llm-deepseek"]
+  cfg --> plugin_coding_llm_deepseek
+  plugin_coding_bash["bash<br/>@deepseek-ai/dsh-bash-local"]
+  cfg --> plugin_coding_bash
+  plugin_coding_stdio_agent["stdio-agent<br/>@deepseek-ai/dsh-stdio-agent"]
+  cfg --> plugin_coding_stdio_agent
+  plugin_coding_stdio_agent --> bundle_agent_core["@deepseek-ai/dsh-agent-core"]
+  plugin_coding_stdio_agent --> bundle_jsonl["@deepseek-ai/dsh-session-persistence-jsonl"]
+  plugin_coding_stdio_agent --> frontdoor_stdio["readline UI<br/>console logger<br/>pre-created main agent"]
+  bundle_agent_core --> spine_llm["ctx.llm"]
+  bundle_agent_core --> spine_sessions["ctx.sessions"]
+  bundle_agent_core --> spine_tools["ctx.tools + tool-bash"]
+  bundle_agent_core --> spine_loop["ctx.agents + ctx.agentLoop"]
+  plugin_coding_compact_basic["compact-basic<br/>@deepseek-ai/dsh-compact-basic"]
+  cfg --> plugin_coding_compact_basic
+  plugin_coding_subagent["subagent<br/>@deepseek-ai/dsh-subagent"]
+  cfg --> plugin_coding_subagent
+  plugin_coding_subagent_spawn["subagent-spawn<br/>@deepseek-ai/dsh-subagent-spawn"]
+  cfg --> plugin_coding_subagent_spawn
+  plugin_coding_subagent_fork["subagent-fork<br/>@deepseek-ai/dsh-subagent-fork"]
+  cfg --> plugin_coding_subagent_fork
+  plugin_coding_tool_subagent["tool-subagent<br/>@deepseek-ai/dsh-tool-subagent"]
+  cfg --> plugin_coding_tool_subagent
+  plugin_coding_tool_subagent_fork["tool-subagent-fork<br/>@deepseek-ai/dsh-tool-subagent"]
+  cfg --> plugin_coding_tool_subagent_fork
+  plugin_coding_tool_todo["tool-todo<br/>@deepseek-ai/dsh-tool-todo"]
+  cfg --> plugin_coding_tool_todo
+  plugin_coding_fs_local["fs-local<br/>@deepseek-ai/dsh-fs-local"]
+  cfg --> plugin_coding_fs_local
+  plugin_coding_fs_policy["fs-policy<br/>@deepseek-ai/dsh-fs-policy"]
+  cfg --> plugin_coding_fs_policy
+  plugin_coding_tool_fs["tool-fs<br/>@deepseek-ai/dsh-tool-fs"]
+  cfg --> plugin_coding_tool_fs
+```
+
+| Plugin id | Package / module |
+| --- | --- |
+| `hmr` | `@cordisjs/plugin-hmr` |
+| `llm-deepseek` | `@deepseek-ai/dsh-llm-deepseek` |
+| `bash` | `@deepseek-ai/dsh-bash-local` |
+| `stdio-agent` | `@deepseek-ai/dsh-stdio-agent` |
+| `compact-basic` | `@deepseek-ai/dsh-compact-basic` |
+| `subagent` | `@deepseek-ai/dsh-subagent` |
+| `subagent-spawn` | `@deepseek-ai/dsh-subagent-spawn` |
+| `subagent-fork` | `@deepseek-ai/dsh-subagent-fork` |
+| `tool-subagent` | `@deepseek-ai/dsh-tool-subagent` |
+| `tool-subagent-fork` | `@deepseek-ai/dsh-tool-subagent` |
+| `tool-todo` | `@deepseek-ai/dsh-tool-todo` |
+| `fs-local` | `@deepseek-ai/dsh-fs-local` |
+| `fs-policy` | `@deepseek-ai/dsh-fs-policy` |
+| `tool-fs` | `@deepseek-ai/dsh-tool-fs` |
+
+Source config: [`examples/coding-agent/cordis.yml`](cordis.yml).
+
+Maintenance mode: hybrid: the leaf plugin list is parsed from its `cordis.yml`; app package expansion is curated from package source.
--- a/examples/echo-agent/composition.md
+++ b/examples/echo-agent/composition.md
@@ -0,0 +1,40 @@
+<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
+     Run `pnpm run gen-doc-graphs` to regenerate. -->
+
+# Echo Agent App Composition
+
+The echo demo swaps in a local mock LLM and teaching echo tool, then loads the stdio app package for the shared spine and terminal front door.
+
+```mermaid
+flowchart LR
+  cfg["examples/echo-agent<br/>cordis.yml"]
+  plugin_echo_hmr["hmr<br/>@cordisjs/plugin-hmr"]
+  cfg --> plugin_echo_hmr
+  plugin_echo_mock_llm["mock-llm<br/>./src/mock-llm.ts"]
+  cfg --> plugin_echo_mock_llm
+  plugin_echo_echo_tool["echo-tool<br/>./src/echo-tool.ts"]
+  cfg --> plugin_echo_echo_tool
+  plugin_echo_bash["bash<br/>@deepseek-ai/dsh-bash-local"]
+  cfg --> plugin_echo_bash
+  plugin_echo_stdio_agent["stdio-agent<br/>@deepseek-ai/dsh-stdio-agent"]
+  cfg --> plugin_echo_stdio_agent
+  plugin_echo_stdio_agent --> bundle_agent_core["@deepseek-ai/dsh-agent-core"]
+  plugin_echo_stdio_agent --> bundle_jsonl["@deepseek-ai/dsh-session-persistence-jsonl"]
+  plugin_echo_stdio_agent --> frontdoor_stdio["readline UI<br/>console logger<br/>pre-created main agent"]
+  bundle_agent_core --> spine_llm["ctx.llm"]
+  bundle_agent_core --> spine_sessions["ctx.sessions"]
+  bundle_agent_core --> spine_tools["ctx.tools + tool-bash"]
+  bundle_agent_core --> spine_loop["ctx.agents + ctx.agentLoop"]
+```
+
+| Plugin id | Package / module |
+| --- | --- |
+| `hmr` | `@cordisjs/plugin-hmr` |
+| `mock-llm` | `./src/mock-llm.ts` |
+| `echo-tool` | `./src/echo-tool.ts` |
+| `bash` | `@deepseek-ai/dsh-bash-local` |
+| `stdio-agent` | `@deepseek-ai/dsh-stdio-agent` |
+
+Source config: [`examples/echo-agent/cordis.yml`](cordis.yml).
+
+Maintenance mode: hybrid: the leaf plugin list is parsed from its `cordis.yml`; app package expansion is curated from package source.
--- a/package.json
+++ b/package.json
@@ -29,6 +29,7 @@
    "verify-md-links": "tsx scripts/verify-md-links.ts",
    "verify-doc-refs": "tsx scripts/verify-doc-refs.ts",
    "verify-package-paths": "tsx scripts/verify-package-paths.ts",
+    "verify-mermaid": "tsx scripts/verify-mermaid.ts",
    "verify-rfc-classification": "tsx scripts/verify-rfc-classification.ts",
    "verify-type-equiv": "tsx scripts/verify-type-equiv.ts",
    "verify-translation-pairing": "tsx scripts/verify-translation-pairing.ts",
@@ -39,12 +40,14 @@
    "verify-cordis-catalog": "tsx scripts/gen-cordis-catalog.ts --check",
    "gen-tool-catalog": "tsx scripts/gen-tool-catalog.ts",
    "verify-tool-catalog": "tsx scripts/gen-tool-catalog.ts --check",
+    "gen-doc-graphs": "tsx scripts/gen-doc-graphs.ts",
+    "verify-doc-graphs": "tsx scripts/gen-doc-graphs.ts --check",
    "gen-persistence-catalog": "tsx scripts/gen-persistence-catalog.ts",
    "verify-persistence-catalog": "tsx scripts/gen-persistence-catalog.ts --check",
    "gen-module-graph": "tsx scripts/gen-module-graph.ts",
    "verify-module-graph": "tsx scripts/gen-module-graph.ts --check",
    "constraints": "tsx scripts/check-workspace-constraints.ts",
-    "doc-sync": "pnpm run doc-typecheck && pnpm run verify-cordis-catalog && pnpm run verify-tool-catalog && pnpm run verify-persistence-catalog && pnpm run verify-md-wrap && pnpm run verify-md-links && pnpm run verify-doc-refs && pnpm run verify-package-paths && pnpm run verify-rfc-classification && pnpm run verify-type-equiv && pnpm run verify-translation-pairing && pnpm run verify-doc-budgets",
+    "doc-sync": "pnpm run doc-typecheck && pnpm run verify-cordis-catalog && pnpm run verify-tool-catalog && pnpm run verify-persistence-catalog && pnpm run verify-doc-graphs && pnpm run verify-md-wrap && pnpm run verify-md-links && pnpm run verify-doc-refs && pnpm run verify-package-paths && pnpm run verify-mermaid && pnpm run verify-rfc-classification && pnpm run verify-type-equiv && pnpm run verify-translation-pairing && pnpm run verify-doc-budgets",
    "hygiene": "pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-node-next-types",
    "demo:echo": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/echo-agent/cordis.yml",
    "demo:repl": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/coding-agent/cordis.yml",
@@ -54,15 +57,18 @@
  "devDependencies": {
    "@agentclientprotocol/sdk": "0.25.1",
    "@stylistic/eslint-plugin": "^5.10.0",
+    "@types/jsdom": "^28.0.3",
    "@types/mdast": "^4.0.4",
    "@types/node": "^25.3.5",
    "@vitest/coverage-v8": "^4.1.8",
    "eslint": "^10.4.1",
    "fast-check": "^4.8.0",
+    "jsdom": "29.1.1",
    "knip": "^6.16.1",
    "lefthook": "^2.1.9",
    "mdast-util-from-markdown": "^2.0.3",
    "mdast-util-gfm": "^3.1.0",
+    "mermaid": "11.16.0",
    "micromark-extension-gfm": "^3.0.0",
    "publint": "^0.3.21",
    "tsdown": "^0.22.2",
--- a/packages/bash/bash-local/README.md
+++ b/packages/bash/bash-local/README.md
@@ -27,4 +27,4 @@ Design surveyed against the bash tools of Claude Code, OpenCode, Codex, and pi;

 ## Sandboxing

-`TODO(permissions/sandbox)`: execution policy does NOT belong in this package. Use the `tools/pre-execute` deny/ask gate or implement a sandboxing `BashExecutor` — see docs/architecture.md § plugin checklist. Reference points: Claude Code wraps commands in sandbox-exec/bubblewrap; Codex applies seatbelt/landlock plus an execpolicy prefix-rule engine.
+`TODO(permissions/sandbox)`: execution policy does NOT belong in this package. Use the `tools/pre-execute` deny/ask gate or implement a sandboxing `BashExecutor` — see docs/architecture.md § Extending The Harness. Reference points: Claude Code wraps commands in sandbox-exec/bubblewrap; Codex applies seatbelt/landlock plus an execpolicy prefix-rule engine.
--- a/packages/bash/bash-local/src/index.ts
+++ b/packages/bash/bash-local/src/index.ts
@@ -5,8 +5,9 @@
 * survey notes), tracks background tasks, and kills everything on dispose.
 *
 * TODO(permissions/sandbox): execution policy does NOT belong here — use
- * the `tools/pre-execute` deny/ask gate (see docs/architecture.md § plugin
- * checklist) or implement a sandboxing `BashExecutor`. Reference points:
+ * the `tools/pre-execute` deny/ask gate (see docs/architecture.md
+ * § Extending The Harness) or implement a sandboxing `BashExecutor`.
+ * Reference points:
 * Claude Code wraps commands in sandbox-exec/bubblewrap; Codex applies
 * seatbelt/landlock plus an execpolicy prefix-rule engine.
 *
--- a/packages/bash/tool-bash/src/index.ts
+++ b/packages/bash/tool-bash/src/index.ts
@@ -33,7 +33,7 @@
 * TODO(permissions): commands run with the executor's full authority. The
 * permission/sandbox seam is the `tools/pre-execute` waterfall (deny/ask) plus
 * sandboxing `BashExecutor` implementations — see docs/architecture.md
- * § plugin checklist.
+ * § Extending The Harness.
 *
 * @module @deepseek-ai/dsh-tool-bash
 */
--- a/packages/core/system-prompt/tests/system-prompt.spec.ts
+++ b/packages/core/system-prompt/tests/system-prompt.spec.ts
@@ -7,17 +7,17 @@ describe('SystemPrompt', () => {
    const ctx = new Context()
    await ctx.plugin(SystemPrompt)

-    ctx.systemPrompt.section({ name: 'persona', order: 0, text: 'You are DeepSeek Code.' })
+    ctx.systemPrompt.section({ name: 'persona', order: 0, text: 'You are DeepSeek Harness SDK.' })
    ctx.systemPrompt.section({ name: 'cwd', order: 20, text: () => 'cwd: /tmp' })
    ctx.systemPrompt.section({ name: 'rules', order: 10, text: 'Be precise.' })
    ctx.systemPrompt.tools(() => [{ name: 'echo', description: 'echo back', parameters: {} }])

    const assembly = await ctx.systemPrompt.assemble()
    expect(assembly.sections.map(s => s.name)).toEqual(['persona', 'rules', 'cwd'])
-    expect(assembly.sections.map(s => s.text)).toEqual(['You are DeepSeek Code.', 'Be precise.', 'cwd: /tmp'])
+    expect(assembly.sections.map(s => s.text)).toEqual(['You are DeepSeek Harness SDK.', 'Be precise.', 'cwd: /tmp'])
    expect(assembly.tools).toEqual([{ name: 'echo', description: 'echo back', parameters: {} }])
    expect(assembly.variables).toEqual({})
-    expect(renderPrompt(assembly)).toBe('You are DeepSeek Code.\n\nBe precise.\n\ncwd: /tmp')
+    expect(renderPrompt(assembly)).toBe('You are DeepSeek Harness SDK.\n\nBe precise.\n\ncwd: /tmp')
  })

  it('resolves section text providers against the assemble context, at each assemble call', async () => {
--- a/packages/core/tools/tests/gen-tool-catalog.spec.ts
+++ b/packages/core/tools/tests/gen-tool-catalog.spec.ts
@@ -93,10 +93,13 @@ describe('gen-tool-catalog render', () => {
      {
        pkg: '@deepseek-ai/dsh-tool-demo',
        source: 'packages/demo/tool-demo/src/index.ts',
+        requires: ['ctx.tools'],
+        writes: ['tool/result'],
        schemas: [{ name: 'demo', description: 'A demo tool.', parameters: { type: 'object', properties: {} } }],
      },
    ]
    const md = render(catalog)
+    expect(md).toContain('| `@deepseek-ai/dsh-tool-demo` | `demo` | `ctx.tools` | `tool/result` |')
    expect(md).toContain('## `@deepseek-ai/dsh-tool-demo`')
    expect(md).toContain('### `demo`')
    expect(md).toContain('A demo tool.')
--- a/packages/fs/fs/README.md
+++ b/packages/fs/fs/README.md
@@ -31,7 +31,7 @@ The mutation runs inside the backend's per-target lock either way, so an uncondi

 ## The `fs/*` policy events

-This package declares three events (see the generated [catalog](../../../docs/cordis-catalog/events-and-services.md)) so the emitter (`@deepseek-ai/dsh-tool-fs`) and the policy listener (`@deepseek-ai/dsh-fs-policy`) share a vocabulary without the emitter depending on the policy plugin. `fs/write-intent` and `fs/edit-intent` are single-slot decision waterfalls (the listener fully decides, never calling `next()`); `fs/observed` is a fire-and-forget recording event. They carry only `dsh-fs` vocabulary plus an opaque `object` actor — no model-facing concepts and no agent/session owner structure.
+This package declares three events (see the generated [events catalog](../../../docs/cordis-catalog/events.md)) so the emitter (`@deepseek-ai/dsh-tool-fs`) and the policy listener (`@deepseek-ai/dsh-fs-policy`) share a vocabulary without the emitter depending on the policy plugin. `fs/write-intent` and `fs/edit-intent` are single-slot decision waterfalls (the listener fully decides, never calling `next()`); `fs/observed` is a fire-and-forget recording event. They carry only `dsh-fs` vocabulary plus an opaque `object` actor — no model-facing concepts and no agent/session owner structure.

 ## A provider seam, not the policy layer

--- a/packages/ui/acp/README.md
+++ b/packages/ui/acp/README.md
@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-acp

-The **Agent Client Protocol (ACP)** bridge: exposes the DeepSeek Harness coding agent as an ACP server over JSON-RPC stdio, so editors (Zed and other ACP clients) can drive it — streaming render, tool-call display, and resumable sessions. Zed is the current target client: baseline ACP behavior should remain reasonable for other clients, but bridge capabilities and compatibility decisions are evaluated against Zed first. **N concurrent sessions per connection** (see [ACP multi-session](../../../docs/rfc/proposed/feature/2026-06-14-acp-multi-session.md)): each maps to its own `ReactLoopAgent`, and every event is demuxed strictly by session id so two sessions streaming at once never interleave.
+The **Agent Client Protocol (ACP)** bridge: exposes DeepSeek Harness SDK agents as an ACP server over JSON-RPC stdio, so editors (Zed and other ACP clients) can drive them — streaming render, tool-call display, and resumable sessions. Zed is the current target client: baseline ACP behavior should remain reasonable for other clients, but bridge capabilities and compatibility decisions are evaluated against Zed first. **N concurrent sessions per connection** (see [ACP multi-session](../../../docs/rfc/proposed/feature/2026-06-14-acp-multi-session.md)): each maps to its own `ReactLoopAgent`, and every event is demuxed strictly by session id so two sessions streaming at once never interleave.

 It is a **client-driver / UI plugin**, the structured analogue of the readline `stdio-chat` plugin — NOT a loop change and NOT a [capability seam](../../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md). It consumes the existing `agent/*` event taxonomy, the `dsh-agent` create/resume factory, and `dsh-session-persistence`.

--- a/packages/ui/acp/package.json
+++ b/packages/ui/acp/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@deepseek-ai/dsh-acp",
-  "description": "Agent Client Protocol (ACP) bridge: drive the DeepSeek Harness coding agent from an ACP editor over JSON-RPC stdio",
+  "description": "Agent Client Protocol (ACP) bridge: drive DeepSeek Harness SDK agents from an ACP editor over JSON-RPC stdio",
  "version": "0.0.1",
  "private": true,
  "type": "module",
--- a/packages/web/web-search-deepseek/tests/deepseek.e2e.ts
+++ b/packages/web/web-search-deepseek/tests/deepseek.e2e.ts
@@ -28,7 +28,7 @@ maybe('DeepSeekSearchProvider real API', () => {
      maxTokens: DEEPSEEK_DEFAULT_MAX_TOKENS,
      maxUses: DEEPSEEK_DEFAULT_MAX_USES,
    })
-    const result = await provider.search({ query: 'What is the DeepSeek coding agent?', maxResults: 5 })
+    const result = await provider.search({ query: 'What is the DeepSeek Harness SDK?', maxResults: 5 })
    expect(result.providerId).toBe('deepseek')
    expect(result.sources.length).toBeGreaterThan(0)
    for (const source of result.sources) expect(source.url).toMatch(/^https?:\/\//)
--- a/packages/web/web-search-exa/tests/exa.e2e.ts
+++ b/packages/web/web-search-exa/tests/exa.e2e.ts
@@ -16,7 +16,7 @@ maybe('ExaSearchProvider real API', () => {
      searchType: EXA_DEFAULT_SEARCH_TYPE,
      highlightsPerResult: EXA_DEFAULT_HIGHLIGHTS_PER_RESULT,
    })
-    const result = await provider.search({ query: 'DeepSeek coding agent', maxResults: 5 })
+    const result = await provider.search({ query: 'DeepSeek Harness SDK', maxResults: 5 })
    expect(result.providerId).toBe('exa')
    expect(result.sources.length).toBeGreaterThan(0)
    for (const source of result.sources) expect(source.url).toMatch(/^https?:\/\//)
--- a/packages/web/web-search-perplexity/tests/perplexity.e2e.ts
+++ b/packages/web/web-search-perplexity/tests/perplexity.e2e.ts
@@ -16,7 +16,7 @@ maybe('PerplexitySearchProvider real API', () => {
      model: process.env.PERPLEXITY_MODEL ?? PERPLEXITY_DEFAULT_MODEL,
      maxTokens: PERPLEXITY_DEFAULT_MAX_TOKENS,
    })
-    const result = await provider.search({ query: 'What is the DeepSeek coding agent?', maxResults: 5 })
+    const result = await provider.search({ query: 'What is the DeepSeek Harness SDK?', maxResults: 5 })
    expect(result.providerId).toBe('perplexity')
    expect(result.content ?? '').not.toBe('')
    for (const source of result.sources) expect(source.url).toMatch(/^https?:\/\//)
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
--- a/scripts/doc-budgets.manifest.json
+++ b/scripts/doc-budgets.manifest.json
@@ -1,7 +1,8 @@
 {
  "AGENTS.md": 1575,
  "docs/AGENTS.md": 1315,
-  "docs/architecture.md": 1890,
+  "docs/architecture.md": 1630,
+  "docs/cordis-primer.md": 550,
  "docs/defensive-patterns.md": 550,
  "docs/testing.md": 800,
  "examples/AGENTS.md": 610,
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -1,25 +1,28 @@
 /**
- * Generate (and verify) the cordis events + services catalog in
- * docs/cordis-catalog/events-and-services.md.
+ * Generate (and verify) the cordis events and services catalogs in
+ * docs/cordis-catalog/events.md and docs/cordis-catalog/services.md.
 *
- * The catalog is the WIRING-axis reference: every cordis event a plugin can
- * listen to (exact signature + dispatch mode) and every `ctx.<key>` service it
- * can call (exact public interface). It complements the core-data-structures
- * catalog (the VOCABULARY axis — the types these signatures move around).
+ * The two pages are the WIRING-axis reference, one axis each: every cordis
+ * event a plugin can listen to (exact signature + dispatch mode) and every
+ * `ctx.<key>` service it can call (exact public interface). They complement the
+ * core-data-structures catalog (the VOCABULARY axis — the types these
+ * signatures move around).
 *
- * The catalog is FULLY GENERATED from source — never hand-edit it. The codebase
- * is disciplined enough that a pure-AST pass captures the whole truthful
- * surface: every event/service is a string literal that round-trips to a static
- * `interface Events` / `interface Context` declaration (no dynamically-named
- * events, no runtime-only services). So the committed file is a build artifact
- * and a regenerate-and-diff freshness check (`--check`) makes drift structurally
- * impossible. Because generation enumerates source rather than checking a
- * hand-written subset, a brand-new event cannot be silently undocumented — it
- * appears in the next regenerate, and an un-regenerated file fails `--check`.
+ * The catalogs are FULLY GENERATED from source — never hand-edit them. The
+ * codebase is disciplined enough that a pure-AST pass captures the whole
+ * truthful surface: every event/service is a string literal that round-trips
+ * to a static `interface Events` / `interface Context` declaration (no
+ * dynamically-named events, no runtime-only services). So the committed files
+ * are build artifacts and a regenerate-and-diff freshness check (`--check`)
+ * makes drift structurally impossible. Because generation enumerates source
+ * rather than checking a hand-written subset, a brand-new event cannot be
+ * silently undocumented — it appears in the next regenerate, and an
+ * un-regenerated file fails `--check`.
 *
- *   `tsx scripts/gen-cordis-catalog.ts`          → write the catalog
- *   `tsx scripts/gen-cordis-catalog.ts --check`  → exit 1 if the committed file
- *                                                  is stale (CI / pre-push gate)
+ *   `tsx scripts/gen-cordis-catalog.ts`          → write both catalogs
+ *   `tsx scripts/gen-cordis-catalog.ts --check`  → exit 1 if a committed
+ *                                                  catalog is stale (CI /
+ *                                                  pre-push gate)
 *
 * The HARNESS tier (the `@deepseek-ai/dsh-*` events + services) is rendered in
 * full from source: signature, the `@mode` badge, and the declaration's JSDoc.
@@ -52,7 +55,8 @@ import { resolve } from 'node:path'
 import ts from 'typescript'

 const root = resolve(import.meta.dirname, '..')
-const OUT = 'docs/cordis-catalog/events-and-services.md'
+const OUT_EVENTS = 'docs/cordis-catalog/events.md'
+const OUT_SERVICES = 'docs/cordis-catalog/services.md'

 /** The fenced-block info string for generated signature blocks (skipped by
 * doc-typecheck, since a bare signature fragment is not standalone-compilable). */
@@ -63,7 +67,8 @@ type Mode = 'emit' | 'waterfall' | 'parallel' | 'serial'

 /**
 * Cross-link map: a type name that appears in a signature → the
- * core-data-structures page that documents it (path relative to OUT's folder).
+ * core-data-structures page that documents it (path relative to the catalogs'
+ * folder).
 * Hand-curated and catalog-owned, NOT derived from type-equiv.manifest.json —
 * that manifest documents the `…Map` symbols (`ContentBlockMap`) while
 * signatures reference the derived UNION names (`ContentBlock`), and it lists a
@@ -506,7 +511,7 @@ function typeLinks(signature: string): string {

 /** Render one harness event entry. */
 function renderEvent(e: EventEntry): string[] {
-  const out = [`#### \`${e.name}\` — ${e.mode}`, '']
+  const out = [`### \`${e.name}\` — ${e.mode}`, '']
  if (e.doc) out.push(e.doc, '')
  out.push('```' + FENCE, e.signature, '```', '')
  const links = typeLinks(e.signature)
@@ -518,7 +523,7 @@ function renderEvent(e: EventEntry): string[] {
 /** Render one harness service entry. */
 function renderService(s: ServiceEntry): string[] {
  const kind = s.abstract ? ' (abstract seam)' : ''
-  const out = [`### \`ctx.${s.key}\` — \`${s.type}\`${kind}`, '']
+  const out = [`## \`ctx.${s.key}\` — \`${s.type}\`${kind}`, '']
  if (s.doc) out.push(s.doc, '')
  if (s.methods.length) {
    out.push('```' + FENCE, ...s.methods, '```', '')
@@ -529,51 +534,71 @@ function renderService(s: ServiceEntry): string[] {
  return out
 }

-/** Render the full catalog (pure, deterministic given sorted inputs). */
-function render(events: EventEntry[], services: ServiceEntry[]): string {
+/** The shared generated-file banner comment. */
+const BANNER = [
+  '<!-- Generated by scripts/gen-cordis-catalog.ts — do not edit by hand.',
+  '     Run `pnpm run gen-cordis-catalog` to regenerate. -->',
+  '',
+]
+
+/** The shared GENERATED + freshness-gate + fence notice paragraph. */
+const GATE_NOTICE = 'This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence (skipped by doc-typecheck, since a bare signature is not standalone-compilable). Type names in a signature link to the page that documents them.'
+
+/** Render the events catalog (pure, deterministic given sorted inputs). */
+function renderEvents(events: EventEntry[]): string {
  const lines: string[] = [
-    '<!-- Generated by scripts/gen-cordis-catalog.ts — do not edit by hand.',
-    '     Run `pnpm run gen-cordis-catalog` to regenerate. -->',
+    ...BANNER,
+    '# Cordis Events Catalog',
    '',
-    '# Cordis Events & Services Catalog',
+    'Every cordis event a plugin can listen to: exact signature, dispatch mode, and the declaration\'s JSDoc. This is one axis of the **wiring** reference a plugin author works against — the callable `ctx.<key>` surface is the sibling [services catalog](services.md), and [core-data-structures/](../core-data-structures/core.md) catalogs the *data structures* these signatures move around.',
    '',
-    'An index reference to the **wiring** a plugin author works against: every cordis event you can listen to (exact signature + dispatch mode) and every `ctx.<key>` service you can call (exact public interface). It complements [core-data-structures/](../core-data-structures/core.md), which catalogs the *data structures* these signatures move around — this page is the verbs, that page is the nouns.',
+    GATE_NOTICE,
    '',
-    'This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence (skipped by doc-typecheck, since a bare signature is not standalone-compilable). Type names in a signature link to the page that documents them.',
+    'The **harness tier** below (the `@deepseek-ai/dsh-*` packages) is the vocabulary this repo owns, grouped by scope. The **inherited tier** at the end is the cordis-core + loader/hmr/timer event surface a plugin also sees — pinned vendor source, summarized tersely.',
    '',
-    'The **harness tier** below (the `@deepseek-ai/dsh-*` packages) is the vocabulary this repo owns. The **inherited tier** at the end is the cordis-core + loader/hmr/timer surface a plugin also sees — pinned vendor source, summarized tersely.',
-    '',
-    '## Events',
-    '',
-    'Dispatch modes: **emit** (fire-and-forget), **waterfall** (each listener gets `next()` and may transform or veto — see [waterfall semantics](../architecture.md#cordis-waterfall-semantics-important)), **parallel** (awaited fan-out; all listeners run), **serial** (awaited in registration order until one returns a bail value — anything other than `null`, `false`, or `undefined`).',
+    'Dispatch modes: **emit** (fire-and-forget), **waterfall** (each listener gets `next()` and may transform or veto — see [waterfall semantics](../cordis-primer.md#cordis-waterfall-semantics)), **parallel** (awaited fan-out; all listeners run), **serial** (awaited in registration order until one returns a bail value — anything other than `null`, `false`, or `undefined`).',
    '',
  ]
  const scopes = [...new Set(events.map(e => e.scope))].sort()
  for (const scope of scopes) {
-    lines.push(`### \`${scope}/*\``, '')
+    lines.push(`## \`${scope}/*\``, '')
    for (const e of events.filter(x => x.scope === scope).sort((a, b) => a.name.localeCompare(b.name))) {
      lines.push(...renderEvent(e))
    }
  }
  lines.push(
-    '## Services',
+    '## Inherited events (cordis core + loader/hmr/timer)',
    '',
-    'The `ctx.<key>` services the harness provides. An abstract seam (e.g. `ctx.bash`) is implemented by a separate package; the interface is what consumers code against.',
-    '',
-  )
-  for (const s of services) lines.push(...renderService(s))
-  lines.push(
-    '## Inherited tier (cordis core + loader/hmr/timer)',
-    '',
-    'The framework surface every plugin inherits, beyond the harness vocabulary above. This is pinned vendor source ([vendoring policy](../../vendor/README.md)); it is summarized here so the catalog is a complete picture of what `ctx` and the event bus offer, without elevating framework internals to the harness tier\'s prominence.',
-    '',
-    '### Inherited events',
+    'The framework events every plugin also sees, beyond the harness vocabulary above. This is pinned vendor source ([vendoring policy](../../vendor/README.md)); it is summarized here so the page is a complete picture of the event bus, without elevating framework internals to the harness tier\'s prominence.',
    '',
  )
  for (const e of INHERITED_EVENTS) {
    lines.push(`- \`${e.name}\` — ${e.summary} ([\`${e.source}\`](../../${e.source.split(':')[0]}))`)
  }
-  lines.push('', '### Inherited `ctx` members', '')
+  lines.push('')
+  return lines.join('\n')
+}
+
+/** Render the services catalog (pure, deterministic given sorted inputs). */
+function renderServices(services: ServiceEntry[]): string {
+  const lines: string[] = [
+    ...BANNER,
+    '# Cordis Services Catalog',
+    '',
+    'Every `ctx.<key>` service a plugin can call: the exact public interface plus the class JSDoc. This is one axis of the **wiring** reference a plugin author works against — the events a plugin listens to are the sibling [events catalog](events.md), and [core-data-structures/](../core-data-structures/core.md) catalogs the *data structures* these signatures move around. An abstract seam (e.g. `ctx.bash`) is implemented by a separate package; the interface is what consumers code against.',
+    '',
+    GATE_NOTICE,
+    '',
+    'The **harness tier** below (the `@deepseek-ai/dsh-*` packages) is the vocabulary this repo owns. The **inherited tier** at the end is the cordis-core + loader/hmr/timer `ctx` surface a plugin also sees — pinned vendor source, summarized tersely.',
+    '',
+  ]
+  for (const s of services) lines.push(...renderService(s))
+  lines.push(
+    '## Inherited `ctx` members (cordis core + loader/hmr/timer)',
+    '',
+    'The framework `ctx` surface every plugin also sees, beyond the harness services above. This is pinned vendor source ([vendoring policy](../../vendor/README.md)); it is summarized here so the page is a complete picture of what `ctx` offers, without elevating framework internals to the harness tier\'s prominence.',
+    '',
+  )
  for (const s of INHERITED_SERVICES) {
    lines.push(`- \`${s.name}\` — ${s.summary} ([\`${s.source}\`](../../${s.source.split(':')[0]}))`)
  }
@@ -581,31 +606,38 @@ function render(events: EventEntry[], services: ServiceEntry[]): string {
  return lines.join('\n')
 }

-/** CLI entry: `--write` (default) writes the catalog, `--check` fails if stale.
- * Guarded behind an entry-point check so importing this module for tests neither
- * regenerates the committed file nor calls process.exit. */
+/** CLI entry: `--write` (default) writes both catalogs, `--check` fails if
+ * either is stale. Guarded behind an entry-point check so importing this module
+ * for tests neither regenerates the committed files nor calls process.exit. */
 function main(): void {
-  const content = render(collectEvents(), collectServices())
+  const outputs: [string, string][] = [
+    [OUT_EVENTS, renderEvents(collectEvents())],
+    [OUT_SERVICES, renderServices(collectServices())],
+  ]
  if (process.argv.includes('--check')) {
-    let committed: string | null = null
-    try {
-      committed = readFileSync(resolve(root, OUT), 'utf8')
-    } catch {
-      // Only ENOENT (not yet generated) is expected; a present-but-unreadable
-      // file is not a state this repo produces. Either way the remedy is the
-      // same — regenerate — so treat a read failure as "stale".
-      committed = null
+    const stale: string[] = []
+    for (const [out, content] of outputs) {
+      let committed: string | null = null
+      try {
+        committed = readFileSync(resolve(root, out), 'utf8')
+      } catch {
+        // Only ENOENT (not yet generated) is expected; a present-but-unreadable
+        // file is not a state this repo produces. Either way the remedy is the
+        // same — regenerate — so treat a read failure as "stale".
+        committed = null
+      }
+      if (committed !== content) stale.push(out)
    }
-    if (committed === content) {
-      console.log(`gen-cordis-catalog: ${OUT} is up to date.`)
+    if (stale.length === 0) {
+      console.log(`gen-cordis-catalog: ${OUT_EVENTS} and ${OUT_SERVICES} are up to date.`)
      process.exit(0)
    }
-    console.error(`gen-cordis-catalog: ${OUT} is stale. Run \`pnpm run gen-cordis-catalog\` and commit ${OUT}.`)
+    console.error(`gen-cordis-catalog: ${stale.join(' and ')} ${stale.length === 1 ? 'is' : 'are'} stale. Run \`pnpm run gen-cordis-catalog\` and commit the result.`)
    process.exit(1)
  }

-  writeFileSync(resolve(root, OUT), content)
-  console.log(`gen-cordis-catalog: wrote ${OUT}.`)
+  for (const [out, content] of outputs) writeFileSync(resolve(root, out), content)
+  console.log(`gen-cordis-catalog: wrote ${OUT_EVENTS} and ${OUT_SERVICES}.`)
 }

 // Run only when invoked as a script, not when imported by a test.
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -0,0 +1,776 @@
+/**
+ * Generate (and verify) the relationship-diagram docs.
+ *
+ * This is the relationship layer above the existing catalogs:
+ * - module-graph.md answers "which packages depend on which packages?"
+ * - cordis-catalog/ answers "which events and services exist?"
+ * - tool-catalog/ answers "which tools does the model see?"
+ * - generated relationship diagrams answer "how do those pieces fit together?"
+ *
+ * Generated pages discover the enumerable facts from source. Hybrid pages use
+ * discovered inventory plus small manifests for policy that source cannot infer
+ * (for example, whether a package is an implementation or consumer in a seam).
+ * Curated pages are still emitted here so the graph docs are one regenerated unit,
+ * but their diagrams intentionally explain flow and ownership rather than
+ * pretending to enumerate every source edge.
+ *
+ *   `tsx scripts/gen-doc-graphs.ts`          -> write generated diagram docs
+ *   `tsx scripts/gen-doc-graphs.ts --check`  -> exit 1 if any file is stale
+ */
+
+import { existsSync, globSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, relative, resolve } from 'node:path'
+import ts from 'typescript'
+import { collectEvents, collectServices } from './gen-cordis-catalog.ts'
+
+const root = resolve(import.meta.dirname, '..')
+const SCOPE = '@deepseek-ai/dsh-'
+
+interface PkgJson {
+  name: string
+  peerDependencies?: Record<string, string>
+}
+
+interface Pkg {
+  short: string
+  name: string
+  group: string
+  rel: string
+  deps: string[]
+}
+
+interface GraphDoc {
+  rel: string
+  content: string
+}
+
+interface ServiceRole {
+  key: string
+  pkg: string
+  title: string
+  mode: 'core' | 'seam' | 'bundle'
+  implementations?: string[]
+  consumers?: string[]
+  companions?: string[]
+  note: string
+}
+
+interface ExamplePlugin {
+  id: string
+  name: string
+}
+
+interface EventRelation {
+  dispatchers: Map<string, Set<string>>
+  listeners: Set<string>
+}
+
+const GROUP_ORDER = [
+  'util',
+  'llm',
+  'core',
+  'bash',
+  'fs',
+  'compact',
+  'subagent',
+  'web',
+  'todo',
+  'hooks',
+  'session-persistence',
+  'support',
+  'ui',
+]
+
+const SERVICE_ROLES: ServiceRole[] = [
+  {
+    key: 'llm',
+    pkg: 'llm',
+    title: 'LLM adapter registry',
+    mode: 'seam',
+    implementations: ['llm-deepseek', 'llm-pi-ai', 'llm-replay'],
+    consumers: ['agent-loop', 'compact-basic'],
+    note: 'Adapters register provider implementations; the loop and compaction call the provider-neutral stream service.',
+  },
+  {
+    key: 'sessions',
+    pkg: 'session',
+    title: 'In-memory session store',
+    mode: 'core',
+    consumers: ['agent-loop', 'agent', 'session-persistence', 'subagent-inprocess', 'invariants'],
+    note: 'Owns append-only Session instances and emits the durable session event feed.',
+  },
+  {
+    key: 'sessionPersistence',
+    pkg: 'session-persistence',
+    title: 'Durable session persistence seam',
+    mode: 'seam',
+    implementations: ['session-persistence-jsonl', 'session-persistence-sqlite'],
+    consumers: ['agent-loop', 'acp'],
+    note: 'Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time.',
+  },
+  {
+    key: 'systemPrompt',
+    pkg: 'system-prompt',
+    title: 'System prompt assembly registry',
+    mode: 'core',
+    consumers: ['agent-loop', 'tools', 'tool-fs', 'tool-web'],
+    note: 'Collects prompt sections and model-facing tool schemas for each step.',
+  },
+  {
+    key: 'tools',
+    pkg: 'tools',
+    title: 'Tool registry and execution waterfall',
+    mode: 'core',
+    consumers: ['agent-loop', 'tool-bash', 'tool-fs', 'tool-subagent', 'tool-todo', 'tool-web', 'acp'],
+    note: 'Registers tool definitions, exposes schemas to the prompt, and routes calls through tools/pre-execute and tools/post-execute.',
+  },
+  {
+    key: 'agents',
+    pkg: 'agent',
+    title: 'Agent registry',
+    mode: 'core',
+    consumers: ['agent-loop', 'acp', 'subagent-inprocess', 'stdio-agent', 'invariants'],
+    note: 'Owns live Agent handles and the create/resume factory seam.',
+  },
+  {
+    key: 'agentLoop',
+    pkg: 'agent-loop',
+    title: 'Concrete loop driver',
+    mode: 'bundle',
+    consumers: ['agent-core'],
+    note: 'The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package.',
+  },
+  {
+    key: 'bash',
+    pkg: 'bash',
+    title: 'Bash executor seam',
+    mode: 'seam',
+    implementations: ['bash-local'],
+    consumers: ['tool-bash', 'hooks-claude', 'hooks-codex'],
+    note: 'The model-facing bash tools and hook bridges consume this seam; sandboxed or remote executors can replace bash-local.',
+  },
+  {
+    key: 'fs',
+    pkg: 'fs',
+    title: 'Filesystem provider seam',
+    mode: 'seam',
+    implementations: ['fs-local'],
+    consumers: ['tool-fs'],
+    companions: ['fs-policy'],
+    note: 'tool-fs executes read/write/edit through ctx.fs; fs-policy contributes observed-state checks through the fs/* event gate.',
+  },
+  {
+    key: 'compact',
+    pkg: 'compact',
+    title: 'Compaction seam',
+    mode: 'seam',
+    implementations: ['compact-basic'],
+    consumers: ['compact-basic'],
+    note: 'The basic backend currently consumes the pre-step event directly; a model-facing compact tool remains deferred.',
+  },
+  {
+    key: 'subagents',
+    pkg: 'subagent',
+    title: 'Subagent provider registry',
+    mode: 'seam',
+    implementations: ['subagent-spawn', 'subagent-fork', 'subagent-acp', 'subagent-mock'],
+    consumers: ['tool-subagent'],
+    note: 'Providers implement transports; tool-subagent exposes one configured provider as a model-facing tool name.',
+  },
+  {
+    key: 'web',
+    pkg: 'web',
+    title: 'Web access provider registry',
+    mode: 'seam',
+    implementations: ['web-search-exa', 'web-search-perplexity', 'web-search-deepseek', 'web-fetch-local'],
+    consumers: ['tool-web'],
+    note: 'Search and fetch providers register into one ctx.web seam; tool-web owns the stable model-facing names.',
+  },
+]
+
+const DYNAMIC_EVENT_DISPATCHERS: Array<{ event: string; pkg: string; method: string }> = [
+  // Subagent lifecycle events intentionally bypass ctx.emit and call
+  // ctx.events.dispatch directly so one throwing listener cannot starve later
+  // listeners or strand an already-started child run.
+  { event: 'subagent/start', pkg: 'subagent', method: 'events.dispatch' },
+  { event: 'subagent/end', pkg: 'subagent', method: 'events.dispatch' },
+]
+
+function generatedHeader(title: string): string[] {
+  return [
+    '<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.',
+    '     Run `pnpm run gen-doc-graphs` to regenerate. -->',
+    '',
+    `# ${title}`,
+    '',
+  ]
+}
+
+function maintenanceFooter(source: string): string[] {
+  return [`Maintenance mode: ${source}.`, '']
+}
+
+function graphIndexLink(rel: string): string {
+  return relative('docs', rel).replaceAll('\\', '/')
+}
+
+function linkFromDoc(docRel: string, targetRel: string): string {
+  return relative(dirname(docRel), targetRel).replaceAll('\\', '/')
+}
+
+function collectPackages(): Pkg[] {
+  const pkgs: Pkg[] = []
+  for (const rel of globSync('packages/*/*/package.json', { cwd: root }).sort()) {
+    const json = JSON.parse(readFileSync(resolve(root, rel), 'utf8')) as PkgJson
+    if (!json.name.startsWith(SCOPE)) continue
+    const [, group, leaf] = rel.split('/')
+    if (group === undefined || leaf === undefined) throw new Error(`gen-doc-graphs: unexpected package path ${rel}`)
+    const deps = Object.keys(json.peerDependencies ?? {})
+      .filter(dep => dep.startsWith(SCOPE))
+      .map(dep => dep.slice(SCOPE.length))
+      .sort()
+    pkgs.push({
+      short: json.name.slice(SCOPE.length),
+      name: json.name,
+      group,
+      rel: dirname(rel),
+      deps,
+    })
+  }
+  return topoSort(pkgs)
+}
+
+function topoSort(pkgs: Pkg[]): Pkg[] {
+  const remaining = new Map(pkgs.map(p => [p.short, p]))
+  const placed = new Set<string>()
+  const out: Pkg[] = []
+  while (remaining.size > 0) {
+    const ready = [...remaining.values()]
+      .filter(pkg => pkg.deps.every(dep => placed.has(dep)))
+      .sort(comparePackages)
+    if (ready.length === 0) throw new Error(`gen-doc-graphs: dependency cycle among ${[...remaining.keys()].join(', ')}`)
+    for (const pkg of ready) {
+      out.push(pkg)
+      placed.add(pkg.short)
+      remaining.delete(pkg.short)
+    }
+  }
+  return out
+}
+
+function comparePackages(a: Pkg, b: Pkg): number {
+  const groupA = GROUP_ORDER.indexOf(a.group)
+  const groupB = GROUP_ORDER.indexOf(b.group)
+  const normA = groupA === -1 ? Number.MAX_SAFE_INTEGER : groupA
+  const normB = groupB === -1 ? Number.MAX_SAFE_INTEGER : groupB
+  return normA - normB || a.group.localeCompare(b.group) || a.short.localeCompare(b.short)
+}
+
+function nodeId(prefix: string, value: string): string {
+  return `${prefix}_${value.replace(/[^a-zA-Z0-9_]/g, '_')}`
+}
+
+function escLabel(value: string): string {
+  return value.replace(/"/g, '\\"')
+}
+
+function mermaidCode(value: string): string {
+  return `<code>${value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')}</code>`
+}
+
+function repoLink(path: string, label: string, up = '..'): string {
+  return `[${label}](${up}/${path})`
+}
+
+function sourceLink(source: string, up = '..'): string {
+  return repoLink(source.split(':')[0] ?? source, `\`${source}\``, up)
+}
+
+function pkgLink(pkg: Pkg | undefined, fallback: string, up = '..'): string {
+  return pkg ? repoLink(pkg.rel, `\`${pkg.short}\``, up) : `\`${fallback}\``
+}
+
+function pkgList(names: string[] | undefined, pkgsByShort: Map<string, Pkg>): string {
+  if (!names || names.length === 0) return '-'
+  return names.map(name => pkgLink(pkgsByShort.get(name), name)).join(', ')
+}
+
+function tableCell(value: string): string {
+  return value.replace(/\|/g, '\\|').replace(/\n/g, '<br>')
+}
+
+function assertServiceRolesComplete(): void {
+  const discovered = new Set(collectServices().map(service => service.key))
+  const classified = new Set(SERVICE_ROLES.map(role => role.key))
+  const missing = [...discovered].filter(key => !classified.has(key)).sort()
+  const stale = [...classified].filter(key => !discovered.has(key)).sort()
+  if (missing.length || stale.length) {
+    throw new Error([
+      missing.length ? `missing service role classification: ${missing.join(', ')}` : '',
+      stale.length ? `stale service role classification: ${stale.join(', ')}` : '',
+    ].filter(Boolean).join('; '))
+  }
+}
+
+function renderCapabilitySeams(pkgs: Pkg[]): string {
+  assertServiceRolesComplete()
+  const pkgsByShort = new Map(pkgs.map(pkg => [pkg.short, pkg]))
+  const maintenance = 'hybrid: services are discovered from Cordis declarations; interface/implementation/consumer roles are classified in `scripts/gen-doc-graphs.ts` with a completeness guard'
+  const nodes = new Map<string, string>()
+  const edges = new Set<string>()
+  const companionEdges = new Set<string>()
+  const addNode = (id: string, label: string): void => {
+    if (!nodes.has(id)) nodes.set(id, `  ${id}["${escLabel(label)}"]`)
+  }
+  const addEdge = (from: string, to: string): void => { edges.add(`  ${from} --> ${to}`) }
+  const lines = generatedHeader('Capability Seams And Core Services')
+  lines.push(
+    'A service can be a core spine service, a swappable capability seam, or a bundle/composition point. The graph shows the package that owns the service declaration, known implementation packages, and packages that consume the service directly.',
+    '',
+    '```mermaid',
+    'flowchart LR',
+  )
+  for (const role of SERVICE_ROLES) {
+    const svc = nodeId('svc', role.key)
+    const owner = nodeId('pkg', role.pkg)
+    addNode(owner, role.pkg)
+    addNode(svc, `ctx.${role.key}<br/>${role.title}`)
+    addEdge(owner, svc)
+    for (const impl of role.implementations ?? []) {
+      addNode(nodeId('pkg', impl), impl)
+      addEdge(nodeId('pkg', impl), svc)
+    }
+    for (const consumer of role.consumers ?? []) {
+      addNode(nodeId('pkg', consumer), consumer)
+      addEdge(svc, nodeId('pkg', consumer))
+    }
+    for (const companion of role.companions ?? []) {
+      addNode(nodeId('pkg', companion), companion)
+      companionEdges.add(`  ${svc} -. event gate .-> ${nodeId('pkg', companion)}`)
+    }
+  }
+  lines.push(...nodes.values(), ...[...edges].sort(), ...[...companionEdges].sort())
+  lines.push('```', '', '| ctx key | Role | Owner | Implementations | Direct consumers | Companion plugins | Note |', '| --- | --- | --- | --- | --- | --- | --- |')
+  for (const role of SERVICE_ROLES) {
+    lines.push(`| \`ctx.${role.key}\` | \`${role.mode}\` | ${pkgLink(pkgsByShort.get(role.pkg), role.pkg)} | ${pkgList(role.implementations, pkgsByShort)} | ${pkgList(role.consumers, pkgsByShort)} | ${pkgList(role.companions, pkgsByShort)} | ${tableCell(role.note)} |`)
+  }
+  lines.push('', ...maintenanceFooter(maintenance))
+  return lines.join('\n')
+}
+
+function parseExampleCordis(rel: string): ExamplePlugin[] {
+  const text = readFileSync(resolve(root, rel), 'utf8')
+  const plugins: ExamplePlugin[] = []
+  let current: { id: string; name?: string } | null = null
+  const flush = (): void => {
+    if (current?.name) plugins.push({ id: current.id, name: current.name })
+  }
+  for (const line of text.split('\n')) {
+    const id = /^-\s+id:\s+(.+?)\s*$/.exec(line)
+    if (id?.[1] !== undefined) {
+      flush()
+      current = { id: stripYamlScalar(id[1]) }
+      continue
+    }
+    const name = /^\s+name:\s+(.+?)\s*$/.exec(line)
+    if (name?.[1] !== undefined && current) current.name = stripYamlScalar(name[1])
+  }
+  flush()
+  return plugins
+}
+
+function stripYamlScalar(value: string): string {
+  return value.trim().replace(/^['"]|['"]$/g, '')
+}
+
+const APP_EXAMPLES = [
+  {
+    id: 'echo',
+    rel: 'examples/echo-agent/composition.md',
+    title: 'Echo Agent App Composition',
+    label: 'examples/echo-agent',
+    config: 'examples/echo-agent/cordis.yml',
+    summary: 'The echo demo swaps in a local mock LLM and teaching echo tool, then loads the stdio app package for the shared spine and terminal front door.',
+  },
+  {
+    id: 'coding',
+    rel: 'examples/coding-agent/composition.md',
+    title: 'Coding Agent App Composition',
+    label: 'examples/coding-agent',
+    config: 'examples/coding-agent/cordis.yml',
+    summary: 'The coding REPL demo adds the real DeepSeek adapter, filesystem tools, todo_write, compaction, and both subagent transports on top of the stdio app package.',
+  },
+  {
+    id: 'acp',
+    rel: 'examples/acp-agent/composition.md',
+    title: 'ACP Agent App Composition',
+    label: 'examples/acp-agent',
+    config: 'examples/acp-agent/cordis.yml',
+    summary: 'The ACP demo exposes the same agent spine over JSON-RPC stdio, with no stdout logger and no pre-created agent; clients create sessions through the ACP bridge.',
+  },
+]
+
+type AppExample = typeof APP_EXAMPLES[number]
+
+function renderAppExpansion(lines: string[], appNode: string, pluginName: string): void {
+  const agentCore = nodeId('bundle', 'agent_core')
+  const jsonl = nodeId('bundle', 'jsonl')
+  lines.push(`  ${appNode} --> ${agentCore}["@deepseek-ai/dsh-agent-core"]`)
+  lines.push(`  ${appNode} --> ${jsonl}["@deepseek-ai/dsh-session-persistence-jsonl"]`)
+  if (pluginName === '@deepseek-ai/dsh-stdio-agent') {
+    lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'stdio')}["readline UI<br/>console logger<br/>pre-created main agent"]`)
+  } else if (pluginName === '@deepseek-ai/dsh-acp-agent') {
+    lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'acp')}["@deepseek-ai/dsh-acp<br/>JSON-RPC stdio bridge<br/>sessions created by client"]`)
+  }
+  lines.push(
+    `  ${agentCore} --> ${nodeId('spine', 'llm')}["ctx.llm"]`,
+    `  ${agentCore} --> ${nodeId('spine', 'sessions')}["ctx.sessions"]`,
+    `  ${agentCore} --> ${nodeId('spine', 'tools')}["ctx.tools + tool-bash"]`,
+    `  ${agentCore} --> ${nodeId('spine', 'loop')}["ctx.agents + ctx.agentLoop"]`,
+  )
+}
+
+function renderAppComposition(example: AppExample): string {
+  const plugins = parseExampleCordis(example.config)
+  const maintenance = 'hybrid: the leaf plugin list is parsed from its `cordis.yml`; app package expansion is curated from package source'
+  const lines = generatedHeader(example.title)
+  lines.push(
+    example.summary,
+    '',
+    '```mermaid',
+    'flowchart LR',
+    `  cfg["${escLabel(example.label)}<br/>cordis.yml"]`,
+  )
+  for (const plugin of plugins) {
+    const pluginNode = nodeId(`plugin_${example.id}`, plugin.id)
+    lines.push(`  ${pluginNode}["${escLabel(plugin.id)}<br/>${escLabel(plugin.name)}"]`)
+    lines.push(`  cfg --> ${pluginNode}`)
+    if (plugin.name === '@deepseek-ai/dsh-stdio-agent' || plugin.name === '@deepseek-ai/dsh-acp-agent') {
+      renderAppExpansion(lines, pluginNode, plugin.name)
+    }
+  }
+  lines.push(
+    '```',
+    '',
+    '| Plugin id | Package / module |',
+    '| --- | --- |',
+    ...plugins.map(plugin => `| \`${plugin.id}\` | \`${plugin.name}\` |`),
+    '',
+    `Source config: [\`${example.config}\`](${linkFromDoc(example.rel, example.config)}).`,
+  )
+  lines.push('', ...maintenanceFooter(maintenance))
+  return lines.join('\n')
+}
+
+function collectEventRelations(): Map<string, EventRelation> {
+  const out = new Map<string, EventRelation>()
+  const ensure = (event: string): EventRelation => {
+    const existing = out.get(event)
+    if (existing) return existing
+    const next = { dispatchers: new Map<string, Set<string>>(), listeners: new Set<string>() }
+    out.set(event, next)
+    return next
+  }
+  for (const rel of globSync('packages/*/*/src/**/*.ts', { cwd: root }).sort()) {
+    const [, , leaf] = rel.split('/')
+    if (leaf === undefined) continue
+    const text = readFileSync(resolve(root, rel), 'utf8')
+    const sf = ts.createSourceFile(rel, text, ts.ScriptTarget.Latest, true)
+    const visit = (node: ts.Node): void => {
+      if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+        const method = node.expression.name.text
+        if (!isCordisContextReceiver(node.expression, sf)) {
+          ts.forEachChild(node, visit)
+          return
+        }
+        if (method === 'on') {
+          const event = eventArg(node.arguments, method)
+          if (event) ensure(event).listeners.add(leaf)
+        } else if (method === 'emit' || method === 'parallel' || method === 'serial' || method === 'waterfall') {
+          const event = eventArg(node.arguments, method)
+          if (event) {
+            const relation = ensure(event)
+            const methods = relation.dispatchers.get(leaf) ?? new Set<string>()
+            methods.add(method)
+            relation.dispatchers.set(leaf, methods)
+          }
+        }
+      }
+      ts.forEachChild(node, visit)
+    }
+    visit(sf)
+  }
+  for (const entry of DYNAMIC_EVENT_DISPATCHERS) {
+    const relation = ensure(entry.event)
+    const methods = relation.dispatchers.get(entry.pkg) ?? new Set<string>()
+    methods.add(entry.method)
+    relation.dispatchers.set(entry.pkg, methods)
+  }
+  return out
+}
+
+function isCordisContextReceiver(expr: ts.PropertyAccessExpression, sf: ts.SourceFile): boolean {
+  const target = expr.expression.getText(sf)
+  return target === 'ctx' || target === 'this.ctx'
+}
+
+function eventArg(args: ts.NodeArray<ts.Expression>, method: string): string | undefined {
+  if (method === 'waterfall') {
+    const arg = args.find(ts.isStringLiteralLike)
+    return arg?.text
+  }
+  const first = args[0]
+  return first && ts.isStringLiteralLike(first) ? first.text : undefined
+}
+
+function relationPackages(map: Map<string, Set<string>>, pkgsByShort: Map<string, Pkg>): string {
+  if (map.size === 0) return '-'
+  return [...map.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([pkg, methods]) => `${pkgLink(pkgsByShort.get(pkg), pkg)} (${[...methods].sort().map(m => `\`${m}\``).join(', ')})`)
+    .join(', ')
+}
+
+function listenerPackages(listeners: Set<string>, pkgsByShort: Map<string, Pkg>): string {
+  if (listeners.size === 0) return '-'
+  return [...listeners].sort().map(pkg => pkgLink(pkgsByShort.get(pkg), pkg)).join(', ')
+}
+
+function renderEventRelations(pkgs: Pkg[]): string {
+  const events = collectEvents()
+  const relations = collectEventRelations()
+  const pkgsByShort = new Map(pkgs.map(pkg => [pkg.short, pkg]))
+  const maintenance = 'hybrid generated: Cordis event declarations and most producer/listener edges are AST-scanned; dynamic dispatch sites are classified in `scripts/gen-doc-graphs.ts`'
+  const lines = generatedHeader('Event Producer And Consumer Matrix')
+  lines.push(
+    'This matrix shows which packages dispatch each harness-owned event and which packages listen to it. It is intentionally a table rather than one large graph: events are many-to-many, and dense relation data is easier to review in rows. Dynamic dispatch overrides cover sites that deliberately bypass `ctx.emit`, such as subagent lifecycle containment.',
+    '',
+    '| Event | Mode | Declared in | Dispatchers | Listeners |',
+    '| --- | --- | --- | --- | --- |',
+  )
+  for (const event of [...events].sort((a, b) => a.name.localeCompare(b.name))) {
+    const relation = relations.get(event.name) ?? { dispatchers: new Map<string, Set<string>>(), listeners: new Set<string>() }
+    lines.push(`| \`${event.name}\` | \`${event.mode}\` | ${sourceLink(event.source)} | ${relationPackages(relation.dispatchers, pkgsByShort)} | ${listenerPackages(relation.listeners, pkgsByShort)} |`)
+  }
+  const declared = new Set(events.map(event => event.name))
+  const extra = [...relations.keys()].filter(event => !declared.has(event)).sort()
+  if (extra.length > 0) {
+    lines.push('', '## Non-harness or undeclared event strings seen in package source', '', '| Event string | Dispatchers | Listeners |', '| --- | --- | --- |')
+    for (const event of extra) {
+      const relation = relations.get(event)
+      if (!relation) continue
+      lines.push(`| \`${event}\` | ${relationPackages(relation.dispatchers, pkgsByShort)} | ${listenerPackages(relation.listeners, pkgsByShort)} |`)
+    }
+  }
+  lines.push('', ...maintenanceFooter(maintenance))
+  return lines.join('\n')
+}
+
+function renderLifecycle(): string {
+  const maintenance = 'curated Mermaid sequence; exact event signatures live in the generated Cordis catalog'
+  return [
+    ...generatedHeader('Agent Turn And Step Lifecycle'),
+    'This sequence is the visual companion to [architecture.md](architecture.md#loop-lifecycle-session--turn--step). It keeps durable replay facts on `session/event` and live control/status on `agent/*`.',
+    '',
+    '```mermaid',
+    'sequenceDiagram',
+    '  participant User',
+    '  participant Agent',
+    '  participant Driver',
+    '  participant Hooks as hook listeners',
+    '  participant Prompt as ctx.systemPrompt',
+    '  participant LLM as ctx.llm',
+    '  participant Tools as ctx.tools',
+    '  participant Session',
+    '  participant Persistence',
+    '  participant SDK as UI or SDK listener',
+    '  User->>Agent: send(content)',
+    `  Agent-->>SDK: ${mermaidCode('agent/queued')}`,
+    '  Agent->>Driver: queued work wakes driver',
+    `  Driver-->>SDK: ${mermaidCode('agent/status')} running`,
+    `  Driver->>Session: ${mermaidCode('turn/start')}`,
+    `  Driver->>Hooks: ${mermaidCode('agent/prompt-submit')} waterfall`,
+    '  Hooks-->>Driver: allow, block, or add context',
+    `  Driver->>Session: ${mermaidCode('user/message')} or rejected ${mermaidCode('turn/end')}`,
+    `  Driver->>Prompt: ${mermaidCode('system-prompt/assemble')} waterfall`,
+    `  Driver-->>Driver: ${mermaidCode('agent/pre-step')} serial checkpoint`,
+    `  Driver->>Session: ${mermaidCode('step/start')}`,
+    `  Driver->>LLM: ${mermaidCode('agent/request')} waterfall, then ${mermaidCode('llm/stream')} waterfall`,
+    '  LLM-->>Driver: StreamChunk*',
+    `  Driver->>Session: ${mermaidCode('assistant/chunk')}*`,
+    `  Session-->>SDK: ${mermaidCode('session/event')} ${mermaidCode('assistant/chunk')}*`,
+    `  Driver->>Hooks: ${mermaidCode('agent/step-result')} waterfall`,
+    `  Driver->>Session: ${mermaidCode('assistant/message')}`,
+    `  Driver->>Session: ${mermaidCode('tool/call')}`,
+    '  Driver->>Tools: execute through pre and post waterfalls',
+    '  Tools-->>Session: tool-owned events when applicable',
+    `  Driver->>Session: ${mermaidCode('tool/result')} and ${mermaidCode('step/end')}`,
+    `  Driver->>Hooks: ${mermaidCode('agent/turn-continuation')} waterfall`,
+    `  Driver->>Session: ${mermaidCode('turn/end')}`,
+    `  Driver->>Persistence: ${mermaidCode('session/flush')} parallel checkpoint`,
+    `  Driver-->>SDK: ${mermaidCode('agent/status')} idle`,
+    '```',
+    '',
+    'SDK users that need replayable transcript data should consume `session/event`; `agent/*` is the live coordination surface for queue/status, prompt interception, request shaping, steering, continuation, and errors.',
+    '',
+    ...maintenanceFooter(maintenance),
+  ].join('\n')
+}
+
+function renderToolPipeline(): string {
+  const maintenance = 'curated Mermaid flow; exact tool schemas and event signatures live in generated catalogs'
+  return [
+    ...generatedHeader('Tool Execution Pipeline'),
+    'This graph shows where policy, hooks, sandboxing, filesystem guards, result rewriting, and UI rendering fit without changing the loop. The key extension points are the `tools/pre-execute` and `tools/post-execute` waterfalls.',
+    '',
+    '```mermaid',
+    'flowchart TD',
+    '  model["Assistant message contains tool-call block"]',
+    `  toolCall["Session event: ${mermaidCode('tool/call')}<br/>logged before execution"]`,
+    '  presentCall["UI pending card<br/>presentCall(args)"]',
+    `  pre["${mermaidCode('tools/pre-execute')} waterfall<br/>hooks, permission, sandbox"]`,
+    '  denied["deny or ask<br/>tool body skipped"]',
+    '  toolBody["Registered tool execute() body"]',
+    `  fsGate["${mermaidCode('fs/write-intent')} or ${mermaidCode('fs/edit-intent')}<br/>tool-fs mutations only"]`,
+    `  owned["Tool-owned session events<br/>${mermaidCode('todo/write')}, ${mermaidCode('fs/observed')}, ${mermaidCode('hook/invoked')}, ${mermaidCode('hook/result')}"]`,
+    `  post["${mermaidCode('tools/post-execute')} waterfall<br/>accept, block, replace, add context"]`,
+    '  context["Buffered additionalContext<br/>context/message after all tool results"]',
+    `  toolResult["Session event: ${mermaidCode('tool/result')}<br/>single model-facing outcome"]`,
+    '  presentResult["UI completed card<br/>presentResult(args, result)"]',
+    '  model --> toolCall',
+    '  toolCall --> presentCall',
+    '  toolCall --> pre',
+    '  pre -->|allow| toolBody',
+    '  pre -->|deny or ask| denied',
+    '  denied --> post',
+    '  toolBody --> fsGate',
+    '  fsGate --> toolBody',
+    '  toolBody --> owned',
+    '  toolBody --> post',
+    '  post --> context',
+    '  post --> toolResult',
+    '  toolResult --> presentResult',
+    '```',
+    '',
+    'Filesystem read-before-edit checks live below `tool-fs` on the `fs/*` event gate, while hook bridges and future permission prompts live on the generic tool waterfalls. That split lets the same hooks observe bash, fs, web, todo, and subagent calls without coupling those tools to one policy service.',
+    '',
+    ...maintenanceFooter(maintenance),
+  ].join('\n')
+}
+
+function renderSnapshotReplay(): string {
+  const maintenance = 'curated Mermaid sequence based on the snapshot test harness'
+  return [
+    ...generatedHeader('ACP Snapshot Replay'),
+    'This graph explains what a snapshot scenario proves: recorded real-model session logs are replayed keylessly, ACP stdout is normalized and diffed, and scenario workspaces preserve tool side effects that the UI stream alone cannot prove.',
+    '',
+    '```mermaid',
+    'sequenceDiagram',
+    '  participant Recorder as Real API recording',
+    '  participant Fixture as snapshot fixture',
+    '  participant Workspace',
+    '  participant Replay as llm-replay adapter',
+    '  participant ACP as acp-agent subprocess',
+    '  participant Golden as stdout golden',
+    '  Recorder->>Fixture: session.jsonl + workspace inputs',
+    '  Fixture->>Workspace: seed files and hook configs',
+    '  Fixture->>Replay: recorded StreamChunk script',
+    `  Replay->>ACP: deterministic ${mermaidCode('llm/stream')} chunks`,
+    '  ACP->>Workspace: bash, fs, and hook side effects',
+    '  ACP->>Golden: normalized sessionUpdate stream',
+    '  Golden-->>ACP: diff must be empty',
+    '```',
+    '',
+    'The fs and hook snapshot matrix is valuable because it proves world state, hook decisions, and failed tool-card rendering, not just that replay returns text.',
+    '',
+    ...maintenanceFooter(maintenance),
+  ].join('\n')
+}
+
+function renderDocs(): GraphDoc[] {
+  const pkgs = collectPackages()
+  const docs: GraphDoc[] = [
+    { rel: 'docs/capability-seams.md', content: renderCapabilitySeams(pkgs) },
+    ...APP_EXAMPLES.map(example => ({ rel: example.rel, content: renderAppComposition(example) })),
+    { rel: 'docs/event-producer-consumer.md', content: renderEventRelations(pkgs) },
+    { rel: 'docs/agent-lifecycle.md', content: renderLifecycle() },
+    { rel: 'docs/tool-execution-pipeline.md', content: renderToolPipeline() },
+    { rel: 'docs/acp/snapshot-replay.md', content: renderSnapshotReplay() },
+  ]
+  docs.unshift({ rel: 'docs/graph-atlas.md', content: renderIndex(docs) })
+  return docs
+}
+
+function renderIndex(docs: GraphDoc[]): string {
+  const labels: Record<string, string> = {
+    'docs/capability-seams.md': 'capability seams and core services',
+    'examples/echo-agent/composition.md': 'echo-agent app composition',
+    'examples/coding-agent/composition.md': 'coding-agent app composition',
+    'examples/acp-agent/composition.md': 'acp-agent app composition',
+    'docs/event-producer-consumer.md': 'event producer/consumer matrix',
+    'docs/agent-lifecycle.md': 'agent turn and step lifecycle',
+    'docs/tool-execution-pipeline.md': 'tool execution pipeline',
+    'docs/acp/snapshot-replay.md': 'ACP snapshot replay',
+  }
+  const modes: Record<string, string> = {
+    'docs/capability-seams.md': 'hybrid generated',
+    'examples/echo-agent/composition.md': 'hybrid generated',
+    'examples/coding-agent/composition.md': 'hybrid generated',
+    'examples/acp-agent/composition.md': 'hybrid generated',
+    'docs/event-producer-consumer.md': 'hybrid generated',
+    'docs/agent-lifecycle.md': 'curated',
+    'docs/tool-execution-pipeline.md': 'curated',
+    'docs/acp/snapshot-replay.md': 'curated',
+  }
+  const rows = [
+    '| [module dependency graph](module-graph.md) | `generated` |',
+    '| [tool schema catalog and package map](tool-catalog/tools.md) | `generated` |',
+    ...docs.map((doc) => {
+      const link = graphIndexLink(doc.rel)
+      return `| [${labels[doc.rel] ?? link}](${link}) | \`${modes[doc.rel] ?? 'generated'}\` |`
+    }),
+  ]
+  const maintenance = 'mixed: each linked page declares generated, hybrid, or curated mode'
+  return [
+    ...generatedHeader('Documentation Graph Index'),
+    'These diagrams are the relationship layer above the generated catalogs. Use them to navigate package topology, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type shapes still live in the generated [events](cordis-catalog/events.md) / [services](cordis-catalog/services.md) catalogs, [tool-catalog/](tool-catalog/tools.md), and [core-data-structures/](core-data-structures/core.md).',
+    '',
+    'The process decision behind this index is recorded in [the documentation graph RFC](rfc/implemented/process/2026-07-03-documentation-graph-atlas.md).',
+    '',
+    '| Graph | Mode |',
+    '| --- | --- |',
+    ...rows,
+    '',
+    'Regenerate with `pnpm run gen-doc-graphs`; verify freshness with `pnpm run verify-doc-graphs`.',
+    '',
+    ...maintenanceFooter(maintenance),
+  ].join('\n')
+}
+
+function main(): void {
+  const docs = renderDocs()
+  if (process.argv.includes('--check')) {
+    const stale: string[] = []
+    for (const doc of docs) {
+      const abs = resolve(root, doc.rel)
+      const committed = existsSync(abs) ? readFileSync(abs, 'utf8') : null
+      if (committed !== doc.content) stale.push(doc.rel)
+    }
+    if (stale.length === 0) {
+      console.log(`gen-doc-graphs: ${docs.length} graph doc(s) are up to date.`)
+      return
+    }
+    console.error(`gen-doc-graphs: stale graph doc(s): ${stale.join(', ')}. Run \`pnpm run gen-doc-graphs\` and commit the result.`)
+    process.exit(1)
+  }
+
+  for (const doc of docs) {
+    mkdirSync(dirname(resolve(root, doc.rel)), { recursive: true })
+    writeFileSync(resolve(root, doc.rel), doc.content)
+  }
+  console.log(`gen-doc-graphs: wrote ${docs.length} graph doc(s).`)
+}
+
+if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) {
+  main()
+}
--- a/scripts/gen-module-graph.ts
+++ b/scripts/gen-module-graph.ts
@@ -6,7 +6,8 @@
 * these as `workspace:^` plus test-only extras, which would add noise). This
 * script reads every `packages/* /* /package.json`, keeps only the
 * `@deepseek-ai/dsh-*` peer edges (dropping the `cordis` peer), and renders a
- * GitHub-viewable Mermaid graph plus a dependency table.
+ * GitHub-viewable Mermaid graph grouped by `packages/<group>/` plus a
+ * dependency table.
 *
 * The file is fully generated — never hand-edit it. Output is deterministic
 * (packages and edges sorted) so a regenerate-and-diff freshness check is
@@ -17,8 +18,8 @@
 *                                                is stale (CI / pre-push gate)
 */

+import { dirname, resolve } from 'node:path'
 import { globSync, readFileSync, writeFileSync } from 'node:fs'
-import { resolve } from 'node:path'

 const root = resolve(import.meta.dirname, '..')
 const OUT = 'docs/module-graph.md'
@@ -27,10 +28,30 @@ const SCOPE = '@deepseek-ai/dsh-'
 interface Pkg {
  /** Short name, `@deepseek-ai/dsh-` prefix stripped (e.g. `agent-loop`). */
  short: string
+  /** Package group from `packages/<group>/<pkg>`. */
+  group: string
+  /** Repo-relative package directory. */
+  rel: string
  /** Short names of this package's in-repo peer dependencies, sorted. */
  deps: string[]
 }

+const GROUP_ORDER = [
+  'util',
+  'llm',
+  'core',
+  'bash',
+  'fs',
+  'compact',
+  'subagent',
+  'web',
+  'todo',
+  'hooks',
+  'session-persistence',
+  'support',
+  'ui',
+]
+
 /** Read every workspace package and its `@deepseek-ai/dsh-*` peer edges. */
 function collect(): Pkg[] {
  const pkgs: Pkg[] = []
@@ -44,7 +65,9 @@ function collect(): Pkg[] {
      .filter(d => d.startsWith(SCOPE))
      .map(d => d.slice(SCOPE.length))
      .sort()
-    pkgs.push({ short: json.name.slice(SCOPE.length), deps })
+    const [, group, leaf] = rel.split('/')
+    if (group === undefined || leaf === undefined) throw new Error(`gen-module-graph: unexpected package path ${rel}`)
+    pkgs.push({ short: json.name.slice(SCOPE.length), group, rel: dirname(rel), deps })
  }
  return topoSort(pkgs)
 }
@@ -63,7 +86,7 @@ function topoSort(pkgs: Pkg[]): Pkg[] {
  while (remaining.size > 0) {
    const ready = [...remaining.values()]
      .filter(p => p.deps.every(d => placed.has(d)))
-      .sort((a, b) => a.short.localeCompare(b.short))
+      .sort(comparePackages)
    if (ready.length === 0) throw new Error(`gen-module-graph: dependency cycle among ${[...remaining.keys()].join(', ')}`)
    for (const p of ready) {
      out.push(p)
@@ -74,28 +97,71 @@ function topoSort(pkgs: Pkg[]): Pkg[] {
  return out
 }

+function comparePackages(a: Pkg, b: Pkg): number {
+  const groupA = GROUP_ORDER.indexOf(a.group)
+  const groupB = GROUP_ORDER.indexOf(b.group)
+  const normA = groupA === -1 ? Number.MAX_SAFE_INTEGER : groupA
+  const normB = groupB === -1 ? Number.MAX_SAFE_INTEGER : groupB
+  return normA - normB || a.group.localeCompare(b.group) || a.short.localeCompare(b.short)
+}
+
+function nodeId(prefix: string, value: string): string {
+  return `${prefix}_${value.replace(/[^a-zA-Z0-9_]/g, '_')}`
+}
+
+function escLabel(value: string): string {
+  return value.replace(/"/g, '\\"')
+}
+
+function packageLink(pkg: Pkg): string {
+  return `[\`${pkg.short}\`](../${pkg.rel})`
+}
+
 /** Render the full docs/module-graph.md content (pure, deterministic). */
 function render(pkgs: Pkg[]): string {
  const edges: string[] = []
  for (const p of pkgs) {
-    for (const d of p.deps) edges.push(`  ${p.short} --> ${d}`)
+    for (const d of p.deps) edges.push(`  ${nodeId('pkg', p.short)} --> ${nodeId('pkg', d)}`)
  }
-  const rows = pkgs.map(p => `| \`${p.short}\` | ${p.deps.length ? p.deps.map(d => `\`${d}\``).join(', ') : '—'} |`)
+  const byShort = new Map(pkgs.map(pkg => [pkg.short, pkg]))
+  const groups = [...new Set(pkgs.map(pkg => pkg.group))].sort((a, b) => {
+    const ia = GROUP_ORDER.indexOf(a)
+    const ib = GROUP_ORDER.indexOf(b)
+    const na = ia === -1 ? Number.MAX_SAFE_INTEGER : ia
+    const nb = ib === -1 ? Number.MAX_SAFE_INTEGER : ib
+    return na - nb || a.localeCompare(b)
+  })
+  const groupBlocks: string[] = []
+  for (const group of groups) {
+    groupBlocks.push(`  subgraph ${nodeId('group', group)}["packages/${escLabel(group)}"]`)
+    for (const pkg of pkgs.filter(p => p.group === group).sort((a, b) => a.short.localeCompare(b.short))) {
+      groupBlocks.push(`    ${nodeId('pkg', pkg.short)}["${escLabel(pkg.short)}"]`)
+    }
+    groupBlocks.push('  end')
+  }
+  const rows = pkgs.map((p) => {
+    const deps = p.deps.length ? p.deps.map((d) => {
+      const dep = byShort.get(d)
+      return dep ? packageLink(dep) : `\`${d}\``
+    }).join(', ') : '—'
+    return `| ${packageLink(p)} | \`${p.group}\` | ${deps} |`
+  })
  return [
    '<!-- Generated by scripts/gen-module-graph.ts — do not edit by hand.',
    '     Run `pnpm run gen-module-graph` to regenerate. -->',
    '',
    '# Module dependency graph',
    '',
-    'Inter-package dependencies among the `@deepseek-ai/dsh-*` harness packages, derived from each package\'s `peerDependencies` (the canonical runtime-dependency signal). An edge `a --> b` means package `a` depends on package `b`. Names have the `@deepseek-ai/dsh-` prefix stripped.',
+    'Inter-package dependencies among the `@deepseek-ai/dsh-*` harness packages, derived from each package\'s `peerDependencies` (the canonical runtime-dependency signal) and grouped by the `packages/<group>/<pkg>` hierarchy. An edge `a --> b` means package `a` depends on package `b`. Names have the `@deepseek-ai/dsh-` prefix stripped.',
    '',
    '```mermaid',
-    'graph TD',
+    'flowchart TD',
+    ...groupBlocks,
    ...edges,
    '```',
    '',
-    '| Package | Depends on |',
-    '| --- | --- |',
+    '| Package | Group | Depends on |',
+    '| --- | --- | --- |',
    ...rows,
    '',
  ].join('\n')
--- a/scripts/gen-persistence-catalog.ts
+++ b/scripts/gen-persistence-catalog.ts
@@ -404,7 +404,7 @@ export function render(events: AnnotatedLogEventEntry[]): string {
    '',
    '# Persistence Log Event Catalog',
    '',
-    'Every event type that can appear in a session\'s durable event log: each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with the payload it carries, its surface badge, and the declaration it comes from. It complements [session.md](../core-data-structures/session.md) (the `SessionEvent` envelope, surface list, and `deriveMessages()` projection), [persistence.md](../core-data-structures/persistence.md) (how the log is made durable), and the [cordis catalog](../cordis-catalog/events-and-services.md) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).',
+    'Every event type that can appear in a session\'s durable event log: each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with the payload it carries, its surface badge, and the declaration it comes from. It complements [session.md](../core-data-structures/session.md) (the `SessionEvent` envelope, surface list, and `deriveMessages()` projection), [persistence.md](../core-data-structures/persistence.md) (how the log is made durable), and the [cordis events catalog](../cordis-catalog/events.md) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).',
    '',
    'This file is GENERATED from source (`scripts/gen-persistence-catalog.ts`) and verified fresh by `pnpm run verify-persistence-catalog` (part of `doc-sync`) — do not edit it by hand. Payload blocks use a `ts persistence-catalog` fence (skipped by doc-typecheck, since a bare payload fragment is not standalone-compilable). Type names in a payload link to the page that documents them. See [the persistence-log-catalog RFC](../rfc/implemented/process/2026-07-04-persistence-log-catalog.md).',
    '',
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -75,6 +75,12 @@ interface ToolPackage {
  dir: string
  /** Repo-relative source path linked from the catalog entry. */
  source: string
+  /** Services or owning runtime surfaces the package requires at execution time. */
+  requires: string[]
+  /** Session events or other visible state the tools write or affect. */
+  writes: string[]
+  /** Additional model-visible names shipped by example/app config. */
+  shippedNames?: string[]
  /** Plug the injected seams + the tool plugin onto a context that already
   * carries `systemPrompt` + `tools`. */
  mount: (ctx: Context) => Promise<void>
@@ -98,15 +104,21 @@ const TOOL_PACKAGES: ToolPackage[] = [
    pkg: '@deepseek-ai/dsh-tool-bash',
    dir: 'tool-bash',
    source: 'packages/bash/tool-bash/src/index.ts',
+    requires: ['ctx.tools', 'ctx.bash'],
+    writes: ['tool/call', 'tool/result', 'context/message via agent.inject() for background completion notices'],
    async mount(ctx) {
      await ctx.plugin(LocalBashExecutor)
      await ctx.plugin(ToolBash)
    },
+    note:
+      'The bash/bash_output/bash_kill tools are model-facing consumers of the bash executor seam.',
  },
  {
    pkg: '@deepseek-ai/dsh-tool-fs',
    dir: 'tool-fs',
    source: 'packages/fs/tool-fs/src/index.ts',
+    requires: ['ctx.tools', 'ctx.fs', 'ctx.systemPrompt'],
+    writes: ['tool/call', 'fs/write-intent or fs/edit-intent for mutations', 'fs/observed after successful file operations', 'tool/result'],
    async mount(ctx) {
      // The tool injects `fs`; boot the local backend to satisfy it. The schemas
      // do not depend on the policy plugin (an event gate that changes behavior,
@@ -121,6 +133,9 @@ const TOOL_PACKAGES: ToolPackage[] = [
    pkg: '@deepseek-ai/dsh-tool-subagent',
    dir: 'tool-subagent',
    source: 'packages/subagent/tool-subagent/src/index.ts',
+    requires: ['ctx.tools', 'ctx.subagents'],
+    writes: ['tool/call', 'tool/result', 'child session events through the chosen provider'],
+    shippedNames: ['subagent', 'subagent_fork'],
    async mount(ctx) {
      await ctx.plugin(SubagentService)
      // Register a scripted provider under the name the tool delegates to.
@@ -134,14 +149,20 @@ const TOOL_PACKAGES: ToolPackage[] = [
    pkg: '@deepseek-ai/dsh-tool-todo',
    dir: 'tool-todo',
    source: 'packages/todo/tool-todo/src/index.ts',
+    requires: ['ctx.tools', 'owning Agent session'],
+    writes: ['tool/call', 'todo/write', 'tool/result'],
    async mount(ctx) {
      await ctx.plugin(ToolTodo)
    },
+    note:
+      'todo_write is session-owned state; UIs render the latest todo/write event as a checklist or ACP plan.',
  },
  {
    pkg: '@deepseek-ai/dsh-tool-web',
    dir: 'tool-web',
    source: 'packages/web/tool-web/src/index.ts',
+    requires: ['ctx.tools', 'ctx.web', 'ctx.systemPrompt'],
+    writes: ['tool/call', 'tool/result'],
    async mount(ctx) {
      // The tools inject `web`; boot the seam plus one search and one fetch
      // provider so both `web_search` and `web_fetch` register. The schemas do
@@ -152,6 +173,8 @@ const TOOL_PACKAGES: ToolPackage[] = [
      await ctx.plugin(WebFetchLocal)
      await ctx.plugin(ToolWeb)
    },
+    note:
+      'web_search and web_fetch keep provider selection behind ctx.web so model-visible schemas stay stable across backend swaps.',
  },
 ]

@@ -159,6 +182,9 @@ const TOOL_PACKAGES: ToolPackage[] = [
 interface CatalogPackage {
  pkg: string
  source: string
+  requires: string[]
+  writes: string[]
+  shippedNames?: string[]
  schemas: ToolSchema[]
  /** A deployment note (see {@link ToolPackage.note}), rendered after the tools. */
  note?: string
@@ -208,7 +234,15 @@ export async function collectToolCatalog(packages: ToolPackage[] = TOOL_PACKAGES
      await ctx.plugin(ToolRegistry)
      await entry.mount(ctx)
      const schemas = ctx.tools.schemas().sort((a, b) => a.name.localeCompare(b.name))
-      catalog.push({ pkg: entry.pkg, source: entry.source, schemas, ...entry.note !== undefined ? { note: entry.note } : {} })
+      catalog.push({
+        pkg: entry.pkg,
+        source: entry.source,
+        requires: entry.requires,
+        writes: entry.writes,
+        schemas,
+        ...entry.shippedNames !== undefined ? { shippedNames: entry.shippedNames } : {},
+        ...entry.note !== undefined ? { note: entry.note } : {},
+      })
    } finally {
      await ctx.fiber.dispose()
    }
@@ -225,6 +259,14 @@ function renderTool(schema: ToolSchema, source: string): string[] {
  return out
 }

+function codeList(values: string[] | undefined): string {
+  return values?.length ? values.map(value => `\`${value}\``).join(', ') : '-'
+}
+
+function tableCell(value: string | undefined): string {
+  return value ? value.replace(/\|/g, '\\|').replace(/\n/g, '<br>') : '-'
+}
+
 /** Render the full catalog (pure, deterministic given the manifest-ordered input). */
 export function render(catalog: ToolCatalog): string {
  const lines: string[] = [
@@ -233,12 +275,20 @@ export function render(catalog: ToolCatalog): string {
    '',
    '# Tool Schema Catalog',
    '',
-    'Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the [cordis events & services catalog](../cordis-catalog/events-and-services.md) (the wiring a plugin listens to and calls) and [core-data-structures/](../core-data-structures/core.md) (the types those signatures move) — this page is the *tools* the agent is offered.',
+    'Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the cordis [events](../cordis-catalog/events.md) & [services](../cordis-catalog/services.md) catalogs (the wiring a plugin listens to and calls) and [core-data-structures/](../core-data-structures/core.md) (the types those signatures move) — this page is the *tools* the agent is offered.',
    '',
    'This file is GENERATED and verified fresh by `pnpm run verify-tool-catalog` (part of `doc-sync`) — do not edit it by hand. Unlike the cordis catalog (a pure source-AST pass), this generator BOOTS each tool plugin on a real context and reads `ctx.tools.schemas()`, because a tool schema is not statically knowable (runtime-spread enums, concatenated descriptions, config-driven names, raw-JSON-Schema MCP tools). A completeness guard globs `packages/*/tool-*` and fails if any package is missing from the generator\'s boot manifest, so a new tool cannot be silently undocumented. See [the tool-schema-catalog RFC](../rfc/implemented/process/2026-07-02-tool-schema-catalog.md).',
    '',
    'Scope: shipped product tools under `packages/*/tool-*`, each booted with its DEFAULT config. The registered tool NAME can be a load-time config (e.g. `tool-subagent`\'s `toolName`), so a deployment may surface a package under a different or additional name — a per-package note records those shipped aliases where they exist. The `examples/` demo tools (e.g. `echo`) are excluded, matching the cordis catalog\'s packages-only scope.',
    '',
+    '## Tool Package Map',
+    '',
+    'This table connects model-visible tool names to the plugin package and service seams behind them. Exact JSON Schemas follow in the package sections below.',
+    '',
+    '| Tool package | Model-visible names | Requires | Writes / affects | Shipped aliases | Deployment note |',
+    '| --- | --- | --- | --- | --- | --- |',
+    ...catalog.map(entry => `| \`${entry.pkg}\` | ${codeList(entry.schemas.map(schema => schema.name))} | ${codeList(entry.requires)} | ${codeList(entry.writes)} | ${codeList(entry.shippedNames)} | ${tableCell(entry.note)} |`),
+    '',
  ]
  for (const entry of catalog) {
    lines.push(`## \`${entry.pkg}\``, '')
--- a/scripts/verify-doc-refs.ts
+++ b/scripts/verify-doc-refs.ts
@@ -2,7 +2,7 @@
 * Doc-sync gate: verify that doc references written in TypeScript COMMENTS
 * resolve to a file that exists. Source comments cite docs by root-relative
 * prose path — `see docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md`,
- * `docs/architecture.md § plugin checklist`. `verify-md-links` parses Markdown
+ * `docs/architecture.md § Where New Behavior Goes`. `verify-md-links` parses Markdown
 * link AST and never sees these, so a doc rename or move could silently orphan
 * a `.ts` comment that points at it. The RFC classification reorg
 * ([the classification RFC](../docs/rfc/implemented/process/2026-06-20-rfc-classification.md))
@@ -12,7 +12,7 @@
 * Detection is a token scan, NOT an AST walk: doc refs live in free prose inside
 * comments, not in a structured form. We match `docs/<path>.md` tokens and
 * REQUIRE the `.md` extension, so extensionless prose (`docs/postmortem/0001`,
- * `docs/architecture.md § plugin checklist` — the section suffix is outside the
+ * `docs/architecture.md § Where New Behavior Goes` — the section suffix is outside the
 * token) is left alone rather than misread as a path. Each token is resolved
 * ROOT-RELATIVE (the way the comments are written) and must exist on disk. This
 * is checker, not fixer: it reports and never rewrites.
@@ -43,7 +43,7 @@ const isExcluded = (p: string): boolean =>
 * Match a `docs/….md` reference token. The `.md` extension is required so a
 * bare `docs/postmortem/0001` (no extension) does not register as a path. The
 * character class stops at whitespace, backticks, parens, and the section sign,
- * so trailing prose (`… .md § plugin checklist`) is not swallowed into the path.
+ * so trailing prose (`… .md § Where New Behavior Goes`) is not swallowed into the path.
 */
 const DOC_REF = /\bdocs\/[A-Za-z0-9._/-]+\.md/g

--- a/scripts/verify-mermaid.ts
+++ b/scripts/verify-mermaid.ts
@@ -0,0 +1,108 @@
+/**
+ * Doc-sync gate: verify every fenced ```mermaid block parses with Mermaid's
+ * own parser. Markdown link/type/code gates can say a diagram block exists and
+ * is linked, but only Mermaid can catch syntax errors that GitHub would fail to
+ * render.
+ *
+ * Scope matches the Markdown link gate so any Mermaid diagram in repo-authored
+ * docs is checked: README.md, README.zh.md, docs/** /*.md,
+ * packages/* /*.md, packages/* /* /*.md, examples/** /*.md, AGENTS.md,
+ * packages/AGENTS.md, and .agents/skills/** /*.md.
+ *
+ * Run: `tsx scripts/verify-mermaid.ts`.
+ */
+
+import { readFileSync, realpathSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { glob } from 'node:fs/promises'
+import { fromMarkdown } from 'mdast-util-from-markdown'
+import { gfmFromMarkdown } from 'mdast-util-gfm'
+import { gfm } from 'micromark-extension-gfm'
+import { JSDOM } from 'jsdom'
+import type { Nodes } from 'mdast'
+
+const root = resolve(import.meta.dirname, '..')
+
+const PATTERNS = [
+  'README.md',
+  'README.zh.md',
+  'docs/**/*.md',
+  'packages/*/*.md',
+  'packages/*/*/*.md',
+  'examples/**/*.md',
+  'AGENTS.md',
+  'packages/AGENTS.md',
+  '.agents/skills/**/*.md',
+]
+
+interface Block {
+  file: string
+  line: number
+  source: string
+}
+
+interface Violation {
+  file: string
+  line: number
+  message: string
+}
+
+function extractMermaidBlocks(file: string): Block[] {
+  const source = readFileSync(resolve(root, file), 'utf8')
+  const tree = fromMarkdown(source, { extensions: [gfm()], mdastExtensions: [gfmFromMarkdown()] })
+  const out: Block[] = []
+  const visit = (node: Nodes): void => {
+    if (node.type === 'code' && node.lang === 'mermaid') {
+      out.push({ file, line: node.position?.start.line ?? 0, source: node.value })
+    }
+    if ('children' in node) {
+      for (const child of node.children) visit(child)
+    }
+  }
+  visit(tree)
+  return out
+}
+
+function formatError(error: unknown): string {
+  if (error instanceof Error) return error.message.replace(/\s+/g, ' ').trim()
+  return String(error).replace(/\s+/g, ' ').trim()
+}
+
+const blocks: Block[] = []
+const seen = new Set<string>()
+let checkedFiles = 0
+for (const pattern of PATTERNS) {
+  for await (const match of glob(pattern, { cwd: root })) {
+    const real = realpathSync(resolve(root, match))
+    if (seen.has(real)) continue
+    seen.add(real)
+    checkedFiles++
+    blocks.push(...extractMermaidBlocks(match))
+  }
+}
+
+const violations: Violation[] = []
+const { window } = new JSDOM('')
+Object.defineProperty(globalThis, 'window', { value: window })
+Object.defineProperty(globalThis, 'document', { value: window.document })
+Object.defineProperty(globalThis, 'navigator', { value: window.navigator })
+const mermaid = (await import('mermaid')).default
+mermaid.initialize({ startOnLoad: false })
+for (const block of blocks) {
+  try {
+    await mermaid.parse(block.source, { suppressErrors: false })
+  } catch (error: unknown) {
+    violations.push({ file: block.file, line: block.line, message: formatError(error) })
+  }
+}
+
+if (violations.length === 0) {
+  console.log(`verify-mermaid: ${blocks.length} mermaid block(s) parsed across ${checkedFiles} file(s).`)
+  process.exit(0)
+}
+
+console.error('verify-mermaid: Mermaid syntax errors found:')
+for (const violation of violations) {
+  console.error(`  ${violation.file}:${violation.line}  ${violation.message}`)
+}
+process.exit(1)