From cd9737d5696c29e234e69eb9a10dccf62121f00a Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Mon, 6 Jul 2026 22:09:30 +0800
Subject: [PATCH 1/7] Gate JSDoc completeness on every package export
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

New doc-sync gate verify-export-jsdoc walks every module-level exported
name under packages/*/*/src and requires description prose everywhere,
plus @param per parameter and @returns on non-void annotated returns for
function-like exports, public class methods, properties, and accessors.
The parsing + check helpers move out of gen-cordis-catalog.ts into a
shared scripts/jsdoc.ts so 'documented' means one thing on both gated
surfaces.

Deliberate exemptions (documented in the RFC): heritage-declared class
members (the seam declaration is the doc's one home — the one checker
query in an otherwise pure-AST walk), cordis plugin-protocol slots
(name/inject/reusable/Config/apply, top-level and static), constructors,
overload implementations, declare-module augmentation bodies, and
re-export statements (checked at the defining module).

The 203 under-documented exports the gate found at adoption are filled
in this change, so the gate lands green; generated catalogs/graphs are
regenerated for the shifted line pointers.

RFC: docs/rfc/implemented/process/2026-07-06-export-surface-jsdoc-gate.md
---
 AGENTS.md                                     |   2 +-
 docs/cordis-catalog/events.md                 |  22 +-
 docs/cordis-catalog/services.md               |  10 +-
 docs/development.i18n.yaml                    |   4 +-
 docs/development.md                           |   1 +
 docs/development.zh.md                        |   1 +
 docs/event-producer-consumer.md               |  22 +-
 docs/persistence-catalog/log-events.md        |  30 +-
 docs/rfc/INDEX.md                             |   1 +
 .../2026-07-06-export-surface-jsdoc-gate.md   |  42 ++
 package.json                                  |   3 +-
 packages/bash/bash-local/src/run.ts           |  29 +-
 packages/bash/bash/src/types.ts               |  13 +-
 packages/bash/tool-bash/src/index.ts          |   2 +
 packages/compact/compact-basic/src/index.ts   |  26 +-
 packages/compact/compact-basic/src/types.ts   |   3 +
 packages/core/agent-loop/src/agent.ts         |   6 +
 packages/core/agent-loop/src/inbox.ts         |  30 +-
 packages/core/agent-loop/src/index.ts         |   4 +
 packages/core/agent-loop/src/loop.ts          |  11 +-
 packages/core/agent-loop/src/request-log.ts   |   5 +-
 packages/core/agent/src/types.ts              |  18 +-
 .../agent/tests/verify-export-jsdoc.spec.ts   | 296 +++++++++++++
 packages/core/session/src/index.ts            |   8 +
 packages/core/session/src/json.ts             |   4 +
 packages/core/session/src/repair.ts           |   2 +
 packages/core/session/src/surface.ts          |   4 +
 packages/core/session/src/tool-pairing.ts     |   6 +
 packages/core/session/src/types.ts            |   9 +-
 packages/core/system-prompt/src/index.ts      |   5 +
 packages/core/tools/src/schema.ts             |  13 +
 packages/fs/fs-local/src/fsio.ts              |  50 ++-
 packages/fs/fs-local/src/index.ts             |   1 +
 packages/fs/fs/src/types.ts                   |  14 +-
 packages/fs/tool-fs/src/diff.ts               |   6 +
 packages/fs/tool-fs/src/edit.ts               |  20 +-
 packages/fs/tool-fs/src/read-render.ts        |  11 +-
 packages/fs/tool-fs/src/read.ts               |  13 +-
 packages/fs/tool-fs/src/session-cwd.ts        |   6 +-
 packages/fs/tool-fs/src/write.ts              |  19 +-
 packages/hooks/hook-protocol/src/codec.ts     |   6 +
 packages/hooks/hook-protocol/src/events.ts    |  11 +-
 packages/hooks/hook-protocol/src/matcher.ts   |   4 +
 packages/hooks/hook-protocol/src/merge.ts     |   2 +
 packages/hooks/hook-protocol/src/runner.ts    |   5 +
 packages/hooks/hooks-claude/src/config.ts     |  10 +-
 packages/hooks/hooks-codex/src/config.ts      |   2 +
 packages/llm/llm-deepseek/src/adapter.ts      |   8 +-
 packages/llm/llm-deepseek/src/index.ts        |   6 +
 packages/llm/llm-deepseek/src/serialize.ts    |  11 +-
 packages/llm/llm-deepseek/src/sse.ts          |   2 +
 packages/llm/llm-deepseek/src/translate.ts    |  10 +-
 packages/llm/llm-deepseek/src/types.ts        |  18 +
 packages/llm/llm-pi-ai/src/adapter.ts         |  10 +-
 packages/llm/llm-pi-ai/src/convert.ts         |  17 +-
 packages/llm/llm-pi-ai/src/index.ts           |   5 +
 packages/llm/llm/src/assembler.ts             |  15 +-
 packages/llm/llm/src/attribution.ts           |   4 +
 packages/llm/llm/src/brand.ts                 |   6 +-
 packages/llm/llm/src/error.ts                 |   7 +-
 packages/llm/llm/src/index.ts                 |   6 +-
 packages/llm/llm/src/never.ts                 |   3 +
 packages/llm/llm/src/types.ts                 |   4 +
 .../session-persistence-jsonl/src/format.ts   |  42 +-
 .../session-persistence-jsonl/src/index.ts    |   1 +
 .../session-persistence-sqlite/src/schema.ts  |  19 +-
 .../session-persistence/src/coordinator.ts    |   5 +
 .../session-persistence/src/index.ts          |   4 +
 packages/subagent/subagent-acp/src/run.ts     |  31 +-
 packages/subagent/subagent-fork/src/index.ts  |   2 +
 .../subagent/subagent-inprocess/src/index.ts  |  13 +-
 packages/subagent/subagent/src/types.ts       |   1 +
 packages/support/llm-replay/src/index.ts      |  14 +
 packages/ui/acp/src/codec.ts                  |   8 +
 packages/ui/acp/src/index.ts                  |  38 +-
 packages/ui/app-boot/src/index.ts             |  16 +
 packages/ui/stdio-agent/src/stdio-chat.ts     |   4 +
 packages/web/tool-web/src/fetch.ts            |  38 +-
 packages/web/tool-web/src/html.ts             |   4 +
 packages/web/tool-web/src/index.ts            |   1 +
 packages/web/tool-web/src/search.ts           |  33 +-
 packages/web/web-fetch-local/src/index.ts     |   1 +
 packages/web/web-fetch-local/src/policy.ts    |  20 +
 packages/web/web-search-deepseek/src/index.ts |   1 +
 .../web/web-search-deepseek/src/provider.ts   |   8 +
 packages/web/web-search-exa/src/index.ts      |   1 +
 packages/web/web-search-exa/src/provider.ts   |  14 +-
 .../web/web-search-perplexity/src/index.ts    |   1 +
 .../web/web-search-perplexity/src/provider.ts |  12 +-
 scripts/gen-cordis-catalog.ts                 | 191 +-------
 scripts/jsdoc.ts                              | 216 ++++++++++
 scripts/verify-export-jsdoc.ts                | 408 ++++++++++++++++++
 92 files changed, 1802 insertions(+), 289 deletions(-)
 create mode 100644 docs/rfc/implemented/process/2026-07-06-export-surface-jsdoc-gate.md
 create mode 100644 packages/core/agent/tests/verify-export-jsdoc.spec.ts
 create mode 100644 scripts/jsdoc.ts
 create mode 100644 scripts/verify-export-jsdoc.ts

diff --git a/AGENTS.md b/AGENTS.md
index 0fbc56a646..8e6eb7c4f9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -109,7 +109,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY` (and optional `DEEPSEEK_BASE_UR
 
 ## Type safety and documentation
 
-Everything compiles under `strict: true` with `noImplicitAny`; every remaining `any` carries a comment saying why a narrower type is infeasible. Every module has a module-level doc comment; every export (and non-obvious method) has a JSDoc explaining semantics — contracts, disposal, errors — not the name restated; internal helpers only where non-obvious; one-liners when one line suffices. Lean toward the stricter lint rule and the extra mechanical gate: encode invariants in checks (`verify-*` scripts), preferring a narrow justified escape hatch over a rule left off globally. Type gymnastics are acceptable inside core packages when they buy plugin-author DX (the `defineTool` schema DSL is the canonical example).
+Everything compiles under `strict: true` with `noImplicitAny`; every remaining `any` carries a comment saying why a narrower type is infeasible. Every module has a module-level doc comment; every export (and non-obvious method) has a JSDoc explaining semantics — contracts, disposal, errors — not the name restated; internal helpers only where non-obvious; one-liners when one line suffices. The export half is mechanical: `verify-export-jsdoc` (in `doc-sync`) requires description prose on every package export plus `@param`/`@returns` (and an annotated return) on function-like ones — heritage-declared members, plugin-protocol slots, and constructors exempt ([export-gate RFC](docs/rfc/implemented/process/2026-07-06-export-surface-jsdoc-gate.md)). Lean toward the stricter lint rule and the extra mechanical gate: encode invariants in checks (`verify-*` scripts), preferring a narrow justified escape hatch over a rule left off globally. Type gymnastics are acceptable inside core packages when they buy plugin-author DX (the `defineTool` schema DSL is the canonical example).
 
 Docs are part of every change: code changes update their README and JSDoc in the SAME change; a bilingual-pair edit updates the counterpart and re-records ([i18n contract](docs/i18n/README.md)). The writing rules — document the current state never the history, one physical line per paragraph, one home per fact — and the word-budget gate live in [docs/AGENTS.md](docs/AGENTS.md).
 
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index 753cf8f4d0..237a7b2469 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -23,7 +23,7 @@ An agent was registered in the AgentRegistry and is ready to receive messages.
 
 Types: [Agent](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/types.ts:248`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:264`](../../packages/core/agent/src/types.ts)
 
 ### `agent/disposed` — emit
 
@@ -35,7 +35,7 @@ An agent was disposed and removed from the registry; its fiber and any in-flight
 
 Types: [Agent](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/types.ts:255`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:271`](../../packages/core/agent/src/types.ts)
 
 ### `agent/error` — emit
 
@@ -47,7 +47,7 @@ A step or turn errored. The loop reports a failure here (plus the logger) even w
 
 Types: [Agent](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/types.ts:404`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:420`](../../packages/core/agent/src/types.ts)
 
 ### `agent/pre-step` — serial
 
@@ -61,7 +61,7 @@ Serial (awaited in registration order), not a waterfall: a listener mutates the
 
 Types: [Agent](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/types.ts:333`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:349`](../../packages/core/agent/src/types.ts)
 
 ### `agent/prompt-submit` — waterfall
 
@@ -73,7 +73,7 @@ Waterfall: decide what happens to ONE drained queued message before it becomes a
 
 Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/types.ts:346`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:362`](../../packages/core/agent/src/types.ts)
 
 ### `agent/queued` — emit
 
@@ -85,7 +85,7 @@ A message entered the agent's inbox (queued or steering). `source` is the resolv
 
 Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/types.ts:273`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:289`](../../packages/core/agent/src/types.ts)
 
 ### `agent/request` — waterfall
 
@@ -97,7 +97,7 @@ Waterfall: shape the step's call configuration — model switching, sampling ove
 
 Types: [Agent](../core-data-structures/core.md) · [LlmCallConfig](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/types.ts:369`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:385`](../../packages/core/agent/src/types.ts)
 
 ### `agent/session-start` — emit
 
@@ -109,7 +109,7 @@ The agent's session lifecycle began, fired once before its first turn. `source`
 
 Types: [Agent](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/types.ts:288`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:304`](../../packages/core/agent/src/types.ts)
 
 ### `agent/status` — emit
 
@@ -121,7 +121,7 @@ Agent status changed (`idle` ⇄ `running`, or → `disposed`). Drive lifecycle
 
 Types: [Agent](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/types.ts:264`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:280`](../../packages/core/agent/src/types.ts)
 
 ### `agent/step-result` — waterfall
 
@@ -133,7 +133,7 @@ Waterfall: post-process the assembled assistant Message before tool dispatch (va
 
 Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/types.ts:379`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:395`](../../packages/core/agent/src/types.ts)
 
 ### `agent/turn-continuation` — waterfall
 
@@ -145,7 +145,7 @@ Waterfall: override the turn-continuation decision via a typed ContinuationDecis
 
 Types: [Agent](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/types.ts:392`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:408`](../../packages/core/agent/src/types.ts)
 
 ## `fs/*`
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 0221946118..4397f58cab 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -21,7 +21,7 @@ createAgent(options: CreateAgentOptions): AgentHandle
 async resume(options: ResumeAgentOptions): Promise<AgentHandle>
 ```
 
-Source: [`packages/core/agent-loop/src/index.ts:63`](../../packages/core/agent-loop/src/index.ts)
+Source: [`packages/core/agent-loop/src/index.ts:67`](../../packages/core/agent-loop/src/index.ts)
 
 ## `ctx.agents` — `AgentRegistry`
 
@@ -124,7 +124,7 @@ stream(options: GenerateOptions): AsyncIterable<StreamChunk>
 
 Types: [GenerateOptions](../core-data-structures/core.md) · [StreamChunk](../core-data-structures/llm-streaming.md)
 
-Source: [`packages/llm/llm/src/index.ts:84`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:88`](../../packages/llm/llm/src/index.ts)
 
 ## `ctx.sessionPersistence` — `SessionPersistence` (abstract seam)
 
@@ -146,7 +146,7 @@ abstract list(): Promise<SessionHeader[]>
 
 Types: [SessionEvent](../core-data-structures/core.md)
 
-Source: [`packages/session-persistence/session-persistence/src/index.ts:98`](../../packages/session-persistence/session-persistence/src/index.ts)
+Source: [`packages/session-persistence/session-persistence/src/index.ts:102`](../../packages/session-persistence/session-persistence/src/index.ts)
 
 ## `ctx.sessions` — `SessionStore`
 
@@ -163,7 +163,7 @@ get(id: SessionId): Session | undefined
 list(): Session[]
 ```
 
-Source: [`packages/core/session/src/index.ts:371`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:379`](../../packages/core/session/src/index.ts)
 
 ## `ctx.subagents` — `SubagentService`
 
@@ -189,7 +189,7 @@ variable(name: string, provider: (context: AssembleContext) => string | undefine
 assemble(context: AssembleContext = {}): Promise<PromptAssembly>
 ```
 
-Source: [`packages/core/system-prompt/src/index.ts:198`](../../packages/core/system-prompt/src/index.ts)
+Source: [`packages/core/system-prompt/src/index.ts:203`](../../packages/core/system-prompt/src/index.ts)
 
 ## `ctx.tools` — `ToolRegistry`
 
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index cef11b8352..119f058ad6 100644
--- 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: f032764fff29baaca007211db8b69d9a5129078f
-development.zh.md: 3a650d03ce7cafd0e34290ae918e5a303c2ad8a9
+development.md: 578fa619b8b3c7f5a306c8ad9cd880ab648b9b0c
+development.zh.md: e0189ae9b4c42f3f61ccc30b9205ff11f64f1fec
diff --git a/docs/development.md b/docs/development.md
index f032764fff..578fa619b8 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -98,6 +98,7 @@ 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 verify-export-jsdoc    # fail if a module-level package export lacks complete JSDoc
 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
diff --git a/docs/development.zh.md b/docs/development.zh.md
index 3a650d03ce..e0189ae9b4 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -98,6 +98,7 @@ 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 verify-export-jsdoc    # fail if a module-level package export lacks complete JSDoc
 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
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 24a2793826..2260c724b4 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -7,17 +7,17 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 
 | Event | Mode | Declared in | Dispatchers | Listeners |
 | --- | --- | --- | --- | --- |
-| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:248`](../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:255`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) |
-| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:404`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - |
-| `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:333`](../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:346`](../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:273`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - |
-| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:369`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - |
-| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:288`](../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:264`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`stdio-agent`](../packages/ui/stdio-agent) |
-| `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:379`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - |
-| `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:392`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:264`](../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:271`](../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:420`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - |
+| `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:349`](../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:362`](../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:289`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - |
+| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:385`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - |
+| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:304`](../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:280`](../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:395`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - |
+| `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:408`](../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) |
diff --git a/docs/persistence-catalog/log-events.md b/docs/persistence-catalog/log-events.md
index 5d6f23f6a8..9801a3cfec 100644
--- a/docs/persistence-catalog/log-events.md
+++ b/docs/persistence-catalog/log-events.md
@@ -23,7 +23,7 @@ Raw stream chunk — token-level replay fidelity.
 
 Types: [StreamChunk](../core-data-structures/llm-streaming.md)
 
-Source: [`packages/core/session/src/types.ts:298`](../../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:304`](../../packages/core/session/src/types.ts)
 
 #### `assistant/message` — surface
 
@@ -35,7 +35,7 @@ Assembled assistant message for one step (derived history uses this). Carries th
 
 Types: [ContentBlock](../core-data-structures/core.md) · [TokenUsage](../core-data-structures/llm-streaming.md)
 
-Source: [`packages/core/session/src/types.ts:305`](../../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:311`](../../packages/core/session/src/types.ts)
 
 ### `compact/*`
 
@@ -83,7 +83,7 @@ In-session context injection (file-change notices, subdir AGENTS.md, skill conte
 
 Types: [ContentBlock](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md)
 
-Source: [`packages/core/session/src/types.ts:296`](../../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:302`](../../packages/core/session/src/types.ts)
 
 ### `hook/*`
 
@@ -119,7 +119,7 @@ A queued prompt an `agent/prompt-submit` listener VETOED — the durable record
 
 Types: [ContentBlock](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md)
 
-Source: [`packages/core/session/src/types.ts:290`](../../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:296`](../../packages/core/session/src/types.ts)
 
 ### `request/*`
 
@@ -131,7 +131,7 @@ Full snapshot of the EpochHeader the NEXT request is built under, with the Reque
 'request/header': { header: EpochHeader; reason: RequestHeaderReason }
 ```
 
-Source: [`packages/core/session/src/types.ts:350`](../../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:356`](../../packages/core/session/src/types.ts)
 
 #### `request/header-delta` — log-only
 
@@ -141,7 +141,7 @@ Amendment to the folded EpochHeader: at least one of a SystemDelta, a ToolsDelta
 'request/header-delta': { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig }
 ```
 
-Source: [`packages/core/session/src/types.ts:361`](../../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:367`](../../packages/core/session/src/types.ts)
 
 ### `steering/*`
 
@@ -155,7 +155,7 @@ Steering content injected between steps of a running turn.
 
 Types: [ContentBlock](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md)
 
-Source: [`packages/core/session/src/types.ts:323`](../../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:329`](../../packages/core/session/src/types.ts)
 
 ### `step/*`
 
@@ -167,7 +167,7 @@ Closes step `step` of turn `turn`.
 'step/end': { turn: number; step: number }
 ```
 
-Source: [`packages/core/session/src/types.ts:277`](../../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:283`](../../packages/core/session/src/types.ts)
 
 #### `step/start` — log-only
 
@@ -177,7 +177,7 @@ Opens step `step` of turn `turn` — one model call plus the tool executions it
 'step/start': { turn: number; step: number }
 ```
 
-Source: [`packages/core/session/src/types.ts:275`](../../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:281`](../../packages/core/session/src/types.ts)
 
 ### `todo/*`
 
@@ -193,7 +193,7 @@ NOT a SurfaceEventType: it produces no LLM message and never reaches `deriveMess
 
 Types: [TodoItem](../core-data-structures/session.md)
 
-Source: [`packages/core/session/src/types.ts:337`](../../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:343`](../../packages/core/session/src/types.ts)
 
 ### `tool/*`
 
@@ -207,7 +207,7 @@ The model requested one tool invocation: `name` with the raw `arguments` JSON st
 
 Types: [CallId](../core-data-structures/core.md)
 
-Source: [`packages/core/session/src/types.ts:311`](../../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:317`](../../packages/core/session/src/types.ts)
 
 #### `tool/result` — surface
 
@@ -219,7 +219,7 @@ A completed tool call's model-facing result, plus an optional tool-private `meta
 
 Types: [CallId](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md)
 
-Source: [`packages/core/session/src/types.ts:321`](../../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:327`](../../packages/core/session/src/types.ts)
 
 ### `turn/*`
 
@@ -233,7 +233,7 @@ Closes turn `turn` with the TurnEndReason that ended it. The loop fires the awai
 
 Types: [TurnEndReason](../core-data-structures/session.md)
 
-Source: [`packages/core/session/src/types.ts:273`](../../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:279`](../../packages/core/session/src/types.ts)
 
 #### `turn/start` — log-only
 
@@ -245,7 +245,7 @@ Opens turn `turn`. `trigger` records what started it — a drained message batch
 
 Types: [TurnTrigger](../core-data-structures/session.md)
 
-Source: [`packages/core/session/src/types.ts:267`](../../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:273`](../../packages/core/session/src/types.ts)
 
 ### `user/*`
 
@@ -259,4 +259,4 @@ A user-visible prompt (queued message drained at turn start).
 
 Types: [ContentBlock](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md)
 
-Source: [`packages/core/session/src/types.ts:279`](../../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:285`](../../packages/core/session/src/types.ts)
diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md
index 921c6389e8..f6d62e855e 100644
--- a/docs/rfc/INDEX.md
+++ b/docs/rfc/INDEX.md
@@ -142,6 +142,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
 | [Generate the RFC index tables](implemented/process/2026-07-04-generate-rfc-index-tables.md) | 2026-07-04 |
 | [Generated persistence log event catalog](implemented/process/2026-07-04-persistence-log-catalog.md) | 2026-07-04 |
 | [One gated in-file format for RFCs](implemented/process/2026-07-05-uniform-rfc-format.md) | 2026-07-05 |
+| [Export-surface JSDoc gate](implemented/process/2026-07-06-export-surface-jsdoc-gate.md) | 2026-07-06 |
 
 ### Testing
 
diff --git a/docs/rfc/implemented/process/2026-07-06-export-surface-jsdoc-gate.md b/docs/rfc/implemented/process/2026-07-06-export-surface-jsdoc-gate.md
new file mode 100644
index 0000000000..fa92fbcb3d
--- /dev/null
+++ b/docs/rfc/implemented/process/2026-07-06-export-surface-jsdoc-gate.md
@@ -0,0 +1,42 @@
+# RFC: Export-surface JSDoc gate
+
+Status: implemented
+
+## Problem
+
+The [cordis JSDoc completeness gate](2026-07-04-cordis-jsdoc-completeness-gate.md) made undocumented parameters and results impossible on the cordis surface — `interface Events` members and `ctx.<key>` service classes — but that surface is a fraction of what a plugin author imports. The AGENTS.md rule "every export (and non-obvious method) has a JSDoc explaining semantics" stayed prose-checkable only by review everywhere else, and nothing at all asked for `@param`/`@returns` on ordinary exported functions. A survey at adoption found 203 under-documented module-level exports across 34 packages: seam-adjacent helpers (`runBash`, `readForEdit`, `htmlToMarkdown`), format codecs, whole undocumented interfaces and type aliases — exactly the names an IDE consumer hovers.
+
+## Decision
+
+A new gate, `scripts/verify-export-jsdoc.ts` (`pnpm run verify-export-jsdoc`, wired into `doc-sync` beside `verify-cordis-catalog`), walks every module-level exported name under each `packages/<group>/<pkg>/src/` tree. The parsing and check helpers moved from `gen-cordis-catalog.ts` into a shared `scripts/jsdoc.ts`, so "documented" means the same thing on both surfaces: description prose ends at the first block tag, every checkable parameter needs a non-empty `@param`, a non-void ANNOTATED return needs a non-empty `@returns`, a stale `@param` errors, and violations aggregate into one report.
+
+The contract by declaration kind:
+
+- Every exported name needs JSDoc with non-empty description prose.
+- Function-like exports (function declarations; consts with function initializers) follow the full function contract. A const whose declarator is type-annotated (`export const f: Handler = …`) defers the return contract to the named type; `@returns` stays optional there.
+- Exported classes need class-level prose; public methods (statics included — reachable on the exported name) follow the function contract; public properties and accessors need prose (a get/set pair is covered by the getter). Overload implementations are exempt — the signatures carry the docs.
+- Exported interfaces, type aliases, and enums need prose on the declaration; member-level enforcement is deliberately deferred (the highest-value member surface — seam service classes — is already under the cordis gate).
+- Exported namespaces recurse; the namespace itself needs prose only when it does not merge with a documented same-name declaration (the Config-namespace idiom documents the plugin once).
+- `declare module` / `declare global` bodies and `export … from` re-export statements are skipped: an augmentation is not an export of the package, and a re-exported definition is checked where it is defined.
+
+Three exemption families keep the gate from demanding boilerplate, in the spirit of the cordis gate's `this`/`next` exemptions (documenting an exempt name anyway is allowed; only absence goes unchecked):
+
+- **Heritage members.** A class member whose name exists on an `extends`/`implements` heritage type is exempt: the seam declaration is the doc's one home, and the IDE inherits it on hover — re-documenting every `LocalBashExecutor.run` invites drift. This is the one question the walk asks the TYPE CHECKER (heritage types live across package boundaries, resolved through the repo `paths` map); everything else stays pure AST, and the annotated-return requirement is kept for symmetry with the cordis gate (it bound nothing at adoption — every exported function was already annotated).
+- **Plugin-protocol slots.** Top-level `name` / `inject` / `reusable` / `Config` consts and the `apply` entry, plus the same slots as statics on a plugin class, are framework protocol: their shape is fixed by cordis, and the module doc comment plus the `interface Config` carry the plugin's real semantics.
+- **Constructors**, mirroring the cordis gate: plugin classes are framework-constructed, and the class doc owns the story.
+
+`collectExportJsdocViolations()` returns the violation list (the CLI exits 1 on non-empty) so the negative-path tests in `packages/core/agent/tests/verify-export-jsdoc.spec.ts` assert on findings directly, driving fixture packages through every rejection and every exemption.
+
+## Alternatives considered
+
+- **eslint-plugin-jsdoc** (`require-jsdoc`/`require-param`/`require-returns`) — covers the mechanical core but cannot express the repo's contract: the heritage-member exemption needs cross-package type resolution, the protocol-slot and namespace-merge idioms are cordis-specific, and the completeness semantics (prose-above-tags, stale-tag errors, aggregate reporting) already have one home in `scripts/jsdoc.ts` shared with the catalog generator. Two subtly different definitions of "documented" is the failure mode this repo's one-home rule exists to prevent.
+- **Extending `gen-cordis-catalog.ts`** — the catalog generator renders a curated surface and gates its freshness; a repo-wide walk has no catalog to render. Sharing the helpers while keeping the walks separate keeps each gate's scope legible.
+- **Enforcing interface/type-alias member docs** — deferred: it would multiply the checked surface for members that are largely self-describing fields, while the seam classes carrying the load-bearing member contracts are already gated. Revisit if member-doc drift shows up in review.
+
+## Consequences
+
+- A new export cannot land undocumented: `verify-export-jsdoc` fails `doc-sync`, which pre-push and CI already run. The 203 gaps found at adoption were filled in the same change, so the gate landed green.
+- Exported functions must annotate return types (universal at adoption, now load-bearing) and use identifier parameters where `@param` must name them.
+- Seam docs are canonical: an implementation inherits its heritage docs, and behavior notes worth keeping on the implementation are additions, not requirements.
+- The gate builds a `ts.Program` (~6s) — the one doc gate that pays for type resolution; acceptable inside `doc-sync`, which already compiles doc snippets.
+- The protocol-slot names are reserved by convention at module top level; a non-protocol export coincidentally named `apply` or `Config` would go unchecked — accepted, documented here.
diff --git a/package.json b/package.json
index 7453a022e9..662f381711 100644
--- a/package.json
+++ b/package.json
@@ -39,6 +39,7 @@
     "gen-cordis-catalog": "tsx scripts/gen-cordis-catalog.ts",
     "gen-rfc-index": "tsx scripts/gen-rfc-index.ts",
     "verify-cordis-catalog": "tsx scripts/gen-cordis-catalog.ts --check",
+    "verify-export-jsdoc": "tsx scripts/verify-export-jsdoc.ts",
     "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",
@@ -48,7 +49,7 @@
     "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-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-rfc-format && 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-export-jsdoc && 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-rfc-format && 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",
diff --git a/packages/bash/bash-local/src/run.ts b/packages/bash/bash-local/src/run.ts
index 489d380787..b39e45c5f5 100644
--- a/packages/bash/bash-local/src/run.ts
+++ b/packages/bash/bash-local/src/run.ts
@@ -56,6 +56,8 @@ export const SENSITIVE_ENV_PATTERN = /KEY|SECRET|TOKEN/i
  * by in-process plugins (the hooks bridges), not the model — `dsh-tool-bash`
  * builds its request from named fields only and does not forward model input
  * here (see its README, § "The tool builds its request from named args only").
+ * @param extra - caller-supplied entries merged last; an explicit entry wins even against the scrub and the overrides.
+ * @returns the environment to hand to `spawn` for the child process.
  */
 export function childEnv(extra?: Record<string, string>): NodeJS.ProcessEnv {
   const env: NodeJS.ProcessEnv = {}
@@ -147,6 +149,14 @@ export class OutputCollector {
     private readonly spillDir: string,
   ) {}
 
+  /**
+   * Ingest one stream chunk, counting it toward the whole-stream total. On
+   * first overflow of the in-memory cap a spill file is opened and every chunk
+   * (already-collected ones included) is appended there from then on; the
+   * in-memory tail then drops whole chunks from its head (or the head of a
+   * single over-cap chunk) until it fits the cap again.
+   * @param chunk - the raw bytes from one stream 'data' event.
+   */
   push(chunk: Buffer): void {
     this.total += chunk.length
     const overflows = this.bytes + chunk.length > this.maxBytes
@@ -190,7 +200,10 @@ export class OutputCollector {
   // the bottom of this file) and `totalBytes` is read only by a test. The live
   // background-poll path goes through `readFrom()`, so inline snapshot() into
   // finalize() and drop or privatize the totalBytes getter.
-  /** Read the collected tail without finalizing (the final-result snapshot). */
+  /**
+   * Read the collected tail without finalizing (the final-result snapshot).
+   * @returns the retained tail text, the truncation flag, and the spill path when one was created.
+   */
   snapshot(): CollectedOutput {
     return {
       text: Buffer.concat(this.chunks).toString('utf8'),
@@ -209,6 +222,8 @@ export class OutputCollector {
    * pushed since `fromByte`. When `fromByte` has already slid out of the
    * in-memory tail window, the read is `lossy` — it returns the whole
    * retained tail and the gap is only recoverable from the spill file.
+   * @param fromByte - whole-stream offset to resume from (a prior read's `nextOffset`; 0 for the first read).
+   * @returns the delta text, the offset for the next read, the `lossy` flag, and the spill path when one was created.
    */
   readFrom(fromByte: number): { text: string; nextOffset: number; lossy: boolean; spillPath?: string } {
     const windowStart = this.total - this.bytes
@@ -223,7 +238,12 @@ export class OutputCollector {
     }
   }
 
-  /** Close the spill file (if any) and return the final output. */
+  /**
+   * Close the spill file (if any) and return the final output. A failed close
+   * (delayed writeback fault) stops advertising the spill path — the file may
+   * be missing its tail — but still returns the in-memory result.
+   * @returns the final collected output: tail text, truncation flag, and the spill path when intact.
+   */
   finalize(): CollectedOutput {
     if (this.spillFd !== undefined) {
       try {
@@ -249,6 +269,8 @@ export class OutputCollector {
  * host process — a kill that cannot be delivered is reported by the process
  * NOT dying, which callers already handle via escalation/timeouts. No-op for
  * non-positive pids (spawn never started a process).
+ * @param pid - the group leader's pid; non-positive means the spawn failed and the call is a no-op.
+ * @param sig - the signal to deliver to the whole group.
  */
 export function killGroup(pid: number, sig: NodeJS.Signals): void {
   if (pid <= 0) return
@@ -290,6 +312,9 @@ export interface RunningBash {
  * exec sessions addressable via session ids + stdin writes. We deliberately
  * spawn a fresh non-login `bash -c` per call for determinism (no rc files,
  * no inherited shell state); revisit when real workflows demand it.
+ * @param spec - the fully-resolved run (command, cwd, limits); no defaulting happens here.
+ * @param internals - test-only knobs; omitted fields fall back to the private per-process spill dir.
+ * @returns the live handle: pid, the two live collectors, the outcome promise, and `kill()`.
  */
 export function runBash(spec: SpawnSpec, internals: RunInternals = {}): RunningBash {
   const spillDir = internals.spillDir ?? privateSpillDir()
diff --git a/packages/bash/bash/src/types.ts b/packages/bash/bash/src/types.ts
index 9acd5c7cb7..4715ace318 100644
--- a/packages/bash/bash/src/types.ts
+++ b/packages/bash/bash/src/types.ts
@@ -11,7 +11,11 @@ import type { Branded } from '@deepseek-ai/dsh-brand'
 /** Identifies one background task within an executor (generated `bash-N`). */
 export type BashTaskId = Branded<'BashTaskId'>
 
-/** Brand a string as a {@link BashTaskId}. */
+/**
+ * Brand a string as a {@link BashTaskId}.
+ * @param id - the raw task-id string (the executor generates `bash-N`).
+ * @returns the same string, branded; no validation is performed.
+ */
 export function BashTaskId(id: string): BashTaskId {
   return id as BashTaskId
 }
@@ -26,7 +30,12 @@ export function BashTaskId(id: string): BashTaskId {
  */
 export type OwnerToken = Branded<'OwnerToken'>
 
-/** Brand a string as an {@link OwnerToken}. */
+/**
+ * Brand a string as an {@link OwnerToken}. Only the consuming boundary
+ * (`dsh-tool-bash`) should cast its own id vocabulary in — see the type's doc.
+ * @param id - the consumer's raw owner identity (the tool layer passes the owning agent's session id).
+ * @returns the same string, branded; no validation is performed.
+ */
 export function OwnerToken(id: string): OwnerToken {
   return id as OwnerToken
 }
diff --git a/packages/bash/tool-bash/src/index.ts b/packages/bash/tool-bash/src/index.ts
index 478ed70ca5..d4a3105165 100644
--- a/packages/bash/tool-bash/src/index.ts
+++ b/packages/bash/tool-bash/src/index.ts
@@ -99,6 +99,8 @@ function streamText(output: CollectedOutput): string {
  * stderr section, then exit-status markers. Non-zero exits are REPORTED, not
  * errored — the model decides how to react; only infrastructure failures
  * (spawn errors, aborts) surface as isError results.
+ * @param result - the completed foreground run from the executor.
+ * @returns the model-facing text: output body (or `(no output)`), then any timeout/signal/exit markers, each on its own line.
  */
 export function renderResult(result: BashRunResult): string {
   const out = streamText(result.stdout)
diff --git a/packages/compact/compact-basic/src/index.ts b/packages/compact/compact-basic/src/index.ts
index 01fcadbaea..03f7c9ab4b 100644
--- a/packages/compact/compact-basic/src/index.ts
+++ b/packages/compact/compact-basic/src/index.ts
@@ -216,6 +216,11 @@ export class BasicCompactService extends CompactService {
    * Estimate the token count of content blocks — chars divided by the
    * `charsPerToken` config, with per-block overhead. Override in a subclass to
    * plug in a real tokenizer.
+   *
+   * @param blocks - the blocks to estimate; `tool-result` blocks recurse into
+   *   their nested content, and unknown (merge-extended) types fall back to
+   *   their JSON-stringified length.
+   * @returns the estimated token count.
    */
   estimateContentTokens(blocks: readonly ContentBlock[]): number {
     const { charsPerToken } = this.config
@@ -246,6 +251,11 @@ export class BasicCompactService extends CompactService {
   /**
    * Estimate token count for a single session event. Returns 0 for non-message
    * event types (boundaries, chunks, usage, errors, compact markers).
+   *
+   * @param event - any session event; only the message-bearing types carry
+   *   content to count.
+   * @returns the estimated token count of the event's content, or 0 for a
+   *   non-message event.
    */
   estimateEventTokens(event: SessionEvent): number {
     switch (event.type) {
@@ -260,7 +270,14 @@ export class BasicCompactService extends CompactService {
     }
   }
 
-  /** Estimate total tokens across a list of messages plus optional system prompt. */
+  /**
+   * Estimate total tokens across a list of messages plus optional system prompt.
+   *
+   * @param messages - the derived conversation messages; each adds a fixed
+   *   role-framing overhead on top of its content estimate.
+   * @param systemPrompt - counted at chars / `charsPerToken` when provided.
+   * @returns the estimated token footprint of the whole request.
+   */
   estimateTokens(messages: readonly Message[], systemPrompt?: string): number {
     let total = 0
     for (const msg of messages) {
@@ -293,6 +310,13 @@ export class BasicCompactService extends CompactService {
    * used (`model`, `maxTokens`) — the caller logs the envelope on the
    * `compact/summary` provenance event, so an overriding subclass (template
    * or remote summarizer) reports its own envelope honestly.
+   *
+   * @param text - plain-text rendering of the conversation region to condense.
+   * @param agent - supplies the fallback model and the session id stamped on
+   *   the call; throws when neither it nor the config names a model.
+   * @param signal - optional abort signal, forwarded into the model call.
+   * @returns the text-only summary blocks plus the call envelope used
+   *   (`model`, and `maxTokens` when the summarizer has a cap).
    */
   async summarize(
     text: string, agent: Agent, signal?: AbortSignal,
diff --git a/packages/compact/compact-basic/src/types.ts b/packages/compact/compact-basic/src/types.ts
index 2f10084ac3..a590c01431 100644
--- a/packages/compact/compact-basic/src/types.ts
+++ b/packages/compact/compact-basic/src/types.ts
@@ -54,6 +54,9 @@ export type ResolvedConfig = Required<BasicCompactConfig>
  * each committed summary must be smaller than the content it shadows, and
  * `compactIfNeeded` may re-compact up to `compactionRetries` extra times before
  * throwing if the surface still exceeds the threshold.
+ *
+ * @param config - the raw, unresolved backend config.
+ * @returns the validated config with `auto` and `charsPerToken` defaulted.
  */
 export function resolveConfig(config: BasicCompactConfig): ResolvedConfig {
   const resolved: ResolvedConfig = { auto: true, charsPerToken: 4, ...config }
diff --git a/packages/core/agent-loop/src/agent.ts b/packages/core/agent-loop/src/agent.ts
index 433c28326b..49de0f77c4 100644
--- a/packages/core/agent-loop/src/agent.ts
+++ b/packages/core/agent-loop/src/agent.ts
@@ -22,6 +22,10 @@ import { isTurnOpen, lastTurnNumber, runLoop } from './loop.ts'
  * the agent/* event taxonomy — plugins never need this class.
  */
 export class ReactLoopAgent implements Agent {
+  /**
+   * The queued + steering FIFOs behind {@link send}/{@link steer}. Public so
+   * the driver loop can drain it; {@link cancel} clears it wholesale.
+   */
   readonly inbox = new Inbox()
 
   private _status: AgentStatus = 'idle'
@@ -256,6 +260,8 @@ export class ReactLoopAgent implements Agent {
    * promise (unblocking the idle wait), releases any `whenIdle` waiters, and
    * aborts the current request if any. The returned `agent.done` promise
    * resolves once the loop exits.
+   * @returns the disposer — idempotent and infallible (it runs inside the
+   *   fiber's LIFO disposal chain, where a throw would skip later disposers).
    */
   start(): () => void {
     this.done = runLoop(this.ctx, this, {
diff --git a/packages/core/agent-loop/src/inbox.ts b/packages/core/agent-loop/src/inbox.ts
index a7b2e64e2c..abb588b919 100644
--- a/packages/core/agent-loop/src/inbox.ts
+++ b/packages/core/agent-loop/src/inbox.ts
@@ -24,30 +24,47 @@ export class Inbox {
   private steeringMessages: InboxMessage[] = []
   private wakeup: (() => void) | undefined
 
-  /** Resolves when a queued message arrives (used by the idle loop). */
+  /** True while queued messages are pending — read by the idle wait's fast path and the loop's turn-start checks. */
   get hasQueued(): boolean {
     return this.queuedMessages.length > 0
   }
 
+  /** True while steering messages are pending — read by `cancel()`'s arm gate and the loop's stop-override check. */
   get hasSteering(): boolean {
     return this.steeringMessages.length > 0
   }
 
+  /**
+   * Add a message to the queued FIFO and wake a parked {@link waitForQueued}.
+   * @param message - the message to queue for the next turn start.
+   */
   enqueue(message: InboxMessage): void {
     this.queuedMessages.push(message)
     this.wakeup?.()
   }
 
+  /**
+   * Add a message to the steering FIFO. Deliberately no wakeup: steering is
+   * drained between steps of a running turn, never by the idle wait —
+   * `Agent.steer()` on an idle agent falls back to `send()` instead.
+   * @param message - the message to inject between steps of the running turn.
+   */
   steer(message: InboxMessage): void {
     this.steeringMessages.push(message)
   }
 
-  /** Drain all queued messages (turn start). */
+  /**
+   * Drain all queued messages (turn start).
+   * @returns the drained messages in arrival order; the queued FIFO is left empty.
+   */
   drainQueued(): InboxMessage[] {
     return this.queuedMessages.splice(0)
   }
 
-  /** Drain all steering messages (between steps). */
+  /**
+   * Drain all steering messages (between steps).
+   * @returns the drained messages in arrival order; the steering FIFO is left empty.
+   */
   drainSteering(): InboxMessage[] {
     return this.steeringMessages.splice(0)
   }
@@ -62,7 +79,12 @@ export class Inbox {
     this.steeringMessages.length = 0
   }
 
-  /** Wait until a queued message arrives or `cancel` resolves. */
+  /**
+   * Wait until a queued message arrives or `cancel` resolves.
+   * @param cancel - a promise whose resolution abandons the wait without a
+   *   message (the driver loop passes the agent's disposed promise so a parked
+   *   loop can exit).
+   */
   waitForQueued(cancel: Promise<void>): Promise<void> {
     if (this.hasQueued) return Promise.resolve()
     const { promise, resolve } = Promise.withResolvers<void>()
diff --git a/packages/core/agent-loop/src/index.ts b/packages/core/agent-loop/src/index.ts
index 9eaa61624a..55620650c1 100644
--- a/packages/core/agent-loop/src/index.ts
+++ b/packages/core/agent-loop/src/index.ts
@@ -29,6 +29,10 @@ declare module 'cordis' {
   }
 }
 
+/**
+ * Plugin config: the agents to create — or resume, via `resumeSessionId` —
+ * declaratively at startup, so a cordis.yml deployment needs no code.
+ */
 export interface Config {
   /** Agents created from configuration at startup. */
   agents: (AgentOptions & {
diff --git a/packages/core/agent-loop/src/loop.ts b/packages/core/agent-loop/src/loop.ts
index 9484f0ad5f..eb5b07ba23 100644
--- a/packages/core/agent-loop/src/loop.ts
+++ b/packages/core/agent-loop/src/loop.ts
@@ -185,6 +185,9 @@ export interface LoopHandle {
  *     re-enqueue leftover steering as queued          ⟵ steering is never stranded
  *   idle (emit agent/status) unless more queued
  * ```
+ * @param ctx - the plugin context the loop reaches events (agent/…, session/flush) and services (systemPrompt, llm, tools) through.
+ * @param agent - the agent this invocation drives for its whole lifetime (its inbox, session, and options).
+ * @param handle - the bridge to the agent's mutable state: status/abort setters plus the disposal and cancel-marker reads.
  */
 export async function runLoop(ctx: Context, agent: ReactLoopAgent, handle: LoopHandle): Promise<void> {
   // Per-instance transmission bookkeeping: whether THIS loop instance has
@@ -875,7 +878,11 @@ function withoutToolCalls(message: Message): Message {
   return { ...message, content: message.content.filter(block => block.type !== 'tool-call') }
 }
 
-/** The last turn number in a (possibly seeded) session log, or 0. */
+/**
+ * The last turn number in a (possibly seeded) session log, or 0.
+ * @param session - the session whose log is scanned for the latest `turn/start`.
+ * @returns the latest `turn/start`'s turn number, or 0 when the log has none (the next turn is this plus one).
+ */
 export function lastTurnNumber(session: Session): number {
   const lastStart = session.events.findLast(event => event.type === 'turn/start')
   return lastStart?.data.turn ?? 0
@@ -889,6 +896,8 @@ export function lastTurnNumber(session: Session): number {
  * returns to idle), so status is not a reliable open-turn signal. Used by
  * `inject()` to choose between appending into an open turn vs. wrapping the
  * injection in its own one-shot turn (the turn-enclosure RFC).
+ * @param session - the session whose log is inspected.
+ * @returns true when the log's last turn boundary is a `turn/start` with no matching `turn/end` yet.
  */
 export function isTurnOpen(session: Session): boolean {
   const last = session.events.findLast(e => e.type === 'turn/start' || e.type === 'turn/end')
diff --git a/packages/core/agent-loop/src/request-log.ts b/packages/core/agent-loop/src/request-log.ts
index 07c57b9ff9..90f47068fa 100644
--- a/packages/core/agent-loop/src/request-log.ts
+++ b/packages/core/agent-loop/src/request-log.ts
@@ -19,7 +19,10 @@ export interface TransmissionLog {
   loggedHeader: boolean
 }
 
-/** Fresh bookkeeping for a newly-started loop instance. */
+/**
+ * Fresh bookkeeping for a newly-started loop instance.
+ * @returns state with `loggedHeader` false, so the instance's first request appends an anchoring snapshot.
+ */
 export function createTransmissionLog(): TransmissionLog {
   return { loggedHeader: false }
 }
diff --git a/packages/core/agent/src/types.ts b/packages/core/agent/src/types.ts
index 1fd6a57867..46bc52128a 100644
--- a/packages/core/agent/src/types.ts
+++ b/packages/core/agent/src/types.ts
@@ -50,7 +50,11 @@ import type {} from '@deepseek-ai/dsh-system-prompt'
 /** Identifies one live agent in the registry. */
 export type AgentId = Branded<'AgentId'>
 
-/** Brand a string as an {@link AgentId}. */
+/**
+ * Brand a string as an {@link AgentId}.
+ * @param id - the raw agent id string.
+ * @returns the same string, branded (a compile-time cast — no runtime cost).
+ */
 export function AgentId(id: string): AgentId {
   return id as AgentId
 }
@@ -80,10 +84,22 @@ export interface AgentOptions {
   model?: string
 }
 
+/**
+ * Options for {@link Agent.send}/{@link Agent.steer}/{@link Agent.inject}. An
+ * absent `source` resolves to `{ kind: 'user' }`, so a plugin supplying content
+ * must label itself here or its message is recorded as a user prompt (see
+ * {@link HookContext} on why that label is load-bearing).
+ */
 export interface SendOptions {
   source?: MessageSource
 }
 
+/**
+ * An agent's lifecycle state, emitted on every transition as `agent/status`:
+ * `idle` (parked, waiting for queued work), `running` (a turn is in progress),
+ * `disposed` (terminal — no transition leaves it, and `send`/`steer`/`inject`
+ * throw).
+ */
 export type AgentStatus = 'idle' | 'running' | 'disposed'
 
 /**
diff --git a/packages/core/agent/tests/verify-export-jsdoc.spec.ts b/packages/core/agent/tests/verify-export-jsdoc.spec.ts
new file mode 100644
index 0000000000..89439a3a59
--- /dev/null
+++ b/packages/core/agent/tests/verify-export-jsdoc.spec.ts
@@ -0,0 +1,296 @@
+/**
+ * Negative-path tests for the export-surface JSDoc gate
+ * (`scripts/verify-export-jsdoc.ts`).
+ *
+ * The gate's positive half runs against the real tree in CI (`pnpm run
+ * verify-export-jsdoc`, part of doc-sync). What that run cannot prove is that
+ * the walk REJECTS an undocumented surface the way it promises to — and that
+ * every deliberate exemption (heritage members, plugin-protocol slots,
+ * constructors, overload implementations, augmentation bodies, re-exports)
+ * actually holds. These tests drive `collectExportJsdocViolations()` against
+ * synthetic fixture packages, mirroring the gen-cordis-catalog negative
+ * tests.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { collectExportJsdocViolations } from '../../../../scripts/verify-export-jsdoc.ts'
+
+const roots: string[] = []
+
+afterEach(() => {
+  while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+/** Write fixture files under `packages/group/fix/src/` and return the scan root. */
+function fixture(files: Record<string, string>): string {
+  const root = mkdtempSync(join(tmpdir(), 'export-jsdoc-'))
+  roots.push(root)
+  for (const [rel, content] of Object.entries(files)) {
+    const abs = join(root, 'packages', 'group', 'fix', 'src', rel)
+    mkdirSync(dirname(abs), { recursive: true })
+    writeFileSync(abs, content)
+  }
+  return root
+}
+
+/** Single-file fixture shorthand: the content becomes `src/index.ts`. */
+const make = (content: string): string => fixture({ 'index.ts': content })
+
+describe('verify-export-jsdoc functions and consts', () => {
+  it('accepts a fully documented surface', () => {
+    expect(collectExportJsdocViolations(make(`
+/**
+ * Add one to a count.
+ * @param n - the count to bump.
+ * @returns the count plus one.
+ */
+export function bump(n: number): number { return n + 1 }
+
+/**
+ * Fire-and-forget (void needs no @returns).
+ * @param flag - whether to arm.
+ */
+export function poke(flag: boolean): void { void flag }
+
+/** The default retry budget. */
+export const RETRIES = 3
+
+/**
+ * Halve a count.
+ * @param n - the count to halve.
+ * @returns the count halved.
+ */
+export const halve = (n: number): number => n / 2
+`))).toEqual([])
+  })
+
+  it('flags an exported function with no JSDoc at all', () => {
+    expect(collectExportJsdocViolations(make(
+      'export function bare(): void {}\n',
+    ))).toEqual([expect.stringMatching(/exported function 'bare' .* has no JSDoc\./)])
+  })
+
+  it('flags a missing @param and a missing @returns', () => {
+    const violations = collectExportJsdocViolations(make(
+      '/** Docs without tags. */\nexport function f(x: number): number { return x }\n',
+    ))
+    expect(violations).toEqual([
+      expect.stringMatching(/exported function 'f' .* is missing @param x\./),
+      expect.stringMatching(/exported function 'f' .* is missing @returns \(return type: number\)\./),
+    ])
+  })
+
+  it('flags an unannotated (inferred) return type', () => {
+    expect(collectExportJsdocViolations(make(
+      '/**\n * Docs.\n * @param x - value.\n */\nexport function f(x: number) { return x }\n',
+    ))).toEqual([expect.stringMatching(/no return type annotation/)])
+  })
+
+  it('flags tags-only JSDoc with no description prose', () => {
+    expect(collectExportJsdocViolations(make(
+      '/**\n * @param x - value.\n */\nexport function f(x: number): void {}\n',
+    ))).toEqual([expect.stringMatching(/no description prose above its block tags/)])
+  })
+
+  it('flags a stale @param and a binding-pattern parameter', () => {
+    const violations = collectExportJsdocViolations(make(
+      '/**\n * Docs.\n * @param ghost - not real.\n */\nexport function f({ a }: { a: number }): void {}\n',
+    ))
+    expect(violations).toEqual([
+      expect.stringMatching(/parameter '\{ a \}' is a binding pattern; the export surface needs simple identifier parameters/),
+      expect.stringMatching(/@param ghost does not match any parameter \(stale tag\?\)/),
+    ])
+  })
+
+  it('exempts a `this` receiver annotation from @param', () => {
+    expect(collectExportJsdocViolations(make(
+      '/**\n * Docs.\n * @param x - value.\n */\nexport function f(this: object, x: number): void {}\n',
+    ))).toEqual([])
+  })
+
+  it('waives @returns for a declarator-annotated const but not an unannotated one', () => {
+    expect(collectExportJsdocViolations(make(`
+type Fn = (x: number) => number
+/**
+ * Uses the named signature.
+ * @param x - value.
+ */
+export const good: Fn = x => x
+/**
+ * No signature anywhere.
+ * @param x - value.
+ */
+export const bad = (x: number) => x
+`))).toEqual([expect.stringMatching(/exported const 'bad' .* has no return type annotation/)])
+  })
+
+  it('requires description prose on a non-function const', () => {
+    expect(collectExportJsdocViolations(make(
+      'export const LIMIT = 10\n',
+    ))).toEqual([expect.stringMatching(/exported const 'LIMIT' .* has no JSDoc\./)])
+  })
+})
+
+describe('verify-export-jsdoc type-level exports', () => {
+  it('requires description prose on interfaces, type aliases, and enums', () => {
+    const violations = collectExportJsdocViolations(make(
+      'export interface I { a: number }\nexport type T = number\nexport enum E { A }\n',
+    ))
+    expect(violations).toEqual([
+      expect.stringMatching(/exported interface 'I' .* has no JSDoc\./),
+      expect.stringMatching(/exported type 'T' .* has no JSDoc\./),
+      expect.stringMatching(/exported enum 'E' .* has no JSDoc\./),
+    ])
+  })
+
+  it('skips `declare module` augmentation bodies (the cordis gate owns them)', () => {
+    expect(collectExportJsdocViolations(make(
+      "declare module 'cordis' {\n  interface Events {\n    'fix/x'(): void\n  }\n}\nexport {}\n",
+    ))).toEqual([])
+  })
+})
+
+describe('verify-export-jsdoc export forms', () => {
+  it('resolves an `export { … }` list to the local declaration', () => {
+    expect(collectExportJsdocViolations(make(
+      'function f(): void {}\nexport { f }\n',
+    ))).toEqual([expect.stringMatching(/exported function 'f' .* has no JSDoc\./)])
+  })
+
+  it('reports a re-exported module once, at its defining file', () => {
+    const violations = collectExportJsdocViolations(fixture({
+      'index.ts': "export * from './other.ts'\n",
+      'other.ts': 'export function f(): void {}\n',
+    }))
+    expect(violations).toEqual([expect.stringMatching(/other\.ts:1\) has no JSDoc\./)])
+  })
+
+  it('exempts overload implementations when the signatures are documented', () => {
+    expect(collectExportJsdocViolations(make(`
+/**
+ * From a number.
+ * @param x - the number.
+ * @returns its text.
+ */
+export function f(x: number): string
+/**
+ * From a flag.
+ * @param x - the flag.
+ * @returns its text.
+ */
+export function f(x: boolean): string
+export function f(x: number | boolean): string { return String(x) }
+`))).toEqual([])
+  })
+})
+
+describe('verify-export-jsdoc classes', () => {
+  it('flags an undocumented class, method, property, and accessor', () => {
+    const violations = collectExportJsdocViolations(make(`
+export class C {
+  state = 1
+  get view(): number { return this.state }
+  run(x: number): number { return x }
+}
+`))
+    expect(violations).toEqual([
+      expect.stringMatching(/exported class 'C' .* has no JSDoc\./),
+      expect.stringMatching(/exported class property 'C.state' .* has no JSDoc\./),
+      expect.stringMatching(/exported class accessor 'C.view' .* has no JSDoc\./),
+      expect.stringMatching(/exported class method 'C.run' .* has no JSDoc\./),
+    ])
+  })
+
+  it('exempts members declared by an extends/implements heritage type', () => {
+    expect(collectExportJsdocViolations(make(`
+/** Seam. */
+export abstract class Base {
+  /**
+   * Do it.
+   * @param x - input.
+   * @returns output.
+   */
+  abstract run(x: number): number
+}
+/** Iface. */
+export interface Sized {
+  /** Byte size. */
+  size: number
+}
+/** Impl. */
+export class Impl extends Base implements Sized {
+  size = 0
+  run(x: number): number { return x }
+}
+`))).toEqual([])
+  })
+
+  it('skips private/protected/#private members and constructors', () => {
+    expect(collectExportJsdocViolations(make(`
+/** Documented. */
+export class C {
+  #secret = 1
+  private hidden(): void {}
+  protected hook(): void {}
+  constructor(x: number) { void x }
+}
+`))).toEqual([])
+  })
+
+  it('exempts plugin-protocol statics but checks other statics', () => {
+    const violations = collectExportJsdocViolations(make(`
+/** Plugin. */
+export class C {
+  static Config = { a: 1 }
+  static inject = ['bash']
+  static reusable = true
+  static other = 1
+}
+`))
+    expect(violations).toEqual([expect.stringMatching(/exported class property 'C.other' .* has no JSDoc\./)])
+  })
+
+  it("covers a set accessor by the getter's doc", () => {
+    expect(collectExportJsdocViolations(make(`
+/** Documented. */
+export class C {
+  /** The current width. */
+  get width(): number { return 1 }
+  set width(_v: number) {}
+}
+`))).toEqual([])
+  })
+})
+
+describe('verify-export-jsdoc plugin protocol and namespaces', () => {
+  it('exempts top-level plugin-protocol exports', () => {
+    expect(collectExportJsdocViolations(make(`
+export const name = 'fix'
+export const inject = ['bash']
+export const reusable = true
+export const Config = { parse: true }
+export function apply(): void {}
+`))).toEqual([])
+  })
+
+  it('recurses into namespaces with qualified names and honors the merge idiom', () => {
+    const violations = collectExportJsdocViolations(make(`
+/** The plugin class. */
+export class Fix {}
+export namespace Fix {
+  export interface Config { a: number }
+}
+export namespace Loose {
+  export const x = 1
+}
+`))
+    expect(violations).toEqual([
+      expect.stringMatching(/exported interface 'Fix.Config' .* has no JSDoc\./),
+      expect.stringMatching(/exported namespace 'Loose' .* has no JSDoc\./),
+      expect.stringMatching(/exported const 'Loose.x' .* has no JSDoc\./),
+    ])
+  })
+})
diff --git a/packages/core/session/src/index.ts b/packages/core/session/src/index.ts
index 18c7b4a8a2..79a1c10a1c 100644
--- a/packages/core/session/src/index.ts
+++ b/packages/core/session/src/index.ts
@@ -153,10 +153,15 @@ export class Session {
     this.header = header ?? { version: SESSION_FORMAT_VERSION, id, createdAt: Date.now() }
   }
 
+  /**
+   * The append-only event log, exposed live by reference (readonly-typed, not
+   * a snapshot): later appends are visible through the same array.
+   */
   get events(): readonly SessionEvent[] {
     return this.log
   }
 
+  /** The next event's sequence number — always the log length (the `seq = log.length` contiguity contract). */
   get seq(): number {
     return this.log.length
   }
@@ -175,6 +180,9 @@ export class Session {
    *   declare how it joins the surface, the sole source of derived history) and
    *   rejected by the compiler for non-surface types like `turn/start` or
    *   `assistant/chunk`.
+   * @returns the logged event — its assigned `seq`/`time` plus the SNAPSHOT of
+   *   `data` that entered the log, so reading `event.data` back sees the logged
+   *   value, never the caller's still-mutable input.
    * @throws if `data` is not losslessly JSON-serializable (BigInt, function,
    *   symbol, undefined, non-finite number, circular ref, or an exotic object
    *   like Map/Set/Date). The event log is the durable source of truth, so this
diff --git a/packages/core/session/src/json.ts b/packages/core/session/src/json.ts
index 47197b7b90..22303c6c61 100644
--- a/packages/core/session/src/json.ts
+++ b/packages/core/session/src/json.ts
@@ -40,6 +40,10 @@ export type JsonValue = null | boolean | number | string | JsonValue[] | { [key:
  * hiding under a symbol/non-enumerable key cannot make the round-trip lossy.
  * Getters are invoked during the check (again as `JSON.stringify` would), so the
  * contract is for plain data records, not objects with side-effecting accessors.
+ * @param value - the candidate event data to test.
+ * @param seen - objects on the current descent path, for circular-reference
+ *   detection; the recursion threads it — callers omit it.
+ * @returns true when `value` survives a JSON round-trip losslessly.
  */
 export function isJsonValue(value: unknown, seen: Set<object> = new Set()): boolean {
   if (value === null) return true
diff --git a/packages/core/session/src/repair.ts b/packages/core/session/src/repair.ts
index b894ef26cb..cb780da013 100644
--- a/packages/core/session/src/repair.ts
+++ b/packages/core/session/src/repair.ts
@@ -54,6 +54,8 @@ import type { SessionEvent } from './types.ts'
  * Only the LAST turn can be open: the invariants plugin guarantees a `turn/end`
  * before any later `turn/start`, so an interior open turn is impossible in a
  * valid committed log. Likewise at most one step is open within that turn.
+ * @param events - the loaded durable log to scan (a valid committed prefix, possibly with a crash tail).
+ * @returns the synthetic closer events to append after `events`, in order; empty when the log is already balanced.
  */
 export function interruptedTurnClosers(events: readonly SessionEvent[]): SessionEvent[] {
   let openTurn: number | null = null
diff --git a/packages/core/session/src/surface.ts b/packages/core/session/src/surface.ts
index 37843970a2..7219856bdb 100644
--- a/packages/core/session/src/surface.ts
+++ b/packages/core/session/src/surface.ts
@@ -29,6 +29,8 @@ const SURFACE_EVENT_TYPES = new Set<string>([
  * surface-eligible event that is MISSING its mandatory marker (e.g. validating
  * a seed/load log); use {@link isSurfaceEvent} to narrow to a fully-formed
  * {@link SurfaceEvent} with `surfaceOp` present.
+ * @param type - the event type string to test.
+ * @returns true when the type is one of the five message-producing types.
  */
 export function isSurfaceEligibleType(type: string): boolean {
   return SURFACE_EVENT_TYPES.has(type)
@@ -38,6 +40,8 @@ export function isSurfaceEligibleType(type: string): boolean {
  * Narrow a {@link SessionEvent} to {@link SurfaceEvent}: checks that the
  * event's `type` is surface-eligible AND that `surfaceOp` is present.
  * The narrowed type has mandatory {@link SurfaceOp}.
+ * @param event - the event to narrow.
+ * @returns true when the event is surface-eligible and carries its `surfaceOp` marker.
  */
 export function isSurfaceEvent(event: SessionEvent): event is SurfaceEvent {
   if (!SURFACE_EVENT_TYPES.has(event.type)) return false
diff --git a/packages/core/session/src/tool-pairing.ts b/packages/core/session/src/tool-pairing.ts
index 638daaf654..6ea3042bd7 100644
--- a/packages/core/session/src/tool-pairing.ts
+++ b/packages/core/session/src/tool-pairing.ts
@@ -74,6 +74,12 @@ function nodeDelta(event: SessionEvent): number {
  * surface successor (`SurfaceNode.next`), or `null` when `end` is the tail —
  * for the cut after `end`.
  *
+ * @param nodes - the surface linked list in head→tail order.
+ * @param events - the session log each node's `seq` indexes into.
+ * @param beforeSeq - names the cut (the node it sits immediately before);
+ *   `null` — or any seq not on the surface — means the after-tail cut.
+ * @returns true when every `tool-call` before the cut is answered before it
+ *   (the unanswered-call depth at the cut is zero).
  * @throws if the surface prefix drives the unanswered-call depth negative — a
  *   `tool/result` with no preceding open `tool-call` on the surface. That is a
  *   corrupt surface (a structural invariant violation), surfaced loudly here
diff --git a/packages/core/session/src/types.ts b/packages/core/session/src/types.ts
index ec227e9884..e2e0e1b216 100644
--- a/packages/core/session/src/types.ts
+++ b/packages/core/session/src/types.ts
@@ -4,7 +4,11 @@ import type { CallId, ContentBlock, LlmCallConfig, MessageSource, StreamChunk, T
 /** Identifies one session in the store (and its persistence artifacts). */
 export type SessionId = Branded<'SessionId'>
 
-/** Brand a string as a {@link SessionId}. */
+/**
+ * Brand a string as a {@link SessionId}.
+ * @param id - the raw session id string.
+ * @returns the same string, branded (a compile-time cast — no runtime cost).
+ */
 export function SessionId(id: string): SessionId {
   return id as SessionId
 }
@@ -102,6 +106,7 @@ export interface TurnTriggerMap {
   injection: { kind: 'injection'; source: MessageSource }
 }
 
+/** The union over {@link TurnTriggerMap} — what started a turn; plugins extend it by merging variants into the map. */
 export type TurnTrigger = TurnTriggerMap[keyof TurnTriggerMap]
 
 /**
@@ -156,6 +161,7 @@ export interface TurnEndReasonMap {
   interrupted: { kind: 'interrupted' }
 }
 
+/** The union over {@link TurnEndReasonMap} — why a turn ended; plugins extend it by merging variants into the map. */
 export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap]
 
 /**
@@ -361,6 +367,7 @@ export interface SessionEventMap {
   'request/header-delta': { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig }
 }
 
+/** The appendable event-type keys of {@link SessionEventMap}, plugin-merged extensions included. */
 export type SessionEventType = keyof SessionEventMap
 
 /**
diff --git a/packages/core/system-prompt/src/index.ts b/packages/core/system-prompt/src/index.ts
index c970c66b30..049b9c3b99 100644
--- a/packages/core/system-prompt/src/index.ts
+++ b/packages/core/system-prompt/src/index.ts
@@ -110,6 +110,7 @@ const VARIABLE_NAME = /^[a-z][a-z0-9_]*$/
 /** A complete `{{...}}` reference group at the scan position (validated after). */
 const GROUP_AT = /^\{\{([^{}]*)\}\}/
 
+/** Plugin config: the deployment-authored fragment of the system prompt (see {@link Config.persona} for its contract). */
 export interface Config {
   /**
    * The deployment's persona — the ONE deployment-authored fragment of the
@@ -138,6 +139,10 @@ export interface Config {
  * while a `}}` still follows (e.g. `{{{model}}}`, `{{a{b}}`) all throw. A
  * lone `{{` with no `}}` anywhere after it is ordinary prose and passes
  * through verbatim. Substituted values are never re-scanned.
+ * @param assembly - the assembly to render (typically the awaited result of
+ *   {@link SystemPrompt.assemble}); only `sections` and `variables` are read.
+ * @returns the full system prompt text; `''` when every section renders empty
+ *   (the caller then sends no system prompt at all).
  */
 export function renderPrompt(assembly: PromptAssembly): string {
   return assembly.sections
diff --git a/packages/core/tools/src/schema.ts b/packages/core/tools/src/schema.ts
index 9149241225..16eff5c324 100644
--- a/packages/core/tools/src/schema.ts
+++ b/packages/core/tools/src/schema.ts
@@ -155,6 +155,9 @@ export interface JsonSchemaObject {
  * `properties`, `required` array).
  *
  * This is a plain function — no schemastery or other framework dependency.
+ * @param spec - the author-facing per-property schema to convert.
+ * @returns the wire-format JSON Schema; the top-level `required` array is
+ *   omitted entirely when no property is marked required.
  */
 export function schemaSpecToJsonSchema(spec: SchemaSpec): JsonSchemaObject {
   const properties: Record<string, unknown> = {}
@@ -269,6 +272,9 @@ function checkSpec(spec: SchemaSpec, value: unknown, path: string): string[] {
  * keys are allowed (no `additionalProperties: false`); `default` is not
  * applied; an `object`/`array` prop without `properties`/`items` only
  * type-checks; `enum` is membership (strings only).
+ * @param spec - the declared parameter schema to validate against.
+ * @param args - the model-generated arguments, however malformed.
+ * @returns the violation messages in declaration order; empty means valid.
  */
 export function validateArgs(spec: SchemaSpec, args: unknown): string[] {
   return checkSpec(spec, args, '')
@@ -340,6 +346,13 @@ export interface DefineToolOptions<S extends SchemaSpec> {
  * Raw JSON-Schema tool definitions (from MCP servers) are still accepted
  * by `ToolRegistry.register()` directly — `defineTool` is sugar for
  * first-party plugin authors.
+ * @param options - the tool's name, description, typed parameter schema,
+ *   execute body, and optional presenters.
+ * @returns a registry-ready {@link ToolDefinition}: its `execute` validates the
+ *   raw args first (throwing {@link ToolArgsError} on mismatch, which the
+ *   registry turns into an isError result), and its presenters validate softly
+ *   (returning undefined on mismatch, since replay may feed them older-schema
+ *   args).
  */
 export function defineTool<S extends SchemaSpec>(options: DefineToolOptions<S>): ToolDefinition {
   // Object-literal execute methods don't use `this`; the reference is safe.
diff --git a/packages/fs/fs-local/src/fsio.ts b/packages/fs/fs-local/src/fsio.ts
index b1b9c25397..f9af5375d2 100644
--- a/packages/fs/fs-local/src/fsio.ts
+++ b/packages/fs/fs-local/src/fsio.ts
@@ -129,6 +129,9 @@ export interface LocalDirEntry {
  * and intermediate directories are created by the write. Two input paths
  * reaching the same file via symlinks share one key. Falls back to the absolute
  * path only when no ancestor (not even the filesystem root) can be resolved.
+ * @param cwd - base directory a relative `path` resolves against.
+ * @param path - absolute or relative path; empty/whitespace-only throws `FS_NOT_FOUND`.
+ * @returns the absolute display path plus the realpath-derived stable target key.
  */
 export async function resolveLocalTarget(cwd: string, path: string): Promise<LocalTarget> {
   if (path.trim().length === 0) throw new FsError('file_path must be a non-empty string', 'FS_NOT_FOUND')
@@ -165,7 +168,11 @@ export async function resolveLocalTarget(cwd: string, path: string): Promise<Loc
   }
 }
 
-/** Probe a path for its version, mode, type, and size. Null if absent. */
+/**
+ * Probe a path for its version, mode, type, and size. Null if absent.
+ * @param absolutePath - the path to stat (typically a target key; symlinks are followed).
+ * @returns the metadata, or null when the path — or a parent segment — does not exist.
+ */
 export async function probe(absolutePath: string): Promise<PathInfo | null> {
   try {
     const info = await stat(absolutePath)
@@ -200,6 +207,9 @@ async function resolveListedChildTarget(parent: LocalTarget, name: string): Prom
  * List direct children of a directory in stable name order. Each child includes
  * a resolved target plus stat metadata when still available; file contents are
  * never read.
+ * @param target - the resolved directory to list; a missing or non-directory target throws.
+ * @param signal - aborts the listing, checked between children (`FS_ABORTED`).
+ * @returns one entry per direct child, sorted by name.
  */
 export async function listDirectory(target: LocalTarget, signal?: AbortSignal): Promise<LocalDirEntry[]> {
   throwIfAborted(signal, 'list')
@@ -290,6 +300,9 @@ async function statRegularFile(target: LocalTarget, verb: 'read', signal?: Abort
 /**
  * Read a whole regular UTF-8 text file into a single decoded string. Rejects
  * non-regular files, invalid UTF-8, and NUL-byte binary samples.
+ * @param target - the resolved file to read.
+ * @param signal - aborts the read (`FS_ABORTED`).
+ * @returns the full decoded text, byte-for-byte (no normalization).
  */
 export async function readWholeText(target: LocalTarget, signal?: AbortSignal): Promise<string> {
   await statRegularFile(target, 'read', signal)
@@ -305,6 +318,9 @@ export async function readWholeText(target: LocalTarget, signal?: AbortSignal):
  * Stream a whole regular UTF-8 text file as decoded text chunks. Same text
  * semantics as {@link readWholeText} (regular-file check, binary/NUL rejection,
  * cross-chunk UTF-8 decoding), but never holds the whole file in memory.
+ * @param target - the resolved file to stream.
+ * @param signal - aborts the stream, including between chunks (`FS_ABORTED`).
+ * @returns decoded text chunks in file order; chunk boundaries carry no meaning.
  */
 export async function* streamWholeText(target: LocalTarget, signal?: AbortSignal): AsyncIterable<string> {
   await statRegularFile(target, 'read', signal)
@@ -352,6 +368,11 @@ async function removeStagingDirOrThrow(stagingDir: string, originalError: unknow
  * (`0o700`) staging directory, fsync, optionally chmod to the final mode while
  * still private, then rename over the target. `mode` (when given) preserves an
  * existing file's permissions across the replace.
+ * @param absolutePath - the final destination (typically a target key); missing parent dirs are created.
+ * @param content - the full UTF-8 text to write.
+ * @param mode - final file mode applied before the rename (an existing file's, to preserve permissions); undefined leaves `0o600`.
+ * @param signal - aborts the write (`FS_ABORTED`); checked before the rename, so the target is never left torn.
+ * @param internals - test seam for pinning temp names and observing the staged file.
  */
 export async function writeFileAtomic(
   absolutePath: string,
@@ -409,6 +430,12 @@ export async function writeFileAtomic(
 /** Line ending style detected before LF normalization. */
 export type LineEndings = 'LF' | 'CRLF'
 
+/**
+ * Collapse CRLF to LF — the canonical in-memory form every edit/diff basis
+ * uses. Lone `\r` bytes (not followed by `\n`) are left untouched.
+ * @param content - decoded text in whatever line-ending style the file had.
+ * @returns the text with every `\r\n` pair replaced by `\n`.
+ */
 function normalizeLineEndings(content: string): string {
   return content.replaceAll('\r\n', '\n')
 }
@@ -420,6 +447,14 @@ function detectLineEndings(raw: string): LineEndings {
   return crlfCount > lfCount ? 'CRLF' : 'LF'
 }
 
+/**
+ * Convert LF-normalized content back to the line-ending style detected at read
+ * time, for write-back. `LF` returns the content unchanged; `CRLF` re-normalizes
+ * first so an already-CRLF sequence is never doubled to `\r\r\n`.
+ * @param content - the LF-normalized (edited) text.
+ * @param lineEndings - the original file's style, as detected by {@link readForEdit}.
+ * @returns the text in the original file's line-ending style.
+ */
 function restoreLineEndings(content: string, lineEndings: LineEndings): string {
   return lineEndings === 'LF' ? content : normalizeLineEndings(content).split('\n').join('\r\n')
 }
@@ -438,6 +473,10 @@ function countOccurrences(content: string, needle: string): number {
 /**
  * Read and decode a file for editing: rejects binaries, returns LF-normalized
  * content plus the original line-ending style for write-back.
+ * @param absolutePath - the file to read (typically a target key).
+ * @param displayPath - the caller-facing path used in error messages.
+ * @param signal - aborts the read (`FS_ABORTED`).
+ * @returns the LF-normalized content and the detected style to restore on write-back.
  */
 export async function readForEdit(
   absolutePath: string,
@@ -459,6 +498,9 @@ export async function readForEdit(
  * prior bytes, so an undiffable prior file simply yields no contextual-hunk basis
  * (the caller treats `null` the same as an absent file: the result renders a
  * whole-file diff rather than an applied hunk).
+ * @param absolutePath - the file to read (typically a target key); it must exist.
+ * @param signal - aborts the read (`FS_ABORTED`).
+ * @returns the LF-normalized text, or null for a binary or non-UTF-8 file.
  */
 export async function readTextForDiff(absolutePath: string, signal?: AbortSignal): Promise<string | null> {
   const buffer = await readFileAbortable(absolutePath, 'read', signal)
@@ -477,6 +519,12 @@ export async function readTextForDiff(absolutePath: string, signal?: AbortSignal
  * `FS_EDIT_NOT_FOUND` on empty `oldString` or zero matches and
  * `FS_AMBIGUOUS_EDIT` on multiple matches when `replaceAll` is false. Returns
  * the edited content (still LF-normalized) and the replacement count.
+ * @param content - the current file content, already LF-normalized.
+ * @param oldString - literal text to find; CRLF inside it is normalized to LF before matching.
+ * @param newString - literal replacement text, normalized the same way.
+ * @param replaceAll - replace every match instead of requiring exactly one.
+ * @param displayPath - the caller-facing path used in error messages.
+ * @returns the edited LF-normalized content plus how many occurrences were replaced.
  */
 export function applyLiteralEdit(
   content: string,
diff --git a/packages/fs/fs-local/src/index.ts b/packages/fs/fs-local/src/index.ts
index 0ad8365d4a..1a3ebc57f6 100644
--- a/packages/fs/fs-local/src/index.ts
+++ b/packages/fs/fs-local/src/index.ts
@@ -73,6 +73,7 @@ export class LocalFileSystem extends FileSystem {
     cwd: z.string().default(process.cwd()),
   })
 
+  /** Validated config (schemastery applied the defaults before construction). */
   readonly config: ResolvedConfig
   /** Test seam forwarded to fsio (force streaming path, pin temp names). */
   internals: FsIoInternals = {}
diff --git a/packages/fs/fs/src/types.ts b/packages/fs/fs/src/types.ts
index 9351a373db..f6f5b8005f 100644
--- a/packages/fs/fs/src/types.ts
+++ b/packages/fs/fs/src/types.ts
@@ -29,7 +29,12 @@ import type { Branded } from '@deepseek-ai/dsh-brand'
  */
 export type FsTargetKey = Branded<'FsTargetKey'>
 
-/** Brand a string as an {@link FsTargetKey}. */
+/**
+ * Brand a string as an {@link FsTargetKey}. For backend use only — a consumer
+ * never manufactures a key, it receives one from `resolve()`.
+ * @param key - the backend's raw key string (the local backend passes a realpath).
+ * @returns the same string, branded; no validation is performed.
+ */
 export function FsTargetKey(key: string): FsTargetKey {
   return key as FsTargetKey
 }
@@ -42,7 +47,12 @@ export function FsTargetKey(key: string): FsTargetKey {
  */
 export type FsVersion = Branded<'FsVersion'>
 
-/** Brand a string as an {@link FsVersion}. */
+/**
+ * Brand a string as an {@link FsVersion}. For backend use only — a consumer
+ * never manufactures a version, it receives one from `stat`/write/edit outcomes.
+ * @param v - the backend's raw version string (the local backend derives it from mtime+size).
+ * @returns the same string, branded; no validation is performed.
+ */
 export function FsVersion(v: string): FsVersion {
   return v as FsVersion
 }
diff --git a/packages/fs/tool-fs/src/diff.ts b/packages/fs/tool-fs/src/diff.ts
index a45082489a..da8b7a872e 100644
--- a/packages/fs/tool-fs/src/diff.ts
+++ b/packages/fs/tool-fs/src/diff.ts
@@ -40,6 +40,10 @@ export type FsDiffMeta = { diffs: FileDiff[] }
  * (a pure insertion) reports `oldText: null` (nothing to diff against), mirroring
  * the call-time card's new-file convention. The unified-diff "\ No newline at end
  * of file" markers are dropped — they annotate the patch, not file content.
+ * @param path - the path stamped on every produced diff (the model-facing `file_path`; the bridge relativizes it).
+ * @param before - the file text before the change (the backend's LF-normalized diff basis).
+ * @param after - the file text after the change, on the same basis.
+ * @returns one diff per applied hunk, in file order; empty when the texts are identical.
  */
 export function computeHunkDiffs(path: string, before: string, after: string): FileDiff[] {
   const patch = structuredPatch('', '', before, after, undefined, undefined, { context: DIFF_CONTEXT })
@@ -83,6 +87,8 @@ function isFileDiff(value: unknown): value is FileDiff {
  * it validates defensively rather than trusting the payload — a bad `meta` yields
  * `undefined`, and the caller decides the fallback (edit → the generic result
  * rendering; write → an args-derived whole-file diff), never a thrown presenter.
+ * @param meta - the opaque `tool/result` meta payload (live or replayed from the session log).
+ * @returns the validated non-empty hunk list, or undefined for an absent/empty/malformed payload.
  */
 export function diffsFromMeta(meta: unknown): FileDiff[] | undefined {
   if (typeof meta !== 'object' || meta === null || Array.isArray(meta)) return undefined
diff --git a/packages/fs/tool-fs/src/edit.ts b/packages/fs/tool-fs/src/edit.ts
index 5ede545b03..220c850d69 100644
--- a/packages/fs/tool-fs/src/edit.ts
+++ b/packages/fs/tool-fs/src/edit.ts
@@ -29,7 +29,13 @@ interface EditInput {
   replaceAll: boolean
 }
 
-/** Validate value constraints the schema DSL can't express. */
+/**
+ * Validate value constraints the schema DSL can't express: a non-blank
+ * `file_path`, a non-empty `old_string`, and `old_string !== new_string`
+ * (an equal pair would be a guaranteed no-op edit).
+ * @param args - the schema-validated raw tool arguments.
+ * @returns the camelCased input with `replace_all` defaulted to false.
+ */
 export function parseEditArgs(args: { file_path: string; old_string: string; new_string: string; replace_all?: boolean }): EditInput {
   if (args.file_path.trim().length === 0) throw new Error('file_path must be a non-empty string')
   if (args.old_string.length === 0) throw new Error('old_string must be a non-empty string')
@@ -42,14 +48,22 @@ export function parseEditArgs(args: { file_path: string; old_string: string; new
   }
 }
 
-/** Format an edit success (single-match or replace-all) as a Claude-style model-facing message. */
+/**
+ * Format an edit success (single-match or replace-all) as a Claude-style model-facing message.
+ * @param displayPath - the backend-resolved path shown to the model.
+ * @param replaceAll - selects the all-occurrences wording over the single-replacement one.
+ * @returns the confirmation sentence the model sees as the tool result.
+ */
 export function formatEditOutput(displayPath: string, replaceAll: boolean): string {
   return replaceAll
     ? `The file ${displayPath} has been updated. All occurrences were successfully replaced.`
     : `The file ${displayPath} has been updated successfully.`
 }
 
-/** Register the `edit` tool and its system-prompt guidance. */
+/**
+ * Register the `edit` tool and its system-prompt guidance.
+ * @param ctx - the plugin context; registrations are effects scoped to it, and execution uses its `fs` service.
+ */
 export function applyEditTool(ctx: Context): void {
   ctx.systemPrompt.section({
     name: 'tool:edit',
diff --git a/packages/fs/tool-fs/src/read-render.ts b/packages/fs/tool-fs/src/read-render.ts
index c54279baa9..8cafc0d400 100644
--- a/packages/fs/tool-fs/src/read-render.ts
+++ b/packages/fs/tool-fs/src/read-render.ts
@@ -119,6 +119,10 @@ function finish(acc: WindowAccumulator, request: ReadWindow, displayPath: string
  * path serves both. Scans for newlines with a capped line buffer (a newline-free
  * giant line is truncated, never buffered past `request.maxLineLength`),
  * enforces the byte cap, and throws `FS_NOT_FOUND` for an offset past EOF.
+ * @param chunks - decoded text chunks in file order; chunk boundaries carry no meaning.
+ * @param request - the resolved window; the caller has already applied its defaults and caps.
+ * @param displayPath - the caller-facing path used in the offset-out-of-range error.
+ * @returns the numbered window lines, the total line count seen, and the byte-cap truncation flag.
  */
 export async function buildWindow(
   chunks: AsyncIterable<string> | Iterable<string>,
@@ -156,7 +160,12 @@ export async function buildWindow(
   return finish(acc, request, displayPath)
 }
 
-/** Format a read outcome as one OpenCode-style line-numbered text block body. */
+/**
+ * Format a read outcome as one OpenCode-style line-numbered text block body.
+ * @param displayPath - the backend-resolved path rendered in the envelope's `<path>` element.
+ * @param outcome - the windowed read to render.
+ * @returns the model-facing envelope: numbered lines plus a continuation or end-of-file footer.
+ */
 export function formatReadOutput(displayPath: string, outcome: FileReadOutcome): string {
   const endLine = outcome.lines.at(-1)?.number ?? Math.max(0, outcome.offset - 1)
   let footer: string
diff --git a/packages/fs/tool-fs/src/read.ts b/packages/fs/tool-fs/src/read.ts
index a9cc4a9806..039d8742e9 100644
--- a/packages/fs/tool-fs/src/read.ts
+++ b/packages/fs/tool-fs/src/read.ts
@@ -58,7 +58,12 @@ function parsePositiveInteger(value: number, name: string): number {
   return value
 }
 
-/** Validate value constraints the schema DSL can't express. `maxLimit` is the deployment's line cap. */
+/**
+ * Validate value constraints the schema DSL can't express. `maxLimit` is the deployment's line cap.
+ * @param args - the schema-validated raw tool arguments; `offset`/`limit` must be positive integers when given.
+ * @param maxLimit - the configured line cap: both the default `limit` and the largest one accepted.
+ * @returns the validated input with `offset` defaulted to 1 and `limit` to `maxLimit`.
+ */
 export function parseReadArgs(args: { file_path: string; offset?: number; limit?: number }, maxLimit: number): ReadInput {
   if (args.file_path.trim().length === 0) throw new Error('file_path must be a non-empty string')
   const offset = args.offset === undefined ? 1 : parsePositiveInteger(args.offset, 'offset')
@@ -67,7 +72,11 @@ export function parseReadArgs(args: { file_path: string; offset?: number; limit?
   return { filePath: args.file_path, offset, limit }
 }
 
-/** Register the `read` tool and its system-prompt guidance. */
+/**
+ * Register the `read` tool and its system-prompt guidance.
+ * @param ctx - the plugin context; registrations are effects scoped to it, and execution uses its `fs` service.
+ * @param caps - the deployment's resolved read caps (plugin config after defaulting).
+ */
 export function applyReadTool(ctx: Context, caps: ReadToolCaps): void {
   ctx.systemPrompt.section({
     name: 'tool:read',
diff --git a/packages/fs/tool-fs/src/session-cwd.ts b/packages/fs/tool-fs/src/session-cwd.ts
index b7774fb201..16ba17e2e5 100644
--- a/packages/fs/tool-fs/src/session-cwd.ts
+++ b/packages/fs/tool-fs/src/session-cwd.ts
@@ -18,7 +18,11 @@
 
 import type { ToolExecution } from '@deepseek-ai/dsh-tools'
 
-/** The session workspace cwd for this call, or `undefined` when none applies. */
+/**
+ * The session workspace cwd for this call, or `undefined` when none applies.
+ * @param exec - the tool-execution context; only its optional `agent` is read.
+ * @returns the calling agent's session cwd, or undefined for a non-agent caller (the backend then applies its own default).
+ */
 export function sessionCwd(exec: ToolExecution): string | undefined {
   return exec.agent?.session.header.cwd
 }
diff --git a/packages/fs/tool-fs/src/write.ts b/packages/fs/tool-fs/src/write.ts
index 1054e2ff2f..fd4eec45f3 100644
--- a/packages/fs/tool-fs/src/write.ts
+++ b/packages/fs/tool-fs/src/write.ts
@@ -21,13 +21,23 @@ import type {} from '@deepseek-ai/dsh-system-prompt'
 import { computeHunkDiffs, diffsFromMeta, type FsDiffMeta } from './diff.ts'
 import { sessionCwd } from './session-cwd.ts'
 
-/** Validate value constraints the schema DSL can't express. */
+/**
+ * Validate value constraints the schema DSL can't express: only a non-blank
+ * `file_path` — an empty `content` is legitimate (it writes an empty file).
+ * @param args - the schema-validated raw tool arguments.
+ * @returns the camelCased input; `content` passes through untouched.
+ */
 export function parseWriteArgs(args: { file_path: string; content: string }): { filePath: string; content: string } {
   if (args.file_path.trim().length === 0) throw new Error('file_path must be a non-empty string')
   return { filePath: args.file_path, content: args.content }
 }
 
-/** Format a write outcome as one model-facing text block body. */
+/**
+ * Format a write outcome as one model-facing text block body.
+ * @param displayPath - the backend-resolved path rendered in the envelope's `<path>` element.
+ * @param outcome - the write outcome; its `operation` selects the Created/Updated wording.
+ * @returns the model-facing confirmation envelope (no file content is echoed back).
+ */
 export function formatWriteOutput(displayPath: string, outcome: FsWriteOutcome): string {
   const verb = outcome.operation === 'create' ? 'Created' : 'Updated'
   return `<path>${displayPath}</path>
@@ -37,7 +47,10 @@ ${verb} file
 </content>`
 }
 
-/** Register the `write` tool and its system-prompt guidance. */
+/**
+ * Register the `write` tool and its system-prompt guidance.
+ * @param ctx - the plugin context; registrations are effects scoped to it, and execution uses its `fs` service.
+ */
 export function applyWriteTool(ctx: Context): void {
   ctx.systemPrompt.section({
     name: 'tool:write',
diff --git a/packages/hooks/hook-protocol/src/codec.ts b/packages/hooks/hook-protocol/src/codec.ts
index 7cf97feca9..59de886e5e 100644
--- a/packages/hooks/hook-protocol/src/codec.ts
+++ b/packages/hooks/hook-protocol/src/codec.ts
@@ -75,6 +75,12 @@ function permissionDecisionOf(value: string | undefined): HookOutput['decision']
  * (`decision`/`reason`/`continue`/`stopReason`/`systemMessage`)
  * are unaffected. Omit `expectedEventName` (or pass a matching one) to apply the
  * block as-is — a caller that doesn't key by event opts out of the check.
+ *
+ * @param exitCode - the process exit code; `undefined` when the hook could not be spawned at all.
+ * @param stdout - the captured stdout stream; consulted for structured JSON only on a 0 exit.
+ * @param stderr - the captured stderr stream; becomes the blocking `reason` on exit 2.
+ * @param expectedEventName - the event the hook is firing for; omit to apply a `hookSpecificOutput` block as-is.
+ * @returns the dialect-neutral decoded outcome.
  */
 export function parseHookOutput(exitCode: number | undefined, stdout: string, stderr: string, expectedEventName?: string): HookOutput {
   const trimmedErr = stderr.trim()
diff --git a/packages/hooks/hook-protocol/src/events.ts b/packages/hooks/hook-protocol/src/events.ts
index 5e14f964fb..df6a10672a 100644
--- a/packages/hooks/hook-protocol/src/events.ts
+++ b/packages/hooks/hook-protocol/src/events.ts
@@ -66,6 +66,9 @@ export const DEFAULT_STDERR_SUMMARY_MAX_CHARS = 500
  * `undefined` when empty, cut at `maxChars` with an ellipsis when over. The
  * bound is a parameter — like `runHook`'s `defaultTimeoutMs`, each bridge owns
  * the config default and passes it in.
+ * @param stderr - the hook's raw captured stderr.
+ * @param maxChars - the character cap for the summary (the bridge's config value).
+ * @returns the trimmed, capped summary, or `undefined` when stderr is blank.
  */
 export function summarizeStderr(stderr: string, maxChars: number): string | undefined {
   const t = stderr.trim()
@@ -73,7 +76,11 @@ export function summarizeStderr(stderr: string, maxChars: number): string | unde
   return t.length > maxChars ? t.slice(0, maxChars) + '…' : t
 }
 
-/** Append a `hook/invoked` provenance event to `session`. */
+/**
+ * Append a `hook/invoked` provenance event to `session`.
+ * @param session - the session whose open turn records the event.
+ * @param invocation - the invocation identity; an absent `matcher` is omitted from the payload.
+ */
 export function appendHookInvoked(session: Session, invocation: HookInvocation): void {
   session.append('hook/invoked', {
     turn: invocation.turn,
@@ -91,6 +98,8 @@ export function appendHookInvoked(session: Session, invocation: HookInvocation):
  * else `'pass'`; `stderrSummary` is the trimmed stderr truncated to
  * `record.stderrSummaryMaxChars` characters (omitted when empty); `exitCode`
  * is omitted when the hook never ran.
+ * @param session - the session whose open turn records the event.
+ * @param record - the outcome to record: the decoded output plus the summary cap and duration.
  */
 export function appendHookResult(session: Session, record: HookResultRecord): void {
   const { output } = record
diff --git a/packages/hooks/hook-protocol/src/matcher.ts b/packages/hooks/hook-protocol/src/matcher.ts
index ee1dd324b3..6863ee999f 100644
--- a/packages/hooks/hook-protocol/src/matcher.ts
+++ b/packages/hooks/hook-protocol/src/matcher.ts
@@ -34,6 +34,10 @@ const CLAUDE_LITERAL = /^[A-Za-z0-9_|]+$/
  * pattern exact-matches the query (splitting `|` into alternatives); every other
  * `claude` pattern and ALL `codex` patterns are tested as an unanchored regex.
  * An invalid regex matches nothing (never throws).
+ * @param matcher - the configured pattern; absent/empty/`'*'` are the match-all sentinels.
+ * @param query - the candidate value (a tool name, a session source, …).
+ * @param mode - the dialect deciding literal-vs-regex interpretation of the pattern.
+ * @returns `true` when the pattern selects the query; `false` on a non-match or an invalid regex.
  */
 export function matchesMatcher(matcher: string | undefined, query: string, mode: MatcherMode): boolean {
   if (isMatchAll(matcher)) return true
diff --git a/packages/hooks/hook-protocol/src/merge.ts b/packages/hooks/hook-protocol/src/merge.ts
index 1e53dbaaea..d219c4eb18 100644
--- a/packages/hooks/hook-protocol/src/merge.ts
+++ b/packages/hooks/hook-protocol/src/merge.ts
@@ -71,6 +71,8 @@ function decisionForRank(maxRank: number): MergedDecision {
  * into one {@link MergedHookOutcome} by the precedence rules above. An empty list
  * yields a neutral outcome (`decision: 'none'`, no stop, empty context) — the
  * caller treats that as "no hook had anything to say".
+ * @param outputs - every matched hook's decoded output, in hook order.
+ * @returns the single folded outcome the bridge maps onto its seam.
  */
 export function mergeHookOutputs(outputs: HookOutput[]): MergedHookOutcome {
   let maxRank = 0
diff --git a/packages/hooks/hook-protocol/src/runner.ts b/packages/hooks/hook-protocol/src/runner.ts
index f5a892c468..e4a2bc8a04 100644
--- a/packages/hooks/hook-protocol/src/runner.ts
+++ b/packages/hooks/hook-protocol/src/runner.ts
@@ -70,6 +70,11 @@ export interface RunHookResult {
  * `exitCode: undefined`, so the caller's merge logic treats it as a
  * non-blocking error rather than crashing the turn. `now` is injected for
  * testable durations.
+ * @param bash - the executor seam the command runs through.
+ * @param hook - the configured command; its `timeoutSec` (wire unit: seconds) overrides the default timeout.
+ * @param options - the invocation's payload, env, cwd, signal, stdin framing, and default timeout.
+ * @param now - millisecond clock used for the reported duration.
+ * @returns the decoded output plus the run's wall-clock duration.
  */
 export async function runHook(
   bash: BashExecutor,
diff --git a/packages/hooks/hooks-claude/src/config.ts b/packages/hooks/hooks-claude/src/config.ts
index d78486e58a..b447c28533 100644
--- a/packages/hooks/hooks-claude/src/config.ts
+++ b/packages/hooks/hooks-claude/src/config.ts
@@ -43,7 +43,12 @@ function asObject(value: unknown): Record<string, unknown> | undefined {
     : undefined
 }
 
-/** Apply `${CLAUDE_PLUGIN_ROOT}` / `${CLAUDE_PROJECT_DIR}` substitution to a command string. */
+/**
+ * Apply `${CLAUDE_PLUGIN_ROOT}` / `${CLAUDE_PROJECT_DIR}` substitution to a command string.
+ * @param command - the raw command from config.
+ * @param vars - the substitution values; a token whose variable is unset stays verbatim.
+ * @returns the command with every occurrence of each set token replaced.
+ */
 export function substituteCommand(command: string, vars: SubstitutionVars): string {
   let out = command
   if (vars.pluginRoot !== undefined) out = out.split('${CLAUDE_PLUGIN_ROOT}').join(vars.pluginRoot)
@@ -57,6 +62,9 @@ export function substituteCommand(command: string, vars: SubstitutionVars): stri
  * Non-command hooks and malformed entries are dropped (recorded in `skipped` /
  * silently ignored) rather than throwing — a bad hook config must not crash boot.
  * `vars` are substituted into every surviving `command`.
+ * @param raw - the parsed JSON config: a settings object with a `hooks` key, or the bare event map.
+ * @param vars - substitution values applied to every surviving `command` (defaults to none).
+ * @returns the runnable per-event groups plus the skipped non-command hooks.
  */
 export function parseClaudeConfig(raw: unknown, vars: SubstitutionVars = {}): ParsedClaudeConfig {
   const config: ClaudeHookConfig = {}
diff --git a/packages/hooks/hooks-codex/src/config.ts b/packages/hooks/hooks-codex/src/config.ts
index 411f058eea..505f8d2bda 100644
--- a/packages/hooks/hooks-codex/src/config.ts
+++ b/packages/hooks/hooks-codex/src/config.ts
@@ -41,6 +41,8 @@ function asObject(value: unknown): Record<string, unknown> | undefined {
  * `type !== 'command'` and `async: true` command hooks are skipped (recorded in
  * `skipped`). Malformed entries are ignored rather than thrown — a bad config
  * must not crash boot. No command substitution (Codex does none).
+ * @param raw - the parsed JSON config: a `{ hooks: … }` wrapper or the bare event map.
+ * @returns the runnable per-event groups plus the skipped hooks with their reasons.
  */
 export function parseCodexConfig(raw: unknown): ParsedCodexConfig {
   const config: CodexHookConfig = {}
diff --git a/packages/llm/llm-deepseek/src/adapter.ts b/packages/llm/llm-deepseek/src/adapter.ts
index 9e5e5179b6..e0627c5695 100644
--- a/packages/llm/llm-deepseek/src/adapter.ts
+++ b/packages/llm/llm-deepseek/src/adapter.ts
@@ -13,7 +13,9 @@ import { parseSse } from './sse.ts'
 import { translate } from './translate.ts'
 import type { WireError } from './types.ts'
 
+/** Constructor options for {@link DeepSeekAdapter}; the plugin's `apply` resolves them from Config + environment. */
 export interface DeepSeekAdapterOptions {
+  /** Bearer token sent in the `authorization` header on every request. */
   apiKey: string
   /** Endpoint base; `/chat/completions` is appended. */
   baseURL: string
@@ -21,7 +23,11 @@ export interface DeepSeekAdapterOptions {
   defaults?: RequestDefaults
 }
 
-/** Map an HTTP status to a stable LlmError code. */
+/**
+ * Map an HTTP status to a stable LlmError code.
+ * @param status - status of a non-2xx provider response.
+ * @returns `AUTH` (401/403), `RATE_LIMIT` (429), `INVALID_REQUEST` (400), `SERVER` (5xx), or `HTTP_<status>` for anything else.
+ */
 export function httpErrorCode(status: number): string {
   if (status === 401 || status === 403) return 'AUTH'
   if (status === 429) return 'RATE_LIMIT'
diff --git a/packages/llm/llm-deepseek/src/index.ts b/packages/llm/llm-deepseek/src/index.ts
index 79313f910f..3a3d7bb4a1 100644
--- a/packages/llm/llm-deepseek/src/index.ts
+++ b/packages/llm/llm-deepseek/src/index.ts
@@ -34,6 +34,12 @@ export type * from './types.ts'
 export const name = 'llm-deepseek'
 export const inject = ['llm']
 
+/**
+ * Plugin config, validated by the same-named schemastery schema. Every field
+ * is optional in yml: credentials/endpoint fall back to the environment (a
+ * missing API key fails plugin load, not the first call), and omitted
+ * thinking fields send nothing on the wire, so the provider default applies.
+ */
 export interface Config {
   /** API key; falls back to $DEEPSEEK_API_KEY. Required one way or the other. */
   apiKey?: string
diff --git a/packages/llm/llm-deepseek/src/serialize.ts b/packages/llm/llm-deepseek/src/serialize.ts
index bbca37223f..10ef905d7e 100644
--- a/packages/llm/llm-deepseek/src/serialize.ts
+++ b/packages/llm/llm-deepseek/src/serialize.ts
@@ -66,6 +66,8 @@ function serializeAssistant(message: Message): WireMessage {
  * `{role: 'tool'}` messages; the harness puts each tool result in its own
  * user-role message, so a mixed user message contributes its text first and
  * its tool results as separate wire messages after.
+ * @param messages - the harness conversation, in order.
+ * @returns the wire messages; order preserved, each tool result expanded into its own entry.
  */
 export function serializeMessages(messages: Message[]): WireMessage[] {
   const wire: WireMessage[] = []
@@ -97,7 +99,14 @@ export function serializeMessages(messages: Message[]): WireMessage[] {
   return wire
 }
 
-/** Build the full wire request. */
+/**
+ * Build the full wire request. Always streaming (`stream: true`, usage
+ * reporting on); optional fields are omitted rather than sent as null, so
+ * provider defaults apply.
+ * @param options - the harness request (model, history, system, tools, sampling).
+ * @param defaults - adapter-level thinking defaults; undefined fields put nothing on the wire.
+ * @returns the chat-completions request body.
+ */
 export function serializeRequest(options: GenerateOptions, defaults: RequestDefaults = {}): WireRequest {
   const messages: WireMessage[] = []
   if (options.system !== undefined) {
diff --git a/packages/llm/llm-deepseek/src/sse.ts b/packages/llm/llm-deepseek/src/sse.ts
index 252870471a..6856289aec 100644
--- a/packages/llm/llm-deepseek/src/sse.ts
+++ b/packages/llm/llm-deepseek/src/sse.ts
@@ -37,6 +37,8 @@ function eventData(block: string): string | undefined {
  * Parse a byte stream into SSE data payloads. Yields `[DONE]` as the final
  * value and returns; throws `LlmError('STREAM_CLOSED')` when the stream ends
  * without it (truncated response — the model call cannot be trusted).
+ * @param stream - raw SSE bytes; reads may split anywhere, including mid-UTF-8 sequence.
+ * @returns each event's data payload in arrival order, the `[DONE]` sentinel last.
  */
 export async function* parseSse(stream: AsyncIterable<Uint8Array>): AsyncGenerator<string> {
   const decoder = new TextDecoder()
diff --git a/packages/llm/llm-deepseek/src/translate.ts b/packages/llm/llm-deepseek/src/translate.ts
index 08cc019b61..cd6bc8f108 100644
--- a/packages/llm/llm-deepseek/src/translate.ts
+++ b/packages/llm/llm-deepseek/src/translate.ts
@@ -29,7 +29,11 @@ interface OpenBlock {
   name?: string
 }
 
-/** Map the wire finish_reason vocabulary to the harness FinishReason. */
+/**
+ * Map the wire finish_reason vocabulary to the harness FinishReason.
+ * @param reason - the wire `finish_reason` string.
+ * @returns the mapped reason; unrecognized values (content_filter, …) become `{kind: 'error'}` with the uppercased value as `code`.
+ */
 export function mapFinishReason(reason: string): FinishReason {
   switch (reason) {
     case 'stop': return { kind: 'stop' }
@@ -46,6 +50,8 @@ export function mapFinishReason(reason: string): FinishReason {
  * (`prompt_tokens = prompt_cache_hit_tokens + prompt_cache_miss_tokens`,
  * api/create-chat-completion); the harness TokenUsage convention is
  * DISJOINT counts, so cache reads are subtracted out of `inputTokens`.
+ * @param usage - wire usage from the finish chunk or the trailing usage-only chunk.
+ * @returns disjoint harness counts; cache/reasoning fields present only when the wire reported them.
  */
 export function mapUsage(usage: WireUsage): TokenUsage {
   const cacheRead = usage.prompt_tokens_details?.cached_tokens ?? usage.prompt_cache_hit_tokens
@@ -75,6 +81,8 @@ function closeBlock(block: OpenBlock): ContentBlock {
 /**
  * Consume SSE data payloads (ending with `[DONE]`) and yield StreamChunks.
  * Malformed JSON payloads abort the stream with `MALFORMED_RESPONSE`.
+ * @param payloads - SSE data payloads from {@link parseSse}, `[DONE]`-terminated.
+ * @returns deltas as they arrive; `block-end`s, `usage`, and `finish` are all deferred to the `[DONE]` sentinel.
  */
 export async function* translate(payloads: AsyncIterable<string>): AsyncGenerator<StreamChunk> {
   let nextIndex = 0
diff --git a/packages/llm/llm-deepseek/src/types.ts b/packages/llm/llm-deepseek/src/types.ts
index 072c43babb..a9d7403a35 100644
--- a/packages/llm/llm-deepseek/src/types.ts
+++ b/packages/llm/llm-deepseek/src/types.ts
@@ -48,12 +48,18 @@ export interface WireToolMessage {
   content: string
 }
 
+/** One entry of the request `messages` array, discriminated on `role`. */
 export type WireMessage =
   | WireSystemMessage
   | WireUserMessage
   | WireAssistantMessage
   | WireToolMessage
 
+/**
+ * Assistant-role history message. The harness replays `content: ""` (never
+ * null) on tool-call-only turns — some gateways reject null — and sends null
+ * only when the turn carried neither text nor tool calls.
+ */
 export interface WireAssistantMessage {
   role: 'assistant'
   content: string | null
@@ -66,12 +72,14 @@ export interface WireAssistantMessage {
   tool_calls?: WireToolCall[]
 }
 
+/** A completed tool call replayed on an assistant history message; `arguments` is the raw JSON string. */
 export interface WireToolCall {
   id: string
   type: 'function'
   function: { name: string; arguments: string }
 }
 
+/** One entry of the request `tools` array; `parameters` is a JSON Schema object. */
 export interface WireTool {
   type: 'function'
   function: {
@@ -88,11 +96,13 @@ export interface WireChunk {
   usage?: WireUsage | null
 }
 
+/** One streamed choice (requests always ask for a single one); `finish_reason` is non-null only on its terminal chunk. */
 export interface WireChoice {
   delta?: WireDelta
   finish_reason?: string | null
 }
 
+/** The incremental content of one streamed choice; any subset of fields may be present per chunk. */
 export interface WireDelta {
   role?: string
   /** Visible text. Null/empty on reasoning/tool-call chunks. */
@@ -105,6 +115,7 @@ export interface WireDelta {
   tool_calls?: WireToolCallDelta[]
 }
 
+/** A streamed fragment of one tool call; fragments sharing an `index` concatenate into one call. */
 export interface WireToolCallDelta {
   /** Disambiguates parallel tool calls; stable across a call's deltas. */
   index: number
@@ -119,6 +130,13 @@ export interface WireToolCallDelta {
   }
 }
 
+/**
+ * Wire token accounting. `prompt_tokens` INCLUDES cache hits (it equals
+ * `prompt_cache_hit_tokens + prompt_cache_miss_tokens`); `mapUsage` subtracts
+ * them to keep the harness convention of disjoint counts.
+ * `prompt_tokens_details.cached_tokens` is the OpenAI-compat spelling of the
+ * hit count.
+ */
 export interface WireUsage {
   prompt_tokens: number
   completion_tokens: number
diff --git a/packages/llm/llm-pi-ai/src/adapter.ts b/packages/llm/llm-pi-ai/src/adapter.ts
index a24e335d8b..00107e8e1c 100644
--- a/packages/llm/llm-pi-ai/src/adapter.ts
+++ b/packages/llm/llm-pi-ai/src/adapter.ts
@@ -21,14 +21,22 @@ import { toPiContext, toStreamChunks } from './convert.ts'
 /** Reasoning levels surfaced by this adapter (DeepSeek wire: high|max). */
 export type PiAiReasoning = 'off' | 'high' | 'xhigh'
 
+/** Constructor options for {@link PiAiAdapter}; the plugin's `apply` resolves them from Config + environment. */
 export interface PiAiAdapterOptions {
+  /** Bearer token pi-ai sends on every request. */
   apiKey: string
+  /** Endpoint base; `/chat/completions` is appended. */
   baseURL: string
   /** Thinking level applied to every request ('off' disables thinking). */
   reasoning?: PiAiReasoning | undefined
 }
 
-/** Build the inline pi-ai model descriptor for one DeepSeek model name. */
+/**
+ * Build the inline pi-ai model descriptor for one DeepSeek model name.
+ * @param modelId - harness model name; sent verbatim on the wire.
+ * @param options - adapter options; only `baseURL` is read here (key and reasoning apply per request, not per descriptor).
+ * @returns a descriptor with every DeepSeek compat flag explicit — pi-ai's URL-based auto-detection is never relied on.
+ */
 export function buildModel(modelId: string, options: PiAiAdapterOptions): Model<'openai-completions'> {
   return {
     id: modelId,
diff --git a/packages/llm/llm-pi-ai/src/convert.ts b/packages/llm/llm-pi-ai/src/convert.ts
index 6fa96a0597..9652cb7d56 100644
--- a/packages/llm/llm-pi-ai/src/convert.ts
+++ b/packages/llm/llm-pi-ai/src/convert.ts
@@ -55,6 +55,8 @@ function parseArguments(raw: string): Record<string, unknown> {
  * NAME (pi-ai's `toolName`), which the harness doesn't carry on the result
  * block — it is recovered from the preceding assistant tool-call with the
  * same id.
+ * @param options - the harness request; `options.system` maps to pi-ai's single `systemPrompt` slot.
+ * @returns the pi-ai context; `tools` is omitted entirely when the request declares none.
  */
 export function toPiContext(options: GenerateOptions): PiContext {
   const toolNames = new Map<CallId, string>()
@@ -159,7 +161,11 @@ function emptyPiUsage(): PiUsage {
   }
 }
 
-/** Map pi-ai usage (reasoning folded into output by pi-ai). */
+/**
+ * Map pi-ai usage (reasoning folded into output by pi-ai).
+ * @param usage - cumulative usage from the terminal pi-ai event.
+ * @returns harness counts; cache fields appear only when non-zero (pi-ai reports zeros, not absence).
+ */
 export function mapUsage(usage: PiUsage): TokenUsage {
   return {
     inputTokens: usage.input,
@@ -177,7 +183,11 @@ function classifyPiAiError(message: string): string {
   return 'PI_AI_ERROR'
 }
 
-/** Map a terminal pi-ai event to the harness finish reason. */
+/**
+ * Map a terminal pi-ai event to the harness finish reason.
+ * @param message - the assistant message carried by the `done` or `error` event.
+ * @returns the harness reason; `error` yields `{kind: 'error'}` with a code classified from the error text.
+ */
 export function mapStopReason(message: AssistantMessage): FinishReason {
   switch (message.stopReason) {
     case 'stop': return { kind: 'stop' }
@@ -195,6 +205,9 @@ export function mapStopReason(message: AssistantMessage): FinishReason {
  * Translate the pi-ai event stream into StreamChunks. pi-ai never throws
  * mid-stream — failures arrive as `error` events, which become error/aborted
  * `finish` chunks (the harness protocol's other error-delivery style).
+ * @param events - one assistant turn's pi-ai event stream.
+ * @returns the harness chunks, ending with `usage` then `finish`; throws
+ *   `LlmError` (`STREAM_CLOSED`) if the source ends without a terminal event.
  */
 export async function* toStreamChunks(events: AsyncIterable<AssistantMessageEvent>): AsyncGenerator<StreamChunk> {
   // pi-ai contentIndex ↔ our block index map 1:1 (both count blocks from 0
diff --git a/packages/llm/llm-pi-ai/src/index.ts b/packages/llm/llm-pi-ai/src/index.ts
index bef0d4b3f5..43468ba507 100644
--- a/packages/llm/llm-pi-ai/src/index.ts
+++ b/packages/llm/llm-pi-ai/src/index.ts
@@ -29,6 +29,11 @@ export { mapStopReason, mapUsage, toPiContext, toStreamChunks } from './convert.
 export const name = 'llm-pi-ai'
 export const inject = ['llm']
 
+/**
+ * Plugin config, validated by the same-named schemastery schema. Every field
+ * is optional in yml: credentials/endpoint fall back to the environment (a
+ * missing API key fails plugin load, not the first call).
+ */
 export interface Config {
   /** API key; falls back to $DEEPSEEK_API_KEY. Required one way or the other. */
   apiKey?: string
diff --git a/packages/llm/llm/src/assembler.ts b/packages/llm/llm/src/assembler.ts
index 328ef01c54..1b8ba6e60c 100644
--- a/packages/llm/llm/src/assembler.ts
+++ b/packages/llm/llm/src/assembler.ts
@@ -40,6 +40,8 @@ export class BlockAssembler {
   /**
    * Feed one chunk. Returns the completed block when the chunk closes one
    * (an explicit `block-end`), otherwise undefined.
+   * @param chunk - the next raw chunk, in stream order.
+   * @returns the authoritative block from the first `block-end` at its index; undefined for every other chunk.
    */
   push(chunk: StreamChunk): ContentBlock | undefined {
     switch (chunk.type) {
@@ -123,20 +125,29 @@ export class BlockAssembler {
     return partial
   }
 
-  /** Assemble all blocks seen so far, in stream order. */
+  /**
+   * Assemble all blocks seen so far, in stream order.
+   * @returns one block per seen index; an open block assembles from its
+   *   accumulated deltas (an unknown block type never closed by `block-end` throws).
+   */
   blocks(): ContentBlock[] {
     return this.order.map(index => this.assemble(this.mustGet(index), index))
   }
 
+  /** Usage from the `usage` chunk; undefined until one arrives. */
   get usage(): TokenUsage | undefined {
     return this._usage
   }
 
+  /** Finish reason from the `finish` chunk; `{kind: 'stop'}` when the stream ended without one. */
   get finish(): FinishReason {
     return this._finish ?? { kind: 'stop' }
   }
 
-  /** The assembled assistant message. */
+  /**
+   * The assembled assistant message.
+   * @returns an assistant-role message over `blocks()` (same open-block assembly rules).
+   */
   message(): Message {
     return { role: 'assistant', content: this.blocks() }
   }
diff --git a/packages/llm/llm/src/attribution.ts b/packages/llm/llm/src/attribution.ts
index 61ee2f9ddd..0250062eec 100644
--- a/packages/llm/llm/src/attribution.ts
+++ b/packages/llm/llm/src/attribution.ts
@@ -54,6 +54,8 @@ export const APP_IDENTITY: AppIdentity = {
  * The standard `User-Agent` value: `product/version (+url)`. The
  * parenthesized `+url` comment is the conventional self-identification form
  * (RFC 9110 §10.1.5 product + comment syntax).
+ * @param identity - the identity to render; defaults to {@link APP_IDENTITY}.
+ * @returns the ready-to-send header value.
  */
 export function userAgent(identity: AppIdentity = APP_IDENTITY): string {
   return `${identity.product}/${identity.version} (+${identity.url})`
@@ -63,6 +65,8 @@ export function userAgent(identity: AppIdentity = APP_IDENTITY): string {
  * Build the attribution headers an adapter must send on every provider
  * request. Header names are lowercase (HTTP field names are case-insensitive
  * on the wire).
+ * @param identity - the identity to send; defaults to {@link APP_IDENTITY} — omission cannot suppress attribution.
+ * @returns headers to merge into the provider request (currently just `user-agent`).
  */
 export function attributionHeaders(
   identity: AppIdentity = APP_IDENTITY,
diff --git a/packages/llm/llm/src/brand.ts b/packages/llm/llm/src/brand.ts
index 3082cc0141..ee1cf786b1 100644
--- a/packages/llm/llm/src/brand.ts
+++ b/packages/llm/llm/src/brand.ts
@@ -17,7 +17,11 @@ import type { Branded } from '@deepseek-ai/dsh-brand'
  */
 export type CallId = Branded<'CallId'>
 
-/** Brand a string as a {@link CallId}. */
+/**
+ * Brand a string as a {@link CallId}.
+ * @param id - the provider-issued (or synthesized) call id.
+ * @returns the same string, branded; no validation is performed.
+ */
 export function CallId(id: string): CallId {
   return id as CallId
 }
diff --git a/packages/llm/llm/src/error.ts b/packages/llm/llm/src/error.ts
index 6f28898798..2627455789 100644
--- a/packages/llm/llm/src/error.ts
+++ b/packages/llm/llm/src/error.ts
@@ -18,6 +18,7 @@
  * `ErrorOptions`. `name` defaults to the subclass constructor name.
  */
 export class HarnessError extends Error {
+  /** Stable machine-routable failure class (e.g. `RATE_LIMIT`); route on this, never by parsing `message`. */
   readonly code: string
 
   constructor(message: string, code: string, options?: ErrorOptions) {
@@ -27,7 +28,11 @@ export class HarnessError extends Error {
   }
 }
 
-/** Narrow an arbitrary thrown value to a HarnessError (for `instanceof` at seams). */
+/**
+ * Narrow an arbitrary thrown value to a HarnessError (for `instanceof` at seams).
+ * @param value - the caught value (`unknown` in catch clauses).
+ * @returns true only for real instances; duck-typed or cross-realm errors do not narrow.
+ */
 export function isHarnessError(value: unknown): value is HarnessError {
   return value instanceof HarnessError
 }
diff --git a/packages/llm/llm/src/index.ts b/packages/llm/llm/src/index.ts
index 0bab45e1bb..667e9bca78 100644
--- a/packages/llm/llm/src/index.ts
+++ b/packages/llm/llm/src/index.ts
@@ -73,7 +73,11 @@ export class LlmError extends HarnessError {
  * same value to the wire.
  */
 export abstract class LlmAdapter {
-  /** Stream one model call as raw chunks. The only required method. */
+  /**
+   * Stream one model call as raw chunks. The only required method.
+   * @param options - the fully-assembled request; implementations must honor `options.signal`.
+   * @returns the chunk stream, obeying the adapter contract documented on `StreamChunk`.
+   */
   abstract stream(options: GenerateOptions): AsyncIterable<StreamChunk>
 }
 
diff --git a/packages/llm/llm/src/never.ts b/packages/llm/llm/src/never.ts
index 8eed137f15..1243611415 100644
--- a/packages/llm/llm/src/never.ts
+++ b/packages/llm/llm/src/never.ts
@@ -26,6 +26,9 @@
  * variant was added without updating the switch (compile error at the call
  * site — the desired outcome) or a value escaped its type (runtime throw
  * with diagnostics — the safety net).
+ * @param value - the impossible value; typed `never` so an unhandled variant fails compilation at the call site.
+ * @param context - optional label (e.g. the switch site) prefixed into the throw message.
+ * @returns never — it always throws, with the offending value JSON-rendered in the message.
  */
 export function assertNever(value: never, context?: string): never {
   // JSON.stringify is typed string but returns undefined for undefined input;
diff --git a/packages/llm/llm/src/types.ts b/packages/llm/llm/src/types.ts
index 7163ddc1d9..1644885a73 100644
--- a/packages/llm/llm/src/types.ts
+++ b/packages/llm/llm/src/types.ts
@@ -70,7 +70,9 @@ export interface ContentBlockMap {
   'tool-result': ToolResultBlock
 }
 
+/** The block `type` tag vocabulary; widens as plugins merge new shapes into {@link ContentBlockMap}. */
 export type ContentBlockType = keyof ContentBlockMap
+/** Any known content block, derived from {@link ContentBlockMap}; switch on `type` and fall through unknowns (merge-extensible). */
 export type ContentBlock = ContentBlockMap[ContentBlockType]
 
 /** A single message in a conversation history. */
@@ -88,6 +90,7 @@ export interface MessageSourceMap {
   plugin: { kind: 'plugin'; plugin: string }
 }
 
+/** Any known message source, derived from {@link MessageSourceMap}; switch on `kind` and fall through unknowns (merge-extensible). */
 export type MessageSource = MessageSourceMap[keyof MessageSourceMap]
 
 /**
@@ -102,6 +105,7 @@ export interface FinishReasonMap {
   'error': { kind: 'error'; message: string; code?: string }
 }
 
+/** Any known finish reason, derived from {@link FinishReasonMap}; switch on `kind` and fall through unknowns (merge-extensible). */
 export type FinishReason = FinishReasonMap[keyof FinishReasonMap]
 
 /**
diff --git a/packages/session-persistence/session-persistence-jsonl/src/format.ts b/packages/session-persistence/session-persistence-jsonl/src/format.ts
index 63cf899e45..5ec01283b4 100644
--- a/packages/session-persistence/session-persistence-jsonl/src/format.ts
+++ b/packages/session-persistence/session-persistence-jsonl/src/format.ts
@@ -27,7 +27,11 @@ export interface HeaderLine {
   seedLength?: number
 }
 
-/** Build the header line object from a {@link SessionHeader}. */
+/**
+ * Build the header line object from a {@link SessionHeader}.
+ * @param header - the immutable session metadata to serialize.
+ * @returns the `type: 'session'`-tagged line object, absent optional fields omitted (never null).
+ */
 export function toHeaderLine(header: SessionHeader): HeaderLine {
   return {
     type: 'session',
@@ -40,7 +44,11 @@ export function toHeaderLine(header: SessionHeader): HeaderLine {
   }
 }
 
-/** Parse a header line back into a {@link SessionHeader}. */
+/**
+ * Parse a header line back into a {@link SessionHeader}.
+ * @param line - the shape-checked first line of a log (see the `isHeaderLine` guard).
+ * @returns the header, absent optional fields omitted.
+ */
 export function fromHeaderLine(line: HeaderLine): SessionHeader {
   return {
     version: line.version,
@@ -77,6 +85,8 @@ function isHeaderLine(value: unknown): value is HeaderLine {
  * `Buffer.from(…, 'utf8')` would do, breaking injectivity). `.` is in the safe
  * set for readability but the whole-segment tokens `.`/`..` are escaped so they
  * can never traverse.
+ * @param raw - the string to encode; must be non-empty (throws on `''`).
+ * @returns the escaped single path segment, decodable back to `raw`.
  */
 export function encodeSegment(raw: string): string {
   if (raw.length === 0) throw new Error('cannot encode an empty path segment')
@@ -97,9 +107,12 @@ export function encodeSegment(raw: string): string {
 
 /**
  * The directory a session's files live in: the configured root, then a per-cwd
- * subdirectory so sessions group by project. The cwd subdir is a stable hash
- * (short, collision-resistant, filesystem-safe) plus an encoded suffix for
- * readability; sessions without a cwd go in a shared `_no-cwd` bucket.
+ * subdirectory so sessions group by project. The cwd subdir is a stable hash of
+ * the cwd (short, collision-resistant, filesystem-safe); sessions without a
+ * cwd go in a shared `_no-cwd` bucket.
+ * @param root - the backend's session root directory.
+ * @param cwd - the session's project directory; `undefined` selects the shared `_no-cwd` bucket.
+ * @returns the per-cwd bucket directory path under `root`.
  */
 export function sessionDir(root: string, cwd: string | undefined): string {
   if (cwd === undefined) return join(root, '_no-cwd')
@@ -107,12 +120,22 @@ export function sessionDir(root: string, cwd: string | undefined): string {
   return join(root, `cwd-${hash}`)
 }
 
-/** The append-only event-log file path for a session. */
+/**
+ * The append-only event-log file path for a session.
+ * @param root - the backend's session root directory.
+ * @param cwd - the session's project directory (picks the per-cwd bucket; `undefined` → `_no-cwd`).
+ * @param id - the session id, path-encoded via {@link encodeSegment} before filesystem use.
+ * @returns the session's `.jsonl` log file path.
+ */
 export function logPath(root: string, cwd: string | undefined, id: SessionId): string {
   return join(sessionDir(root, cwd), `${encodeSegment(id)}.jsonl`)
 }
 
-/** Serialize one event as a JSONL line (no trailing newline). */
+/**
+ * Serialize one event as a JSONL line (no trailing newline).
+ * @param event - the event to serialize verbatim.
+ * @returns the event's single-line JSON text; the writer adds the newline.
+ */
 export function eventLine(event: SessionEvent): string {
   return JSON.stringify(event)
 }
@@ -135,6 +158,9 @@ export function eventLine(event: SessionEvent): string {
  * This relies on the session-log invariant that every event lives inside a turn
  * (`Session.append` enforces it): only the final turn can be open, so the
  * preserved tail is at most one unclosed turn.
+ * @param buffer - the raw bytes of the log file (header line first).
+ * @returns the header, the preserved event prefix, and `committedBytes` — the
+ *   byte offset the next append truncates any torn tail to.
  */
 export function scanLog(buffer: Buffer): { meta: SessionHeader; events: SessionEvent[]; committedBytes: number } {
   const text = buffer.toString('utf8')
@@ -239,6 +265,8 @@ export function scanLog(buffer: Buffer): { meta: SessionHeader; events: SessionE
  * `undefined` if it is missing/not a header. Used by `list()` to read session
  * metadata WITHOUT parsing the whole log: a session picker scales with the
  * number of sessions, not the total size of every conversation.
+ * @param firstLine - the first line of a log file (without its trailing newline).
+ * @returns the parsed header, or `undefined` when the line is not a well-formed session header.
  */
 export function parseHeaderMeta(firstLine: string): SessionHeader | undefined {
   let parsed: unknown
diff --git a/packages/session-persistence/session-persistence-jsonl/src/index.ts b/packages/session-persistence/session-persistence-jsonl/src/index.ts
index 6de7eafeb3..a69c979756 100644
--- a/packages/session-persistence/session-persistence-jsonl/src/index.ts
+++ b/packages/session-persistence/session-persistence-jsonl/src/index.ts
@@ -31,6 +31,7 @@ import {
   encodeSegment, eventLine, logPath, parseHeaderMeta, scanLog, sessionDir, toHeaderLine,
 } from './format.ts'
 
+/** Plugin config: where the JSONL backend keeps its session logs (`root` is required — no default). */
 export interface Config {
   /**
    * Root directory for all session files. Required (no default): a default of
diff --git a/packages/session-persistence/session-persistence-sqlite/src/schema.ts b/packages/session-persistence/session-persistence-sqlite/src/schema.ts
index 2ed6f5853c..2dacbe04a0 100644
--- a/packages/session-persistence/session-persistence-sqlite/src/schema.ts
+++ b/packages/session-persistence/session-persistence-sqlite/src/schema.ts
@@ -76,6 +76,9 @@ export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
  * is the merged layout carrying every column; bumping past the collided v3
  * makes the version check reject both sibling v3 databases instead of opening
  * one against columns it does not have.
+ * @param path - the SQLite database file to open (created when absent).
+ * @param journalMode - the journal pragma to apply — a closed in-code union, validated by the plugin Config.
+ * @returns the open handle with pragmas applied and both tables ensured.
  */
 export function openDatabase(path: string, journalMode: JournalMode): DatabaseSync {
   const db = new DatabaseSync(path)
@@ -120,7 +123,11 @@ export function openDatabase(path: string, journalMode: JournalMode): DatabaseSy
   return db
 }
 
-/** Reconstruct the {@link SessionHeader} from a `sessions` row. */
+/**
+ * Reconstruct the {@link SessionHeader} from a `sessions` row.
+ * @param row - the `sessions` table row.
+ * @returns the header, `NULL` columns mapped to omitted optional fields.
+ */
 export function rowToMeta(row: SessionRow): SessionHeader {
   return {
     version: row.version,
@@ -132,7 +139,12 @@ export function rowToMeta(row: SessionRow): SessionHeader {
   }
 }
 
-/** Reconstruct a {@link SessionEvent} from an `events` row (parses `data`). */
+/**
+ * Reconstruct a {@link SessionEvent} from an `events` row (parses `data`).
+ * @param row - the `events` table row; `data` and the surface columns hold JSON text.
+ * @returns the reconstructed event; throws when a JSON column fails to parse
+ *   ({@link scanRows} treats that as a hole, not corruption, in the tail).
+ */
 export function rowToEvent(row: EventRow): SessionEvent {
   // Surface-metadata fields are conditional on the event type in the type
   // system; spread them so each variant gets only the fields it declares.
@@ -172,6 +184,9 @@ export function rowToEvent(row: EventRow): SessionEvent {
  * This relies on the session-log invariant that every event lives inside a turn
  * (`Session.append` enforces it): only the final turn can be open, so the
  * preserved tail is at most one unclosed turn.
+ * @param rows - one session's event rows, ordered by seq ascending.
+ * @returns the preserved event prefix, plus `tornFrom` — the seq the physical
+ *   delete starts at — when a torn tail exists.
  */
 export function scanRows(rows: readonly EventRow[]): { preserved: SessionEvent[]; tornFrom?: number } {
   // Pass 1: parse each row's data; a row whose data is not valid JSON is a hole.
diff --git a/packages/session-persistence/session-persistence/src/coordinator.ts b/packages/session-persistence/session-persistence/src/coordinator.ts
index 7c7b044ee1..0180999842 100644
--- a/packages/session-persistence/session-persistence/src/coordinator.ts
+++ b/packages/session-persistence/session-persistence/src/coordinator.ts
@@ -186,6 +186,7 @@ export class PersistenceCoordinator<TornMarker = unknown> {
   /**
    * Register a new session's metadata (lazy: no physical write until the first
    * {@link append}). Rejects if the id is already tracked or already persisted.
+   * @param meta - the immutable header (id, version, cwd, lineage) to record; snapshotted at call time.
    */
   create(meta: SessionHeader): Promise<void> {
     // Snapshot the metadata at call time: the op runs later (behind the
@@ -216,6 +217,8 @@ export class PersistenceCoordinator<TornMarker = unknown> {
   /**
    * Durably persist a batch of events. Honors the append-only and contiguous-seq
    * contracts; rejects non-JSON-serializable `event.data`.
+   * @param id - the session the batch belongs to.
+   * @param events - the contiguous batch to persist, in seq order; deep-cloned at call time.
    */
   async append(id: SessionId, events: readonly SessionEvent[]): Promise<void> {
     // Validate serializability BEFORE cloning so a bad event surfaces the typed
@@ -252,6 +255,8 @@ export class PersistenceCoordinator<TornMarker = unknown> {
    * Reload a session: its {@link SessionHeader} plus the event log up to the last
    * durable checkpoint, with any interrupted final turn durably closed (synthetic
    * boundary events) during load.
+   * @param id - the persisted session to reload.
+   * @returns the header plus the event log, ending on a balanced `turn/end`.
    */
   load(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
     return this.serialize(id, () => this.loadCore(id))
diff --git a/packages/session-persistence/session-persistence/src/index.ts b/packages/session-persistence/session-persistence/src/index.ts
index 5e1af6e563..1588ed2526 100644
--- a/packages/session-persistence/session-persistence/src/index.ts
+++ b/packages/session-persistence/session-persistence/src/index.ts
@@ -45,6 +45,9 @@ declare module 'cordis' {
  *
  * The comparison includes the full event payload, not just seq/type/time, so a
  * mutated seed cannot be grafted onto a durable log with the same envelope.
+ * @param seed - the live session's creation-time event snapshot.
+ * @param prefix - the persisted prefix the seed must reproduce.
+ * @returns `true` when the prefix fits within the seed and every event matches by JSON text.
  */
 export function seedCoversPrefix(seed: readonly SessionEvent[], prefix: readonly SessionEvent[]): boolean {
   return prefix.length <= seed.length
@@ -58,6 +61,7 @@ export function seedCoversPrefix(seed: readonly SessionEvent[], prefix: readonly
  * Reject non-JSON-serializable event data before a backend serializes a batch.
  * Live session appends already enforce this; persistence append paths also
  * accept replay/fork batches that may bypass a live session instance.
+ * @param events - the batch to validate; throws naming the offending event's type and seq.
  */
 export function assertSerializable(events: readonly SessionEvent[]): void {
   for (const event of events) {
diff --git a/packages/subagent/subagent-acp/src/run.ts b/packages/subagent/subagent-acp/src/run.ts
index 74291b7e65..d7631f4d8d 100644
--- a/packages/subagent/subagent-acp/src/run.ts
+++ b/packages/subagent/subagent-acp/src/run.ts
@@ -121,7 +121,12 @@ export const DEFAULT_DISPOSE_GRACE_MS = 3_000
  */
 export const SENSITIVE_ENV_PATTERN = /KEY|SECRET|TOKEN/i
 
-/** The ambient env minus credential-shaped vars, plus the spec's explicit env. */
+/**
+ * The ambient env minus credential-shaped vars, plus the spec's explicit env.
+ * @param extra - explicit vars layered on top AFTER the scrub, so a
+ * credential-shaped name supplied deliberately still reaches the child.
+ * @returns the environment to spawn the child with.
+ */
 export function buildChildEnv(extra: Record<string, string>): NodeJS.ProcessEnv {
   const env: NodeJS.ProcessEnv = {}
   for (const [key, value] of Object.entries(process.env)) {
@@ -130,7 +135,12 @@ export function buildChildEnv(extra: Record<string, string>): NodeJS.ProcessEnv
   return { ...env, ...extra }
 }
 
-/** Map an ACP {@link StopReason} to a harness {@link SubagentStopReason}. */
+/**
+ * Map an ACP {@link StopReason} to a harness {@link SubagentStopReason}.
+ * @param reason - the terminal reason from the child's `session/prompt` response.
+ * @returns the harness equivalent; `max_turn_requests` and any unknown future
+ * variant map to `error`, so an unclean stop is never reported as `completed`.
+ */
 export function acpStopReason(reason: StopReason): SubagentStopReason {
   switch (reason) {
     case 'end_turn':
@@ -155,12 +165,20 @@ export function acpStopReason(reason: StopReason): SubagentStopReason {
   }
 }
 
-/** Collect the text of an ACP content block (non-text blocks contribute nothing). */
+/**
+ * Collect the text of an ACP content block (non-text blocks contribute nothing).
+ * @param content - the content block off a streamed `agent_message_chunk`.
+ * @returns the block's text, or `''` for a non-text block.
+ */
 export function acpContentText(content: AcpContentBlock): string {
   return content.type === 'text' ? content.text : ''
 }
 
-/** Translate the harness prompt blocks into ACP prompt blocks (text only). */
+/**
+ * Translate the harness prompt blocks into ACP prompt blocks (text only).
+ * @param prompt - the harness prompt; non-text blocks are dropped.
+ * @returns the ACP text blocks, in order.
+ */
 export function toAcpPrompt(prompt: ContentBlock[]): AcpContentBlock[] {
   const blocks: AcpContentBlock[] = []
   for (const block of prompt) {
@@ -206,6 +224,11 @@ function exitsWithin(child: ChildProcess, ms: number): Promise<boolean> {
  * failure (a spawn/transport/RPC error resolves with `stopReason: 'error'`), per
  * the seam contract. `cancel()` sends `session/cancel`; `dispose()` kills the
  * subprocess and awaits its exit (quiescent teardown).
+ * @param request - the start request; the driver consumes `prompt` and `signal`
+ * (an already-aborted signal yields an inert `aborted` run with no spawn).
+ * @param spec - the resolved spawn spec: command/args/cwd, env, permission
+ * policy, dispose graces, and the optional error sink.
+ * @returns the live run handle for the child subprocess.
  */
 export function startAcpRun(request: SubagentStartRequest, spec: AcpRunSpec): SubagentRun {
   const id = AgentId(randomUUID())
diff --git a/packages/subagent/subagent-fork/src/index.ts b/packages/subagent/subagent-fork/src/index.ts
index b6d0c10e44..1cd00472e9 100644
--- a/packages/subagent/subagent-fork/src/index.ts
+++ b/packages/subagent/subagent-fork/src/index.ts
@@ -47,6 +47,8 @@ export const Config: z<Config> = z.object({
  * empty — i.e. fresh — child). The result is contiguous from seq 0 (the live
  * log keeps `seq === index`), so it is a valid session seed; the in-flight,
  * unbalanced turn is dropped so the invariants replay accepts it.
+ * @param parent - the agent whose session log to slice.
+ * @returns the seed events, contiguous from seq 0; empty when no turn has completed.
  */
 export function completedTurnPrefix(parent: Agent): SessionEvent[] {
   const events = parent.session.events
diff --git a/packages/subagent/subagent-inprocess/src/index.ts b/packages/subagent/subagent-inprocess/src/index.ts
index 1107926aa2..4b657ee810 100644
--- a/packages/subagent/subagent-inprocess/src/index.ts
+++ b/packages/subagent/subagent-inprocess/src/index.ts
@@ -34,7 +34,11 @@ declare module '@deepseek-ai/dsh-agent' {
   }
 }
 
-/** Read an agent's delegation depth (absent ⇒ a top-level agent, depth 0). */
+/**
+ * Read an agent's delegation depth (absent ⇒ a top-level agent, depth 0).
+ * @param agent - the agent whose options may carry `subagentDepth`.
+ * @returns 0 for a top-level agent, its parent's depth + 1 for a subagent.
+ */
 export function depthOf(agent: Agent): number {
   return agent.options.subagentDepth ?? 0
 }
@@ -88,6 +92,13 @@ export interface InProcessRunOptions {
  * the matching `turn/end.reason` the stop reason. `dispose()` delegates to the
  * factory's {@link AgentHandle.dispose} (stop loop → await quiescence → remove
  * session); `cancel()` cancels the child's in-flight turn.
+ *
+ * Throws {@link SubagentDepthError} before creating anything when the child's
+ * depth (parent depth + 1) would exceed `request.maxDepth`.
+ * @param ctx - the context whose `agents` factory creates and owns the child.
+ * @param request - the start request (prompt, parent, signal, per-child options).
+ * @param options - the backend's inputs: provider name plus the optional seed.
+ * @returns the live run handle for the child agent.
  */
 export function startInProcessRun(
   ctx: Context,
diff --git a/packages/subagent/subagent/src/types.ts b/packages/subagent/subagent/src/types.ts
index ef76a96e5d..e88c77428a 100644
--- a/packages/subagent/subagent/src/types.ts
+++ b/packages/subagent/subagent/src/types.ts
@@ -93,6 +93,7 @@ export interface SubagentStopReasonMap {
   refusal: 'refusal'
 }
 
+/** The union over {@link SubagentStopReasonMap} — widens automatically as backends merge in variants. */
 export type SubagentStopReason = SubagentStopReasonMap[keyof SubagentStopReasonMap]
 
 /**
diff --git a/packages/support/llm-replay/src/index.ts b/packages/support/llm-replay/src/index.ts
index 78f46e705e..3a09947231 100644
--- a/packages/support/llm-replay/src/index.ts
+++ b/packages/support/llm-replay/src/index.ts
@@ -124,6 +124,8 @@ export interface SessionScript {
  * Parse a session `.jsonl` buffer into its event list. Line 0 is the session
  * header (a `{type:'session',…}` record), every subsequent non-empty line is a
  * {@link SessionEvent}. The header is skipped; malformed lines fail loud.
+ * @param text - the raw `.jsonl` file contents.
+ * @returns every event after the header, in log order.
  */
 export function parseSessionLog(text: string): SessionEvent[] {
   const lines = text.split('\n').filter(line => line.trim().length > 0)
@@ -147,6 +149,8 @@ export function parseSessionLog(text: string): SessionEvent[] {
  * own model calls; absent ⇒ 0). A header missing a field falls back to a stable
  * default (`''` / `0` / `0`) rather than throwing: a no-model fixture is
  * header-only and still orders fine as the single (primary) script.
+ * @param text - the raw `.jsonl` file contents (only the header line is read).
+ * @returns the header's `id`, `createdAt`, and `seedLength`, defaulted when absent.
  */
 export function parseSessionHeader(text: string): { id: string; createdAt: number; seedLength: number } {
   const firstLine = text.split('\n').find(line => line.trim().length > 0) ?? '{}'
@@ -176,6 +180,8 @@ export function parseSessionHeader(text: string): { id: string; createdAt: numbe
  * sidecar with an explicit `throw` (or `hang`) entry instead. {@link
  * deriveReplayScript} throws, naming the offending `(turn, step)`, so a missing
  * override fails loud rather than silently replaying a thrown call as success.
+ * @param events - the recorded session's events; only `assistant/chunk` is consulted.
+ * @returns one `chunks` entry per recorded model call, in call order.
  */
 export function deriveReplayScript(events: SessionEvent[]): ReplayEntry[] {
   const script: ReplayEntry[] = []
@@ -214,6 +220,8 @@ export function deriveReplayScript(events: SessionEvent[]): ReplayEntry[] {
  * Fail-loud if the JSONL fixture is missing (the scenario was never recorded) —
  * never silently returns an empty script, so a coverage hole can't masquerade
  * as a passing replay.
+ * @param config - the fixture paths; only `file` and `overrideFile` are consulted.
+ * @returns the primary session's replay entries.
  */
 export function loadReplayScript(config: ReplayConfig): ReplayEntry[] {
   if (config.overrideFile !== undefined && existsSync(config.overrideFile)) {
@@ -241,6 +249,8 @@ export function loadReplayScript(config: ReplayConfig): ReplayEntry[] {
  * the parent issues the FIRST model call (it must stream before it can delegate
  * in the synchronous nested cut), so binding it to the first live session is
  * correct regardless of a timestamp tie.
+ * @param config - the fixture paths: the primary log plus any recorded child logs.
+ * @returns the primary script first, then the child scripts in bind order.
  */
 export function loadSessionScripts(config: ReplayConfig): SessionScript[] {
   const primaryEntries = loadReplayScript(config)
@@ -355,6 +365,9 @@ async function* replayEntry(entry: ReplayEntry, signal: AbortSignal | undefined)
  * Each per-session cursor advances synchronously at listener-invocation time
  * (not lazily inside the generator) so call ORDER within a session, not
  * iteration order, fixes the mapping.
+ * @param ctx - the context whose `llm/stream` waterfall the listener short-circuits.
+ * @param config - the resolved fixture paths (env-var defaulting is `apply`'s job).
+ * @returns the `ctx.on` disposer that removes the listener.
  */
 export function installLlmReplay(ctx: Context, config: ReplayConfig): () => void {
   const scripts = loadSessionScripts(config)
@@ -408,6 +421,7 @@ export function installLlmReplay(ctx: Context, config: ReplayConfig): () => void
 export const name = 'llm-replay'
 export const inject = ['llm']
 
+/** Plugin config: the {@link ReplayConfig} inputs, each defaulting to its `DSH_SNAPSHOT_*` env var in `apply`. */
 export interface Config {
   /** Override the fixture path; defaults to `$DSH_SNAPSHOT_FILE`. */
   file?: string
diff --git a/packages/ui/acp/src/codec.ts b/packages/ui/acp/src/codec.ts
index 444e71545c..3830dba676 100644
--- a/packages/ui/acp/src/codec.ts
+++ b/packages/ui/acp/src/codec.ts
@@ -39,6 +39,8 @@ import type { ContentBlock as AcpContentBlock, StopReason } from '@agentclientpr
  *                 hook before any step ran — ACP has no "rejected" reason, and a
  *                 blocked prompt is, from the client's view, the prompt not being
  *                 carried out; `cancelled` is the closest legal wire reason)
+ * @param reason - the harness turn-end reason to translate.
+ * @returns the legal ACP wire value per the mapping above.
  */
 export function turnEndToStopReason(reason: TurnEndReason): StopReason {
   switch (reason.kind) {
@@ -71,6 +73,8 @@ export function turnEndToStopReason(reason: TurnEndReason): StopReason {
  * `reasoning` is surfaced via `agent_thought_chunk`
  * streaming rather than as a message block, and `tool-call`/`tool-result`
  * are handled by the tool-call update path.
+ * @param block - the harness content block to translate.
+ * @returns the ACP block, or `undefined` for a kind with no message-content mapping.
  */
 export function harnessBlockToAcpContent(block: ContentBlock): AcpContentBlock | undefined {
   switch (block.type) {
@@ -89,6 +93,8 @@ export function harnessBlockToAcpContent(block: ContentBlock): AcpContentBlock |
  * concatenated verbatim; resource links become explicit textual references so
  * baseline ACP clients can point at files without the bridge silently dropping
  * that context.
+ * @param prompt - the ACP prompt blocks to flatten.
+ * @returns the concatenated text, with resource links rendered as bracketed references.
  */
 export function acpPromptToText(prompt: readonly AcpContentBlock[]): string {
   return prompt
@@ -109,6 +115,8 @@ export function acpPromptToText(prompt: readonly AcpContentBlock[]): string {
  * Whether an ACP prompt contains content the bridge cannot accept. Baseline ACP
  * requires `text` and `resource_link`; richer inline payloads (`resource`,
  * image, audio, …) are rejected rather than silently dropped.
+ * @param prompt - the ACP prompt blocks to inspect.
+ * @returns `true` when any block is neither `text` nor `resource_link`.
  */
 export function promptHasUnsupportedContent(prompt: readonly AcpContentBlock[]): boolean {
   return prompt.some(block => block.type !== 'text' && block.type !== 'resource_link')
diff --git a/packages/ui/acp/src/index.ts b/packages/ui/acp/src/index.ts
index a819e607d0..b4fa277311 100644
--- a/packages/ui/acp/src/index.ts
+++ b/packages/ui/acp/src/index.ts
@@ -701,6 +701,8 @@ export function apply(ctx: Context, config: AcpConfig): void {
  * Build per-agent options from the plugin config, omitting absent fields
  * (exactOptionalPropertyTypes: never assign `undefined` to an optional key).
  * Exported for unit coverage of both the present and absent branches.
+ * @param config - the plugin config carrying the optional model name.
+ * @returns the per-agent options, with `model` present only when configured.
  */
 export function agentOptions(config: AcpConfig): { model?: string } {
   return {
@@ -764,6 +766,16 @@ function validateMcpServers(params: { mcpServers?: unknown[] }): void {
  *
  * Other event types (turn/step boundaries, context/message, …) produce
  * no client update.
+ * @param sessionId - the ACP session id stamped on every emitted notification.
+ * @param event - the harness session event to translate.
+ * @param notify - sink for each produced `session/update` notification; called
+ * zero or more times per event (best-effort UI feed, never load-bearing).
+ * @param presenter - resolves tool-owned render intent for tool events;
+ * defaults to the generic-fallback {@link nullToolPresenter}.
+ * @param terminal - the connection's terminal-rendering context; defaults to
+ * disabled (the plain-text console-block fallback).
+ * @param options - `includeUserMessages` (default `true`): live streaming
+ * passes `false` so a prompt the client just sent is not echoed back.
  */
 export function streamSessionEventUpdate(
   sessionId: SessionId,
@@ -825,6 +837,8 @@ export function streamSessionEventUpdate(
  * harness status triple IS `PlanEntryStatus`). The ACP client REPLACES its whole
  * plan on each `plan` update, matching the harness's whole-list-replace
  * semantics, so no per-entry diffing is needed.
+ * @param todos - the harness todo list (the whole list, not a diff).
+ * @returns the ACP plan body, one entry per todo.
  */
 export function todosToPlan(todos: TodoItem[]): Plan {
   return { entries: todos.map((todo): PlanEntry => ({ content: todo.content, priority: 'medium', status: todo.status })) }
@@ -885,7 +899,16 @@ export class ToolPresenter {
     private readonly onError: (message: string) => void = () => {},
   ) {}
 
-  /** Pending-state render intent for a `tool/call`; remembers `(name, args, card)` for the matching result. */
+  /**
+   * Pending-state render intent for a `tool/call`; remembers `(name, args, card)`
+   * for the matching result.
+   * @param callId - the call id the matching `tool/result` will look up.
+   * @param name - the tool name, resolved against the registry for `presentCall`.
+   * @param argsJson - the raw arguments JSON from the event; parsed for the view
+   * (a non-JSON string is surfaced raw).
+   * @returns the tool-owned view, or the generic fallback (title = tool name,
+   * kind `other`, parsed args as raw input) when the tool defines none or threw.
+   */
   call(callId: CallId, name: string, argsJson: string): ToolCallView {
     const args = parseToolArguments(argsJson)
     let present: ToolCallView | undefined
@@ -905,7 +928,18 @@ export class ToolPresenter {
     return view
   }
 
-  /** Completed-state render intent for a `tool/result`; consumes the remembered `(name, args, card)`. */
+  /**
+   * Completed-state render intent for a `tool/result`; consumes the remembered
+   * `(name, args, card)`.
+   * @param callId - the id of the matching `tool/call`; an unknown or late id
+   * falls back to the raw content.
+   * @param content - the result's content blocks (the fallback and fill-in body).
+   * @param isError - whether the result is an error, forwarded to `presentResult`.
+   * @param meta - the result's machine-readable meta, forwarded when present.
+   * @returns the tool-owned view — an orphaned `terminal` result (no terminal
+   * call side) and a content-less `generic` are normalized — or the raw-content
+   * generic card when the tool defines no `presentResult` or threw.
+   */
   result(callId: CallId, content: ContentBlock[], isError: boolean, meta?: unknown): ToolResultView {
     const call = this.pending.get(callId)
     this.pending.delete(callId)
diff --git a/packages/ui/app-boot/src/index.ts b/packages/ui/app-boot/src/index.ts
index 5515501188..8f3392e913 100644
--- a/packages/ui/app-boot/src/index.ts
+++ b/packages/ui/app-boot/src/index.ts
@@ -36,6 +36,10 @@ import Loader from '@cordisjs/plugin-loader'
  * the SAME directory (the keyless replay tree). Other modes — including no
  * snapshot mode at all — use the path as-is. Returns an absolute path resolved
  * from `cwd`.
+ * @param configPath - the requested config path (absolute, or relative to `cwd`).
+ * @param snapshotMode - the bin's `$DSH_SNAPSHOT` value; only `'replay'` swaps the basename.
+ * @param cwd - the base a relative `configPath` resolves against.
+ * @returns the absolute path of the config to boot.
  */
 export function resolveConfigPath(
   configPath: string, snapshotMode: string | undefined, cwd: string = process.cwd(),
@@ -54,6 +58,9 @@ export function resolveConfigPath(
  * them via the `!!js` tag. A present-but-unreadable `.env` is a real
  * misconfiguration: surface it via `warn` (one line, default stderr) rather
  * than silently running with the wrong environment.
+ * @param binName - the diagnostic prefix on the warn line.
+ * @param dir - the directory whose `.env` to load.
+ * @param warn - sink for the one-line misconfiguration diagnostic.
  */
 export function loadEnv(
   binName: string, dir: string = process.cwd(),
@@ -90,6 +97,9 @@ export interface FailLoudProcess {
  * STDERR (never stdout — for the ACP bin that channel carries JSON-RPC) and
  * guarantees `exit(1)`. Install before `boot()`. Returns the uninstaller
  * (tests use it; the bins run until exit and never do).
+ * @param binName - the diagnostic prefix on the fatal-failure line.
+ * @param proc - the process slice to register on; tests inject a fake.
+ * @returns the uninstaller that removes the rejection handler.
  */
 export function installFailLoud(binName: string, proc: FailLoudProcess = process): () => void {
   const handler = (err: unknown): void => {
@@ -108,6 +118,8 @@ export function installFailLoud(binName: string, proc: FailLoudProcess = process
  * entry is the one legitimate fiber-less state: `Entry.refresh()` deliberately
  * skips `init()` for it — a valid "plugin turned off" config, not a failed
  * import — so it is excluded.
+ * @param ctx - the settled context whose loader entries to audit.
+ * @param binName - the diagnostic prefix on the thrown error.
  */
 export function assertEntriesLoaded(ctx: Context, binName: string): void {
   const failed = [...ctx.loader.entries()].filter(entry => entry.fiber === undefined && !entry.disabled)
@@ -139,6 +151,10 @@ export function assertEntriesLoaded(ctx: Context, binName: string): void {
  * active under `node --expose-internals`; a consumer running a built bin must
  * pass that flag (or install the plugins where node hoists them). Relative
  * specifiers resolve against the config directory with no flag.
+ * @param binName - the diagnostic prefix for load-failure errors.
+ * @param absoluteConfigPath - the config to include; must already be absolute
+ * (see {@link resolveConfigPath}).
+ * @returns the root context once every entry has started.
  */
 export async function boot(binName: string, absoluteConfigPath: string): Promise<Context> {
   const ctx = new Context()
diff --git a/packages/ui/stdio-agent/src/stdio-chat.ts b/packages/ui/stdio-agent/src/stdio-chat.ts
index 2996e11e89..78b0a5ae5b 100644
--- a/packages/ui/stdio-agent/src/stdio-chat.ts
+++ b/packages/ui/stdio-agent/src/stdio-chat.ts
@@ -63,6 +63,10 @@ function isTTYPair(input: Readable, output: Writable): boolean {
  * directly with fakes. Returns nothing — all registration is via `ctx.on`/
  * `ctx.effect`, so fiber disposal tears every listener and the readline
  * interface down.
+ * @param ctx - the context supplying the `agents` service and the event feeds.
+ * @param config - the plugin config; defaults are re-applied here for direct
+ * callers that bypass Loader validation.
+ * @param runtime - the process-I/O seam (line source, render sink, exit hook).
  */
 export function createStdioChat(ctx: Context, config: Config, runtime: StdioRuntime): void {
   // Default here too (not just via schemastery's `.default()`): this helper is
diff --git a/packages/web/tool-web/src/fetch.ts b/packages/web/tool-web/src/fetch.ts
index 5f7334d952..9c9243e90f 100644
--- a/packages/web/tool-web/src/fetch.ts
+++ b/packages/web/tool-web/src/fetch.ts
@@ -14,7 +14,13 @@ import { assertNever } from '@deepseek-ai/dsh-llm'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 import { htmlToMarkdown } from './html.ts'
 
-/** Validate value constraints the schema DSL can't express. */
+/**
+ * Validate value constraints the schema DSL can't express: a non-blank `url`,
+ * and a positive `timeout_ms` when present. Throws a plain `Error` otherwise.
+ *
+ * @param args - the schema-validated `web_fetch` arguments.
+ * @returns the arguments renamed to the seam's camelCase request fields.
+ */
 export function parseFetchArgs(args: { url: string; timeout_ms?: number }): { url: string; timeoutMs?: number } {
   if (args.url.trim().length === 0) throw new Error('url must be a non-empty string')
   if (args.timeout_ms !== undefined && (!Number.isFinite(args.timeout_ms) || args.timeout_ms <= 0)) {
@@ -23,7 +29,13 @@ export function parseFetchArgs(args: { url: string; timeout_ms?: number }): { ur
   return { url: args.url, ...args.timeout_ms !== undefined ? { timeoutMs: args.timeout_ms } : {} }
 }
 
-/** Render a fetched body to model-facing markdown text. */
+/**
+ * Render a fetched body to model-facing markdown text.
+ *
+ * @param body - the decoded body; `html` is converted via
+ *   {@link htmlToMarkdown}, `text` passes through verbatim.
+ * @returns the text for the tool's output block.
+ */
 export function renderBody(body: WebFetchBody): string {
   switch (body.kind) {
     case 'html':
@@ -36,19 +48,35 @@ export function renderBody(body: WebFetchBody): string {
   }
 }
 
-/** Format a fetch result as one model-facing text block. */
+/**
+ * Format a fetch result as one model-facing text block.
+ *
+ * @param result - the seam's fetch outcome.
+ * @returns a `Fetched <url> (HTTP <status>)` header, the rendered body, and a
+ *   fetch-something-narrower notice when the provider truncated the content.
+ */
 export function formatFetchOutput(result: WebFetchResult): string {
   const header = `Fetched ${result.url} (HTTP ${result.statusCode})`
   const footer = result.truncated ? '\n\n(Content truncated. Fetch a more specific URL or section for the full text.)' : ''
   return `${header}\n\n${renderBody(result.body)}${footer}`
 }
 
-/** Pending-call presentation: a fetch card titled by the URL. */
+/**
+ * Pending-call presentation: a fetch card titled by the URL.
+ *
+ * @param args - the raw tool arguments; only `url` feeds the view.
+ * @returns the generic card view (`kind: 'fetch'`) shown while the call runs.
+ */
 export function presentFetchCall(args: { url: string; timeout_ms?: number }): GenericCallView {
   return { card: 'generic', title: args.url, kind: 'fetch', rawInput: args.url }
 }
 
-/** Register the `web_fetch` tool and its system-prompt guidance. */
+/**
+ * Register the `web_fetch` tool and its system-prompt guidance.
+ *
+ * @param ctx - context whose `tools` and `systemPrompt` registries receive the
+ *   registrations; both are effect-scoped and unregister on plugin dispose.
+ */
 export function applyWebFetchTool(ctx: Context): void {
   ctx.systemPrompt.section({
     name: 'tool:web_fetch',
diff --git a/packages/web/tool-web/src/html.ts b/packages/web/tool-web/src/html.ts
index 622be86fd5..d848ad6225 100644
--- a/packages/web/tool-web/src/html.ts
+++ b/packages/web/tool-web/src/html.ts
@@ -44,6 +44,10 @@ function safeFromCodePoint(code: number, fallback: string): string {
  * Convert an HTML document to a readable markdown-ish text approximation.
  * Best-effort and lossy by design — fidelity is the job of a future heavier
  * converter, not this fallback.
+ *
+ * @param html - the raw HTML source.
+ * @returns plain text with markdown headings, list bullets, and links;
+ *   whitespace collapsed to at most one blank line and trimmed.
  */
 export function htmlToMarkdown(html: string): string {
   let text = html
diff --git a/packages/web/tool-web/src/index.ts b/packages/web/tool-web/src/index.ts
index c0191c023b..78b6a4bdf3 100644
--- a/packages/web/tool-web/src/index.ts
+++ b/packages/web/tool-web/src/index.ts
@@ -33,6 +33,7 @@ export const name = 'tool-web'
 /** Services required by the web tool suite. */
 export const inject = ['tools', 'web', 'systemPrompt']
 
+/** Plugin config: which web tools to register, and the `web_search` source cap. */
 export interface Config {
   /** Register `web_search`. Defaults to true. */
   search?: boolean
diff --git a/packages/web/tool-web/src/search.ts b/packages/web/tool-web/src/search.ts
index 28e4e9a2e9..3776940cde 100644
--- a/packages/web/tool-web/src/search.ts
+++ b/packages/web/tool-web/src/search.ts
@@ -20,7 +20,13 @@ import type {} from '@deepseek-ai/dsh-system-prompt'
  */
 export const WEB_SEARCH_MAX_RESULTS = 8
 
-/** Validate value constraints the schema DSL can't express. */
+/**
+ * Validate value constraints the schema DSL can't express: a non-blank
+ * `query`. Throws a plain `Error` otherwise.
+ *
+ * @param args - the schema-validated `web_search` arguments.
+ * @returns the accepted arguments, passed through unchanged.
+ */
 export function parseSearchArgs(args: { query: string }): { query: string } {
   if (args.query.trim().length === 0) throw new Error('query must be a non-empty string')
   return { query: args.query }
@@ -38,7 +44,14 @@ function sourceLabel(url: string, title: string | undefined): string {
   }
 }
 
-/** Format a search result as one model-facing text block. */
+/**
+ * Format a search result as one model-facing text block.
+ *
+ * @param result - the seam's search outcome.
+ * @returns the provider answer (when any), a markdown source list with snippet
+ *   and date metadata (or `No results found.`), a refine-the-query note when
+ *   truncated, and a standing cite-your-sources instruction.
+ */
 export function formatSearchOutput(result: WebSearchResult): string {
   const parts: string[] = []
   if (result.content !== undefined && result.content.length > 0) parts.push(result.content)
@@ -62,12 +75,24 @@ export function formatSearchOutput(result: WebSearchResult): string {
   return parts.join('\n\n')
 }
 
-/** Pending-call presentation: a search card titled by the query. */
+/**
+ * Pending-call presentation: a search card titled by the query.
+ *
+ * @param args - the raw tool arguments; only `query` feeds the view.
+ * @returns the generic card view (`kind: 'search'`) shown while the call runs.
+ */
 export function presentSearchCall(args: { query: string }): GenericCallView {
   return { card: 'generic', title: args.query, kind: 'search', rawInput: args.query }
 }
 
-/** Register the `web_search` tool and its system-prompt guidance. `maxResults` is the deployment's source cap. */
+/**
+ * Register the `web_search` tool and its system-prompt guidance.
+ *
+ * @param ctx - context whose `tools` and `systemPrompt` registries receive the
+ *   registrations; both are effect-scoped and unregister on plugin dispose.
+ * @param maxResults - the deployment's source cap, sent as every seam
+ *   request's `maxResults`.
+ */
 export function applyWebSearchTool(ctx: Context, maxResults: number): void {
   ctx.systemPrompt.section({
     name: 'tool:web_search',
diff --git a/packages/web/web-fetch-local/src/index.ts b/packages/web/web-fetch-local/src/index.ts
index 7eb614f39a..b6f97bf0d9 100644
--- a/packages/web/web-fetch-local/src/index.ts
+++ b/packages/web/web-fetch-local/src/index.ts
@@ -30,6 +30,7 @@ export const name = 'web-fetch-local'
 /** The web seam this provider registers into. */
 export const inject = ['web']
 
+/** Plugin config: the provider's transport and size limits plus its `User-Agent` (all defaulted). */
 export interface Config {
   /** Maximum accepted request URL length. */
   maxUrlLength?: number
diff --git a/packages/web/web-fetch-local/src/policy.ts b/packages/web/web-fetch-local/src/policy.ts
index 7a76bd1af1..f37697765a 100644
--- a/packages/web/web-fetch-local/src/policy.ts
+++ b/packages/web/web-fetch-local/src/policy.ts
@@ -16,6 +16,10 @@ export type FetchableKind = 'html' | 'text'
  * enforces before any network access: http(s) only, no embedded credentials,
  * bounded length. Returns the parsed `URL`. Throws {@link WebError} otherwise.
  * (SSRF / private-network blocking is deferred — see the package RFC.)
+ *
+ * @param input - the raw URL string from the fetch request.
+ * @param maxUrlLength - inclusive upper bound on `input`'s length.
+ * @returns the parsed `URL`.
  */
 export function validateFetchUrl(input: string, maxUrlLength: number): URL {
   if (input.length > maxUrlLength) {
@@ -40,6 +44,10 @@ export function validateFetchUrl(input: string, maxUrlLength: number): URL {
  * Two URLs are same-origin when scheme, hostname, and port match. A redirect
  * that crosses origins is refused so each new origin requires a fresh tool call
  * (and thus a fresh provider/permission decision).
+ *
+ * @param a - one of the two URLs to compare.
+ * @param b - the other URL to compare.
+ * @returns true when `a` and `b` share scheme, hostname, and port.
  */
 export function isSameOrigin(a: URL, b: URL): boolean {
   return a.protocol === b.protocol && a.hostname === b.hostname && a.port === b.port
@@ -49,6 +57,10 @@ export function isSameOrigin(a: URL, b: URL): boolean {
  * Classify a response `Content-Type` into a decodable body kind, or `undefined`
  * for an unsupported (e.g. binary) type. `text/html` and `application/xhtml+xml`
  * are `html`; other `text/*` plus a few structured text types are `text`.
+ *
+ * @param contentType - the raw `Content-Type` header, or `null` when the
+ *   response carries none (unsupported).
+ * @returns the decodable kind, or `undefined` for an unsupported type.
  */
 export function classifyContentType(contentType: string | null): FetchableKind | undefined {
   const mime = (contentType ?? '').replace(/;.*$/s, '').trim().toLowerCase()
@@ -63,6 +75,10 @@ export function classifyContentType(contentType: string | null): FetchableKind |
  * or `undefined` when absent. The provider feeds this label to `TextDecoder`
  * so a non-UTF-8 response is decoded with its declared encoding rather than
  * silently mangled into replacement characters.
+ *
+ * @param contentType - the raw `Content-Type` header, or `null` when the
+ *   response carries none.
+ * @returns the lower-cased charset label, or `undefined` when none is declared.
  */
 export function parseCharset(contentType: string | null): string | undefined {
   const match = /;\s*charset\s*=\s*"?([^";]+)"?/i.exec(contentType ?? '')
@@ -74,6 +90,10 @@ export function parseCharset(contentType: string | null): string | undefined {
  * none is declared. Throws {@link WebError} `WEB_UNSUPPORTED_CONTENT_TYPE` when
  * the label is present but not a charset `TextDecoder` recognizes — better to
  * fail loudly than return mojibake.
+ *
+ * @param charset - the declared charset label (from {@link parseCharset}), or
+ *   `undefined` to default to UTF-8.
+ * @returns a decoder for the declared (or defaulted) encoding.
  */
 export function decoderForCharset(charset: string | undefined): TextDecoder {
   if (charset === undefined) return new TextDecoder('utf-8')
diff --git a/packages/web/web-search-deepseek/src/index.ts b/packages/web/web-search-deepseek/src/index.ts
index c993fa8808..2c3f0ede3b 100644
--- a/packages/web/web-search-deepseek/src/index.ts
+++ b/packages/web/web-search-deepseek/src/index.ts
@@ -44,6 +44,7 @@ export const name = 'web-search-deepseek'
 /** The web seam this provider registers into. */
 export const inject = ['web']
 
+/** Plugin config (all optional — `apply` fills env-var and constant defaults). */
 export interface Config {
   /** DeepSeek API key. Falls back to `$DEEPSEEK_API_KEY`. Empty → unavailable. */
   apiKey?: string
diff --git a/packages/web/web-search-deepseek/src/provider.ts b/packages/web/web-search-deepseek/src/provider.ts
index 40566b4f75..0406f86510 100644
--- a/packages/web/web-search-deepseek/src/provider.ts
+++ b/packages/web/web-search-deepseek/src/provider.ts
@@ -62,6 +62,7 @@ export const DEEPSEEK_DEFAULT_MAX_USES = 5
 /** Attribution header sent on every request. Bump with the package version. */
 const USER_AGENT = 'deepseek-harness/0.0.1'
 
+/** Resolved provider options (the plugin's `apply` supplies env-var and constant defaults). */
 export interface DeepSeekSearchProviderOptions {
   /** DeepSeek API key. Empty/absent → `status()` reports `missing-credential`. */
   apiKey: string
@@ -82,6 +83,9 @@ export interface DeepSeekSearchProviderOptions {
  * is the snippet surface: Anthropic `web_search_result` items carry
  * `url`/`title`/`page_age` but typically NO inline snippet — the excerpt lives
  * in a separate `text` block's citation, keyed by `url` (first occurrence wins).
+ *
+ * @param blocks - the response's content blocks; non-`text` blocks are skipped.
+ * @returns the `url → cited_text` map (empty when no citations are present).
  */
 export function citationSnippets(blocks: readonly ContentBlock[]): Map<string, string> {
   const map = new Map<string, string>()
@@ -106,6 +110,10 @@ export function citationSnippets(blocks: readonly ContentBlock[]): Map<string, s
  * Throws `WEB_PROVIDER_ERROR` (strict mode) when no `web_search_tool_result`
  * block is present — native search did not trigger, and prose-scraping is not a
  * fallback.
+ *
+ * @param query - the original request query, echoed on the result.
+ * @param response - the parsed Messages response body.
+ * @returns the normalized result with deduped, snippet-joined sources.
  */
 export function mapAnthropicResponse(query: string, response: AnthropicResponse): WebSearchResult {
   const blocks = response.content ?? []
diff --git a/packages/web/web-search-exa/src/index.ts b/packages/web/web-search-exa/src/index.ts
index 39a20b16a4..fc284dd79a 100644
--- a/packages/web/web-search-exa/src/index.ts
+++ b/packages/web/web-search-exa/src/index.ts
@@ -35,6 +35,7 @@ export const name = 'web-search-exa'
 /** The web seam this provider registers into. */
 export const inject = ['web']
 
+/** Plugin config (all optional — `apply` fills env-var and constant defaults). */
 export interface Config {
   /** Exa API key. Falls back to `$EXA_API_KEY`. Empty → provider unavailable. */
   apiKey?: string
diff --git a/packages/web/web-search-exa/src/provider.ts b/packages/web/web-search-exa/src/provider.ts
index f187f90344..41cf86e244 100644
--- a/packages/web/web-search-exa/src/provider.ts
+++ b/packages/web/web-search-exa/src/provider.ts
@@ -37,6 +37,7 @@ export const EXA_DEFAULT_HIGHLIGHTS_PER_RESULT = 1
 /** Attribution header sent on every request. Bump with the package version. */
 const USER_AGENT = 'deepseek-harness/0.0.1'
 
+/** Resolved provider options (the plugin's `apply` supplies env-var and constant defaults). */
 export interface ExaSearchProviderOptions {
   /** Exa API key. Empty/absent → `status()` reports `missing-credential`. */
   apiKey: string
@@ -54,6 +55,10 @@ export interface ExaSearchProviderOptions {
  * Map one Exa result to a normalized source, or `undefined` when it carries no
  * portable snippet (an entry with no highlight is dropped — the seam has no
  * other field to derive a snippet from, and inventing one would lie).
+ *
+ * @param result - one entry of Exa's `results[]`.
+ * @returns the normalized source, or `undefined` when the entry has no
+ *   non-blank highlight.
  */
 export function mapExaResult(result: ExaResult): WebSearchSource | undefined {
   const snippet = result.highlights?.find(highlight => highlight.trim().length > 0)
@@ -66,7 +71,14 @@ export function mapExaResult(result: ExaResult): WebSearchSource | undefined {
   }
 }
 
-/** Map an Exa response envelope to a normalized search result. */
+/**
+ * Map an Exa response envelope to a normalized search result.
+ *
+ * @param query - the original request query, echoed on the result.
+ * @param response - the parsed `POST /search` response body.
+ * @returns the normalized result; snippet-less entries are dropped
+ *   ({@link mapExaResult}).
+ */
 export function mapExaResponse(query: string, response: ExaSearchResponse): WebSearchResult {
   const sources = (response.results ?? [])
     .map(mapExaResult)
diff --git a/packages/web/web-search-perplexity/src/index.ts b/packages/web/web-search-perplexity/src/index.ts
index 3d375eaabb..b71d5052d6 100644
--- a/packages/web/web-search-perplexity/src/index.ts
+++ b/packages/web/web-search-perplexity/src/index.ts
@@ -29,6 +29,7 @@ export const name = 'web-search-perplexity'
 /** The web seam this provider registers into. */
 export const inject = ['web']
 
+/** Plugin config (all optional — `apply` fills env-var and constant defaults). */
 export interface Config {
   /** Perplexity API key. Falls back to `$PERPLEXITY_API_KEY`. Empty → unavailable. */
   apiKey?: string
diff --git a/packages/web/web-search-perplexity/src/provider.ts b/packages/web/web-search-perplexity/src/provider.ts
index ed72ea82c3..8338c6f616 100644
--- a/packages/web/web-search-perplexity/src/provider.ts
+++ b/packages/web/web-search-perplexity/src/provider.ts
@@ -41,6 +41,7 @@ export type PerplexityRecency = 'day' | 'week' | 'month' | 'year'
 /** Attribution header sent on every request. Bump with the package version. */
 const USER_AGENT = 'deepseek-harness/0.0.1'
 
+/** Resolved provider options (the plugin's `apply` supplies env-var and constant defaults). */
 export interface PerplexitySearchProviderOptions {
   /** Perplexity API key. Empty/absent → `status()` reports `missing-credential`. */
   apiKey: string
@@ -54,7 +55,12 @@ export interface PerplexitySearchProviderOptions {
   searchRecency?: PerplexityRecency
 }
 
-/** Map one structured Perplexity search result to a normalized source. */
+/**
+ * Map one structured Perplexity search result to a normalized source.
+ *
+ * @param result - one entry of the response's `search_results[]`.
+ * @returns the normalized source; blank fields are omitted rather than set empty.
+ */
 export function mapPerplexityResult(result: PerplexitySearchResult): WebSearchSource {
   return {
     url: result.url,
@@ -68,6 +74,10 @@ export function mapPerplexityResult(result: PerplexitySearchResult): WebSearchSo
  * Map a Perplexity response envelope to a normalized search result. Prefers
  * structured `search_results[]`; falls back to URL-only `citations[]` (those
  * sources carry just a `url`) only when `search_results` is absent.
+ *
+ * @param query - the original request query, echoed on the result.
+ * @param response - the parsed chat-completions response body.
+ * @returns the normalized result; `content` is omitted when the answer is empty.
  */
 export function mapPerplexityResponse(query: string, response: PerplexityResponse): WebSearchResult {
   const content = response.choices?.[0]?.message?.content
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 4a7a417e02..cbdf7a688d 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -40,7 +40,9 @@
  * a stale `@param` naming no real parameter errors. Violations aggregate into
  * ONE error listing every offender. The tags are enforcement-only: parseJsDoc
  * stops prose at the first block tag, so they never change the rendered
- * catalog. The INHERITED
+ * catalog. The parsing + check helpers live in `scripts/jsdoc.ts`, shared with
+ * the whole-export-surface gate (`scripts/verify-export-jsdoc.ts`) so
+ * "documented" means the same thing on both surfaces. The INHERITED
  * tier (cordis core + loader/hmr/timer) is pinned vendor source a plugin author
  * also sees; it is rendered tersely (name + one-line + source pointer) from a
  * curated table in this script, NOT elevated to the harness tier's prominence.
@@ -53,6 +55,7 @@
 import { globSync, readFileSync, writeFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 import ts from 'typescript'
+import { checkParams, checkReturns, parseJsDoc, parseTags, pointer, rawJsDoc, reportViolations, type Mode } from './jsdoc.ts'
 
 const root = resolve(import.meta.dirname, '..')
 const OUT_EVENTS = 'docs/cordis-catalog/events.md'
@@ -62,9 +65,6 @@ const OUT_SERVICES = 'docs/cordis-catalog/services.md'
  * doc-typecheck, since a bare signature fragment is not standalone-compilable). */
 const FENCE = 'ts cordis-catalog'
 
-/** A dispatch mode, rendered as the badge after an event name. */
-type Mode = 'emit' | 'waterfall' | 'parallel' | 'serial'
-
 /**
  * Cross-link map: a type name that appears in a signature → the
  * core-data-structures page that documents it (path relative to the catalogs'
@@ -146,132 +146,6 @@ interface InheritedEntry {
   source: string
 }
 
-/** Repo-relative source pointer `file:line` for a node's first character. */
-function pointer(rel: string, sf: ts.SourceFile, node: ts.Node): string {
-  const { line } = sf.getLineAndCharacterOfPosition(node.getStart(sf))
-  return `${rel}:${line + 1}`
-}
-
-/** The raw `/** … *​/` JSDoc block immediately preceding a node, or '' if none. */
-function rawJsDoc(text: string, node: ts.Node): string {
-  const ranges = ts.getLeadingCommentRanges(text, node.getFullStart()) ?? []
-  const jsdoc = ranges.filter(r => text.slice(r.pos, r.pos + 3) === '/**').at(-1)
-  return jsdoc ? text.slice(jsdoc.pos, jsdoc.end) : ''
-}
-
-/**
- * Parse a raw JSDoc block into description prose + the `@mode` tag (when
- * present). Output obeys the repo's markdown conventions so the generated file
- * passes verify-md-wrap: each prose paragraph collapses to ONE physical line,
- * and a `-` bullet list is preserved with each item on its own single line
- * (continuation lines folded in). `{@link Foo}` unwraps to `Foo`. Description
- * prose ends at the FIRST block tag (standard JSDoc semantics): tag lines and
- * their continuation lines are never prose, so `@param`/`@returns` blocks are
- * invisible to the rendered catalog.
- */
-function parseJsDoc(raw: string): { doc: string; mode: Mode | null } {
-  const inner = raw
-    .replace(/^\/\*\*/, '')
-    .replace(/\*\/$/, '')
-    .split('\n')
-    .map(l => l.replace(/^\s*\*?\s?/, '').replace(/\s+$/, ''))
-  let mode: Mode | null = null
-  let inTags = false
-  const blocks: string[] = []
-  let para: string[] = []
-  let list: string[] = []
-  let item: string[] = []
-  const join = (parts: string[]): string => parts.join(' ').replace(/\s+/g, ' ').trim()
-  const flushItem = (): void => {
-    if (item.length) list.push(join(item))
-    item = []
-  }
-  const flushList = (): void => {
-    flushItem()
-    if (list.length) blocks.push(list.join('\n')) // one block, items on own lines
-    list = []
-  }
-  const flushPara = (): void => {
-    flushList()
-    if (para.length) blocks.push(join(para))
-    para = []
-  }
-  for (const line of inner) {
-    const m = /^@mode\s+(emit|waterfall|parallel|serial)\s*$/.exec(line)
-    if (m) { mode = m[1] as Mode; flushPara(); inTags = true; continue }
-    if (line.startsWith('@')) { flushPara(); inTags = true; continue }
-    if (inTags) continue // block-tag territory: continuations are never prose
-    if (line.trim() === '') { flushPara(); continue }
-    if (/^-\s+/.test(line)) {
-      // A list item starts: a pending paragraph (e.g. an intro line directly
-      // above the list, no blank between) flushes FIRST so it renders above.
-      flushItem()
-      if (para.length) { blocks.push(join(para)); para = [] }
-      item.push(line)
-      continue
-    }
-    if (item.length) { item.push(line); continue } // continuation of current item
-    para.push(line)
-  }
-  flushPara()
-  const doc = blocks.join('\n\n').replace(/\{@link\s+([^}]+)\}/g, '$1').trim()
-  return { doc, mode }
-}
-
-/**
- * Parse the block tags of a raw JSDoc comment for the completeness checks:
- * every `@param name — description` entry plus the `@returns` description.
- * Standard JSDoc block-tag semantics — a tag's description runs across
- * continuation lines until the next tag or a blank line, and the `-`/`—`
- * separator after a param name is optional. `[name]` optional-brackets unwrap
- * to `name`. Rendering never sees these: parseJsDoc stops prose at the first
- * block tag.
- */
-function parseTags(raw: string): { params: Map<string, string>; returns: string | null } {
-  const inner = raw
-    .replace(/^\/\*\*/, '')
-    .replace(/\*\/$/, '')
-    .split('\n')
-    .map(l => l.replace(/^\s*\*?\s?/, '').replace(/\s+$/, ''))
-  const params = new Map<string, string>()
-  let returns: string | null = null
-  let sink: ((text: string) => void) | null = null
-  for (const line of inner) {
-    const param = /^@param\s+(\[?[\w$]+\]?)\s*(?:[-—–]\s*)?(.*)$/.exec(line)
-    if (param) {
-      const name = (param[1] ?? '').replace(/^\[|\]$/g, '')
-      let acc = param[2] ?? ''
-      params.set(name, acc)
-      sink = (t) => { acc = acc ? `${acc} ${t}` : t; params.set(name, acc) }
-      continue
-    }
-    const ret = /^@returns?(?:\s+[-—–]?\s*(.*))?$/.exec(line)
-    if (ret) {
-      let acc = ret[1] ?? ''
-      returns = acc
-      sink = (t) => { acc = acc ? `${acc} ${t}` : t; returns = acc }
-      continue
-    }
-    if (line.startsWith('@') || line.trim() === '') { sink = null; continue }
-    sink?.(line.trim())
-  }
-  return { params, returns }
-}
-
-/**
- * Throw one aggregate error for every completeness violation a walk collected.
- * Aggregation (vs the fail-fast the @mode check used to do) is deliberate: a
- * remediation pass sees the whole list at once instead of replaying the gate
- * once per offender.
- */
-function reportViolations(violations: string[]): void {
-  if (violations.length === 0) return
-  throw new Error(
-    `gen-cordis-catalog: ${violations.length} JSDoc completeness violation(s) (see AGENTS.md):\n`
-    + violations.map(v => `  ${v}`).join('\n'),
-  )
-}
-
 /** Find the `declare module 'cordis'` body in a source file, or null. */
 function cordisModuleBody(sf: ts.SourceFile): ts.ModuleBlock | null {
   for (const stmt of sf.statements) {
@@ -334,27 +208,13 @@ export function collectEvents(scanRoot: string = root): EventEntry[] {
         // (mode machinery, documented once by @mode semantics). Documenting an
         // exempt parameter anyway is allowed — only absence is checked.
         const { params } = parseTags(raw)
-        for (const p of member.parameters) {
-          if (!ts.isIdentifier(p.name)) {
-            violations.push(`${where}: parameter '${p.name.getText(sf)}' is a binding pattern; the event surface needs simple identifier parameters so @param can name them.`)
-            continue
-          }
-          const pname = p.name.text
-          if (pname === 'this' || (hasNext && p === last)) continue
-          const desc = params.get(pname)
-          if (desc === undefined) violations.push(`${where} is missing @param ${pname}.`)
-          else if (!desc.trim()) violations.push(`${where}: @param ${pname} has an empty description.`)
-        }
-        for (const tag of params.keys()) {
-          if (!member.parameters.some(p => ts.isIdentifier(p.name) && p.name.text === tag)) {
-            violations.push(`${where}: @param ${tag} does not match any parameter (stale tag?).`)
-          }
-        }
+        checkParams(where, 'event', member.parameters, params, sf,
+          p => (ts.isIdentifier(p.name) && p.name.text === 'this') || (hasNext && p === last), violations)
         if (mode) entries.push({ name, scope: name.split('/')[0] ?? name, signature, mode, doc, source: src })
       }
     }
   }
-  reportViolations(violations)
+  reportViolations('gen-cordis-catalog', violations)
   return entries
 }
 
@@ -415,35 +275,12 @@ export function collectServices(scanRoot: string = root): ServiceEntry[] {
         if (!raw) { violations.push(`${where} has no JSDoc.`); continue }
         if (!parseJsDoc(raw).doc) violations.push(`${where} has no description prose above its block tags.`)
         const { params, returns } = parseTags(raw)
-        // Every parameter needs a non-empty @param; a `this` receiver
-        // annotation is not payload and is exempt.
-        for (const p of member.parameters) {
-          if (!ts.isIdentifier(p.name)) {
-            violations.push(`${where}: parameter '${p.name.getText(sf)}' is a binding pattern; the service surface needs simple identifier parameters so @param can name them.`)
-            continue
-          }
-          const pname = p.name.text
-          if (pname === 'this') continue
-          const desc = params.get(pname)
-          if (desc === undefined) violations.push(`${where} is missing @param ${pname}.`)
-          else if (!desc.trim()) violations.push(`${where}: @param ${pname} has an empty description.`)
-        }
-        for (const tag of params.keys()) {
-          if (!member.parameters.some(p => ts.isIdentifier(p.name) && p.name.text === tag)) {
-            violations.push(`${where}: @param ${tag} does not match any parameter (stale tag?).`)
-          }
-        }
-        // A non-void result needs a non-empty @returns. The return type must be
-        // ANNOTATED: a pure-AST walk cannot classify an inferred return. On a
-        // `void`/`Promise<void>` method @returns stays optional (resolution
-        // timing can be worth documenting), never required.
-        const rt = member.type?.getText(sf).replace(/\s+/g, ' ')
-        if (rt === undefined) {
-          violations.push(`${where} has no return type annotation; annotate it explicitly so the gate can classify the result.`)
-        } else if (!/^(void|Promise<void>)$/.test(rt)) {
-          if (returns === null) violations.push(`${where} is missing @returns (return type: ${rt}).`)
-          else if (!returns.trim()) violations.push(`${where}: @returns has an empty description.`)
-        }
+        // Every parameter needs a non-empty @param (`this` receiver exempt),
+        // and a non-void ANNOTATED result needs a non-empty @returns — the
+        // shared checkers carry the exact contract.
+        checkParams(where, 'service', member.parameters, params, sf,
+          p => ts.isIdentifier(p.name) && p.name.text === 'this', violations)
+        checkReturns(where, member.type, returns, sf, violations)
       }
       entries.push({
         key,
@@ -455,7 +292,7 @@ export function collectServices(scanRoot: string = root): ServiceEntry[] {
       })
     }
   }
-  reportViolations(violations)
+  reportViolations('gen-cordis-catalog', violations)
   return entries.sort((a, b) => a.key.localeCompare(b.key))
 }
 
diff --git a/scripts/jsdoc.ts b/scripts/jsdoc.ts
new file mode 100644
index 0000000000..d2f6d30503
--- /dev/null
+++ b/scripts/jsdoc.ts
@@ -0,0 +1,216 @@
+/**
+ * Shared JSDoc parsing and completeness-check helpers for the documentation
+ * gates: the cordis catalog generator (`scripts/gen-cordis-catalog.ts` — the
+ * events + `ctx.<key>` service surface) and the export-surface gate
+ * (`scripts/verify-export-jsdoc.ts` — every module-level export). One home for
+ * the mechanics so "documented" means the same thing on every gated surface:
+ * description prose ends at the first block tag; every checkable parameter
+ * needs a non-empty `@param`; a non-void ANNOTATED return needs a non-empty
+ * `@returns`; a stale `@param` naming no real parameter errors.
+ */
+
+import ts from 'typescript'
+
+/** Repo-relative source pointer `file:line` for a node's first character. */
+export function pointer(rel: string, sf: ts.SourceFile, node: ts.Node): string {
+  const { line } = sf.getLineAndCharacterOfPosition(node.getStart(sf))
+  return `${rel}:${line + 1}`
+}
+
+/** The raw `/** … *​/` JSDoc block immediately preceding a node, or '' if none. */
+export function rawJsDoc(text: string, node: ts.Node): string {
+  const ranges = ts.getLeadingCommentRanges(text, node.getFullStart()) ?? []
+  const jsdoc = ranges.filter(r => text.slice(r.pos, r.pos + 3) === '/**').at(-1)
+  return jsdoc ? text.slice(jsdoc.pos, jsdoc.end) : ''
+}
+
+/** A dispatch mode, rendered as the badge after an event name in the catalog. */
+export type Mode = 'emit' | 'waterfall' | 'parallel' | 'serial'
+
+/**
+ * Parse a raw JSDoc block into description prose + the `@mode` tag (when
+ * present). Output obeys the repo's markdown conventions so the generated
+ * catalog passes verify-md-wrap: each prose paragraph collapses to ONE physical
+ * line, and a `-` bullet list is preserved with each item on its own single
+ * line (continuation lines folded in). `{@link Foo}` unwraps to `Foo`.
+ * Description prose ends at the FIRST block tag (standard JSDoc semantics):
+ * tag lines and their continuation lines are never prose, so `@param` /
+ * `@returns` blocks are invisible to the rendered catalog.
+ * @param raw - the raw comment text including the JSDoc delimiters.
+ * @returns the collapsed description prose plus the parsed `@mode` (or null).
+ */
+export function parseJsDoc(raw: string): { doc: string; mode: Mode | null } {
+  const inner = raw
+    .replace(/^\/\*\*/, '')
+    .replace(/\*\/$/, '')
+    .split('\n')
+    .map(l => l.replace(/^\s*\*?\s?/, '').replace(/\s+$/, ''))
+  let mode: Mode | null = null
+  let inTags = false
+  const blocks: string[] = []
+  let para: string[] = []
+  let list: string[] = []
+  let item: string[] = []
+  const join = (parts: string[]): string => parts.join(' ').replace(/\s+/g, ' ').trim()
+  const flushItem = (): void => {
+    if (item.length) list.push(join(item))
+    item = []
+  }
+  const flushList = (): void => {
+    flushItem()
+    if (list.length) blocks.push(list.join('\n')) // one block, items on own lines
+    list = []
+  }
+  const flushPara = (): void => {
+    flushList()
+    if (para.length) blocks.push(join(para))
+    para = []
+  }
+  for (const line of inner) {
+    const m = /^@mode\s+(emit|waterfall|parallel|serial)\s*$/.exec(line)
+    if (m) { mode = m[1] as Mode; flushPara(); inTags = true; continue }
+    if (line.startsWith('@')) { flushPara(); inTags = true; continue }
+    if (inTags) continue // block-tag territory: continuations are never prose
+    if (line.trim() === '') { flushPara(); continue }
+    if (/^-\s+/.test(line)) {
+      // A list item starts: a pending paragraph (e.g. an intro line directly
+      // above the list, no blank between) flushes FIRST so it renders above.
+      flushItem()
+      if (para.length) { blocks.push(join(para)); para = [] }
+      item.push(line)
+      continue
+    }
+    if (item.length) { item.push(line); continue } // continuation of current item
+    para.push(line)
+  }
+  flushPara()
+  const doc = blocks.join('\n\n').replace(/\{@link\s+([^}]+)\}/g, '$1').trim()
+  return { doc, mode }
+}
+
+/**
+ * Parse the block tags of a raw JSDoc comment for the completeness checks:
+ * every `@param name — description` entry plus the `@returns` description.
+ * Standard JSDoc block-tag semantics — a tag's description runs across
+ * continuation lines until the next tag or a blank line, and the `-`/`—`
+ * separator after a param name is optional. `[name]` optional-brackets unwrap
+ * to `name`. Rendering never sees these: parseJsDoc stops prose at the first
+ * block tag.
+ * @param raw - the raw comment text including the JSDoc delimiters.
+ * @returns the `@param` name→description map plus the `@returns` description
+ * (null when the tag is absent, '' when present but empty).
+ */
+export function parseTags(raw: string): { params: Map<string, string>; returns: string | null } {
+  const inner = raw
+    .replace(/^\/\*\*/, '')
+    .replace(/\*\/$/, '')
+    .split('\n')
+    .map(l => l.replace(/^\s*\*?\s?/, '').replace(/\s+$/, ''))
+  const params = new Map<string, string>()
+  let returns: string | null = null
+  let sink: ((text: string) => void) | null = null
+  for (const line of inner) {
+    const param = /^@param\s+(\[?[\w$]+\]?)\s*(?:[-—–]\s*)?(.*)$/.exec(line)
+    if (param) {
+      const name = (param[1] ?? '').replace(/^\[|\]$/g, '')
+      let acc = param[2] ?? ''
+      params.set(name, acc)
+      sink = (t) => { acc = acc ? `${acc} ${t}` : t; params.set(name, acc) }
+      continue
+    }
+    const ret = /^@returns?(?:\s+[-—–]?\s*(.*))?$/.exec(line)
+    if (ret) {
+      let acc = ret[1] ?? ''
+      returns = acc
+      sink = (t) => { acc = acc ? `${acc} ${t}` : t; returns = acc }
+      continue
+    }
+    if (line.startsWith('@') || line.trim() === '') { sink = null; continue }
+    sink?.(line.trim())
+  }
+  return { params, returns }
+}
+
+/**
+ * Check the `@param` half of the completeness contract for one function-like
+ * declaration: every checkable parameter carries a non-empty `@param`, and no
+ * `@param` is stale. A binding-pattern parameter is a violation (it has no name
+ * for `@param` to match); an exempt parameter may be documented but its absence
+ * is never checked. Violations append to `violations` in place.
+ * @param where - the offender label violations open with, e.g. `event 'x' (file:1)`.
+ * @param surface - the surface noun for the binding-pattern message ("event", "service", "export").
+ * @param parameters - the declaration's parameter list.
+ * @param tags - the parsed `@param` name→description map from parseTags.
+ * @param sf - the source file (for rendering a binding pattern's text).
+ * @param isExempt - which parameters need no `@param` (e.g. `this`, a waterfall's trailing `next`).
+ * @param violations - the aggregate list violations append to.
+ */
+export function checkParams(
+  where: string,
+  surface: string,
+  parameters: readonly ts.ParameterDeclaration[],
+  tags: Map<string, string>,
+  sf: ts.SourceFile,
+  isExempt: (p: ts.ParameterDeclaration) => boolean,
+  violations: string[],
+): void {
+  for (const p of parameters) {
+    if (!ts.isIdentifier(p.name)) {
+      violations.push(`${where}: parameter '${p.name.getText(sf)}' is a binding pattern; the ${surface} surface needs simple identifier parameters so @param can name them.`)
+      continue
+    }
+    if (isExempt(p)) continue
+    const desc = tags.get(p.name.text)
+    if (desc === undefined) violations.push(`${where} is missing @param ${p.name.text}.`)
+    else if (!desc.trim()) violations.push(`${where}: @param ${p.name.text} has an empty description.`)
+  }
+  for (const tag of tags.keys()) {
+    if (!parameters.some(p => ts.isIdentifier(p.name) && p.name.text === tag)) {
+      violations.push(`${where}: @param ${tag} does not match any parameter (stale tag?).`)
+    }
+  }
+}
+
+/**
+ * Check the `@returns` half of the completeness contract: a non-`void` /
+ * `Promise<void>` return needs a non-empty `@returns`, and the return type must
+ * be ANNOTATED — a pure-AST walk cannot classify an inferred return. On a void
+ * declaration `@returns` stays optional (resolution timing can be worth
+ * documenting), never required. Violations append to `violations` in place.
+ * @param where - the offender label violations open with.
+ * @param typeNode - the declared return type annotation, or undefined when inferred.
+ * @param returns - the parsed `@returns` description from parseTags (null when absent).
+ * @param sf - the source file (for rendering the annotation's text).
+ * @param violations - the aggregate list violations append to.
+ */
+export function checkReturns(
+  where: string,
+  typeNode: ts.TypeNode | undefined,
+  returns: string | null,
+  sf: ts.SourceFile,
+  violations: string[],
+): void {
+  if (typeNode === undefined) {
+    violations.push(`${where} has no return type annotation; annotate it explicitly so the gate can classify the result.`)
+    return
+  }
+  const rt = typeNode.getText(sf).replace(/\s+/g, ' ')
+  if (/^(void|Promise<void>)$/.test(rt)) return
+  if (returns === null) violations.push(`${where} is missing @returns (return type: ${rt}).`)
+  else if (!returns.trim()) violations.push(`${where}: @returns has an empty description.`)
+}
+
+/**
+ * Throw one aggregate error for every completeness violation a walk collected.
+ * Aggregation (vs failing fast) is deliberate: a remediation pass sees the
+ * whole list at once instead of replaying the gate once per offender.
+ * @param gate - the reporting gate's name, prefixed to the error message.
+ * @param violations - the collected violation lines; no-op when empty.
+ */
+export function reportViolations(gate: string, violations: string[]): void {
+  if (violations.length === 0) return
+  throw new Error(
+    `${gate}: ${violations.length} JSDoc completeness violation(s) (see AGENTS.md):\n`
+    + violations.map(v => `  ${v}`).join('\n'),
+  )
+}
diff --git a/scripts/verify-export-jsdoc.ts b/scripts/verify-export-jsdoc.ts
new file mode 100644
index 0000000000..2779a53e68
--- /dev/null
+++ b/scripts/verify-export-jsdoc.ts
@@ -0,0 +1,408 @@
+/**
+ * Verify JSDoc completeness for EVERY module-level exported name of every
+ * non-vendored package (each `packages/<group>/<pkg>/src/` tree). This is the
+ * mechanical form of the AGENTS.md rule "every export has a JSDoc explaining
+ * semantics", generalizing the cordis-surface gate (`gen-cordis-catalog.ts`,
+ * which owns `interface Events` members and `ctx.<key>` service classes) to
+ * the whole export surface; the parsing + check helpers are shared via
+ * `scripts/jsdoc.ts` so "documented" means the same thing on both.
+ *
+ *   `tsx scripts/verify-export-jsdoc.ts`  → exit 1 listing every offender
+ *
+ * The contract, per exported declaration kind:
+ *
+ * - Every exported name needs JSDoc with non-empty description prose (prose
+ *   ends at the first block tag, standard JSDoc semantics).
+ * - A function-like export (function declaration, or a const with a function
+ *   initializer) additionally needs a non-empty `@param` per parameter
+ *   (`this` receiver annotations exempt; a stale `@param` errors) and a
+ *   non-empty `@returns` unless the return type is `void`/`Promise<void>`.
+ *   The walk classifies returns syntactically, so the return type must be
+ *   ANNOTATED — except a const whose DECLARATOR is type-annotated (e.g.
+ *   `export const f: Handler = …`), where the named type owns the return
+ *   contract and `@returns` stays optional.
+ * - An exported class needs class-level JSDoc; its public methods (static
+ *   included — they are reachable on the exported name) follow the function
+ *   contract, and public properties and accessors need description prose (on
+ *   a get/set pair the getter's doc covers both). A member whose name exists
+ *   on an `extends`/`implements` heritage type is EXEMPT — the seam
+ *   declaration is the doc's one home, the IDE inherits it, and re-documenting
+ *   every implementation invites drift. This is the one question the walk
+ *   asks the TYPE CHECKER (heritage members live across package boundaries);
+ *   everything else is pure AST. Constructors are exempt like the cordis
+ *   gate's: plugin classes are framework-constructed, and the class doc owns
+ *   the story.
+ * - Exported interfaces, type aliases, enums: description prose on the
+ *   declaration (member-level docs stay review's job; the highest-value
+ *   member surface — seam service classes — is already under the cordis
+ *   gate).
+ * - An exported namespace recurses (its exported members are package
+ *   surface); the namespace itself needs prose only when it does not merge
+ *   with an already-documented same-name declaration (the Config-namespace
+ *   idiom documents the class/function once, not twice).
+ * - The cordis plugin-protocol slots are exempt: top-level `name` / `inject`
+ *   / `reusable` / `Config` consts and the `apply` entry, plus the same
+ *   slots as statics on a plugin class. Their shape is fixed by the
+ *   framework, so a doc would restate the protocol — the module doc comment
+ *   and the `interface Config` carry the plugin's real semantics. (These
+ *   names are reserved by cordis convention; documenting one anyway is
+ *   allowed, only absence goes unchecked.)
+ * - Overload groups: each overload signature carries its own docs; the
+ *   implementation signature is exempt (callers never see it).
+ * - Skipped: `declare module` / `declare global` augmentation bodies (the
+ *   cordis gate's turf; an augmentation is not an export of the package) and
+ *   re-export statements with a module specifier (`export … from`) — the
+ *   defining module is walked on its own, and external definitions are not
+ *   ours to document.
+ */
+
+import { existsSync, globSync } from 'node:fs'
+import { resolve } from 'node:path'
+import ts from 'typescript'
+import { checkParams, checkReturns, parseJsDoc, parseTags, pointer, rawJsDoc } from './jsdoc.ts'
+
+const root = resolve(import.meta.dirname, '..')
+
+/** Plugin-protocol slot names exempt as statics on an exported class. */
+const PROTOCOL_STATICS = new Set(['Config', 'inject', 'name', 'reusable'])
+
+/** Plugin-protocol slot names exempt as top-level exports (const or function). */
+const PROTOCOL_EXPORTS = new Set(['Config', 'inject', 'name', 'reusable', 'apply'])
+
+/** Per-file walk state threaded through the scope recursion. */
+interface Walk {
+  /** Repo-relative path of the file being walked. */
+  rel: string
+  /** The parsed source file. */
+  sf: ts.SourceFile
+  /** Raw file text (rawJsDoc reads comment ranges out of it). */
+  text: string
+  /** The program's checker, consulted only for heritage-member lookups. */
+  checker: ts.TypeChecker
+  /** The aggregate violation list, appended in place. */
+  violations: string[]
+}
+
+/** True when a statement carries the `export` modifier. */
+function isExported(stmt: ts.Statement): boolean {
+  return ts.canHaveModifiers(stmt) && (ts.getModifiers(stmt)?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) ?? false)
+}
+
+/** True for a class member a consumer cannot reach: `private`/`protected`/`#name`. */
+function isNonPublic(member: ts.ClassElement): boolean {
+  const mods = ts.canHaveModifiers(member) ? ts.getModifiers(member) : undefined
+  return (mods?.some(m => m.kind === ts.SyntaxKind.PrivateKeyword || m.kind === ts.SyntaxKind.ProtectedKeyword) ?? false)
+    || ('name' in member && ts.isPrivateIdentifier(member.name))
+}
+
+/** True when a class member carries the `static` modifier. */
+function isStatic(member: ts.ClassElement): boolean {
+  const mods = ts.canHaveModifiers(member) ? ts.getModifiers(member) : undefined
+  return mods?.some(m => m.kind === ts.SyntaxKind.StaticKeyword) ?? false
+}
+
+/** The `this`-receiver exemption every function-like check shares. */
+function thisReceiver(p: ts.ParameterDeclaration): boolean {
+  return ts.isIdentifier(p.name) && p.name.text === 'this'
+}
+
+/**
+ * True when a member name exists on any `extends`/`implements` heritage type
+ * of the class — the member implements or overrides a documented seam
+ * declaration, which is the doc's one home (the IDE inherits it on hover).
+ * Static members are looked up on the base CONSTRUCTOR type (only an
+ * `extends` expression has one; an unresolvable or interface expression
+ * yields no property and therefore no exemption).
+ * @param cls - the class whose heritage to search.
+ * @param name - the member name to look up.
+ * @param staticSide - whether to search the constructor side instead of the instance side.
+ * @param checker - the program's type checker.
+ * @returns true when a heritage type declares the member.
+ */
+function inheritedMember(cls: ts.ClassDeclaration, name: string, staticSide: boolean, checker: ts.TypeChecker): boolean {
+  for (const clause of cls.heritageClauses ?? []) {
+    for (const t of clause.types) {
+      const type = staticSide ? checker.getTypeAtLocation(t.expression) : checker.getTypeAtLocation(t)
+      if (type.getProperty(name) !== undefined) return true
+    }
+  }
+  return false
+}
+
+/**
+ * Check description-prose presence for one labeled declaration: JSDoc must
+ * exist and carry prose above its block tags.
+ * @param where - the offender label violations open with.
+ * @param raw - the declaration's raw JSDoc block ('' if none).
+ * @param w - the walk state violations append to.
+ */
+function checkDescribed(where: string, raw: string, w: Walk): void {
+  if (!raw) w.violations.push(`${where} has no JSDoc.`)
+  else if (!parseJsDoc(raw).doc) w.violations.push(`${where} has no description prose above its block tags.`)
+}
+
+/**
+ * Check the full function contract for one labeled function-like declaration:
+ * description prose, `@param` per parameter, `@returns` on a non-void result.
+ * @param where - the offender label violations open with.
+ * @param raw - the declaration's raw JSDoc block ('' if none).
+ * @param parameters - the declaration's parameter list.
+ * @param returnType - the return type annotation, or undefined when inferred.
+ * @param returnsWaived - suppress the `@returns`/annotation requirement (a
+ * declarator-annotated const defers its return contract to the named type).
+ * @param w - the walk state violations append to.
+ */
+function checkFunctionLike(
+  where: string,
+  raw: string,
+  parameters: readonly ts.ParameterDeclaration[],
+  returnType: ts.TypeNode | undefined,
+  returnsWaived: boolean,
+  w: Walk,
+): void {
+  if (!raw) { w.violations.push(`${where} has no JSDoc.`); return }
+  if (!parseJsDoc(raw).doc) w.violations.push(`${where} has no description prose above its block tags.`)
+  const { params, returns } = parseTags(raw)
+  checkParams(where, 'export', parameters, params, w.sf, thisReceiver, w.violations)
+  if (!returnsWaived) checkReturns(where, returnType, returns, w.sf, w.violations)
+}
+
+/**
+ * Check one exported class: class-level prose, the function contract on every
+ * public method (overload implementations exempt), and description prose on
+ * public properties and accessors (a get/set pair is covered by the getter's
+ * doc). Members declared by a heritage type and the plugin-protocol statics
+ * are exempt; constructors are not checked (framework-constructed plugins,
+ * and the class doc owns the story).
+ * @param cls - the exported class declaration.
+ * @param name - the class's surface name (namespace-qualified).
+ * @param w - the walk state violations append to.
+ */
+function checkClass(cls: ts.ClassDeclaration, name: string, w: Walk): void {
+  checkDescribed(`exported class '${name}' (${pointer(w.rel, w.sf, cls)})`, rawJsDoc(w.text, cls), w)
+  const overloadSigs = new Set<string>()
+  const documentedGetters = new Set<string>()
+  for (const m of cls.members) {
+    if ('name' in m && ts.isComputedPropertyName(m.name)) continue
+    if (ts.isMethodDeclaration(m) && !m.body) overloadSigs.add(m.name.getText(w.sf))
+    if (ts.isGetAccessorDeclaration(m)) documentedGetters.add(m.name.getText(w.sf))
+  }
+  for (const m of cls.members) {
+    if (isNonPublic(m) || ts.isConstructorDeclaration(m)) continue
+    if (!('name' in m) || ts.isComputedPropertyName(m.name)) continue // computed/symbol members
+    const mname = m.name.getText(w.sf)
+    if (isStatic(m) && PROTOCOL_STATICS.has(mname)) continue // cordis plugin-protocol slot
+    if (inheritedMember(cls, mname, isStatic(m), w.checker)) continue // the heritage declaration owns the doc
+    if (ts.isMethodDeclaration(m)) {
+      if (m.body && overloadSigs.has(mname)) continue // overload implementation: the signatures carry the docs
+      checkFunctionLike(`exported class method '${name}.${mname}' (${pointer(w.rel, w.sf, m)})`, rawJsDoc(w.text, m), m.parameters, m.type, false, w)
+    } else if (ts.isGetAccessorDeclaration(m) || ts.isPropertyDeclaration(m)) {
+      const kind = ts.isPropertyDeclaration(m) ? 'property' : 'accessor'
+      checkDescribed(`exported class ${kind} '${name}.${mname}' (${pointer(w.rel, w.sf, m)})`, rawJsDoc(w.text, m), w)
+    } else if (ts.isSetAccessorDeclaration(m) && !documentedGetters.has(mname)) {
+      checkDescribed(`exported class accessor '${name}.${mname}' (${pointer(w.rel, w.sf, m)})`, rawJsDoc(w.text, m), w)
+    }
+    // index signatures / static blocks: not named surface
+  }
+}
+
+/**
+ * Check one exported declaration statement, dispatching on its kind.
+ * @param stmt - the exported statement (export modifier or export-list target).
+ * @param prefix - the namespace qualification for surface names ('' at top level).
+ * @param overloadSigs - names in this scope declared as bodyless function overload signatures.
+ * @param byName - this scope's named declarations (for namespace/sibling-merge lookups).
+ * @param w - the walk state violations append to.
+ */
+function checkDecl(
+  stmt: ts.Statement,
+  prefix: string,
+  overloadSigs: Set<string>,
+  byName: Map<string, ts.Statement[]>,
+  w: Walk,
+): void {
+  const at = (n: ts.Node): string => ` (${pointer(w.rel, w.sf, n)})`
+  if (ts.isFunctionDeclaration(stmt)) {
+    const name = stmt.name?.text ?? 'default'
+    if (prefix === '' && PROTOCOL_EXPORTS.has(name)) return // cordis plugin-protocol slot
+    if (stmt.body && overloadSigs.has(name)) return // overload implementation: the signatures carry the docs
+    checkFunctionLike(`exported function '${prefix}${name}'${at(stmt)}`, rawJsDoc(w.text, stmt),
+      stmt.parameters, stmt.type, false, w)
+    return
+  }
+  if (ts.isClassDeclaration(stmt)) {
+    checkClass(stmt, `${prefix}${stmt.name?.text ?? 'default'}`, w)
+    return
+  }
+  if (ts.isInterfaceDeclaration(stmt)) {
+    checkDescribed(`exported interface '${prefix}${stmt.name.text}'${at(stmt)}`, rawJsDoc(w.text, stmt), w)
+    return
+  }
+  if (ts.isTypeAliasDeclaration(stmt)) {
+    checkDescribed(`exported type '${prefix}${stmt.name.text}'${at(stmt)}`, rawJsDoc(w.text, stmt), w)
+    return
+  }
+  if (ts.isEnumDeclaration(stmt)) {
+    checkDescribed(`exported enum '${prefix}${stmt.name.text}'${at(stmt)}`, rawJsDoc(w.text, stmt), w)
+    return
+  }
+  if (ts.isVariableStatement(stmt)) {
+    const raw = rawJsDoc(w.text, stmt) // JSDoc sits on the statement, not the declarator
+    for (const d of stmt.declarationList.declarations) {
+      const name = ts.isIdentifier(d.name) ? d.name.text : d.name.getText(w.sf)
+      if (prefix === '' && PROTOCOL_EXPORTS.has(name)) continue // cordis plugin-protocol slot
+      const where = `exported const '${prefix}${name}'${at(d)}`
+      const init = d.initializer
+      if (init && (ts.isArrowFunction(init) || ts.isFunctionExpression(init))) {
+        // A declarator type annotation (`const f: Handler = …`) hands the
+        // return contract to the named type; the arrow's own annotation is
+        // still checked when it is the only signature the reader has.
+        checkFunctionLike(where, raw, init.parameters, init.type, init.type === undefined && d.type !== undefined, w)
+      } else {
+        checkDescribed(where, raw, w)
+      }
+    }
+    return
+  }
+  if (ts.isModuleDeclaration(stmt) && ts.isIdentifier(stmt.name)) {
+    // A namespace merging with a documented same-name sibling (the
+    // Config-namespace idiom) needs no second doc block of its own.
+    const siblings = (byName.get(stmt.name.text) ?? []).filter(s => s !== stmt)
+    const merged = siblings.some(s => parseJsDoc(rawJsDoc(w.text, s)).doc !== '')
+    if (!merged) checkDescribed(`exported namespace '${prefix}${stmt.name.text}'${at(stmt)}`, rawJsDoc(w.text, stmt), w)
+    let body = stmt.body
+    let nsPrefix = `${prefix}${stmt.name.text}.`
+    while (body !== undefined && ts.isModuleDeclaration(body)) { // dotted `namespace A.B`
+      nsPrefix += `${body.name.getText(w.sf)}.`
+      body = body.body
+    }
+    if (body !== undefined && ts.isModuleBlock(body)) checkScope(body.statements, nsPrefix, w)
+  }
+}
+
+/**
+ * Walk one lexical scope (file top level or a namespace body): check every
+ * exported declaration, resolving `export { … }` lists (no module specifier)
+ * to their local declarations.
+ * @param statements - the scope's statements.
+ * @param prefix - the namespace qualification for surface names ('' at top level).
+ * @param w - the walk state violations append to.
+ */
+function checkScope(statements: readonly ts.Statement[], prefix: string, w: Walk): void {
+  const byName = new Map<string, ts.Statement[]>()
+  const overloadSigs = new Set<string>()
+  const add = (name: string, stmt: ts.Statement): void => {
+    byName.set(name, [...(byName.get(name) ?? []), stmt])
+  }
+  for (const stmt of statements) {
+    if (ts.isFunctionDeclaration(stmt)) {
+      if (stmt.name) add(stmt.name.text, stmt)
+      if (!stmt.body && stmt.name) overloadSigs.add(stmt.name.text)
+    } else if (ts.isClassDeclaration(stmt) || ts.isInterfaceDeclaration(stmt)
+      || ts.isTypeAliasDeclaration(stmt) || ts.isEnumDeclaration(stmt)) {
+      if (stmt.name) add(stmt.name.text, stmt)
+    } else if (ts.isModuleDeclaration(stmt) && ts.isIdentifier(stmt.name)) {
+      add(stmt.name.text, stmt)
+    } else if (ts.isVariableStatement(stmt)) {
+      for (const d of stmt.declarationList.declarations) {
+        if (ts.isIdentifier(d.name)) add(d.name.text, stmt)
+      }
+    }
+  }
+  const checked = new Set<ts.Statement>()
+  const check = (stmt: ts.Statement): void => {
+    if (checked.has(stmt)) return
+    checked.add(stmt)
+    checkDecl(stmt, prefix, overloadSigs, byName, w)
+  }
+  for (const stmt of statements) {
+    if (ts.isModuleDeclaration(stmt)
+      && (ts.isStringLiteral(stmt.name) || (stmt.flags & ts.NodeFlags.GlobalAugmentation) !== 0)) {
+      continue // `declare module '…'` / `declare global` augmentation: not an export of this package
+    }
+    if (ts.isExportDeclaration(stmt)) {
+      if (stmt.moduleSpecifier) continue // re-export: the defining module is walked on its own
+      if (stmt.exportClause && ts.isNamedExports(stmt.exportClause)) {
+        for (const el of stmt.exportClause.elements) {
+          for (const decl of byName.get((el.propertyName ?? el.name).text) ?? []) check(decl)
+          // a name with no local declaration is an imported binding re-exported
+          // without a specifier — its defining module is walked on its own
+        }
+      }
+      continue
+    }
+    if (ts.isExportAssignment(stmt) && !stmt.isExportEquals) {
+      if (ts.isIdentifier(stmt.expression)) {
+        for (const decl of byName.get(stmt.expression.text) ?? []) check(decl)
+      } else {
+        checkDescribed(`default export (${pointer(w.rel, w.sf, stmt)})`, rawJsDoc(w.text, stmt), w)
+      }
+      continue
+    }
+    if (isExported(stmt)) check(stmt)
+  }
+}
+
+/**
+ * Compiler options for the walk's program. The real repo hands over its
+ * tsconfig.base.json (whose `paths` map resolves cross-package imports to
+ * source, so heritage-member lookups see seam types); a fixture root without
+ * one gets bare defaults — fixtures are single-file and self-contained.
+ * Emit-side options are stripped: the walk never emits or asks for
+ * diagnostics, it only binds types on demand.
+ * @param scanRoot - the root being scanned.
+ * @returns compiler options for ts.createProgram.
+ */
+function loadCompilerOptions(scanRoot: string): ts.CompilerOptions {
+  const cfgPath = resolve(scanRoot, 'tsconfig.base.json')
+  if (!existsSync(cfgPath)) return { skipLibCheck: true }
+  const cfg = ts.readConfigFile(cfgPath, ts.sys.readFile.bind(ts.sys)) as { config?: unknown }
+  const parsed = ts.parseJsonConfigFileContent(cfg.config ?? {}, ts.sys, scanRoot)
+  return {
+    ...parsed.options,
+    noEmit: true,
+    composite: false,
+    declaration: false,
+    declarationMap: false,
+    sourceMap: false,
+    incremental: false,
+  }
+}
+
+/**
+ * Walk every non-vendored package source file and collect JSDoc-completeness
+ * violations for its module-level exports. Returns findings instead of
+ * throwing so tests assert on the list; the CLI entry turns a non-empty list
+ * into exit 1.
+ * @param scanRoot - the repo root to scan; tests pass a fixture dir.
+ * @returns every violation, in file order, one human-readable line each.
+ */
+export function collectExportJsdocViolations(scanRoot: string = root): string[] {
+  const violations: string[] = []
+  const rels = globSync('packages/*/*/src/**/*.ts', { cwd: scanRoot }).sort()
+  const program = ts.createProgram(rels.map(rel => resolve(scanRoot, rel)), loadCompilerOptions(scanRoot))
+  const checker = program.getTypeChecker()
+  for (const rel of rels) {
+    const sf = program.getSourceFile(resolve(scanRoot, rel))
+    if (!sf) continue // program root files always resolve; guard for narrowing
+    checkScope(sf.statements, '', { rel, sf, text: sf.text, checker, violations })
+  }
+  return violations
+}
+
+/** CLI entry: list every violation and exit 1, or confirm a clean surface. */
+function main(): void {
+  const violations = collectExportJsdocViolations()
+  if (violations.length === 0) {
+    console.log('verify-export-jsdoc: every exported name on the package surface is documented.')
+    return
+  }
+  console.error(`verify-export-jsdoc: ${violations.length} JSDoc completeness violation(s) (see AGENTS.md):`)
+  for (const v of violations) console.error(`  ${v}`)
+  process.exit(1)
+}
+
+// Run only when invoked as a script, not when imported by a test.
+if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) {
+  main()
+}

From 9ff010cbef92569597058ae46f72917463852396 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Mon, 6 Jul 2026 23:25:33 +0800
Subject: [PATCH 2/7] fix review findings: close export-form and
 heritage-exemption gaps

Codex round-1 review found three fail-open paths in the new gate:

- Unhandled export forms passed silently. checkDecl now fails CLOSED on
  unrecognized exported statement kinds, 'export =' is refused outright,
  'export import X = N.member' is an explicit documented skip (alias;
  definition site owns the doc), and ambient 'declare namespace' bodies
  recurse with implicit export semantics.
- Function-like exports escaped the function contract: non-identifier
  default exports and consts with INLINE function-type annotations now
  get full @param/@returns checks (the named-type waiver stays for
  reference annotations only).
- The heritage exemption was name-only: it no longer exempts a public
  override of a protected-only base member, and parameters the base
  never names keep their @param duty (underscore-prefixed renames of a
  base parameter count as the same parameter).

Eight new negative-path tests pin the closed gaps; RFC and module doc
updated to the refined contract.
---
 .../2026-07-06-export-surface-jsdoc-gate.md   |   9 +-
 .../agent/tests/verify-export-jsdoc.spec.ts   | 100 +++++++++
 scripts/verify-export-jsdoc.ts                | 193 +++++++++++++-----
 3 files changed, 249 insertions(+), 53 deletions(-)

diff --git a/docs/rfc/implemented/process/2026-07-06-export-surface-jsdoc-gate.md b/docs/rfc/implemented/process/2026-07-06-export-surface-jsdoc-gate.md
index fa92fbcb3d..f3e6ab45c5 100644
--- a/docs/rfc/implemented/process/2026-07-06-export-surface-jsdoc-gate.md
+++ b/docs/rfc/implemented/process/2026-07-06-export-surface-jsdoc-gate.md
@@ -13,15 +13,16 @@ A new gate, `scripts/verify-export-jsdoc.ts` (`pnpm run verify-export-jsdoc`, wi
 The contract by declaration kind:
 
 - Every exported name needs JSDoc with non-empty description prose.
-- Function-like exports (function declarations; consts with function initializers) follow the full function contract. A const whose declarator is type-annotated (`export const f: Handler = …`) defers the return contract to the named type; `@returns` stays optional there.
+- Function-like exports (function declarations; consts with function initializers or an INLINE function-type annotation; non-identifier function default exports) follow the full function contract. A const whose declarator is annotated with a NAMED type (`export const f: Handler = …`) defers the signature contract to that type's own declaration and `@returns` stays optional; an inline `(x: T) => U` annotation is the surface signature itself and gets the full contract.
 - Exported classes need class-level prose; public methods (statics included — reachable on the exported name) follow the function contract; public properties and accessors need prose (a get/set pair is covered by the getter). Overload implementations are exempt — the signatures carry the docs.
 - Exported interfaces, type aliases, and enums need prose on the declaration; member-level enforcement is deliberately deferred (the highest-value member surface — seam service classes — is already under the cordis gate).
-- Exported namespaces recurse; the namespace itself needs prose only when it does not merge with a documented same-name declaration (the Config-namespace idiom documents the plugin once).
-- `declare module` / `declare global` bodies and `export … from` re-export statements are skipped: an augmentation is not an export of the package, and a re-exported definition is checked where it is defined.
+- Exported namespaces recurse (inside an ambient `declare` namespace every member exports implicitly); the namespace itself needs prose only when it does not merge with a documented same-name declaration (the Config-namespace idiom documents the plugin once).
+- `declare module` / `declare global` bodies, `export … from` re-export statements, and `export import X = N.member` aliases are skipped: an augmentation is not an export of the package, and a re-exported or aliased definition is checked where it is defined.
+- Everything else fails CLOSED: `export =` is refused outright, and an exported statement kind the dispatch does not recognize is itself a violation — no export form can pass unchecked by omission.
 
 Three exemption families keep the gate from demanding boilerplate, in the spirit of the cordis gate's `this`/`next` exemptions (documenting an exempt name anyway is allowed; only absence goes unchecked):
 
-- **Heritage members.** A class member whose name exists on an `extends`/`implements` heritage type is exempt: the seam declaration is the doc's one home, and the IDE inherits it on hover — re-documenting every `LocalBashExecutor.run` invites drift. This is the one question the walk asks the TYPE CHECKER (heritage types live across package boundaries, resolved through the repo `paths` map); everything else stays pure AST, and the annotated-return requirement is kept for symmetry with the cordis gate (it bound nothing at adoption — every exported function was already annotated).
+- **Heritage members.** A class member whose name exists on an `extends`/`implements` heritage type is exempt: the seam declaration is the doc's one home, and the IDE inherits it on hover — re-documenting every `LocalBashExecutor.run` invites drift. The exemption stops where the override grows surface the base never documented: a protected-only base member does not exempt a public override, and parameters the base never names keep their `@param` duty (an underscore-prefixed rename of a base parameter — the deliberately-unused marker — is the same parameter). This is the one question the walk asks the TYPE CHECKER (heritage types live across package boundaries, resolved through the repo `paths` map); everything else stays pure AST, and the annotated-return requirement is kept for symmetry with the cordis gate (it bound nothing at adoption — every exported function was already annotated).
 - **Plugin-protocol slots.** Top-level `name` / `inject` / `reusable` / `Config` consts and the `apply` entry, plus the same slots as statics on a plugin class, are framework protocol: their shape is fixed by cordis, and the module doc comment plus the `interface Config` carry the plugin's real semantics.
 - **Constructors**, mirroring the cordis gate: plugin classes are framework-constructed, and the class doc owns the story.
 
diff --git a/packages/core/agent/tests/verify-export-jsdoc.spec.ts b/packages/core/agent/tests/verify-export-jsdoc.spec.ts
index 89439a3a59..6682142abf 100644
--- a/packages/core/agent/tests/verify-export-jsdoc.spec.ts
+++ b/packages/core/agent/tests/verify-export-jsdoc.spec.ts
@@ -294,3 +294,103 @@ export namespace Loose {
     ])
   })
 })
+
+describe('verify-export-jsdoc fail-closed forms (review round 1)', () => {
+  it('checks the function contract on a non-identifier default export', () => {
+    expect(collectExportJsdocViolations(make(
+      '/** Doubles. */\nexport default (x: number): number => x * 2\n',
+    ))).toEqual([
+      expect.stringMatching(/default export .* is missing @param x\./),
+      expect.stringMatching(/default export .* is missing @returns \(return type: number\)\./),
+    ])
+    expect(collectExportJsdocViolations(make(
+      '/**\n * Doubles.\n * @param x - the input.\n * @returns twice the input.\n */\nexport default (x: number): number => x * 2\n',
+    ))).toEqual([])
+  })
+
+  it('treats an inline function-type annotation as the surface signature', () => {
+    expect(collectExportJsdocViolations(make(
+      '/** Maps a number. */\nexport declare const f: (x: number) => number\n',
+    ))).toEqual([
+      expect.stringMatching(/exported const 'f' .* is missing @param x\./),
+      expect.stringMatching(/exported const 'f' .* is missing @returns \(return type: number\)\./),
+    ])
+    expect(collectExportJsdocViolations(make(
+      '/**\n * Maps a number.\n * @param x - the input.\n * @returns the mapped value.\n */\nexport const f: (x: number) => number = v => v\n',
+    ))).toEqual([])
+  })
+
+  it('recurses into an ambient declare namespace where members export implicitly', () => {
+    expect(collectExportJsdocViolations(make(
+      'export declare namespace N {\n  function f(x: number): number\n}\n',
+    ))).toEqual([
+      expect.stringMatching(/exported namespace 'N' .* has no JSDoc\./),
+      expect.stringMatching(/exported function 'N.f' .* has no JSDoc\./),
+    ])
+  })
+
+  it('skips an export-import alias (the aliased definition owns the doc)', () => {
+    expect(collectExportJsdocViolations(make(
+      '/** Holder. */\nexport namespace N {\n  /** The value. */\n  export const x = 1\n}\nexport import y = N.x\n',
+    ))).toEqual([])
+  })
+
+  it('refuses an export-equals assignment instead of failing open', () => {
+    expect(collectExportJsdocViolations(make(
+      'const x = 1\nexport = x\n',
+    ))).toEqual([expect.stringMatching(/export-equals assignment .* is not a gate-supported export form/)])
+  })
+})
+
+describe('verify-export-jsdoc heritage refinement (review round 1)', () => {
+  it('requires @param for parameters the base member never names', () => {
+    const violations = collectExportJsdocViolations(make(`
+/** Seam. */
+export abstract class Base {
+  /**
+   * Do it.
+   * @param x - input.
+   * @returns output.
+   */
+  abstract run(x: number): number
+}
+/** Impl. */
+export class Impl extends Base {
+  override run(x: number, verbose?: boolean): number { return verbose ? x : -x }
+}
+`))
+    expect(violations).toEqual([expect.stringMatching(/exported class method 'Impl.run' .* is missing @param verbose\./)])
+  })
+
+  it('does not exempt a public override of a protected-only base member', () => {
+    expect(collectExportJsdocViolations(make(`
+/** Seam. */
+export abstract class Base {
+  /** Subclass hook. */
+  protected hook(): void {}
+}
+/** Impl. */
+export class Impl extends Base {
+  override hook(): void {}
+}
+`))).toEqual([expect.stringMatching(/exported class method 'Impl.hook' .* has no JSDoc\./)])
+  })
+
+  it('treats an underscore-prefixed rename of a base parameter as the same parameter', () => {
+    expect(collectExportJsdocViolations(make(`
+/** Seam. */
+export abstract class Base {
+  /**
+   * Load it.
+   * @param cwd - the working directory to scope the lookup.
+   * @returns the loaded value.
+   */
+  abstract load(cwd: string): number
+}
+/** Impl (ignores cwd). */
+export class Impl extends Base {
+  load(_cwd: string): number { return 1 }
+}
+`))).toEqual([])
+  })
+})
diff --git a/scripts/verify-export-jsdoc.ts b/scripts/verify-export-jsdoc.ts
index 2779a53e68..5a8a28af1a 100644
--- a/scripts/verify-export-jsdoc.ts
+++ b/scripts/verify-export-jsdoc.ts
@@ -13,33 +13,39 @@
  *
  * - Every exported name needs JSDoc with non-empty description prose (prose
  *   ends at the first block tag, standard JSDoc semantics).
- * - A function-like export (function declaration, or a const with a function
- *   initializer) additionally needs a non-empty `@param` per parameter
- *   (`this` receiver annotations exempt; a stale `@param` errors) and a
- *   non-empty `@returns` unless the return type is `void`/`Promise<void>`.
- *   The walk classifies returns syntactically, so the return type must be
- *   ANNOTATED — except a const whose DECLARATOR is type-annotated (e.g.
- *   `export const f: Handler = …`), where the named type owns the return
- *   contract and `@returns` stays optional.
+ * - A function-like export (function declaration, a const with a function
+ *   initializer or an INLINE function-type annotation, or a non-identifier
+ *   function default export) additionally needs a non-empty `@param` per
+ *   parameter (`this` receiver annotations exempt; a stale `@param` errors)
+ *   and a non-empty `@returns` unless the return type is `void` /
+ *   `Promise<void>`. The walk classifies returns syntactically, so the return
+ *   type must be ANNOTATED — except a const whose declarator is annotated
+ *   with a NAMED type (e.g. `export const f: Handler = …`), where that type's
+ *   own declaration owns the signature contract and `@returns` stays
+ *   optional; an inline `(x: T) => U` annotation is the surface signature
+ *   itself and gets the full contract.
  * - An exported class needs class-level JSDoc; its public methods (static
  *   included — they are reachable on the exported name) follow the function
  *   contract, and public properties and accessors need description prose (on
- *   a get/set pair the getter's doc covers both). A member whose name exists
- *   on an `extends`/`implements` heritage type is EXEMPT — the seam
- *   declaration is the doc's one home, the IDE inherits it, and re-documenting
- *   every implementation invites drift. This is the one question the walk
- *   asks the TYPE CHECKER (heritage members live across package boundaries);
- *   everything else is pure AST. Constructors are exempt like the cordis
- *   gate's: plugin classes are framework-constructed, and the class doc owns
- *   the story.
+ *   a get/set pair the getter's doc covers both). A member declared by an
+ *   `extends`/`implements` heritage type is EXEMPT — the seam declaration is
+ *   the doc's one home, the IDE inherits it, and re-documenting every
+ *   implementation invites drift — UNLESS the override grows surface the
+ *   base never documented: a protected-only base member does not exempt a
+ *   public override, and parameters the base never names keep their `@param`
+ *   duty. This is the one question the walk asks the TYPE CHECKER (heritage
+ *   members live across package boundaries); everything else is pure AST.
+ *   Constructors are exempt like the cordis gate's: plugin classes are
+ *   framework-constructed, and the class doc owns the story.
  * - Exported interfaces, type aliases, enums: description prose on the
  *   declaration (member-level docs stay review's job; the highest-value
  *   member surface — seam service classes — is already under the cordis
  *   gate).
  * - An exported namespace recurses (its exported members are package
- *   surface); the namespace itself needs prose only when it does not merge
- *   with an already-documented same-name declaration (the Config-namespace
- *   idiom documents the class/function once, not twice).
+ *   surface; in an ambient `declare` namespace every member exports
+ *   implicitly); the namespace itself needs prose only when it does not
+ *   merge with an already-documented same-name declaration (the
+ *   Config-namespace idiom documents the class/function once, not twice).
  * - The cordis plugin-protocol slots are exempt: top-level `name` / `inject`
  *   / `reusable` / `Config` consts and the `apply` entry, plus the same
  *   slots as statics on a plugin class. Their shape is fixed by the
@@ -50,10 +56,13 @@
  * - Overload groups: each overload signature carries its own docs; the
  *   implementation signature is exempt (callers never see it).
  * - Skipped: `declare module` / `declare global` augmentation bodies (the
- *   cordis gate's turf; an augmentation is not an export of the package) and
- *   re-export statements with a module specifier (`export … from`) — the
- *   defining module is walked on its own, and external definitions are not
- *   ours to document.
+ *   cordis gate's turf; an augmentation is not an export of the package),
+ *   re-export statements with a module specifier (`export … from`) and
+ *   `export import X = N.member` aliases — the defining module is walked on
+ *   its own, and external definitions are not ours to document.
+ * - Everything else fails CLOSED: `export =` is refused outright, and an
+ *   exported statement kind the dispatch does not recognize is itself a
+ *   violation, so no export form can pass unchecked by omission.
  */
 
 import { existsSync, globSync } from 'node:fs'
@@ -107,26 +116,60 @@ function thisReceiver(p: ts.ParameterDeclaration): boolean {
 }
 
 /**
- * True when a member name exists on any `extends`/`implements` heritage type
- * of the class — the member implements or overrides a documented seam
- * declaration, which is the doc's one home (the IDE inherits it on hover).
- * Static members are looked up on the base CONSTRUCTOR type (only an
- * `extends` expression has one; an unresolvable or interface expression
- * yields no property and therefore no exemption).
+ * The heritage-member exemption for one class member. When the member's name
+ * is declared by an `extends`/`implements` heritage type, the seam declaration
+ * is the doc's one home (the IDE inherits it on hover) and the member needs no
+ * doc of its own — EXCEPT where the override grows public surface the base
+ * never documented: a base member that is protected on every declaration does
+ * not exempt a public override (consumers could not call it before), and
+ * parameters the base never names keep their own `@param` duty (the caller
+ * reads the seam doc, which cannot describe them; an underscore-prefixed
+ * rename of a base parameter — the deliberately-unused marker — is the same
+ * parameter, not new surface). Static members are looked
+ * up on the base CONSTRUCTOR type (only an `extends` expression has one; an
+ * unresolvable or interface expression yields no property and therefore no
+ * exemption).
  * @param cls - the class whose heritage to search.
  * @param name - the member name to look up.
  * @param staticSide - whether to search the constructor side instead of the instance side.
  * @param checker - the program's type checker.
- * @returns true when a heritage type declares the member.
+ * @returns null when no exemption applies; otherwise the parameter names the
+ * base declarations carry (`baseParams: null` means the base's parameters are
+ * not syntactically recoverable — a complex heritage type — and the member is
+ * exempt in full).
  */
-function inheritedMember(cls: ts.ClassDeclaration, name: string, staticSide: boolean, checker: ts.TypeChecker): boolean {
+function heritageExemption(
+  cls: ts.ClassDeclaration,
+  name: string,
+  staticSide: boolean,
+  checker: ts.TypeChecker,
+): { baseParams: Set<string> | null } | null {
+  const isProtected = (d: ts.Declaration): boolean =>
+    (ts.canHaveModifiers(d) ? ts.getModifiers(d) : undefined)?.some(m => m.kind === ts.SyntaxKind.ProtectedKeyword) ?? false
   for (const clause of cls.heritageClauses ?? []) {
     for (const t of clause.types) {
       const type = staticSide ? checker.getTypeAtLocation(t.expression) : checker.getTypeAtLocation(t)
-      if (type.getProperty(name) !== undefined) return true
+      const prop = type.getProperty(name)
+      if (prop === undefined) continue
+      const decls = prop.declarations ?? []
+      if (decls.length > 0 && decls.every(isProtected)) continue // public override of a protected base: new surface
+      let baseParams: Set<string> | null = null
+      for (const d of decls) {
+        let params: readonly ts.ParameterDeclaration[] | undefined
+        if (ts.isMethodDeclaration(d) || ts.isMethodSignature(d)) params = d.parameters
+        else if ((ts.isPropertySignature(d) || ts.isPropertyDeclaration(d)) && d.type !== undefined && ts.isFunctionTypeNode(d.type)) {
+          params = d.type.parameters
+        } else continue
+        baseParams ??= new Set()
+        // Leading underscores are the deliberately-unused marker (eslint
+        // argsIgnorePattern), not a rename: `_cwd` overriding `cwd` is the
+        // same parameter, so compare underscore-stripped on both sides.
+        for (const p of params) if (ts.isIdentifier(p.name)) baseParams.add(p.name.text.replace(/^_+/, ''))
+      }
+      return { baseParams }
     }
   }
-  return false
+  return null
 }
 
 /**
@@ -171,9 +214,10 @@ function checkFunctionLike(
  * Check one exported class: class-level prose, the function contract on every
  * public method (overload implementations exempt), and description prose on
  * public properties and accessors (a get/set pair is covered by the getter's
- * doc). Members declared by a heritage type and the plugin-protocol statics
- * are exempt; constructors are not checked (framework-constructed plugins,
- * and the class doc owns the story).
+ * doc). Heritage-declared members are exempt per heritageExemption (an
+ * override's extra parameters keep their @param duty); plugin-protocol
+ * statics are exempt; constructors are not checked (framework-constructed
+ * plugins, and the class doc owns the story).
  * @param cls - the exported class declaration.
  * @param name - the class's surface name (namespace-qualified).
  * @param w - the walk state violations append to.
@@ -192,10 +236,26 @@ function checkClass(cls: ts.ClassDeclaration, name: string, w: Walk): void {
     if (!('name' in m) || ts.isComputedPropertyName(m.name)) continue // computed/symbol members
     const mname = m.name.getText(w.sf)
     if (isStatic(m) && PROTOCOL_STATICS.has(mname)) continue // cordis plugin-protocol slot
-    if (inheritedMember(cls, mname, isStatic(m), w.checker)) continue // the heritage declaration owns the doc
+    const exemption = heritageExemption(cls, mname, isStatic(m), w.checker)
     if (ts.isMethodDeclaration(m)) {
       if (m.body && overloadSigs.has(mname)) continue // overload implementation: the signatures carry the docs
-      checkFunctionLike(`exported class method '${name}.${mname}' (${pointer(w.rel, w.sf, m)})`, rawJsDoc(w.text, m), m.parameters, m.type, false, w)
+      const where = `exported class method '${name}.${mname}' (${pointer(w.rel, w.sf, m)})`
+      if (exemption !== null) {
+        // The heritage declaration owns prose and @returns; parameters the
+        // base never names are new surface and keep their @param duty.
+        const base = exemption.baseParams
+        const inBase = (p: ts.ParameterDeclaration): boolean =>
+          base !== null && ts.isIdentifier(p.name) && base.has(p.name.text.replace(/^_+/, ''))
+        if (base !== null && m.parameters.some(p => ts.isIdentifier(p.name) && p.name.text !== 'this' && !inBase(p))) {
+          const { params } = parseTags(rawJsDoc(w.text, m))
+          checkParams(where, 'export', m.parameters, params, w.sf,
+            p => thisReceiver(p) || inBase(p), w.violations)
+        }
+        continue
+      }
+      checkFunctionLike(where, rawJsDoc(w.text, m), m.parameters, m.type, false, w)
+    } else if (exemption !== null) {
+      continue // the heritage declaration owns the doc (properties/accessors carry no own parameters)
     } else if (ts.isGetAccessorDeclaration(m) || ts.isPropertyDeclaration(m)) {
       const kind = ts.isPropertyDeclaration(m) ? 'property' : 'accessor'
       checkDescribed(`exported class ${kind} '${name}.${mname}' (${pointer(w.rel, w.sf, m)})`, rawJsDoc(w.text, m), w)
@@ -207,11 +267,14 @@ function checkClass(cls: ts.ClassDeclaration, name: string, w: Walk): void {
 }
 
 /**
- * Check one exported declaration statement, dispatching on its kind.
+ * Check one exported declaration statement, dispatching on its kind. Any
+ * exported statement kind the dispatch does not recognize is a violation
+ * (fail closed), so no export form can pass unchecked by omission.
  * @param stmt - the exported statement (export modifier or export-list target).
  * @param prefix - the namespace qualification for surface names ('' at top level).
  * @param overloadSigs - names in this scope declared as bodyless function overload signatures.
  * @param byName - this scope's named declarations (for namespace/sibling-merge lookups).
+ * @param ambient - whether the enclosing scope is ambient (`declare`), where members export implicitly.
  * @param w - the walk state violations append to.
  */
 function checkDecl(
@@ -219,6 +282,7 @@ function checkDecl(
   prefix: string,
   overloadSigs: Set<string>,
   byName: Map<string, ts.Statement[]>,
+  ambient: boolean,
   w: Walk,
 ): void {
   const at = (n: ts.Node): string => ` (${pointer(w.rel, w.sf, n)})`
@@ -253,9 +317,14 @@ function checkDecl(
       if (prefix === '' && PROTOCOL_EXPORTS.has(name)) continue // cordis plugin-protocol slot
       const where = `exported const '${prefix}${name}'${at(d)}`
       const init = d.initializer
-      if (init && (ts.isArrowFunction(init) || ts.isFunctionExpression(init))) {
-        // A declarator type annotation (`const f: Handler = …`) hands the
-        // return contract to the named type; the arrow's own annotation is
+      if (d.type !== undefined && ts.isFunctionTypeNode(d.type)) {
+        // An INLINE function-type annotation is the surface signature itself:
+        // its parameters and result need docs right here. (A NAMED reference
+        // type carries its docs at the type's own declaration instead.)
+        checkFunctionLike(where, raw, d.type.parameters, d.type.type, false, w)
+      } else if (init && (ts.isArrowFunction(init) || ts.isFunctionExpression(init))) {
+        // A named declarator type annotation (`const f: Handler = …`) hands
+        // the return contract to the named type; the arrow's own annotation is
         // still checked when it is the only signature the reader has.
         checkFunctionLike(where, raw, init.parameters, init.type, init.type === undefined && d.type !== undefined, w)
       } else {
@@ -276,8 +345,21 @@ function checkDecl(
       nsPrefix += `${body.name.getText(w.sf)}.`
       body = body.body
     }
-    if (body !== undefined && ts.isModuleBlock(body)) checkScope(body.statements, nsPrefix, w)
+    // In an ambient (`declare`) namespace body, members are implicitly
+    // exported — no `export` modifier required — so the recursion must treat
+    // every statement as surface.
+    const declared = ambient
+      || ((ts.canHaveModifiers(stmt) ? ts.getModifiers(stmt) : undefined)?.some(m => m.kind === ts.SyntaxKind.DeclareKeyword) ?? false)
+    if (body !== undefined && ts.isModuleBlock(body)) checkScope(body.statements, nsPrefix, w, declared)
+    return
   }
+  if (ts.isImportEqualsDeclaration(stmt)) {
+    return // alias re-export (`export import X = N.member`): the aliased definition owns the doc, like `export … from`
+  }
+  // Fail CLOSED: an exported statement kind this dispatch does not recognize
+  // must never pass silently — the gate's whole promise is that unchecked
+  // surface cannot exist. New TypeScript export forms extend the gate here.
+  w.violations.push(`exported statement${at(stmt)} uses an export form verify-export-jsdoc does not handle; extend the gate.`)
 }
 
 /**
@@ -287,8 +369,9 @@ function checkDecl(
  * @param statements - the scope's statements.
  * @param prefix - the namespace qualification for surface names ('' at top level).
  * @param w - the walk state violations append to.
+ * @param ambient - whether this scope is ambient (`declare` namespace or a declaration file), where members export implicitly.
  */
-function checkScope(statements: readonly ts.Statement[], prefix: string, w: Walk): void {
+function checkScope(statements: readonly ts.Statement[], prefix: string, w: Walk, ambient: boolean): void {
   const byName = new Map<string, ts.Statement[]>()
   const overloadSigs = new Set<string>()
   const add = (name: string, stmt: ts.Statement): void => {
@@ -313,7 +396,7 @@ function checkScope(statements: readonly ts.Statement[], prefix: string, w: Walk
   const check = (stmt: ts.Statement): void => {
     if (checked.has(stmt)) return
     checked.add(stmt)
-    checkDecl(stmt, prefix, overloadSigs, byName, w)
+    checkDecl(stmt, prefix, overloadSigs, byName, ambient, w)
   }
   for (const stmt of statements) {
     if (ts.isModuleDeclaration(stmt)
@@ -331,15 +414,25 @@ function checkScope(statements: readonly ts.Statement[], prefix: string, w: Walk
       }
       continue
     }
-    if (ts.isExportAssignment(stmt) && !stmt.isExportEquals) {
+    if (ts.isExportAssignment(stmt)) {
+      if (stmt.isExportEquals) {
+        // `export =` has no ESM consumer surface in this repo and the walk
+        // cannot classify its operand's shape; refuse rather than fail open.
+        w.violations.push(`export-equals assignment (${pointer(w.rel, w.sf, stmt)}) is not a gate-supported export form; use ESM named exports.`)
+        continue
+      }
+      const where = `default export (${pointer(w.rel, w.sf, stmt)})`
       if (ts.isIdentifier(stmt.expression)) {
         for (const decl of byName.get(stmt.expression.text) ?? []) check(decl)
+      } else if (ts.isArrowFunction(stmt.expression) || ts.isFunctionExpression(stmt.expression)) {
+        const fn = stmt.expression
+        checkFunctionLike(where, rawJsDoc(w.text, stmt), fn.parameters, fn.type, false, w)
       } else {
-        checkDescribed(`default export (${pointer(w.rel, w.sf, stmt)})`, rawJsDoc(w.text, stmt), w)
+        checkDescribed(where, rawJsDoc(w.text, stmt), w)
       }
       continue
     }
-    if (isExported(stmt)) check(stmt)
+    if (isExported(stmt) || (ambient && !ts.isImportDeclaration(stmt))) check(stmt)
   }
 }
 
@@ -385,7 +478,9 @@ export function collectExportJsdocViolations(scanRoot: string = root): string[]
   for (const rel of rels) {
     const sf = program.getSourceFile(resolve(scanRoot, rel))
     if (!sf) continue // program root files always resolve; guard for narrowing
-    checkScope(sf.statements, '', { rel, sf, text: sf.text, checker, violations })
+    // A script-style declaration file (no imports/exports) is one big ambient
+    // scope; a module-style .d.ts still honors explicit export modifiers.
+    checkScope(sf.statements, '', { rel, sf, text: sf.text, checker, violations }, sf.isDeclarationFile && !ts.isExternalModule(sf))
   }
   return violations
 }

From eaac3b58a4a6934268f45eef2f0d85edc2920589 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Mon, 6 Jul 2026 23:55:16 +0800
Subject: [PATCH 3/7] fix review findings: close wrapped-expression, alias, and
 binding-pattern gaps
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Codex round-2 review found three adjacent fail-open shapes:

- Wrapped function expressions escaped classification: parentheses,
  as/satisfies casts, and non-null assertions are now peeled before the
  arrow/function test (initializers and default exports), and a
  single-call-signature type literal counts as the surface signature.
  A literal mixing call/construct signatures with anything else is
  refused outright — no single signature to hold the tags against.
- The blanket 'export import X = N.member' skip was unsound (the target
  can be a non-exported namespace member no walk visits): an alias now
  documents itself.
- The heritage extra-parameter duty missed binding-pattern extras,
  which no base declaration can name: they now trigger the standard
  binding-pattern violation.

Five new negative-path tests pin the closed shapes; module doc and RFC
updated.
---
 .../2026-07-06-export-surface-jsdoc-gate.md   |   6 +-
 .../agent/tests/verify-export-jsdoc.spec.ts   |  53 ++++++++-
 scripts/verify-export-jsdoc.ts                | 104 +++++++++++++-----
 3 files changed, 134 insertions(+), 29 deletions(-)

diff --git a/docs/rfc/implemented/process/2026-07-06-export-surface-jsdoc-gate.md b/docs/rfc/implemented/process/2026-07-06-export-surface-jsdoc-gate.md
index f3e6ab45c5..13b9db565f 100644
--- a/docs/rfc/implemented/process/2026-07-06-export-surface-jsdoc-gate.md
+++ b/docs/rfc/implemented/process/2026-07-06-export-surface-jsdoc-gate.md
@@ -13,12 +13,12 @@ A new gate, `scripts/verify-export-jsdoc.ts` (`pnpm run verify-export-jsdoc`, wi
 The contract by declaration kind:
 
 - Every exported name needs JSDoc with non-empty description prose.
-- Function-like exports (function declarations; consts with function initializers or an INLINE function-type annotation; non-identifier function default exports) follow the full function contract. A const whose declarator is annotated with a NAMED type (`export const f: Handler = …`) defers the signature contract to that type's own declaration and `@returns` stays optional; an inline `(x: T) => U` annotation is the surface signature itself and gets the full contract.
+- Function-like exports (function declarations; consts with function initializers or an INLINE callable annotation; non-identifier function default exports) follow the full function contract, with wrapper expressions (parentheses, `as`/`satisfies` casts, non-null assertions) peeled before classifying. A const whose declarator is annotated with a NAMED type (`export const f: Handler = …`) defers the signature contract to that type's own declaration and `@returns` stays optional; an inline `(x: T) => U` annotation or single-call-signature literal is the surface signature itself and gets the full contract, and a literal mixing call/construct signatures with anything else is refused outright (no single signature to hold the tags against — extract a named type).
 - Exported classes need class-level prose; public methods (statics included — reachable on the exported name) follow the function contract; public properties and accessors need prose (a get/set pair is covered by the getter). Overload implementations are exempt — the signatures carry the docs.
 - Exported interfaces, type aliases, and enums need prose on the declaration; member-level enforcement is deliberately deferred (the highest-value member surface — seam service classes — is already under the cordis gate).
 - Exported namespaces recurse (inside an ambient `declare` namespace every member exports implicitly); the namespace itself needs prose only when it does not merge with a documented same-name declaration (the Config-namespace idiom documents the plugin once).
-- `declare module` / `declare global` bodies, `export … from` re-export statements, and `export import X = N.member` aliases are skipped: an augmentation is not an export of the package, and a re-exported or aliased definition is checked where it is defined.
-- Everything else fails CLOSED: `export =` is refused outright, and an exported statement kind the dispatch does not recognize is itself a violation — no export form can pass unchecked by omission.
+- `declare module` / `declare global` bodies and `export … from` re-export statements are skipped: an augmentation is not an export of the package, and a re-exported definition is checked where it is defined. An `export import X = N.member` alias documents ITSELF — its target may be a non-exported namespace member no walk visits, so the "definition owns the doc" rationale does not hold for it.
+- Everything else fails CLOSED: `export =` is refused outright, parameters the base never names keep their `@param` duty even as binding patterns, and an exported statement kind the dispatch does not recognize is itself a violation — no export form can pass unchecked by omission.
 
 Three exemption families keep the gate from demanding boilerplate, in the spirit of the cordis gate's `this`/`next` exemptions (documenting an exempt name anyway is allowed; only absence goes unchecked):
 
diff --git a/packages/core/agent/tests/verify-export-jsdoc.spec.ts b/packages/core/agent/tests/verify-export-jsdoc.spec.ts
index 6682142abf..501dfb8c3e 100644
--- a/packages/core/agent/tests/verify-export-jsdoc.spec.ts
+++ b/packages/core/agent/tests/verify-export-jsdoc.spec.ts
@@ -329,12 +329,45 @@ describe('verify-export-jsdoc fail-closed forms (review round 1)', () => {
     ])
   })
 
-  it('skips an export-import alias (the aliased definition owns the doc)', () => {
+  it('requires an export-import alias to document itself (its target may be unwalked)', () => {
     expect(collectExportJsdocViolations(make(
       '/** Holder. */\nexport namespace N {\n  /** The value. */\n  export const x = 1\n}\nexport import y = N.x\n',
+    ))).toEqual([expect.stringMatching(/exported alias 'y' .* has no JSDoc\./)])
+    expect(collectExportJsdocViolations(make(
+      'namespace N {\n  export const x = 1\n}\n/** Alias surfacing the internal counter. */\nexport import y = N.x\n',
     ))).toEqual([])
   })
 
+  it('classifies wrapped function initializers and default exports (parens, satisfies)', () => {
+    expect(collectExportJsdocViolations(make(
+      'type Fn = (x: number) => number\n/** Wrapped. */\nexport const f = (((x: number): number => x)) satisfies Fn\n',
+    ))).toEqual([
+      expect.stringMatching(/exported const 'f' .* is missing @param x\./),
+      expect.stringMatching(/exported const 'f' .* is missing @returns \(return type: number\)\./),
+    ])
+    expect(collectExportJsdocViolations(make(
+      'type Fn = (x: number) => number\n/** Wrapped. */\nexport default (((x: number): number => x * 2) satisfies Fn)\n',
+    ))).toEqual([
+      expect.stringMatching(/default export .* is missing @param x\./),
+      expect.stringMatching(/default export .* is missing @returns \(return type: number\)\./),
+    ])
+  })
+
+  it('treats a single-call-signature type literal as the surface signature', () => {
+    expect(collectExportJsdocViolations(make(
+      '/** Maps. */\nexport declare const f: { (x: number): number }\n',
+    ))).toEqual([
+      expect.stringMatching(/exported const 'f' .* is missing @param x\./),
+      expect.stringMatching(/exported const 'f' .* is missing @returns \(return type: number\)\./),
+    ])
+  })
+
+  it('refuses a hybrid callable type literal instead of narrowing the check', () => {
+    expect(collectExportJsdocViolations(make(
+      '/** Hybrid. */\nexport declare const f: { (x: number): number; flush: () => void }\n',
+    ))).toEqual([expect.stringMatching(/exported const 'f'.*callable type literal is not gate-classifiable; extract a named type/)])
+  })
+
   it('refuses an export-equals assignment instead of failing open', () => {
     expect(collectExportJsdocViolations(make(
       'const x = 1\nexport = x\n',
@@ -393,4 +426,22 @@ export class Impl extends Base {
 }
 `))).toEqual([])
   })
+
+  it('flags a binding-pattern parameter an override adds beyond the base', () => {
+    expect(collectExportJsdocViolations(make(`
+/** Seam. */
+export abstract class Base {
+  /**
+   * Do it.
+   * @param x - input.
+   * @returns output.
+   */
+  abstract run(x: number): number
+}
+/** Impl. */
+export class Impl extends Base {
+  override run(x: number, { verbose }: { verbose?: boolean } = {}): number { return verbose ? x : -x }
+}
+`))).toEqual([expect.stringMatching(/exported class method 'Impl.run' .* is a binding pattern/)])
+  })
 })
diff --git a/scripts/verify-export-jsdoc.ts b/scripts/verify-export-jsdoc.ts
index 5a8a28af1a..44b5d2fdaa 100644
--- a/scripts/verify-export-jsdoc.ts
+++ b/scripts/verify-export-jsdoc.ts
@@ -14,16 +14,20 @@
  * - Every exported name needs JSDoc with non-empty description prose (prose
  *   ends at the first block tag, standard JSDoc semantics).
  * - A function-like export (function declaration, a const with a function
- *   initializer or an INLINE function-type annotation, or a non-identifier
+ *   initializer or an INLINE callable annotation, or a non-identifier
  *   function default export) additionally needs a non-empty `@param` per
  *   parameter (`this` receiver annotations exempt; a stale `@param` errors)
  *   and a non-empty `@returns` unless the return type is `void` /
- *   `Promise<void>`. The walk classifies returns syntactically, so the return
- *   type must be ANNOTATED — except a const whose declarator is annotated
- *   with a NAMED type (e.g. `export const f: Handler = …`), where that type's
- *   own declaration owns the signature contract and `@returns` stays
- *   optional; an inline `(x: T) => U` annotation is the surface signature
- *   itself and gets the full contract.
+ *   `Promise<void>`. Wrapper expressions (parentheses, `as` / `satisfies`
+ *   casts, non-null assertions) are peeled before classifying. The walk
+ *   classifies returns syntactically, so the return type must be ANNOTATED —
+ *   except a const whose declarator is annotated with a NAMED type (e.g.
+ *   `export const f: Handler = …`), where that type's own declaration owns
+ *   the signature contract and `@returns` stays optional; an inline
+ *   `(x: T) => U` annotation or single-call-signature literal is the surface
+ *   signature itself and gets the full contract, and a literal mixing
+ *   call/construct signatures with anything else is refused (extract a named
+ *   type).
  * - An exported class needs class-level JSDoc; its public methods (static
  *   included — they are reachable on the exported name) follow the function
  *   contract, and public properties and accessors need description prose (on
@@ -56,10 +60,12 @@
  * - Overload groups: each overload signature carries its own docs; the
  *   implementation signature is exempt (callers never see it).
  * - Skipped: `declare module` / `declare global` augmentation bodies (the
- *   cordis gate's turf; an augmentation is not an export of the package),
- *   re-export statements with a module specifier (`export … from`) and
- *   `export import X = N.member` aliases — the defining module is walked on
- *   its own, and external definitions are not ours to document.
+ *   cordis gate's turf; an augmentation is not an export of the package) and
+ *   re-export statements with a module specifier (`export … from`) — the
+ *   defining module is walked on its own, and external definitions are not
+ *   ours to document. An `export import X = N.member` alias documents
+ *   ITSELF (its target may be a non-exported namespace member no walk
+ *   visits, so a skip would fail open).
  * - Everything else fails CLOSED: `export =` is refused outright, and an
  *   exported statement kind the dispatch does not recognize is itself a
  *   violation, so no export form can pass unchecked by omission.
@@ -115,6 +121,43 @@ function thisReceiver(p: ts.ParameterDeclaration): boolean {
   return ts.isIdentifier(p.name) && p.name.text === 'this'
 }
 
+/**
+ * Peel wrapper expressions that carry no surface of their own — parentheses,
+ * `as` / `satisfies` / angle-bracket casts, non-null assertions — so a
+ * wrapped function expression is still classified as function-like.
+ * @param e - the expression to unwrap.
+ * @returns the innermost non-wrapper expression.
+ */
+function unwrapExpression(e: ts.Expression): ts.Expression {
+  let inner = e
+  while (
+    ts.isParenthesizedExpression(inner) || ts.isAsExpression(inner) || ts.isSatisfiesExpression(inner)
+    || ts.isNonNullExpression(inner) || ts.isTypeAssertionExpression(inner)
+  ) inner = inner.expression
+  return inner
+}
+
+/**
+ * Classify a declarator's type annotation for the function contract: an
+ * inline function type or a type literal that is EXACTLY one call signature
+ * is the surface signature itself; a literal mixing call/construct
+ * signatures with anything else cannot be classified syntactically and is
+ * refused (fail closed — extract a named type); everything else is a plain
+ * value shape.
+ * @param type - the declarator's type annotation.
+ * @returns the signature to check, 'refuse' for an unclassifiable callable literal, or null for a non-callable shape.
+ */
+function callableAnnotation(type: ts.TypeNode): ts.SignatureDeclarationBase | 'refuse' | null {
+  if (ts.isFunctionTypeNode(type)) return type
+  if (!ts.isTypeLiteralNode(type)) return null
+  const signatures = type.members.filter(m => ts.isCallSignatureDeclaration(m) || ts.isConstructSignatureDeclaration(m))
+  if (signatures.length === 0) return null
+  if (signatures.length === 1 && type.members.length === 1 && signatures[0] !== undefined && ts.isCallSignatureDeclaration(signatures[0])) {
+    return signatures[0]
+  }
+  return 'refuse'
+}
+
 /**
  * The heritage-member exemption for one class member. When the member's name
  * is declared by an `extends`/`implements` heritage type, the seam declaration
@@ -242,11 +285,12 @@ function checkClass(cls: ts.ClassDeclaration, name: string, w: Walk): void {
       const where = `exported class method '${name}.${mname}' (${pointer(w.rel, w.sf, m)})`
       if (exemption !== null) {
         // The heritage declaration owns prose and @returns; parameters the
-        // base never names are new surface and keep their @param duty.
+        // base never names — including binding patterns, which no base
+        // declaration can name — are new surface and keep their @param duty.
         const base = exemption.baseParams
         const inBase = (p: ts.ParameterDeclaration): boolean =>
           base !== null && ts.isIdentifier(p.name) && base.has(p.name.text.replace(/^_+/, ''))
-        if (base !== null && m.parameters.some(p => ts.isIdentifier(p.name) && p.name.text !== 'this' && !inBase(p))) {
+        if (base !== null && m.parameters.some(p => !thisReceiver(p) && !inBase(p))) {
           const { params } = parseTags(rawJsDoc(w.text, m))
           checkParams(where, 'export', m.parameters, params, w.sf,
             p => thisReceiver(p) || inBase(p), w.violations)
@@ -316,13 +360,19 @@ function checkDecl(
       const name = ts.isIdentifier(d.name) ? d.name.text : d.name.getText(w.sf)
       if (prefix === '' && PROTOCOL_EXPORTS.has(name)) continue // cordis plugin-protocol slot
       const where = `exported const '${prefix}${name}'${at(d)}`
-      const init = d.initializer
-      if (d.type !== undefined && ts.isFunctionTypeNode(d.type)) {
-        // An INLINE function-type annotation is the surface signature itself:
-        // its parameters and result need docs right here. (A NAMED reference
+      const annotation = d.type !== undefined ? callableAnnotation(d.type) : null
+      const init = d.initializer !== undefined ? unwrapExpression(d.initializer) : undefined
+      if (annotation === 'refuse') {
+        // A literal mixing call/construct signatures with other members (or
+        // overloading them) has no single signature the walk can hold the
+        // tags against — fail closed rather than silently narrow the check.
+        w.violations.push(`${where}: its callable type literal is not gate-classifiable; extract a named type and document it there.`)
+      } else if (annotation !== null) {
+        // An INLINE callable annotation is the surface signature itself: its
+        // parameters and result need docs right here. (A NAMED reference
         // type carries its docs at the type's own declaration instead.)
-        checkFunctionLike(where, raw, d.type.parameters, d.type.type, false, w)
-      } else if (init && (ts.isArrowFunction(init) || ts.isFunctionExpression(init))) {
+        checkFunctionLike(where, raw, annotation.parameters, annotation.type, false, w)
+      } else if (init !== undefined && (ts.isArrowFunction(init) || ts.isFunctionExpression(init))) {
         // A named declarator type annotation (`const f: Handler = …`) hands
         // the return contract to the named type; the arrow's own annotation is
         // still checked when it is the only signature the reader has.
@@ -354,7 +404,11 @@ function checkDecl(
     return
   }
   if (ts.isImportEqualsDeclaration(stmt)) {
-    return // alias re-export (`export import X = N.member`): the aliased definition owns the doc, like `export … from`
+    // An alias (`export import X = N.member`) is a distinct exported name and
+    // its target may be a non-exported namespace member no walk ever visits,
+    // so a blanket skip would fail open — the alias documents itself.
+    checkDescribed(`exported alias '${prefix}${stmt.name.text}'${at(stmt)}`, rawJsDoc(w.text, stmt), w)
+    return
   }
   // Fail CLOSED: an exported statement kind this dispatch does not recognize
   // must never pass silently — the gate's whole promise is that unchecked
@@ -422,11 +476,11 @@ function checkScope(statements: readonly ts.Statement[], prefix: string, w: Walk
         continue
       }
       const where = `default export (${pointer(w.rel, w.sf, stmt)})`
-      if (ts.isIdentifier(stmt.expression)) {
-        for (const decl of byName.get(stmt.expression.text) ?? []) check(decl)
-      } else if (ts.isArrowFunction(stmt.expression) || ts.isFunctionExpression(stmt.expression)) {
-        const fn = stmt.expression
-        checkFunctionLike(where, rawJsDoc(w.text, stmt), fn.parameters, fn.type, false, w)
+      const expr = unwrapExpression(stmt.expression)
+      if (ts.isIdentifier(expr)) {
+        for (const decl of byName.get(expr.text) ?? []) check(decl)
+      } else if (ts.isArrowFunction(expr) || ts.isFunctionExpression(expr)) {
+        checkFunctionLike(where, rawJsDoc(w.text, stmt), expr.parameters, expr.type, false, w)
       } else {
         checkDescribed(where, rawJsDoc(w.text, stmt), w)
       }

From f7bd7e82d177cf1eee7a8cb999875075fd86795b Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 7 Jul 2026 00:20:55 +0800
Subject: [PATCH 4/7] fix review findings: restrict export-import aliases to
 prose-only targets
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Codex round-3: alias prose matches the gate's strength only when the
target's own contract is prose-only. An export-import alias to a
function, class, or namespace target (or an unresolvable one) is now
refused — those carry signature/member contracts the alias cannot
hold; export the declaration directly instead. Const/enum/interface/
type-alias targets keep the self-documentation contract.

Tests pin the refusal for function, class, and namespace targets;
module doc and RFC updated.
---
 .../2026-07-06-export-surface-jsdoc-gate.md   |  2 +-
 .../agent/tests/verify-export-jsdoc.spec.ts   | 13 +++++++++
 scripts/verify-export-jsdoc.ts                | 28 +++++++++++++++----
 3 files changed, 36 insertions(+), 7 deletions(-)

diff --git a/docs/rfc/implemented/process/2026-07-06-export-surface-jsdoc-gate.md b/docs/rfc/implemented/process/2026-07-06-export-surface-jsdoc-gate.md
index 13b9db565f..54c5c54e44 100644
--- a/docs/rfc/implemented/process/2026-07-06-export-surface-jsdoc-gate.md
+++ b/docs/rfc/implemented/process/2026-07-06-export-surface-jsdoc-gate.md
@@ -17,7 +17,7 @@ The contract by declaration kind:
 - Exported classes need class-level prose; public methods (statics included — reachable on the exported name) follow the function contract; public properties and accessors need prose (a get/set pair is covered by the getter). Overload implementations are exempt — the signatures carry the docs.
 - Exported interfaces, type aliases, and enums need prose on the declaration; member-level enforcement is deliberately deferred (the highest-value member surface — seam service classes — is already under the cordis gate).
 - Exported namespaces recurse (inside an ambient `declare` namespace every member exports implicitly); the namespace itself needs prose only when it does not merge with a documented same-name declaration (the Config-namespace idiom documents the plugin once).
-- `declare module` / `declare global` bodies and `export … from` re-export statements are skipped: an augmentation is not an export of the package, and a re-exported definition is checked where it is defined. An `export import X = N.member` alias documents ITSELF — its target may be a non-exported namespace member no walk visits, so the "definition owns the doc" rationale does not hold for it.
+- `declare module` / `declare global` bodies and `export … from` re-export statements are skipped: an augmentation is not an export of the package, and a re-exported definition is checked where it is defined. An `export import X = N.member` alias documents ITSELF — its target may be a non-exported namespace member no walk visits — and only prose-only target kinds are gate-supported: a callable, class, or namespace target carries signature/member contracts the alias prose cannot hold, so the gate refuses it and demands the declaration be exported directly.
 - Everything else fails CLOSED: `export =` is refused outright, parameters the base never names keep their `@param` duty even as binding patterns, and an exported statement kind the dispatch does not recognize is itself a violation — no export form can pass unchecked by omission.
 
 Three exemption families keep the gate from demanding boilerplate, in the spirit of the cordis gate's `this`/`next` exemptions (documenting an exempt name anyway is allowed; only absence goes unchecked):
diff --git a/packages/core/agent/tests/verify-export-jsdoc.spec.ts b/packages/core/agent/tests/verify-export-jsdoc.spec.ts
index 501dfb8c3e..b95fbdcd9b 100644
--- a/packages/core/agent/tests/verify-export-jsdoc.spec.ts
+++ b/packages/core/agent/tests/verify-export-jsdoc.spec.ts
@@ -338,6 +338,19 @@ describe('verify-export-jsdoc fail-closed forms (review round 1)', () => {
     ))).toEqual([])
   })
 
+  it('refuses an export-import alias to a callable, class, or namespace target', () => {
+    const refusal = /exported alias 'g' .* aliases a callable, class, or namespace target/
+    expect(collectExportJsdocViolations(make(
+      'namespace N {\n  export function f(x: number): number { return x }\n}\n/** Alias. */\nexport import g = N.f\n',
+    ))).toEqual([expect.stringMatching(refusal)])
+    expect(collectExportJsdocViolations(make(
+      'namespace N {\n  export class C {\n    run(x: number): number { return x }\n  }\n}\n/** Alias. */\nexport import g = N.C\n',
+    ))).toEqual([expect.stringMatching(refusal)])
+    expect(collectExportJsdocViolations(make(
+      'namespace N {\n  export namespace Sub {\n    export function f(x: number): number { return x }\n  }\n}\n/** Alias. */\nexport import g = N.Sub\n',
+    ))).toEqual([expect.stringMatching(refusal)])
+  })
+
   it('classifies wrapped function initializers and default exports (parens, satisfies)', () => {
     expect(collectExportJsdocViolations(make(
       'type Fn = (x: number) => number\n/** Wrapped. */\nexport const f = (((x: number): number => x)) satisfies Fn\n',
diff --git a/scripts/verify-export-jsdoc.ts b/scripts/verify-export-jsdoc.ts
index 44b5d2fdaa..a2d8a82f97 100644
--- a/scripts/verify-export-jsdoc.ts
+++ b/scripts/verify-export-jsdoc.ts
@@ -64,8 +64,9 @@
  *   re-export statements with a module specifier (`export … from`) — the
  *   defining module is walked on its own, and external definitions are not
  *   ours to document. An `export import X = N.member` alias documents
- *   ITSELF (its target may be a non-exported namespace member no walk
- *   visits, so a skip would fail open).
+ *   ITSELF, and only prose-only target kinds are gate-supported: a callable,
+ *   class, or namespace target carries signature/member contracts the alias
+ *   cannot hold and is refused (export the declaration directly).
  * - Everything else fails CLOSED: `export =` is refused outright, and an
  *   exported statement kind the dispatch does not recognize is itself a
  *   violation, so no export form can pass unchecked by omission.
@@ -404,10 +405,25 @@ function checkDecl(
     return
   }
   if (ts.isImportEqualsDeclaration(stmt)) {
-    // An alias (`export import X = N.member`) is a distinct exported name and
-    // its target may be a non-exported namespace member no walk ever visits,
-    // so a blanket skip would fail open — the alias documents itself.
-    checkDescribed(`exported alias '${prefix}${stmt.name.text}'${at(stmt)}`, rawJsDoc(w.text, stmt), w)
+    const where = `exported alias '${prefix}${stmt.name.text}'${at(stmt)}`
+    // An alias is a distinct exported name whose target may be a non-exported
+    // namespace member no walk ever visits, so it documents ITSELF — which
+    // matches the gate's strength only for prose-only target kinds. A
+    // callable, class, or namespace target carries signature or member
+    // contracts the alias prose cannot hold: refuse those (fail closed) and
+    // demand the declaration be exported directly. An unresolvable target is
+    // refused for the same reason.
+    const sym = w.checker.getSymbolAtLocation(stmt.name)
+    const target = sym !== undefined && (sym.flags & ts.SymbolFlags.Alias) !== 0 ? w.checker.getAliasedSymbol(sym) : sym
+    const RICH_TARGETS = ts.SymbolFlags.Function | ts.SymbolFlags.Class | ts.SymbolFlags.ValueModule | ts.SymbolFlags.NamespaceModule
+    const rich = target === undefined
+      || (target.flags & RICH_TARGETS) !== 0
+      || w.checker.getTypeOfSymbol(target).getCallSignatures().length > 0
+    if (rich) {
+      w.violations.push(`${where} aliases a callable, class, or namespace target whose signature/member contract the alias cannot carry; export the declaration directly instead.`)
+      return
+    }
+    checkDescribed(where, rawJsDoc(w.text, stmt), w)
     return
   }
   // Fail CLOSED: an exported statement kind this dispatch does not recognize

From 3c572cf70a09a00caf05262c964085cca4bfac87 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 7 Jul 2026 16:22:43 +0800
Subject: [PATCH 5/7] fix CI: stop fixture programs parsing the default lib
 (spec timeouts)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The coverage CI lane timed out (5000ms/test) in verify-export-jsdoc.spec.ts:
every test builds a ts.Program, and the fixture branch of
loadCompilerOptions omitted noLib, so each of the 34 tests parsed the
full default lib — measured 231ms/program bare, ~1.5s/test under
coverage instrumentation locally, past 5s on a 2-core runner. Fixtures
are self-contained and nothing in the walk resolves a lib symbol:
noLib + types:[] drops program creation to ~1ms and the spec's
coverage-mode test time from 53s to 0.16s. The real-repo branch
(tsconfig.base.json options) is untouched.
---
 scripts/verify-export-jsdoc.ts | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/scripts/verify-export-jsdoc.ts b/scripts/verify-export-jsdoc.ts
index a2d8a82f97..3845d60f1b 100644
--- a/scripts/verify-export-jsdoc.ts
+++ b/scripts/verify-export-jsdoc.ts
@@ -510,15 +510,17 @@ function checkScope(statements: readonly ts.Statement[], prefix: string, w: Walk
  * Compiler options for the walk's program. The real repo hands over its
  * tsconfig.base.json (whose `paths` map resolves cross-package imports to
  * source, so heritage-member lookups see seam types); a fixture root without
- * one gets bare defaults — fixtures are single-file and self-contained.
- * Emit-side options are stripped: the walk never emits or asks for
- * diagnostics, it only binds types on demand.
+ * one gets `noLib` + no `@types` — fixtures are single-file and
+ * self-contained, nothing in the walk resolves a lib symbol, and default-lib
+ * parsing is ~99% of per-program cost (it made the fixture spec time out
+ * under CI coverage instrumentation). Emit-side options are stripped: the
+ * walk never emits or asks for diagnostics, it only binds types on demand.
  * @param scanRoot - the root being scanned.
  * @returns compiler options for ts.createProgram.
  */
 function loadCompilerOptions(scanRoot: string): ts.CompilerOptions {
   const cfgPath = resolve(scanRoot, 'tsconfig.base.json')
-  if (!existsSync(cfgPath)) return { skipLibCheck: true }
+  if (!existsSync(cfgPath)) return { skipLibCheck: true, noLib: true, types: [] }
   const cfg = ts.readConfigFile(cfgPath, ts.sys.readFile.bind(ts.sys)) as { config?: unknown }
   const parsed = ts.parseJsonConfigFileContent(cfg.config ?? {}, ts.sys, scanRoot)
   return {

From 51b715433d8f89b96901a008d45908aabec09f3a Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 7 Jul 2026 17:05:32 +0800
Subject: [PATCH 6/7] fix review finding: an export list surfaces only the
 declarators it names
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A name resolved through an export list (or a default-export identifier)
mapped back to its whole VariableStatement, and checkDecl walked every
declarator — so a private sibling sharing the statement with an exported
const was wrongly required to carry JSDoc.

The scope dispatch is now two-phase: requests accumulate per statement
(null = whole statement for a direct export modifier or ambient scope;
name sets union across lists, so two lists naming different declarators
of one statement both count), then each surfaced statement is checked
once with the declarator filter. Regressions pin the private-sibling
skip, the cross-list union, and the default-export sibling.
---
 .../agent/tests/verify-export-jsdoc.spec.ts   | 30 +++++++++++++
 scripts/verify-export-jsdoc.ts                | 42 +++++++++++++++----
 2 files changed, 64 insertions(+), 8 deletions(-)

diff --git a/packages/core/agent/tests/verify-export-jsdoc.spec.ts b/packages/core/agent/tests/verify-export-jsdoc.spec.ts
index b95fbdcd9b..ae7dd1bf81 100644
--- a/packages/core/agent/tests/verify-export-jsdoc.spec.ts
+++ b/packages/core/agent/tests/verify-export-jsdoc.spec.ts
@@ -160,6 +160,36 @@ describe('verify-export-jsdoc export forms', () => {
     ))).toEqual([expect.stringMatching(/exported function 'f' .* has no JSDoc\./)])
   })
 
+  it('does not treat a never-exported sibling declarator as surface (review round 2)', () => {
+    // `export { publicValue }` resolves to the whole variable statement; only
+    // the named declarator is surface — the gate must not demand JSDoc for
+    // the private sibling sharing the statement.
+    expect(collectExportJsdocViolations(make(
+      '/** The public knob. */\nconst publicValue = 1, privateHelper = 2\nexport { publicValue }\nvoid privateHelper\n',
+    ))).toEqual([])
+  })
+
+  it('unions declarators across multiple export lists over one statement (review round 2)', () => {
+    // Two lists each name one declarator of the same undocumented statement:
+    // both are surface (deduplicating on first resolution would drop `b`),
+    // while the never-exported `c` stays out.
+    const violations = collectExportJsdocViolations(make(
+      'const a = 1, b = 2, c = 3\nexport { a }\nexport { b }\nvoid c\n',
+    ))
+    expect(violations).toEqual([
+      expect.stringMatching(/exported const 'a' .* has no JSDoc\./),
+      expect.stringMatching(/exported const 'b' .* has no JSDoc\./),
+    ])
+  })
+
+  it('scopes a default-export identifier to its own declarator (review round 2)', () => {
+    // `export default` of an identifier reaches the statement through the
+    // same name lookup as an export list; the sibling stays private.
+    expect(collectExportJsdocViolations(make(
+      '/** The app entry. */\nconst app = 1, scratch = 2\nexport default app\nvoid scratch\n',
+    ))).toEqual([])
+  })
+
   it('reports a re-exported module once, at its defining file', () => {
     const violations = collectExportJsdocViolations(fixture({
       'index.ts': "export * from './other.ts'\n",
diff --git a/scripts/verify-export-jsdoc.ts b/scripts/verify-export-jsdoc.ts
index 3845d60f1b..46e2f82f2b 100644
--- a/scripts/verify-export-jsdoc.ts
+++ b/scripts/verify-export-jsdoc.ts
@@ -321,6 +321,11 @@ function checkClass(cls: ts.ClassDeclaration, name: string, w: Walk): void {
  * @param byName - this scope's named declarations (for namespace/sibling-merge lookups).
  * @param ambient - whether the enclosing scope is ambient (`declare`), where members export implicitly.
  * @param w - the walk state violations append to.
+ * @param only - for a multi-declarator variable statement reached through an
+ *   export list (or a default-export identifier), the declarator names that
+ *   are actually exported; `null` means the whole statement is surface
+ *   (direct `export` modifier or ambient scope). Non-variable statements
+ *   declare exactly one name, so the filter never applies to them.
  */
 function checkDecl(
   stmt: ts.Statement,
@@ -329,6 +334,7 @@ function checkDecl(
   byName: Map<string, ts.Statement[]>,
   ambient: boolean,
   w: Walk,
+  only: ReadonlySet<string> | null = null,
 ): void {
   const at = (n: ts.Node): string => ` (${pointer(w.rel, w.sf, n)})`
   if (ts.isFunctionDeclaration(stmt)) {
@@ -359,6 +365,7 @@ function checkDecl(
     const raw = rawJsDoc(w.text, stmt) // JSDoc sits on the statement, not the declarator
     for (const d of stmt.declarationList.declarations) {
       const name = ts.isIdentifier(d.name) ? d.name.text : d.name.getText(w.sf)
+      if (only !== null && !only.has(name)) continue // sibling declarator the export list never named: not surface
       if (prefix === '' && PROTOCOL_EXPORTS.has(name)) continue // cordis plugin-protocol slot
       const where = `exported const '${prefix}${name}'${at(d)}`
       const annotation = d.type !== undefined ? callableAnnotation(d.type) : null
@@ -462,11 +469,25 @@ function checkScope(statements: readonly ts.Statement[], prefix: string, w: Walk
       }
     }
   }
-  const checked = new Set<ts.Statement>()
-  const check = (stmt: ts.Statement): void => {
-    if (checked.has(stmt)) return
-    checked.add(stmt)
-    checkDecl(stmt, prefix, overloadSigs, byName, ambient, w)
+  // Two-phase dispatch. Phase one accumulates WHICH statements are surface
+  // and, for a variable statement reached by name (an export list or a
+  // default-export identifier), which of its declarators the exports actually
+  // name — `null` marks the whole statement as surface (a direct `export`
+  // modifier, or an ambient scope). Requests for the same statement merge:
+  // `null` absorbs any name set, and name sets union, so
+  // `export { a }; export { b }` over one `const a = …, b = …` checks both
+  // declarators while a never-exported sibling stays out of the surface.
+  // Phase two runs each surfaced statement exactly once. (Checking a
+  // statement eagerly per request would either re-check on the second list or
+  // — deduplicated — silently drop the second list's declarators.)
+  const requested = new Map<ts.Statement, Set<string> | null>()
+  const request = (stmt: ts.Statement, name: string | null): void => {
+    const prior = requested.get(stmt)
+    if (name === null || prior === null) {
+      requested.set(stmt, null)
+      return
+    }
+    requested.set(stmt, prior === undefined ? new Set([name]) : prior.add(name))
   }
   for (const stmt of statements) {
     if (ts.isModuleDeclaration(stmt)
@@ -477,7 +498,8 @@ function checkScope(statements: readonly ts.Statement[], prefix: string, w: Walk
       if (stmt.moduleSpecifier) continue // re-export: the defining module is walked on its own
       if (stmt.exportClause && ts.isNamedExports(stmt.exportClause)) {
         for (const el of stmt.exportClause.elements) {
-          for (const decl of byName.get((el.propertyName ?? el.name).text) ?? []) check(decl)
+          const local = (el.propertyName ?? el.name).text
+          for (const decl of byName.get(local) ?? []) request(decl, local)
           // a name with no local declaration is an imported binding re-exported
           // without a specifier — its defining module is walked on its own
         }
@@ -494,7 +516,7 @@ function checkScope(statements: readonly ts.Statement[], prefix: string, w: Walk
       const where = `default export (${pointer(w.rel, w.sf, stmt)})`
       const expr = unwrapExpression(stmt.expression)
       if (ts.isIdentifier(expr)) {
-        for (const decl of byName.get(expr.text) ?? []) check(decl)
+        for (const decl of byName.get(expr.text) ?? []) request(decl, expr.text)
       } else if (ts.isArrowFunction(expr) || ts.isFunctionExpression(expr)) {
         checkFunctionLike(where, rawJsDoc(w.text, stmt), expr.parameters, expr.type, false, w)
       } else {
@@ -502,7 +524,11 @@ function checkScope(statements: readonly ts.Statement[], prefix: string, w: Walk
       }
       continue
     }
-    if (isExported(stmt) || (ambient && !ts.isImportDeclaration(stmt))) check(stmt)
+    if (isExported(stmt) || (ambient && !ts.isImportDeclaration(stmt))) request(stmt, null)
+  }
+  for (const stmt of statements) {
+    const only = requested.get(stmt)
+    if (only !== undefined) checkDecl(stmt, prefix, overloadSigs, byName, ambient, w, only)
   }
 }
 

From 5e4ac5e4726086a9b042e34e37f8863b44af2f94 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 7 Jul 2026 20:30:34 +0800
Subject: [PATCH 7/7] fix review findings: CI leaf-gate wiring, heritage return
 surface, AGENTS.md self-containedness
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- run-gates.ts docSyncLeafGates() gains verify-export-jsdoc — CI lanes
  and the pre-push hook execute this leaf list, not the doc-sync npm
  script, so the gate was previously unenforced there (proven by
  SessionForkErrorCode landing undocumented via a master merge while
  checks stayed green; now documented). Same wiring gap fixed for
  master's verify-config-catalog, which was also missing from the list.
- The heritage exemption now recovers the base's return surface: a void
  base return carried no @returns duty, so an override returning a
  concrete result documents it itself (annotated overrides run the
  standard check; unannotated ones are classified by the checker so
  faithful void overrides need no boilerplate annotation). Three new
  negative-path tests pin it; RFC and module doc updated.
- AGENTS.md states each principle inline instead of citing RFCs (eight
  citations removed; high-level doc links kept) and the editing section
  now carries the self-containedness rule.
- Generated catalogs/graphs regenerated for the shifted line pointers.
---
 AGENTS.md                                     | 18 ++--
 docs/cordis-catalog/services.md               |  2 +-
 .../2026-07-06-export-surface-jsdoc-gate.md   |  2 +-
 .../agent/tests/verify-export-jsdoc.spec.ts   | 65 +++++++++++++++
 packages/core/session/src/index.ts            |  8 ++
 scripts/run-gates.ts                          |  2 +
 scripts/verify-export-jsdoc.ts                | 82 ++++++++++++++-----
 7 files changed, 148 insertions(+), 31 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index c5c6fcd5c8..57d46556fd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -83,21 +83,21 @@ Real-API tests and demos read `DEEPSEEK_API_KEY` (and optional `DEEPSEEK_BASE_UR
 - Every npm package is `@deepseek-ai/dsh-<name>`; vendored packages keep upstream names and are `private: true`. `cordis` is a peerDependency (+ dev) of every harness package.
 - ESM everywhere (`"type": "module"`). Cross-package imports use package names, never relative paths; in-package relative imports use explicit `.ts` extensions. Dev/test/demo run unbuilt via tsx + the root tsconfig `paths` map; builds are for outside consumers only.
 - **Registrations are effects**: every contribution goes through `ctx.effect()` / `ctx.on()`; a registry's `register()` returns the disposer.
-- **Typed events via declaration merging**; extensible unions use the merge-extensible-map pattern (`ContentBlockMap`, `SessionEventMap`, …). Every new event's JSDoc carries an `@mode` tag and a `@param` per payload parameter (`this`/trailing `next` exempt); every public service-class method documents each parameter and non-void return (`@param`/`@returns`) — the catalog generator hard-errors otherwise ([completeness RFC](docs/rfc/implemented/process/2026-07-04-cordis-jsdoc-completeness-gate.md)); mode semantics are in the [generated events catalog](docs/cordis-catalog/events.md) header ([catalog RFC](docs/rfc/implemented/process/2026-06-20-generated-cordis-catalog.md)).
+- **Typed events via declaration merging**; extensible unions use the merge-extensible-map pattern (`ContentBlockMap`, `SessionEventMap`, …). Every new event's JSDoc carries an `@mode` tag and a `@param` per payload parameter (`this`/trailing `next` exempt); every public service-class method documents each parameter and non-void return (`@param`/`@returns`) — the catalog generator hard-errors otherwise; mode semantics are in the [generated events catalog](docs/cordis-catalog/events.md) header.
 - **Discriminated unions: `switch` on the tag**, not if-chains. Closed unions end with `default: assertNever(...)`; merge-extensible unions must NOT — handle known cases and fall through `default` with a comment.
 - **Waterfall listeners MUST call `next()`** to delegate; returning without it is the veto ([semantics](docs/cordis-primer.md#cordis-waterfall-semantics)).
-- **Model-visible ⟺ logged**: anything that reaches a model request must be reconstructable from the session log; a new model-visible input requires a session event ([reconstructability RFC](docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md)).
+- **Model-visible ⟺ logged**: anything that reaches a model request must be reconstructable from the session log; a new model-visible input requires a session event.
 - **Plugins, not loop changes**: new behavior goes on the documented extension seams; changing `agent-loop` requires updating docs/architecture.md.
-- **Capability seams are three packages** — interface / implementation / consumer ([capability seams](docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)); don't split preemptively.
+- **Capability seams are three packages** — interface / implementation / consumer; don't split preemptively.
 - **Explicit > implicit at package seams**: defaulting is an explicit `resolve(request): Spec` step in the owning implementation, never a hidden `?? default` inside `run()` (the `dsh-bash` request/spec split is the template).
 - **No hardcoded tunables in plugins**: anything two deployments could want different — timeouts, caps, model names, base URLs — is a defaulted, validated `Config` field, not a literal; a `DEFAULT_*` constant or test-only seam is not configurability. The test: changeable from `cordis.yml`, no code edit. Protocol/wire constants, external-spec values, security invariants stay hardcoded.
-- **Opaque cross-boundary ids are branded** (`Branded<B>` from `dsh-brand`), never bare `string` ([branded IDs](docs/rfc/implemented/architecture/2026-06-20-branded-ids.md)).
+- **Opaque cross-boundary ids are branded** (`Branded<B>` from `dsh-brand`), never bare `string`.
 - **An empty `catch` names what it swallows** and why nothing else can reach it; keep the `try` to one statement.
 - **Symmetry is usually more correct**: parallel values get parallel form; asymmetry smells of a missed extraction.
-- **Tests document behavior, not golden truth**: a green test pins what the code DOES, not what it SHOULD do. Before preserving a behavior solely for its test, ask whether it is load-bearing; an artifact changes together with its test, with the why in the PR ([worked example](docs/rfc/implemented/simplification/2026-06-19-drop-mutable-session-summary.md)).
-- **RFCs are proposals, not golden truth**: validate its premise against current code before implementing; friction is evidence of over-reach — amend on the way to `implemented/` ([worked example](docs/rfc/implemented/simplification/2026-06-20-public-agent-stop-surface.md)).
+- **Tests document behavior, not golden truth**: a green test pins what the code DOES, not what it SHOULD do. Before preserving a behavior solely for its test, ask whether it is load-bearing; an artifact changes together with its test, with the why in the PR.
+- **RFCs are proposals, not golden truth**: validate its premise against current code before implementing; friction is evidence of over-reach — amend on the way to `implemented/`.
 - **Testing policy** — [docs/testing.md](docs/testing.md). Transcript/UX changes need snapshots or a PR note. Snapshot fixtures must replay on macOS/Linux; avoid GNU/BSD-only commands (e.g. `sed -i`); fix fixtures, not normalizers.
-- **A tool's ACP render intent is part of its design**, decided up front (`generic`/`terminal`/`diff`, `locations`); presentation methods are pure functions of `args` ([render-intent RFC](docs/rfc/implemented/architecture/2026-07-02-tool-render-intent-union.md), [cookbook](docs/cookbook/adding-a-tool.md)).
+- **A tool's ACP render intent is part of its design**, decided up front (`generic`/`terminal`/`diff`, `locations`); presentation methods are pure functions of `args` ([cookbook](docs/cookbook/adding-a-tool.md)).
 - **A new capability seam, lifecycle shape, or transcript surface names its coverage at every tier (unit, e2e, snapshot) at plan time** and verifies the harness can express it — a gap is scheduled work, not a mid-build surprise.
 - **Merge PRs with merge commits** (`gh pr merge --merge`), never squash/rebase. **Never rewrite a pushed branch**; update a child by merging its parent down. **A review fix lands on the PR that introduced the issue, as a separate commit**, then merges down ([stacked-review guide](docs/cookbook/responding-to-pr-review-on-a-stack.md)).
 - TODO markers: `FIXME`/`TODO`/`XXX` by urgency ([semantics](docs/development.md)).
@@ -109,13 +109,13 @@ Real-API tests and demos read `DEEPSEEK_API_KEY` (and optional `DEEPSEEK_BASE_UR
 
 ## Type safety and documentation
 
-Everything compiles under `strict: true` with `noImplicitAny`; every remaining `any` carries a comment saying why a narrower type is infeasible. Every module has a module-level doc comment; every export (and non-obvious method) has a JSDoc explaining semantics — contracts, disposal, errors — not the name restated; internal helpers only where non-obvious; one-liners when one line suffices. The export half is mechanical: `verify-export-jsdoc` (in `doc-sync`) requires description prose on every package export plus `@param`/`@returns` (and an annotated return) on function-like ones — heritage-declared members, plugin-protocol slots, and constructors exempt ([export-gate RFC](docs/rfc/implemented/process/2026-07-06-export-surface-jsdoc-gate.md)). Lean toward the stricter lint rule and the extra mechanical gate: encode invariants in checks (`verify-*` scripts), preferring a narrow justified escape hatch over a rule left off globally. Type gymnastics are acceptable inside core packages when they buy plugin-author DX (the `defineTool` schema DSL is the canonical example).
+Everything compiles under `strict: true` with `noImplicitAny`; every remaining `any` carries a comment saying why a narrower type is infeasible. Every module has a module-level doc comment; every export (and non-obvious method) has a JSDoc explaining semantics — contracts, disposal, errors — not the name restated; internal helpers only where non-obvious; one-liners when one line suffices. The export half is mechanical: `verify-export-jsdoc` (in `doc-sync`) requires description prose on every package export plus `@param`/`@returns` (and an annotated return) on function-like ones. Heritage-declared members, plugin-protocol slots, and constructors are exempt — their docs' one home is the seam declaration, the framework protocol, and the class doc respectively. Lean toward the stricter lint rule and the extra mechanical gate: encode invariants in checks (`verify-*` scripts), preferring a narrow justified escape hatch over a rule left off globally. Type gymnastics are acceptable inside core packages when they buy plugin-author DX (the `defineTool` schema DSL is the canonical example).
 
 Docs are part of every change: code changes update their README and JSDoc in the SAME change; a bilingual-pair edit updates the counterpart and re-records ([i18n contract](docs/i18n/README.md)). The writing rules — document the current state never the history, one physical line per paragraph, one home per fact — and the word-budget gate live in [docs/AGENTS.md](docs/AGENTS.md).
 
 ## Editing these instructions
 
-`AGENTS.md` is the real file; `CLAUDE.md` is a symlink to it (root, `packages/`, `examples/`). Edit `AGENTS.md`, never the symlink. This file is budget-gated (`verify-doc-budgets`): condense first if it is possible without sacrificing clarity; truly needed additions may justify a ceiling raise.
+`AGENTS.md` is the real file; `CLAUDE.md` is a symlink to it (root, `packages/`, `examples/`). Edit `AGENTS.md`, never the symlink. Keep it self-contained: state each principle inline instead of citing RFCs (they stay discoverable via the RFC index); linking high-level docs — architecture, testing, cookbooks — is fine. This file is budget-gated (`verify-doc-budgets`): condense first if it is possible without sacrificing clarity; truly needed additions may justify a ceiling raise.
 
 ## Vendoring policy
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 4752ce2891..1d929542b8 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -164,7 +164,7 @@ list(): Session[]
 fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session
 ```
 
-Source: [`packages/core/session/src/index.ts:397`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:405`](../../packages/core/session/src/index.ts)
 
 ## `ctx.subagents` — `SubagentService`
 
diff --git a/docs/rfc/implemented/process/2026-07-06-export-surface-jsdoc-gate.md b/docs/rfc/implemented/process/2026-07-06-export-surface-jsdoc-gate.md
index 54c5c54e44..2e98808426 100644
--- a/docs/rfc/implemented/process/2026-07-06-export-surface-jsdoc-gate.md
+++ b/docs/rfc/implemented/process/2026-07-06-export-surface-jsdoc-gate.md
@@ -22,7 +22,7 @@ The contract by declaration kind:
 
 Three exemption families keep the gate from demanding boilerplate, in the spirit of the cordis gate's `this`/`next` exemptions (documenting an exempt name anyway is allowed; only absence goes unchecked):
 
-- **Heritage members.** A class member whose name exists on an `extends`/`implements` heritage type is exempt: the seam declaration is the doc's one home, and the IDE inherits it on hover — re-documenting every `LocalBashExecutor.run` invites drift. The exemption stops where the override grows surface the base never documented: a protected-only base member does not exempt a public override, and parameters the base never names keep their `@param` duty (an underscore-prefixed rename of a base parameter — the deliberately-unused marker — is the same parameter). This is the one question the walk asks the TYPE CHECKER (heritage types live across package boundaries, resolved through the repo `paths` map); everything else stays pure AST, and the annotated-return requirement is kept for symmetry with the cordis gate (it bound nothing at adoption — every exported function was already annotated).
+- **Heritage members.** A class member whose name exists on an `extends`/`implements` heritage type is exempt: the seam declaration is the doc's one home, and the IDE inherits it on hover — re-documenting every `LocalBashExecutor.run` invites drift. The exemption stops where the override grows surface the base never documented: a protected-only base member does not exempt a public override, parameters the base never names keep their `@param` duty (an underscore-prefixed rename of a base parameter — the deliberately-unused marker — is the same parameter), and a concrete result above a void base return keeps its `@returns` duty (an unannotated override's inferred return is classified by the checker, so a faithful void override needs no boilerplate annotation). Heritage lookups and that one return classification are the walk's only TYPE CHECKER questions (heritage types live across package boundaries, resolved through the repo `paths` map); everything else stays pure AST, and the annotated-return requirement is kept for symmetry with the cordis gate (it bound nothing at adoption — every exported function was already annotated).
 - **Plugin-protocol slots.** Top-level `name` / `inject` / `reusable` / `Config` consts and the `apply` entry, plus the same slots as statics on a plugin class, are framework protocol: their shape is fixed by cordis, and the module doc comment plus the `interface Config` carry the plugin's real semantics.
 - **Constructors**, mirroring the cordis gate: plugin classes are framework-constructed, and the class doc owns the story.
 
diff --git a/packages/core/agent/tests/verify-export-jsdoc.spec.ts b/packages/core/agent/tests/verify-export-jsdoc.spec.ts
index ae7dd1bf81..b699a72765 100644
--- a/packages/core/agent/tests/verify-export-jsdoc.spec.ts
+++ b/packages/core/agent/tests/verify-export-jsdoc.spec.ts
@@ -487,4 +487,69 @@ export class Impl extends Base {
 }
 `))).toEqual([expect.stringMatching(/exported class method 'Impl.run' .* is a binding pattern/)])
   })
+
+  it('revives the @returns duty when an override grows a concrete result over a void base', () => {
+    const voidBase = `
+/** Seam. */
+export abstract class Base {
+  /** Do it (fire-and-forget). */
+  abstract run(): void
+}
+`
+    expect(collectExportJsdocViolations(make(`${voidBase}
+/** Impl. */
+export class Impl extends Base {
+  override run(): number { return 1 }
+}
+`))).toEqual([expect.stringMatching(/exported class method 'Impl.run' .* is missing @returns \(return type: number\)\./)])
+    expect(collectExportJsdocViolations(make(`${voidBase}
+/** Impl. */
+export class Impl extends Base {
+  /**
+   * Do it and count.
+   * @returns how many were done.
+   */
+  override run(): number { return 1 }
+}
+`))).toEqual([])
+  })
+
+  it('classifies an unannotated override return over a void base via the checker', () => {
+    const voidBase = `
+/** Seam. */
+export abstract class Base {
+  /** Do it (fire-and-forget). */
+  abstract run(): void
+}
+`
+    expect(collectExportJsdocViolations(make(`${voidBase}
+/** Impl. */
+export class Impl extends Base {
+  override run() { return 1 }
+}
+`))).toEqual([expect.stringMatching(/exported class method 'Impl.run' .* non-void result its heritage declaration does not document/)])
+    expect(collectExportJsdocViolations(make(`${voidBase}
+/** Impl (faithful void, no annotation needed). */
+export class Impl extends Base {
+  override run() {}
+}
+`))).toEqual([])
+  })
+
+  it('keeps the full exemption when the base return already carries the @returns duty', () => {
+    expect(collectExportJsdocViolations(make(`
+/** Seam. */
+export abstract class Base {
+  /**
+   * Count things.
+   * @returns the count.
+   */
+  abstract run(): number
+}
+/** Impl. */
+export class Impl extends Base {
+  override run(): number { return 1 }
+}
+`))).toEqual([])
+  })
 })
diff --git a/packages/core/session/src/index.ts b/packages/core/session/src/index.ts
index b98bcd8d84..cd9e1828b2 100644
--- a/packages/core/session/src/index.ts
+++ b/packages/core/session/src/index.ts
@@ -373,6 +373,14 @@ export class Session {
 /** A fork source: either the live session object or its live store id. */
 export type SessionForkSource = Session | SessionId
 
+/**
+ * Rejection codes for session forking: the fork source id is unknown to the
+ * live store (`SESSION_NOT_FOUND`) or names a session object that is not the
+ * store's live instance (`SESSION_NOT_LIVE`); the requested child id is
+ * already taken (`SESSION_ALREADY_EXISTS`); the boundary is not a contiguous
+ * existing seq (`INVALID_BOUNDARY`); or the boundary event is not a
+ * `turn/end` — a fork must cut on a closed turn (`OPEN_TURN`).
+ */
 export type SessionForkErrorCode =
   | 'SESSION_NOT_FOUND'
   | 'SESSION_NOT_LIVE'
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index 195e188858..6c844f842a 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -257,7 +257,9 @@ function docSyncLeafGates(): Gate[] {
   return [
     pnpmScript('doc-typecheck', 'doc-typecheck'),
     pnpmScript('cordis-catalog', 'verify-cordis-catalog', { label: 'cordis catalog' }),
+    pnpmScript('export-jsdoc', 'verify-export-jsdoc', { label: 'export jsdoc' }),
     pnpmScript('tool-catalog', 'verify-tool-catalog', { label: 'tool catalog' }),
+    pnpmScript('config-catalog', 'verify-config-catalog', { label: 'config catalog' }),
     pnpmScript('persistence-catalog', 'verify-persistence-catalog', { label: 'persistence catalog' }),
     pnpmScript('doc-graphs', 'verify-doc-graphs', { label: 'doc graphs' }),
     pnpmScript('markdown-wrap', 'verify-md-wrap', { label: 'markdown wrap' }),
diff --git a/scripts/verify-export-jsdoc.ts b/scripts/verify-export-jsdoc.ts
index 46e2f82f2b..779888ab90 100644
--- a/scripts/verify-export-jsdoc.ts
+++ b/scripts/verify-export-jsdoc.ts
@@ -36,9 +36,11 @@
  *   the doc's one home, the IDE inherits it, and re-documenting every
  *   implementation invites drift — UNLESS the override grows surface the
  *   base never documented: a protected-only base member does not exempt a
- *   public override, and parameters the base never names keep their `@param`
- *   duty. This is the one question the walk asks the TYPE CHECKER (heritage
- *   members live across package boundaries); everything else is pure AST.
+ *   public override, parameters the base never names keep their `@param`
+ *   duty, and a concrete result above a void base return keeps its
+ *   `@returns` duty. Heritage members (and classifying an unannotated
+ *   override's inferred return above a void base) are the questions the walk
+ *   asks the TYPE CHECKER; everything else is pure AST.
  *   Constructors are exempt like the cordis gate's: plugin classes are
  *   framework-constructed, and the class doc owns the story.
  * - Exported interfaces, type aliases, enums: description prose on the
@@ -165,29 +167,31 @@ function callableAnnotation(type: ts.TypeNode): ts.SignatureDeclarationBase | 'r
  * is the doc's one home (the IDE inherits it on hover) and the member needs no
  * doc of its own — EXCEPT where the override grows public surface the base
  * never documented: a base member that is protected on every declaration does
- * not exempt a public override (consumers could not call it before), and
+ * not exempt a public override (consumers could not call it before);
  * parameters the base never names keep their own `@param` duty (the caller
  * reads the seam doc, which cannot describe them; an underscore-prefixed
  * rename of a base parameter — the deliberately-unused marker — is the same
- * parameter, not new surface). Static members are looked
- * up on the base CONSTRUCTOR type (only an `extends` expression has one; an
- * unresolvable or interface expression yields no property and therefore no
- * exemption).
+ * parameter, not new surface); and a void base return carried no `@returns`
+ * duty, so an override returning a concrete result documents it itself.
+ * Static members are looked up on the base CONSTRUCTOR type (only an
+ * `extends` expression has one; an unresolvable or interface expression
+ * yields no property and therefore no exemption).
  * @param cls - the class whose heritage to search.
  * @param name - the member name to look up.
  * @param staticSide - whether to search the constructor side instead of the instance side.
  * @param checker - the program's type checker.
  * @returns null when no exemption applies; otherwise the parameter names the
- * base declarations carry (`baseParams: null` means the base's parameters are
- * not syntactically recoverable — a complex heritage type — and the member is
- * exempt in full).
+ * base declarations carry (`baseParams: null` when not syntactically
+ * recoverable — a complex heritage type — exempting all parameters) plus
+ * whether every recoverable base return annotation is `void`-like
+ * (`baseVoidReturn: null` when none is recoverable, exempting the result).
  */
 function heritageExemption(
   cls: ts.ClassDeclaration,
   name: string,
   staticSide: boolean,
   checker: ts.TypeChecker,
-): { baseParams: Set<string> | null } | null {
+): { baseParams: Set<string> | null; baseVoidReturn: boolean | null } | null {
   const isProtected = (d: ts.Declaration): boolean =>
     (ts.canHaveModifiers(d) ? ts.getModifiers(d) : undefined)?.some(m => m.kind === ts.SyntaxKind.ProtectedKeyword) ?? false
   for (const clause of cls.heritageClauses ?? []) {
@@ -198,24 +202,50 @@ function heritageExemption(
       const decls = prop.declarations ?? []
       if (decls.length > 0 && decls.every(isProtected)) continue // public override of a protected base: new surface
       let baseParams: Set<string> | null = null
+      let baseVoidReturn: boolean | null = null
       for (const d of decls) {
         let params: readonly ts.ParameterDeclaration[] | undefined
-        if (ts.isMethodDeclaration(d) || ts.isMethodSignature(d)) params = d.parameters
-        else if ((ts.isPropertySignature(d) || ts.isPropertyDeclaration(d)) && d.type !== undefined && ts.isFunctionTypeNode(d.type)) {
+        let returnType: ts.TypeNode | undefined
+        if (ts.isMethodDeclaration(d) || ts.isMethodSignature(d)) {
+          params = d.parameters
+          returnType = d.type
+        } else if ((ts.isPropertySignature(d) || ts.isPropertyDeclaration(d)) && d.type !== undefined && ts.isFunctionTypeNode(d.type)) {
           params = d.type.parameters
+          returnType = d.type.type
         } else continue
         baseParams ??= new Set()
         // Leading underscores are the deliberately-unused marker (eslint
         // argsIgnorePattern), not a rename: `_cwd` overriding `cwd` is the
         // same parameter, so compare underscore-stripped on both sides.
         for (const p of params) if (ts.isIdentifier(p.name)) baseParams.add(p.name.text.replace(/^_+/, ''))
+        if (returnType !== undefined) {
+          const voidish = /^(void|Promise<void>)$/.test(returnType.getText(d.getSourceFile()).replace(/\s+/g, ' '))
+          baseVoidReturn = (baseVoidReturn ?? true) && voidish
+        }
       }
-      return { baseParams }
+      return { baseParams, baseVoidReturn }
     }
   }
   return null
 }
 
+/**
+ * True when a method's INFERRED return type is void-like (void, undefined,
+ * never, or a promise of one) — the one return the walk asks the checker to
+ * classify: an unannotated override above a void heritage member, where
+ * demanding an annotation just to prove faithfulness would be boilerplate.
+ * @param m - a method declaration with no return type annotation.
+ * @param checker - the program's type checker.
+ * @returns true when the inferred result carries nothing to document.
+ */
+function inferredReturnIsVoidish(m: ts.MethodDeclaration, checker: ts.TypeChecker): boolean {
+  const sig = checker.getSignatureFromDeclaration(m)
+  if (sig === undefined) return true // no callable signature: nothing classifiable to document
+  const returned = checker.getReturnTypeOfSignature(sig)
+  const awaited = checker.getAwaitedType(returned) ?? returned
+  return (awaited.flags & (ts.TypeFlags.Void | ts.TypeFlags.Undefined | ts.TypeFlags.Never)) !== 0
+}
+
 /**
  * Check description-prose presence for one labeled declaration: JSDoc must
  * exist and carry prose above its block tags.
@@ -285,17 +315,29 @@ function checkClass(cls: ts.ClassDeclaration, name: string, w: Walk): void {
       if (m.body && overloadSigs.has(mname)) continue // overload implementation: the signatures carry the docs
       const where = `exported class method '${name}.${mname}' (${pointer(w.rel, w.sf, m)})`
       if (exemption !== null) {
-        // The heritage declaration owns prose and @returns; parameters the
-        // base never names — including binding patterns, which no base
-        // declaration can name — are new surface and keep their @param duty.
+        const raw = rawJsDoc(w.text, m)
+        // The heritage declaration owns the prose; parameters the base never
+        // names — including binding patterns, which no base declaration can
+        // name — are new surface and keep their @param duty.
         const base = exemption.baseParams
         const inBase = (p: ts.ParameterDeclaration): boolean =>
           base !== null && ts.isIdentifier(p.name) && base.has(p.name.text.replace(/^_+/, ''))
         if (base !== null && m.parameters.some(p => !thisReceiver(p) && !inBase(p))) {
-          const { params } = parseTags(rawJsDoc(w.text, m))
-          checkParams(where, 'export', m.parameters, params, w.sf,
+          checkParams(where, 'export', m.parameters, parseTags(raw).params, w.sf,
             p => thisReceiver(p) || inBase(p), w.violations)
         }
+        // A void base return carried no @returns duty, so an override growing
+        // a concrete result documents it itself. An annotated override runs
+        // the standard check; an inferred one is classified by the checker
+        // (this branch is already the checker's domain), so a faithful void
+        // override stays exempt without a boilerplate annotation.
+        if (exemption.baseVoidReturn === true) {
+          if (m.type !== undefined) {
+            checkReturns(where, m.type, parseTags(raw).returns, w.sf, w.violations)
+          } else if (!inferredReturnIsVoidish(m, w.checker)) {
+            w.violations.push(`${where} returns a non-void result its heritage declaration does not document; annotate the return type and add @returns.`)
+          }
+        }
         continue
       }
       checkFunctionLike(where, rawJsDoc(w.text, m), m.parameters, m.type, false, w)