docs(graphs): verify mermaid syntax

docs/development.md

@@ -99,6 +99,7 @@ pnpm run verify-cordis-catalog  # fail if the cordis events/services catalog is
 pnpm run gen-doc-graphs     # regenerate docs/graphs/*.md from source and curated graph definitions
 pnpm run verify-doc-graphs  # fail if docs/graphs/*.md is stale
 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 doc-sync       # doc-typecheck, generated doc freshness, markdown wrap/link, and type-equiv verification
 pnpm run gen-module-graph     # regenerate docs/module-graph.md from package peerDeps

docs/graphs/agent-lifecycle.md

@@ -11,31 +11,31 @@ This sequence is the visual companion to [architecture.md](../architecture.md#lo
 sequenceDiagram
   participant User
   participant Agent
-  participant Loop
+  participant Driver
   participant Prompt as ctx.systemPrompt
   participant LLM as ctx.llm
   participant Tools as ctx.tools
   participant Session
   participant Persistence
   User->>Agent: send(content)
-  Agent->>Loop: queued work wakes driver
-  Loop->>Session: turn/start + user/message
-  Loop-->>User: agent/turn-start
-  Loop->>Prompt: system-prompt/assemble waterfall
-  Loop-->>Loop: agent/pre-step serial checkpoint
-  Loop->>Session: step/start
-  Loop->>LLM: agent/request waterfall, then llm/stream waterfall
-  LLM-->>Loop: StreamChunk*
-  Loop->>Session: assistant/chunk*
-  Loop-->>User: agent/stream-chunk* (master live mirror)
-  Loop->>Session: assistant/message
-  Loop->>Tools: tools/execute waterfall for each tool-call
+  Agent->>Driver: queued work wakes driver
+  Driver->>Session: turn/start + user/message
+  Driver-->>User: agent/turn-start
+  Driver->>Prompt: system-prompt/assemble waterfall
+  Driver-->>Driver: agent/pre-step serial checkpoint
+  Driver->>Session: step/start
+  Driver->>LLM: agent/request waterfall, then llm/stream waterfall
+  LLM-->>Driver: StreamChunk*
+  Driver->>Session: assistant/chunk*
+  Driver-->>User: agent/stream-chunk* (master live mirror)
+  Driver->>Session: assistant/message
+  Driver->>Tools: tools/execute waterfall for each tool-call
   Tools-->>Session: tool-owned events when applicable
-  Loop->>Session: tool/result
-  Loop-->>Loop: agent/turn-continuation waterfall
-  Loop->>Session: turn/end
-  Loop->>Persistence: session/flush parallel checkpoint
-  Loop-->>User: agent/status idle
+  Driver->>Session: tool/result
+  Driver-->>Driver: agent/turn-continuation waterfall
+  Driver->>Session: turn/end
+  Driver->>Persistence: session/flush parallel checkpoint
+  Driver-->>User: agent/status idle
 ```
 
 Future pressure from the hooks stack: PR #129 removes the live `agent/stream-chunk` mirror and leaves durable `assistant/chunk` on `session/event` as the authoritative token stream. Consumers that need replayable transcript data should already treat `session/event` as the load-bearing path.

docs/graphs/tool-execution-pipeline.md

@@ -10,21 +10,21 @@ This graph shows where policy, hooks, sandboxing, and future filesystem guards f
 ```mermaid
 flowchart TD
   model["Assistant message contains tool-call block"]
-  call["Session event: tool/call"]
+  toolCall["Session event: tool/call"]
   waterfall["ctx.tools.execute()<br/>tools/execute waterfall"]
   policy["Policy / permission / hooks listener"]
-  body["Registered tool execute() body"]
+  toolBody["Registered tool execute() body"]
   owned["Tool-owned session events<br/>todo/write, future fs policy facts"]
-  result["Session event: tool/result"]
+  toolResult["Session event: tool/result"]
   ui["UI presentation<br/>presentCall / presentResult"]
-  model --> call --> waterfall
+  model --> toolCall --> waterfall
   waterfall --> policy
-  policy -->|next()| body
-  policy -->|veto / throw| result
-  body --> owned
-  body --> result
-  call --> ui
-  result --> ui
+  policy -->|next| toolBody
+  policy -->|veto / throw| toolResult
+  toolBody --> owned
+  toolBody --> toolResult
+  toolCall --> ui
+  toolResult --> ui
 ```
 
 Future pressure from the fs stack: PR #128 snapshots a policy rejection card. The graph keeps the veto path explicit because filesystem read-before-edit checks, permission prompts, and hook bridges all belong on this path.

docs/rfc/implemented/process/2026-07-03-documentation-graph-atlas.md

@@ -53,6 +53,7 @@ The hybrid pages must fail loud when their manifests are stale:
 - 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 tool affordance graph boot-harvests the shipped tool catalog and asserts every tool package has `TOOL_PACKAGE_META`.
 - 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
 
@@ -62,5 +63,5 @@ Use Mermaid for committed diagrams because GitHub renders it in Markdown and it
 
 - Maintainers get visual entry points for topology, seams, event flow, lifecycle, session replay, 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`, so graph drift is caught with the other doc freshness gates.
+- `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 and tool graphs, while hooks should expand the event matrix and tool execution pipeline.