Merge pull request #130 from deepseek-harness/codex/docs-graph-brainstorm

docs: add graph atlas and Mermaid verification
2026-08-15 21:04:50 +00:00 · 2026-07-05 03:20:07 +08:00
parent 99540e6a94 a06e5f1c87
commit 57fd914f95
28 changed files with 3011 additions and 196 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/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/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
@@ -2,7 +2,7 @@

 This document describes the architecture of the DeepSeek Harness — the foundation of **DeepSeek Code**. The governing principle: **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 stack is three tiers: plugins (the loop itself, seam implementations, model-facing tools, bridges) over interface/service packages (each owning one `ctx` key and its vocabulary) over the vendored Cordis kernel (`vendor/`).

-This document covers **behavior**; type shapes live in [core-data-structures/](core-data-structures/core.md), the per-event/service reference in the generated [events](cordis-catalog/events.md) / [services](cordis-catalog/services.md) catalogs, per-package contracts in the package READMEs ([map](../packages/README.md)).
+This document covers **behavior**; type shapes live in [core-data-structures/](core-data-structures/core.md), the per-event/service reference in the generated [events](cordis-catalog/events.md) / [services](cordis-catalog/services.md) catalogs, visual relationship maps in the [documentation graph index](graph-atlas.md), and per-package contracts in the package READMEs ([map](../packages/README.md)).

 ## Service map

--- 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/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: a797008cefe2da205a0a7b8aa7ab818ea0035dd5
-development.zh.md: 69b597bb40135606c01c36f151a6e0ad817f6cf6
+development.md: f032764fff29baaca007211db8b69d9a5129078f
+development.zh.md: 3a650d03ce7cafd0e34290ae918e5a303c2ad8a9
--- a/docs/development.md
+++ b/docs/development.md
@@ -98,8 +98,11 @@ 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.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
@@ -98,8 +98,11 @@ 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.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,36 @@
+<!-- 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:234`](../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:241`](../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:380`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - |
+| `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:319`](../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:332`](../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:259`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - |
+| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:345`](../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:274`](../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:250`](../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:355`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - |
+| `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:368`](../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:77`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude) |
+| `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:70`](../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:26`](../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:32`](../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,176 +3,247 @@

 # 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
-  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 --> 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_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_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` |
-| `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`, `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) |
+| [`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), [`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/rfc/README.md
+++ b/docs/rfc/README.md
@@ -169,6 +169,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/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
@@ -9,6 +9,18 @@ This file is GENERATED and verified fresh by `pnpm run verify-tool-catalog` (par

 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/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/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/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
--- 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-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[] = [
@@ -239,6 +281,14 @@ export function render(catalog: ToolCatalog): string {
    '',
    '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-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)