docs: tighten prose audit after master retarget

scripts/demo-code-mode.mjs

@@ -1,12 +1,6 @@
 /**
- * Boot the Code Mode demo under the UI named on the command line:
- * `pnpm run demo:code-mode [repl|acp]`, default `repl`. Code Mode is the
- * point — the UI is just the surface it happens to wear: each UI boots its
- * base example through that example's `code-mode.cordis.yml` overlay
- * (include ./cordis.yml, flip `tools.mode` to `code`, insert the
- * worker-thread code runtime). Both need DEEPSEEK_API_KEY (repo-root .env
- * works). Anything else on the command line is a misconfiguration and
- * fails loud with usage.
+ * Boot the REPL or ACP Code Mode overlay, defaulting to REPL. Both require a
+ * DeepSeek API key; unsupported arguments fail with usage.
  */
 import { spawn } from 'node:child_process'
 

scripts/doc-budgets.manifest.json

@@ -5,7 +5,7 @@
   "docs/cordis-primer.md": 550,
   "docs/defensive-patterns.md": 550,
   "docs/testing.md": 800,
-  "examples/AGENTS.md": 462,
-  "packages/AGENTS.md": 460,
+  "examples/AGENTS.md": 200,
+  "packages/AGENTS.md": 290,
   "packages/README.md": 710
 }

scripts/gen-doc-graphs.ts

@@ -785,7 +785,7 @@ function renderToolPipeline(): string {
     '  allResults --> context',
     '```',
     '',
-    'Filesystem read-before-edit checks live below `tool-fs` on the `fs/*` event gate; hook bridges and approval-triggering permission policy enter through the generic pre/post tool waterfalls, while `ctx.approval` resolves an `ask` before the monotonic guards; owner policy that must not be reordered uses registered guards; and around-dispatch concerns like the tool-call timeout policy (`@deepseek-ai/dsh-timeout-policy`) wrap core dispatch on `tools/execute`. The synchronous `tools/result` notification observes the immutable final outcome after every transform, lossless-JSON validation, and outer error normalization. That split lets the same hooks observe bash, fs, web, todo, skill, and subagent calls without coupling those tools to one policy service. Code Mode rides the whole pipeline twice over: `run_code` is the reserved registry-owned transport whose body enters the pipeline, and each tool call its program makes re-enters `ctx.tools.execute()` — serialized one at a time, carrying the outer execution\'s opaque token for correlation, and logged as a `tool/code-dispatch` session event, with a deny surfacing to the program as a binding rejection (a sub-call\'s `additionalContext` is deliberately dropped — no safe outlet mid-run preserves call/result adjacency).',
+    'Filesystem read-before-edit policy stays on `fs/*` events. Generic pre/post waterfalls host hook and approval policy, `ctx.approval` resolves asks before guards, and `tools/execute` hosts around-dispatch concerns such as timeouts. `tools/result` observes the immutable final outcome. Code Mode sends both `run_code` and its serialized sub-calls through this pipeline; sub-calls carry the parent token, log `tool/code-dispatch`, surface denials as binding rejections, and omit `additionalContext` to preserve call/result adjacency.',
     '',
     ...maintenanceFooter(maintenance),
   ].join('\n')

scripts/gen-persistence-catalog.ts

@@ -81,15 +81,7 @@ function rawJsDoc(text: string, node: ts.Node): string {
   return jsdoc ? text.slice(jsdoc.pos, jsdoc.end) : ''
 }
 
-/**
- * Parse a raw JSDoc block into description prose, flagging whether any `@mode`
- * tag is present (forbidden on log events). 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.
- */
+/** Parse pre-tag JSDoc prose into one-line paragraphs and bullets for the catalog. */
 function parseJsDoc(raw: string): { doc: string; hasMode: boolean } {
   const inner = raw
     .replace(/^\/\*\*/, '')

scripts/verify-export-jsdoc.ts

@@ -73,12 +73,8 @@ function unwrapExpression(e: ts.Expression): ts.Expression {
 }
 
 /**
- * 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.
+ * Classify inline callable annotations. Mixed callable literals fail closed;
+ * other annotations are ordinary value shapes.
  * @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.
  */

scripts/verify-mermaid.ts

@@ -1,15 +1,6 @@
 /**
- * Doc-sync gate: verify every fenced ```mermaid block parses with Mermaid's
- * own parser. Markdown link/type/code gates can say a diagram block exists and
- * is linked, but only Mermaid can catch syntax errors that GitHub would fail to
- * render.
- *
- * Scope matches the Markdown link gate so any Mermaid diagram in repo-authored
- * docs is checked: README.md, README.zh.md, docs/** /*.md,
- * packages/* /*.md, packages/* /* /*.md, examples/** /*.md, AGENTS.md,
- * packages/AGENTS.md, and .agents/skills/** /*.md.
- *
- * Run: `tsx scripts/verify-mermaid.ts`.
+ * Parse every repo-authored Mermaid fence with Mermaid itself. Scope matches the
+ * Markdown link gate. Run with `tsx scripts/verify-mermaid.ts`.
  */
 
 import { globSync, readFileSync, realpathSync } from 'node:fs'