Merge remote-tracking branch 'origin/master' into cross-family-fs-sandbox

# Conflicts:
#	.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.i18n.yaml
#	.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md
#	.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.zh.md
#	docs/capability-seams.md
#	docs/cordis-catalog/events.md
#	docs/cordis-catalog/services.md
#	docs/event-producer-consumer.md
#	docs/module-graph.md
#	docs/persistence-catalog.md
#	docs/rfc/INDEX.md
#	examples/acp-agent/README.md
#	examples/acp-agent/fs.cordis.snapshot.yml
#	examples/acp-agent/fs.cordis.yml
#	examples/acp-agent/tests/snapshots/escalation-approved/session.jsonl
#	examples/acp-agent/tests/snapshots/escalation-rejected/session.jsonl
#	examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl
#	examples/acp-agent/tests/snapshots/permission-switching/session.jsonl
#	examples/acp-agent/tests/snapshots/workspace-context/system-prompt.expected.md
#	examples/acp-agent/tests/snapshots/workspace-context/tool-schemas.expected.json
#	examples/acp-agent/tests/snapshots/workspace-edit/system-prompt.expected.md
#	examples/acp-agent/tests/snapshots/workspace-edit/tool-schemas.expected.json
#	packages/bash/bash/src/index.ts
#	packages/bash/tool-bash/package.json
#	packages/bash/tool-bash/src/index.ts
#	packages/bash/tool-bash/tests/tools.spec.ts
#	packages/cordis/tool-cordis/src/api-catalog.ts
#	packages/fs/README.md
#	packages/fs/tool-fs/src/edit.ts
#	packages/fs/tool-fs/src/write.ts
#	packages/sandbox/README.md
#	pnpm-lock.yaml

scripts/agent-note-tree.ts

@@ -0,0 +1,78 @@
+/**
+ * Shared structural source of truth for the Agent Note tree. Lifecycle and class
+ * sets are closed under `.agents/notes/README.md`; importing this module is pure.
+ */
+
+import { globSync, readdirSync } from 'node:fs'
+import { resolve, sep } from 'node:path'
+
+export const agentNoteRoot = resolve(import.meta.dirname, '../.agents/notes')
+
+/** The closed set of Agent Note lifecycles (top-level folders under .agents/notes/). */
+const LIFECYCLES = ['proposed', 'implemented', 'rejected'] as const
+
+/**
+ * The closed set of Agent Note classes (nested folder under each lifecycle). Adding a
+ * class is a deliberate act: extend this list AND the README's Classification
+ * section. The gate rejects any folder not listed here.
+ */
+const CLASSES = ['feature', 'bug-fix', 'simplification', 'architecture', 'process', 'testing'] as const
+
+/** Non-Agent Note Markdown allowed to sit directly at a lifecycle root. */
+const ROOT_ALLOWLIST = new Set(['AGENTS.md', 'CLAUDE.md'])
+
+/** One Agent Note file, as discovered by the walker. */
+export interface AgentNote {
+  lifecycle: string
+  /** Path relative to .agents/notes. */
+  rel: string
+  /** `yyyy-mm-dd` from the filename. */
+  date: string
+}
+
+/**
+ * Walk the Agent Note tree, enforcing the structure rules. Returns every valid Agent Note
+ * plus one error string per violation (unknown lifecycle or class folder, bad
+ * depth, or bad filename). Callers treat a non-empty error list as fatal.
+ */
+export function walkAgentNoteTree(): { notes: AgentNote[]; errors: string[] } {
+  const notes: AgentNote[] = []
+  const errors: string[] = []
+  // The lifecycle set is closed too: any directory under .agents/notes/ that is not
+  // a known lifecycle would otherwise hold Agent Notes invisible to the walk below.
+  for (const entry of readdirSync(agentNoteRoot, { withFileTypes: true })) {
+    if (entry.name === 'INDEX.md') {
+      errors.push('structure: INDEX.md — centralized Agent Note indexes are forbidden; browse the lifecycle/class tree or search the repository')
+      continue
+    }
+    if (entry.isDirectory() && !(LIFECYCLES as readonly string[]).includes(entry.name)) {
+      errors.push(`structure: ${entry.name}/ — unknown lifecycle folder (allowed: ${LIFECYCLES.join(', ')})`)
+    }
+  }
+  for (const lifecycle of LIFECYCLES) {
+    for (const match of globSync(`${lifecycle}/**/*.md`, { cwd: agentNoteRoot }).map(path => path.split(sep).join('/')).sort()) {
+      const segs = match.split('/')
+      // Allowlisted file directly at the lifecycle root (e.g. implemented/AGENTS.md).
+      if (segs.length === 2 && ROOT_ALLOWLIST.has(segs[1] ?? '')) continue
+      // A Chinese counterpart (foo.zh.md, docs/i18n/README.md) is the SAME Agent Note,
+      // indexed via its English filename; the pairing gate owns its consistency.
+      if (match.endsWith('.zh.md')) continue
+      const cls = segs[1]
+      const base = segs[2]
+      if (segs.length !== 3 || cls === undefined || base === undefined) {
+        errors.push(`structure: ${match} — expected {lifecycle}/{class}/file.md (got depth ${segs.length})`)
+        continue
+      }
+      if (!(CLASSES as readonly string[]).includes(cls)) {
+        errors.push(`structure: ${match} — unknown class folder "${cls}" (allowed: ${CLASSES.join(', ')})`)
+        continue
+      }
+      if (!/^\d{4}-\d{2}-\d{2}-.+\.md$/.test(base)) {
+        errors.push(`structure: ${match} — filename must be yyyy-mm-dd-topic.md`)
+        continue
+      }
+      notes.push({ lifecycle, rel: match, date: base.slice(0, 10) })
+    }
+  }
+  return { notes, errors }
+}

scripts/build-exe-for-python-sdk.ts

@@ -1,7 +1,7 @@
 /**
  * Build the SDK runtime executables and Python node carrier. The fixed
  * `@yao-pkg/pkg --sea` route, deploy flags, and artifact layout are owned by
- * docs/rfc/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md.
+ * .agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md.
  * The staged closure is symlink-free, and whole-tree assets cover Cordis's
  * runtime imports that pkg cannot discover statically.
  */
@@ -69,7 +69,7 @@ class Target {
     readonly nodeRange: string,
     /**
      * pkg platform tag. Windows is a documented non-goal
-     * (docs/rfc/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md).
+     * (.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md).
      */
     readonly platform: Platform,
     /** pkg CPU tag. */
@@ -190,7 +190,7 @@ class BuildCli {
       '  --dry-run              print every command and config patch without executing.',
       '  --help                 print this help.',
       '',
-      `Build route: ${PKG_SPEC} --sea; see docs/rfc/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md.`,
+      `Build route: ${PKG_SPEC} --sea; see .agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md.`,
       `Stages the node carrier in ${PYTHON_RUNTIME_DIR}/${PYTHON_NODE_SUBDIR} and writes executables to ${OUT_DIR}/.`,
     ].join('\n')
   }

scripts/check-expected-filenames.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Vendored upstream paths follow vendor/README.md instead of repository naming policy.
+root=$(git rev-parse --show-toplevel)
+candidate_file=$(mktemp)
+trap 'unlink "$candidate_file"' EXIT
+git -C "$root" ls-files -z -- \
+  ':(icase,glob)*golden*' \
+  ':(icase,glob)**/*golden*' \
+  ':(exclude,glob)vendor/**' > "$candidate_file"
+
+violations=()
+while IFS= read -r -d '' path; do
+  violations+=("$path")
+done < "$candidate_file"
+
+if (( ${#violations[@]} == 0 )); then
+  echo 'check-expected-filenames: no tracked non-vendor filename contains "golden".'
+  exit 0
+fi
+
+echo 'check-expected-filenames: tracked non-vendor filenames must not contain "golden":' >&2
+printf '  %s\n' "${violations[@]}" >&2
+echo 'Rename each file with an accurate term such as "expected".' >&2
+exit 1

scripts/cordis-walk.ts

@@ -0,0 +1,94 @@
+/**
+ * Shared AST walkers for the cordis documentation generators
+ * (`gen-cordis-catalog.ts`, `gen-website-api.ts`): locating the cordis module
+ * merge in a source file, enumerating its `interface Events` members, and
+ * resolving the `interface Context` service keys to their service classes.
+ * One walk, two renderers — the catalog and the website page carry different
+ * prose but must agree on WHAT exists.
+ */
+
+import ts from 'typescript'
+import { parseJsDoc, pointer, rawJsDoc } from './jsdoc.ts'
+
+/** The body of the cordis module merge in `sf`: `declare module 'cordis'`
+ * (harness packages) or `declare module './context.ts'` (vendor core), or
+ * null when the file has neither. */
+export function cordisModuleBody(sf: ts.SourceFile): ts.ModuleBlock | null {
+  for (const stmt of sf.statements) {
+    if (!ts.isModuleDeclaration(stmt) || !ts.isStringLiteral(stmt.name)) continue
+    if (stmt.name.text !== 'cordis' && stmt.name.text !== './context.ts') continue
+    if (stmt.body && ts.isModuleBlock(stmt.body)) return stmt.body
+  }
+  return null
+}
+
+/** Every `interface Events` method member of a cordis module merge, with the
+ * event name resolved from its (possibly string-literal) property name. */
+export function eventMembers(body: ts.ModuleBlock, sf: ts.SourceFile): { name: string; member: ts.MethodSignature }[] {
+  const out: { name: string; member: ts.MethodSignature }[] = []
+  for (const stmt of body.statements) {
+    if (!ts.isInterfaceDeclaration(stmt) || stmt.name.text !== 'Events') continue
+    for (const member of stmt.members) {
+      if (!ts.isMethodSignature(member)) continue
+      const name = ts.isStringLiteral(member.name) ? member.name.text : member.name.getText(sf)
+      out.push({ name, member })
+    }
+  }
+  return out
+}
+
+/** The `ctx.<key> → type name` map declared by a merge's `interface Context`. */
+function contextKeyMap(body: ts.ModuleBlock, sf: ts.SourceFile): Map<string, string> {
+  const keyToType = new Map<string, string>()
+  for (const stmt of body.statements) {
+    if (!ts.isInterfaceDeclaration(stmt) || stmt.name.text !== 'Context') continue
+    for (const member of stmt.members) {
+      if (!ts.isPropertySignature(member) || !member.type) continue
+      keyToType.set(member.name.getText(sf), member.type.getText(sf))
+    }
+  }
+  return keyToType
+}
+
+/** One `ctx.<key>` service class resolved from a Context merge. */
+export interface ServiceClass {
+  key: string
+  type: string
+  cls: ts.ClassDeclaration
+  abstract: boolean
+  /** Class-level JSDoc prose (empty string when missing — also reported). */
+  doc: string
+}
+
+/**
+ * Resolve each `ctx.<key>` of a merge to the service class declared in the
+ * same file. A key whose type is not a class here (a Pick-mixin member, e.g.
+ * timer helpers) is skipped. A class without JSDoc prose is reported into
+ * `violations` (named `where` by the caller's gate).
+ *
+ * @param body — the cordis module merge body.
+ * @param sf — the source file containing the merge.
+ * @param rel — repo-relative path of `sf`, for violation pointers.
+ * @param violations — sink for JSDoc-completeness violations.
+ * @returns the resolved service classes, in Context-declaration order.
+ */
+export function serviceClasses(
+  body: ts.ModuleBlock,
+  sf: ts.SourceFile,
+  rel: string,
+  violations: string[],
+): ServiceClass[] {
+  const text = sf.getFullText()
+  const out: ServiceClass[] = []
+  for (const [key, type] of contextKeyMap(body, sf)) {
+    const cls = sf.statements.find(
+      (s): s is ts.ClassDeclaration => ts.isClassDeclaration(s) && s.name?.text === type,
+    )
+    if (!cls) continue // a Pick-mixin member, not a class here
+    const abstract = cls.modifiers?.some(m => m.kind === ts.SyntaxKind.AbstractKeyword) ?? false
+    const doc = parseJsDoc(rawJsDoc(text, cls)).doc
+    if (!doc) violations.push(`service ctx.${key} (${pointer(rel, sf, cls)}): class ${type} has no JSDoc.`)
+    out.push({ key, type, cls, abstract, doc })
+  }
+  return out
+}

scripts/demo-code-mode.mjs

@@ -1,7 +1,7 @@
 /**
- * Boot the REPL or ACP Code Mode overlay, defaulting to REPL. Each overlay
+ * Boot the REPL, TUI, or ACP Code Mode overlay, defaulting to REPL. Each overlay
  * includes its base example, selects Code Mode, and adds the worker runtime.
- * Both require a DeepSeek API key; unsupported arguments fail with usage.
+ * All require a DeepSeek API key; unsupported arguments fail with usage.
  */
 import { spawn } from 'node:child_process'
 
@@ -9,14 +9,15 @@ import { spawn } from 'node:child_process'
 // the overlay config (the stdio bin keeps --expose-internals for the cordis
 // Loader's HMR path).
 const UIS = new Map([
-  ['repl', ['--expose-internals', '--import', 'tsx', 'packages/examples/stdio-demo/src/bin.ts', 'examples/coding-agent/code-mode.cordis.yml']],
+  ['repl', ['--expose-internals', '--import', 'tsx', 'packages/examples/stdio-demo/src/bin.ts', 'examples/repl-agent/code-mode.cordis.yml']],
+  ['tui', ['--expose-internals', '--import', 'tsx', 'packages/examples/stdio-demo/src/bin.ts', 'examples/tui-agent/code-mode.cordis.yml']],
   ['acp', ['--import', 'tsx', 'packages/examples/acp-demo/src/bin.ts', '--config', 'examples/acp-agent/code-mode.cordis.yml']],
 ])
 
 const ui = process.argv[2] ?? 'repl'
 const args = UIS.get(ui)
 if (!args || process.argv.length > 3) {
-  console.error('usage: pnpm run demo:code-mode [repl|acp]')
+  console.error('usage: pnpm run demo:code-mode [repl|tui|acp]')
   process.exit(2)
 }
 

scripts/doc-budgets.manifest.json

@@ -1,11 +1,11 @@
 {
-  "AGENTS.md": 1370,
-  "docs/AGENTS.md": 1100,
-  "docs/architecture.md": 1790,
+  "AGENTS.md": 1600,
+  "docs/AGENTS.md": 1150,
+  "docs/architecture.md": 1800,
   "docs/cordis-primer.md": 600,
   "docs/defensive-patterns.md": 550,
-  "docs/testing.md": 800,
-  "examples/AGENTS.md": 200,
-  "packages/AGENTS.md": 290,
+  "docs/testing.md": 960,
+  "examples/AGENTS.md": 310,
+  "packages/AGENTS.md": 650,
   "packages/README.md": 760
 }

scripts/doc-typecheck.ts

@@ -1,13 +1,14 @@
 /**
- * Typecheck Markdown `ts` fences against workspace sources. `ignore-check`
- * fences are reported as opt-outs; generated catalog fragments and
- * `type-equiv` blocks are skipped here because their owning gates verify them.
+ * Typecheck Markdown `ts` fences against the workspace API. `ignore-check` fences are reported as
+ * opt-outs; generated catalog fragments and source-equivalence blocks are skipped here because their
+ * owning gates verify them. A build-coordinated mode consumes existing declarations without emit.
  */
 
 import { execFileSync } from 'node:child_process'
 import { globSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { join, relative, resolve } from 'node:path'
 import ts from 'typescript'
+import { extractFences } from './md-fences.ts'
 
 const root = resolve(import.meta.dirname, '..')
 
@@ -27,60 +28,124 @@ interface Block {
   code: string
 }
 
+/** The info-string → kind table this gate tracks. */
+const KIND_BY_INFO: Record<string, BlockKind> = {
+  'ts': 'check',
+  'ts ignore-check': 'ignore',
+  'ts type-equiv': 'type-equiv',
+  'ts public-api': 'type-equiv',
+  'ts cordis-catalog': 'cordis-catalog',
+  'ts persistence-catalog': 'persistence-catalog',
+  'ts config-catalog': 'config-catalog',
+}
+
 /** Extract every recognized TypeScript fence from one Markdown file. */
 function extractBlocks(absPath: string): Block[] {
-  const text = readFileSync(absPath, 'utf8')
-  const lines = text.split('\n')
   const file = relative(root, absPath)
-  const blocks: Block[] = []
-  let open: { line: number; kind: BlockKind; body: string[] } | null = null
+  return extractFences(absPath, info => KIND_BY_INFO[info] ?? null)
+    .map(f => ({ file, line: f.line, kind: f.kind, code: f.code }))
+}
 
-  lines.forEach((raw, i) => {
-    const fence = /^```(\s*)(\S.*)?$/.exec(raw)
-    if (!fence) {
-      if (open) open.body.push(raw)
-      return
-    }
-    if (open) {
-      // closing fence
-      blocks.push({ file, line: open.line, kind: open.kind, code: open.body.join('\n') })
-      open = null
-      return
-    }
-    // Ignore non-TypeScript fences.
-    const info = (fence[2] ?? '').trim()
-    const kind: BlockKind | null =
-      info === 'ts' ? 'check'
-        : info === 'ts ignore-check' ? 'ignore'
-          : info === 'ts type-equiv' ? 'type-equiv'
-            : info === 'ts cordis-catalog' ? 'cordis-catalog'
-              : info === 'ts persistence-catalog' ? 'persistence-catalog'
-                : info === 'ts config-catalog' ? 'config-catalog'
-                  : null
-    if (kind) open = { line: i + 1, kind, body: [] }
+const configHost: ts.ParseConfigFileHost = {
+  ...ts.sys,
+  getCurrentDirectory: () => root,
+  onUnRecoverableConfigFileDiagnostic(diagnostic) {
+    throw new Error(ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'))
+  },
+}
+
+/** Load root settings and redirect workspace aliases to declarations from the coordinated build. */
+function builtTypeCompilerOptions(): ts.CompilerOptions {
+  const configPath = join(root, 'tsconfig.json')
+  const parsed = ts.getParsedCommandLineOfConfigFile(configPath, {}, configHost)
+  if (!parsed) throw new Error(`doc-typecheck: cannot parse ${configPath}`)
+  if (parsed.errors.length > 0) {
+    throw new Error(parsed.errors.map(error => ts.flattenDiagnosticMessageText(error.messageText, '\n')).join('\n'))
+  }
+  if (parsed.options.paths === undefined) throw new Error('doc-typecheck: root tsconfig has no workspace paths')
+  const paths = Object.fromEntries(Object.entries(parsed.options.paths).map(([specifier, candidates]) => [
+    specifier,
+    candidates.map((candidate) => {
+      if (!candidate.endsWith('/src')) {
+        throw new Error(`doc-typecheck: cannot map workspace source path to built declarations: ${candidate}`)
+      }
+      return `${candidate.slice(0, -'/src'.length)}/lib/types`
+    }),
+  ]))
+  const options: ts.CompilerOptions = {
+    ...parsed.options,
+    paths,
+    noEmit: true,
+    composite: false,
+    incremental: false,
+    declaration: false,
+    declarationMap: false,
+    sourceMap: false,
+    noUnusedLocals: false,
+    noUnusedParameters: false,
+  }
+  delete options.tsBuildInfoFile
+  return options
+}
+
+/** Compile Markdown blocks as virtual files against declarations from the coordinated build. */
+function compileBlocksAgainstBuiltTypes(blocks: Block[]): readonly ts.Diagnostic[] {
+  const options = builtTypeCompilerOptions()
+  const sources = new Map<string, string>()
+  for (const [index, block] of blocks.entries()) {
+    const fileName = resolve(root, '.doc-typecheck', `block-${index}.ts`)
+    sources.set(fileName, block.code.endsWith('\n') ? block.code : `${block.code}\n`)
+  }
+
+  const baseHost = ts.createCompilerHost(options, true)
+  const host: ts.CompilerHost = {
+    ...baseHost,
+    fileExists(fileName) {
+      return sources.has(resolve(fileName)) || baseHost.fileExists(fileName)
+    },
+    readFile(fileName) {
+      return sources.get(resolve(fileName)) ?? baseHost.readFile(fileName)
+    },
+    getSourceFile(fileName, languageVersion, onError, shouldCreateNewSourceFile) {
+      const source = sources.get(resolve(fileName))
+      if (source !== undefined) return ts.createSourceFile(fileName, source, languageVersion, true)
+      return baseHost.getSourceFile(fileName, languageVersion, onError, shouldCreateNewSourceFile)
+    },
+    writeFile() {
+      throw new Error('doc-typecheck: noEmit compilation attempted to write output')
+    },
+  }
+  const program = ts.createProgram([...sources.keys()], options, host)
+  return ts.getPreEmitDiagnostics(program)
+}
+
+/** Render compiler diagnostics with virtual block paths mapped back to Markdown. */
+function formatDiagnostics(diagnostics: readonly ts.Diagnostic[], blocks: Block[]): string {
+  const formatted = ts.formatDiagnostics(diagnostics, {
+    getCanonicalFileName: fileName => fileName,
+    getCurrentDirectory: () => root,
+    getNewLine: () => ts.sys.newLine,
   })
-  return blocks
+  return remapBlockPaths(formatted, blocks)
 }
 
 /** Reuse the repo typecheck graph references from a temp project one directory below root. */
 function workspaceReferences(): { path: string }[] {
   const file = join(root, 'tsconfig.json')
-  // Parse with TypeScript's own JSONC reader, not a hand-rolled comment strip:
-  // a regex strip mistakes the `/*/` in a wildcard path candidate
-  // (`./packages/core/*/src`) for a block comment and corrupts the map.
-  const result = ts.readConfigFile(file, p => readFileSync(p, 'utf8'))
+  // Parse with TypeScript's own JSONC reader: a regex comment stripper corrupts the `/*/` path
+  // candidate in the workspace wildcard.
+  const result = ts.readConfigFile(file, path => readFileSync(path, 'utf8'))
   if (result.error) {
     throw new Error(`doc-typecheck: cannot read ${file}: ${ts.flattenDiagnosticMessageText(result.error.messageText, '\n')}`)
   }
-  // `config` is typed `any` by the TS API; narrow it to the one field we read.
-  const { references } = result.config as { compilerOptions: { paths: Record<string, string[]> }; references: { path: string }[] }
-  return references.map(({ path }) => {
-    const relativeToTemp = path.startsWith('./') ? `../${path.slice(2)}` : `../${path}`
-    return { path: relativeToTemp }
-  })
+  // `config` is typed `any` by the TS API; narrow it to the one field read here.
+  const { references } = result.config as { references: { path: string }[] }
+  return references.map(({ path }) => ({
+    path: path.startsWith('./') ? `../${path.slice(2)}` : `../${path}`,
+  }))
 }
 
-/** The standalone tsconfig for the temp typecheck project. */
+/** The standalone temp project used when no coordinated build owns declaration freshness. */
 function tempTsconfig(): string {
   return JSON.stringify({
     extends: '../tsconfig.json',
@@ -94,7 +159,40 @@ function tempTsconfig(): string {
   })
 }
 
-const markdownGlobs = ['README.md', 'docs/**/*.md', 'packages/*/*.md', 'packages/*/*/*.md']
+/** Compile blocks through project references for the standalone command. */
+function compileBlocksStandalone(blocks: Block[]): string | undefined {
+  const tmp = mkdtempSync(join(root, '.doc-typecheck-'))
+  try {
+    writeFileSync(join(tmp, 'tsconfig.json'), tempTsconfig())
+    for (const [index, block] of blocks.entries()) {
+      writeFileSync(join(tmp, `block-${index}.ts`), block.code.endsWith('\n') ? block.code : `${block.code}\n`)
+    }
+    try {
+      // Invoke tsc's JS entry through Node instead of a platform-specific shell shim.
+      execFileSync(process.execPath, ['node_modules/typescript/bin/tsc', '-b', join(tmp, 'tsconfig.json')], {
+        cwd: root,
+        stdio: 'pipe',
+      })
+      return undefined
+    } catch (error: unknown) {
+      const failed = error as { stdout?: Buffer; stderr?: Buffer }
+      return remapBlockPaths(`${failed.stdout?.toString() ?? ''}${failed.stderr?.toString() ?? ''}`, blocks)
+    }
+  } finally {
+    rmSync(tmp, { recursive: true, force: true })
+  }
+}
+
+/** Map virtual or temporary block paths back to their owning Markdown fences. */
+function remapBlockPaths(output: string, blocks: Block[]): string {
+  return output.replace(/(?:[^\s:()]*[/\\])?block-(\d+)\.ts\((\d+),(\d+)\)/g, (_match, index: string, line: string, column: string) => {
+    const block = blocks[Number(index)]
+    if (!block) return `block-${index}.ts(${line},${column})`
+    return `${block.file} (block at line ${block.line}, +${line}:${column})`
+  })
+}
+
+const markdownGlobs = ['README.md', '.agents/notes/**/*.md', 'docs/**/*.md', 'packages/*/*.md', 'packages/*/*/*.md', 'website/zh-CN/**/*.md']
 
 const files: string[] = []
 for (const pattern of markdownGlobs) {
@@ -114,45 +212,24 @@ if (checked.length === 0) {
   process.exit(0)
 }
 
-const tmp = mkdtempSync(join(root, '.doc-typecheck-'))
-try {
-  writeFileSync(join(tmp, 'tsconfig.json'), tempTsconfig())
-  const fileForBlock = new Map<string, Block>()
-  checked.forEach((block, i) => {
-    const name = `block-${i}.ts`
-    writeFileSync(join(tmp, name), block.code.endsWith('\n') ? block.code : `${block.code}\n`)
-    fileForBlock.set(name, block)
-  })
-
-  try {
-    // tsc's JS entry via the current node, not the .bin shim: the extensionless
-    // shim is not spawnable on Windows (the CVE-2024-27980 class the sibling
-    // scripts hit), and the .cmd variant would need shell:true, which
-    // concatenates args UNESCAPED — a hazard for the temp project path. The JS
-    // entry behaves identically on every platform.
-    execFileSync(process.execPath, ['node_modules/typescript/bin/tsc', '-b', join(tmp, 'tsconfig.json')], { cwd: root, stdio: 'pipe' })
-  } catch (error: unknown) {
-    const failed = error as { stdout?: Buffer; stderr?: Buffer }
-    const out = `${failed.stdout?.toString() ?? ''}${failed.stderr?.toString() ?? ''}`
-    // Rewrite "block-N.ts(line,col)" to the real "file:fenceLine" for triage.
-    const remapped = out.replace(/(?:[^\s:()]*[/\\])?block-(\d+)\.ts\((\d+),(\d+)\)/g, (_m, idx: string, ln: string, col: string) => {
-      const block = fileForBlock.get(`block-${idx}.ts`)
-      if (!block) return `block-${idx}.ts(${ln},${col})`
-      return `${block.file} (block at line ${block.line}, +${ln}:${col})`
-    })
-    console.error('doc-typecheck: documentation code blocks failed to compile.\n')
-    console.error(remapped)
-    process.exit(1)
-  }
-
-  const ratio = ignored.length / ratioDenominator
-  const skipped = all.length - ratioDenominator
-  console.log(`doc-typecheck: ${checked.length} block(s) compiled, ${ignored.length} ignored (${(ratio * 100).toFixed(0)}% opt-out), ${skipped} type-equiv/catalog (checked elsewhere).`)
-  // Guard against the escape hatch becoming the norm.
-  if (ratioDenominator >= 4 && ratio > 0.5) {
-    console.error(`doc-typecheck: too many blocks opt out of checking (${ignored.length}/${ratioDenominator}). Make them compile or delete them.`)
-    process.exit(1)
-  }
-} finally {
-  rmSync(tmp, { recursive: true, force: true })
+const useBuiltTypes = process.env.DSH_DOC_TYPECHECK_USE_BUILD_OUTPUT === '1'
+const compilationError = useBuiltTypes
+  ? (() => {
+    const diagnostics = compileBlocksAgainstBuiltTypes(checked)
+    return diagnostics.length === 0 ? undefined : formatDiagnostics(diagnostics, checked)
+  })()
+  : compileBlocksStandalone(checked)
+if (compilationError !== undefined) {
+  console.error('doc-typecheck: documentation code blocks failed to compile.\n')
+  console.error(compilationError)
+  process.exit(1)
+}
+
+const ratio = ignored.length / ratioDenominator
+const skipped = all.length - ratioDenominator
+console.log(`doc-typecheck: ${checked.length} block(s) compiled, ${ignored.length} ignored (${(ratio * 100).toFixed(0)}% opt-out), ${skipped} type-equiv/catalog (checked elsewhere).`)
+// Guard against the escape hatch becoming the norm.
+if (ratioDenominator >= 4 && ratio > 0.5) {
+  console.error(`doc-typecheck: too many blocks opt out of checking (${ignored.length}/${ratioDenominator}). Make them compile or delete them.`)
+  process.exit(1)
 }

scripts/gen-config-catalog.ts

@@ -837,7 +837,7 @@ export function render(entries: CatalogEntry[]): string {
     '',
     '## Seam packages (not directly loadable)',
     '',
-    'Abstract service classes — a deployment loads a concrete implementation package instead ([capability seams](rfc/implemented/architecture/2026-06-13-capability-seams.md)).',
+    'Abstract service classes — a deployment loads a concrete implementation package instead ([capability seams](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)).',
     '',
     ...entries.filter(e => e.kind === 'seam').map(e => renderTerse(e, ` — abstract \`${e.className ?? ''}\``)),
     '',

scripts/gen-cordis-api.ts

@@ -1,8 +1,9 @@
 /**
  * Generate the model-facing Cordis API data module from the same event/service
- * collector as the documentation catalogs. It emits first-sentence docs, raw
- * signatures, transitive public type shapes, and inherited context entries,
- * without source pointers; output is deterministic and `--check` verifies it.
+ * collector as the documentation catalogs. It emits original declaration
+ * JSDoc, first-sentence summaries, raw signatures, transitive public type
+ * shapes, and inherited context entries, without source pointers; output is
+ * deterministic and `--check` verifies it.
  */
 
 import { globSync, readFileSync, writeFileSync } from 'node:fs'
@@ -80,7 +81,7 @@ function referencedTypes(seeds: string[], decls: Map<string, string>): { name: s
 function render(): string {
   const services = collectServices()
   const events = collectEvents().sort((a, b) => a.name.localeCompare(b.name))
-  const types = referencedTypes(services.flatMap(service => service.methods), collectTypeDecls())
+  const types = referencedTypes(services.flatMap(service => service.methods.map(method => method.signature)), collectTypeDecls())
   const lines: string[] = [
     '/**',
     ' * Generated by scripts/gen-cordis-api.ts — do not edit by hand; run',
@@ -88,22 +89,30 @@ function render(): string {
     ' * `pnpm run verify-cordis-api` in doc-sync).',
     ' *',
     ' * The machine-readable cordis API catalog `cordis_inspect` serves to the',
-    ' * model: harness services (summary + public method signatures), harness',
-    ' * events (mode + signature), and the inherited `ctx` surface. Produced by',
+    ' * model: harness services (summary + public method signatures/JSDoc),',
+    ' * harness events (mode + signature/JSDoc), and the inherited `ctx` surface. Produced by',
     ' * the same AST walk as docs/cordis-catalog, so this data and the rendered',
     ' * docs cannot diverge.',
     ' *',
     ' * @module @deepseek-ai/dsh-tool-cordis/api-catalog',
     ' */',
     '',
-    '/** One harness `ctx.<key>` service: its one-line summary and public method signatures. */',
+    '/** One public service method and its source-owned contract. */',
+    'export interface ServiceApiMethod {',
+    '  /** Public method signature with its body stripped. */',
+    '  signature: string',
+    '  /** Original method JSDoc, with only container indentation removed. */',
+    '  jsDoc: string',
+    '}',
+    '',
+    '/** One harness `ctx.<key>` service: its one-line summary and public methods. */',
     'export interface ServiceApiEntry {',
     '  /** The `ctx.<key>` name, e.g. `tools`. */',
     '  key: string',
     '  /** First sentence of the service class JSDoc. */',
     '  summary: string',
-    '  /** Public method signatures, bodies stripped, in source order. */',
-    '  methods: readonly string[]',
+    '  /** Public methods, bodies stripped, in source order. */',
+    '  methods: readonly ServiceApiMethod[]',
     '}',
     '',
     '/** One harness event: its dispatch mode, exact signature, and one-line summary. */',
@@ -114,6 +123,8 @@ function render(): string {
     '  mode: string',
     '  /** The exact listener signature, whitespace-normalized. */',
     '  signature: string',
+    '  /** Original event JSDoc, with only container indentation removed. */',
+    '  jsDoc: string',
     '  /** First sentence of the event JSDoc. */',
     '  summary: string',
     '}',
@@ -145,7 +156,12 @@ function render(): string {
       lines.push('    methods: [],')
     } else {
       lines.push('    methods: [')
-      for (const method of service.methods) lines.push(`      ${quote(method)},`)
+      for (const method of service.methods) {
+        lines.push('      {')
+        lines.push(`        signature: ${quote(method.signature)},`)
+        lines.push(`        jsDoc: ${quote(method.jsDoc)},`)
+        lines.push('      },')
+      }
       lines.push('    ],')
     }
     lines.push('  },')
@@ -161,6 +177,7 @@ function render(): string {
     lines.push(`    name: ${quote(event.name)},`)
     lines.push(`    mode: ${quote(event.mode)},`)
     lines.push(`    signature: ${quote(event.signature)},`)
+    lines.push(`    jsDoc: ${quote(event.jsDoc)},`)
     lines.push(`    summary: ${quote(firstSentence(event.doc))},`)
     lines.push('  },')
   }

scripts/gen-cordis-catalog.ts

@@ -1,14 +1,15 @@
 /**
  * Generate the Cordis event and service catalogs from static declarations.
- * The walk enforces event modes plus JSDoc parameter/return completeness;
- * inherited Cordis services come from the curated table below. `--check`
- * verifies both committed artifacts.
+ * The walk enforces event modes, JSDoc parameter/return completeness, and
+ * signature type-link coverage; inherited Cordis services come from the
+ * curated table below. `--check` verifies both committed artifacts.
  */
 
 import { globSync, readFileSync, writeFileSync } from 'node:fs'
 import { resolve, sep } from 'node:path'
 import ts from 'typescript'
 import { checkParams, checkReturns, parseJsDoc, parseTags, pointer, rawJsDoc, reportViolations, type Mode } from './jsdoc.ts'
+import { cordisModuleBody, eventMembers, serviceClasses } from './cordis-walk.ts'
 
 const root = resolve(import.meta.dirname, '..')
 const OUT_EVENTS = 'docs/cordis-catalog/events.md'
@@ -19,47 +20,199 @@ const OUT_SERVICES = 'docs/cordis-catalog/services.md'
 const FENCE = 'ts cordis-catalog'
 
 /**
- * One primary core-data-structures page per signature type, shared by the
- * Cordis and config catalogs; union names intentionally do not reuse the
- * type-equivalence manifest's map-symbol entries.
+ * One primary core-data-structures page per project type used by a generated
+ * signature. This stays curated because union names intentionally do not
+ * reuse the type-equivalence manifest's map-symbol entries and some symbols
+ * appear on more than one page.
  */
-// TODO(catalog-type-links): verify or generate link-map coverage.
 export const LINK_MAP: Record<string, string> = {
   Agent: 'core.md',
+  AgentOptions: 'core.md',
+  AgentStatus: 'core.md',
   ContentBlock: 'core.md',
-  Message: 'core.md',
-  MessageSource: 'core.md',
+  ContinuationDecision: 'core.md',
+  ContinuationStop: 'core.md',
   GenerateOptions: 'core.md',
   LlmCallConfig: 'core.md',
+  LlmModelInfo: 'core.md',
+  LlmProviderInfo: 'core.md',
+  Message: 'core.md',
+  MessageSource: 'core.md',
+  PromptDecision: 'core.md',
+  RequestError: 'core.md',
+  RequestErrorDecision: 'core.md',
   SessionEvent: 'core.md',
+  SessionId: 'core.md',
   SessionStartSource: 'core.md',
-  StreamChunk: 'llm-streaming.md',
-  TurnEndReason: 'session.md',
-  ToolDefinition: 'tools.md',
-  ToolExecution: 'tools.md',
-  ToolExecutionInput: 'tools.md',
-  ToolExecutionResult: 'tools.md',
-  ToolExecutionToken: 'tools.md',
   ApprovalOutcome: 'approval.md',
   ApprovalPolicy: 'approval.md',
   ApprovalRequest: 'approval.md',
+  ApprovalService: 'approval.md',
   BashExecRequest: 'bash.md',
   BashExecSpec: 'bash.md',
+  BashProcess: 'bash.md',
   BashRunResult: 'bash.md',
-  ConfinedArgv: 'sandbox.md',
-  SandboxMode: 'sandbox.md',
-  SandboxPolicy: 'sandbox.md',
+  DshEnvironment: 'bash.md',
   CodeRunRequest: 'code-runtime.md',
   CodeRunResult: 'code-runtime.md',
+  CompactionResult: 'compaction.md',
+  CompactionTrigger: 'compaction.md',
+  FileReadOutcome: 'filesystem.md',
+  FsDirEntry: 'filesystem.md',
   FsEditOutcome: 'filesystem.md',
   FsEditRequest: 'filesystem.md',
   FsInfo: 'filesystem.md',
+  FsPathInfo: 'filesystem.md',
+  FsPolicyExec: 'filesystem.md',
   FsTarget: 'filesystem.md',
   FsVersion: 'filesystem.md',
   FsWriteIntent: 'filesystem.md',
   FsWriteOutcome: 'filesystem.md',
-  FsPolicyExec: 'filesystem.md',
-  FileReadOutcome: 'filesystem.md',
+  LlmAdapter: 'llm-streaming.md',
+  LlmService: 'llm-streaming.md',
+  StreamChunk: 'llm-streaming.md',
+  CreateSessionOptions: 'persistence.md',
+  SessionHeader: 'persistence.md',
+  SessionLocation: 'persistence.md',
+  ConfinedArgv: 'sandbox.md',
+  SandboxMode: 'sandbox.md',
+  SandboxPolicy: 'sandbox.md',
+  ScopeKey: 'scope.md',
+  Scoped: 'scope.md',
+  EpochHeader: 'session.md',
+  Session: 'session.md',
+  TurnEndReason: 'session.md',
+  SessionEventReadRequest: 'session-query.md',
+  SessionEventRecord: 'session-query.md',
+  SessionEventTrace: 'session-query.md',
+  SessionEventTraceRequest: 'session-query.md',
+  SessionEventWindow: 'session-query.md',
+  SessionLineageTrace: 'session-query.md',
+  SessionRecord: 'session-query.md',
+  SkillDefinition: 'skills.md',
+  SkillLookupOptions: 'skills.md',
+  SkillProvider: 'skills.md',
+  SkillRegistration: 'skills.md',
+  SkillSummary: 'skills.md',
+  SaveTextSpill: 'spill.md',
+  SpillRef: 'spill.md',
+  SubagentProvider: 'subagent.md',
+  SubagentRun: 'subagent.md',
+  SubagentService: 'subagent.md',
+  SubagentStartRequest: 'subagent.md',
+  AssembleContext: 'system-prompt.md',
+  PromptSection: 'system-prompt.md',
+  SystemPrompt: 'system-prompt.md',
+  ToolProviderResult: 'system-prompt.md',
+  TaskDoneListener: 'tasks.md',
+  TaskId: 'tasks.md',
+  TaskRead: 'tasks.md',
+  TaskSnapshot: 'tasks.md',
+  TaskStart: 'tasks.md',
+  TokenMeasurement: 'token-meter.md',
+  PostToolDecision: 'tools.md',
+  PreToolDecision: 'tools.md',
+  ToolDefinition: 'tools.md',
+  ToolExecution: 'tools.md',
+  ToolExecutionInput: 'tools.md',
+  ToolExecutionMode: 'tools.md',
+  ToolExecutionResult: 'tools.md',
+  ToolExecutionToken: 'tools.md',
+  ToolGuard: 'tools.md',
+  ToolRegistry: 'tools.md',
+  ToolRestriction: 'tools.md',
+  ToolSchema: 'tools.md',
+  AskUserQuestionAnswer: 'user-interaction.md',
+  AskUserQuestionRequest: 'user-interaction.md',
+  UserInteractionProvider: 'user-interaction.md',
+  WebFetchProvider: 'web.md',
+  WebFetchRequest: 'web.md',
+  WebFetchResult: 'web.md',
+  WebSearchProvider: 'web.md',
+  WebSearchRequest: 'web.md',
+  WebSearchResult: 'web.md',
+  WorkflowRun: 'workflow.md',
+  WorkflowRunInfo: 'workflow.md',
+  WorkflowStartRequest: 'workflow.md',
+}
+
+/** TypeScript lib and pinned framework types that have no repository-owned data page. */
+const FOUNDATION_TYPE_NAMES = new Set([
+  'AbortSignal',
+  'AsyncIterable',
+  'Context',
+  'Error',
+  'Pick',
+  'Promise',
+  'Readonly',
+])
+
+/** Project types deliberately documented outside the core-data catalog. */
+const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
+  AgentFactory: 'agent creation seam is owned by packages/core/agent/README.md',
+  AgentHandle: 'agent ownership handle is owned by packages/core/agent/README.md',
+  BashEnvContributor: 'service-local extension type is owned by packages/bash/tool-bash/src/index.ts',
+  BashEnvVariableInfo: 'service-local metadata type is owned by packages/bash/tool-bash/src/index.ts',
+  CompactAgentContext: 'compaction service input is owned by packages/compact/compact/src/index.ts',
+  CreateAgentOptions: 'agent creation contract is owned by packages/core/agent/README.md',
+  PresetOption: 'deployment menu metadata is owned by packages/ui/permission/README.md',
+  PresetSpec: 'deployment preset composition is owned by packages/ui/permission/README.md',
+  PromptAssembly: 'assembly result is owned by packages/core/system-prompt/README.md',
+  ResumeAgentOptions: 'agent resume contract is owned by packages/core/agent/README.md',
+  SessionForkSource: 'service-local fork input is owned by packages/core/session/src/index.ts',
+  SubagentRunEndInfo: 'event-local snapshot is owned by packages/subagent/subagent/src/index.ts',
+  SubagentRunInfo: 'event-local snapshot is owned by packages/subagent/subagent/src/index.ts',
+  WorkflowAgentEndInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
+  WorkflowAgentInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
+  WorkflowResultInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
+}
+
+/** Collect named references from parameter, generic-constraint/default, and return types. */
+function signatureTypeNames(member: ts.MethodSignature | ts.MethodDeclaration, sf: ts.SourceFile): string[] {
+  const declared = new Set(member.typeParameters?.map(parameter => parameter.name.text) ?? [])
+  const referenced = new Set<string>()
+  const visit = (node: ts.Node): void => {
+    if (ts.isTypeReferenceNode(node)) referenced.add(node.typeName.getText(sf))
+    if (ts.isTypeQueryNode(node)) referenced.add(node.exprName.getText(sf))
+    ts.forEachChild(node, visit)
+  }
+  for (const parameter of member.typeParameters ?? []) {
+    if (parameter.constraint) visit(parameter.constraint)
+    if (parameter.default) visit(parameter.default)
+  }
+  for (const parameter of member.parameters) {
+    if (parameter.type) visit(parameter.type)
+  }
+  if (member.type) visit(member.type)
+  return [...referenced].filter(name => !declared.has(name)).sort()
+}
+
+/** Append fail-closed signature type-link violations with actionable ownership choices. */
+function checkTypeLinks(
+  where: string,
+  member: ts.MethodSignature | ts.MethodDeclaration,
+  sf: ts.SourceFile,
+  violations: string[],
+): void {
+  for (const name of signatureTypeNames(member, sf)) {
+    if (Object.hasOwn(LINK_MAP, name)
+      || FOUNDATION_TYPE_NAMES.has(name)
+      || Object.hasOwn(TYPE_LINK_EXEMPTIONS, name)) continue
+    violations.push(
+      `${where} references unclassified type '${name}'. Add it to LINK_MAP with its core-data-structures page, `
+      + 'to FOUNDATION_TYPE_NAMES if TypeScript or Cordis owns it, or to TYPE_LINK_EXEMPTIONS with '
+      + 'the non-catalog documentation owner.',
+    )
+  }
+}
+
+/** Throw one aggregated diagnostic for every unclassified signature type. */
+function reportTypeLinkViolations(gate: string, violations: string[]): void {
+  if (violations.length === 0) return
+  throw new Error(
+    `${gate}: ${violations.length} signature type-link coverage violation(s):\n`
+    + violations.map(violation => `  ${violation}`).join('\n'),
+  )
 }
 
 /** One harness event, extracted from an `interface Events` block. */
@@ -70,6 +223,8 @@ interface EventEntry {
   scope: string
   /** Full signature text (the method-signature member, JSDoc stripped). */
   signature: string
+  /** Original declaration JSDoc, dedented from its containing interface. */
+  jsDoc: string
   /** Dispatch mode from the `@mode` tag. */
   mode: Mode
   /** Description prose (JSDoc minus the `@mode` tag), one line per paragraph. */
@@ -78,6 +233,14 @@ interface EventEntry {
   source: string
 }
 
+/** One public service method and the source contract attached to it. */
+interface ServiceMethodEntry {
+  /** Public method signature (body stripped). */
+  signature: string
+  /** Original method JSDoc, dedented from its containing class. */
+  jsDoc: string
+}
+
 /** One harness service, extracted from an `interface Context` block. */
 interface ServiceEntry {
   /** The `ctx.<key>` name, e.g. `llm`. */
@@ -88,8 +251,8 @@ interface ServiceEntry {
   abstract: boolean
   /** Class-level JSDoc prose, one line per paragraph. */
   doc: string
-  /** Public method signatures (bodies stripped), in source order. */
-  methods: string[]
+  /** Public methods (bodies stripped), in source order. */
+  methods: ServiceMethodEntry[]
   /** Source pointer of the class declaration. */
   source: string
 }
@@ -102,15 +265,8 @@ interface InheritedEntry {
   source: string
 }
 
-/** 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) {
-    if (ts.isModuleDeclaration(stmt) && ts.isStringLiteral(stmt.name) && stmt.name.text === 'cordis') {
-      if (stmt.body && ts.isModuleBlock(stmt.body)) return stmt.body
-    }
-  }
-  return null
-}
+// cordisModuleBody / eventMembers / serviceClasses live in cordis-walk.ts,
+// shared with gen-website-api.ts — one walk, two renderers.
 
 /** The signature text of a method-signature member (everything but a body). */
 function memberSignature(member: ts.TypeElement | ts.ClassElement, sf: ts.SourceFile): string {
@@ -120,6 +276,22 @@ function memberSignature(member: ts.TypeElement | ts.ClassElement, sf: ts.Source
   return sig.replace(/\s*;?\s*$/, '').replace(/\s+/g, ' ').trim()
 }
 
+/**
+ * Copy a node's original JSDoc while removing only the indentation imposed by
+ * its containing interface or class.
+ */
+function jsDocText(text: string, sf: ts.SourceFile, node: ts.Node): string {
+  const raw = rawJsDoc(text, node)
+  if (!raw) return ''
+  const start = text.lastIndexOf(raw, node.getStart(sf))
+  const { line } = sf.getLineAndCharacterOfPosition(start)
+  const lineStart = sf.getPositionOfLineAndCharacter(line, 0)
+  const indent = text.slice(lineStart, start)
+  return raw.split('\n')
+    .map((lineText, index) => index > 0 && lineText.startsWith(indent) ? lineText.slice(indent.length) : lineText)
+    .join('\n')
+}
+
 /** Walk every harness `interface Events` block and extract its events, hard-
  * erroring (aggregated) on any JSDoc-completeness violation: a missing/
  * contradicted `@mode`, missing description prose, or an undocumented payload
@@ -127,6 +299,7 @@ function memberSignature(member: ts.TypeElement | ts.ClassElement, sf: ts.Source
 export function collectEvents(scanRoot: string = root): EventEntry[] {
   const entries: EventEntry[] = []
   const violations: string[] = []
+  const typeLinkViolations: string[] = []
   for (const rel of globSync('packages/*/*/src/*.ts', { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
     const abs = resolve(scanRoot, rel)
     const text = readFileSync(abs, 'utf8')
@@ -134,41 +307,38 @@ export function collectEvents(scanRoot: string = root): EventEntry[] {
     const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
     const body = cordisModuleBody(sf)
     if (!body) continue
-    for (const stmt of body.statements) {
-      if (!ts.isInterfaceDeclaration(stmt) || stmt.name.text !== 'Events') continue
-      for (const member of stmt.members) {
-        if (!ts.isMethodSignature(member)) continue
-        const name = ts.isStringLiteral(member.name) ? member.name.text : member.name.getText(sf)
-        const signature = memberSignature(member, sf)
-        const raw = rawJsDoc(text, member)
-        const { doc, mode } = parseJsDoc(raw)
-        const src = pointer(rel, sf, member)
-        const where = `event '${name}' (${src})`
-        if (!mode) {
-          violations.push(`${where} is missing an @mode tag. Add '@mode emit|waterfall|parallel|serial' to its JSDoc (see AGENTS.md).`)
-        }
-        // Conclusive structural check: a trailing `next: () => …` parameter is a
-        // waterfall. (emit vs parallel vs serial is not structurally
-        // distinguishable, so it is trusted from the tag.)
-        const last = member.parameters.at(-1)
-        const hasNext = !!last && last.name.getText(sf) === 'next'
-        if (mode && hasNext && mode !== 'waterfall') {
-          violations.push(`${where} has a trailing 'next' parameter (structurally a waterfall) but is tagged '@mode ${mode}'. Fix the tag or the signature.`)
-        }
-        if (mode && !hasNext && mode === 'waterfall') {
-          violations.push(`${where} is tagged '@mode waterfall' but has no trailing 'next' parameter. A waterfall delegates via next().`)
-        }
-        if (!doc) violations.push(`${where} has no description prose. Say what happened / what a listener may do, above the block tags.`)
-        // Payload parameters need a non-empty @param. The `this` receiver is not
-        // payload, and a waterfall's trailing `next` is covered by its mode.
-        const { params } = parseTags(raw)
-        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 })
+    for (const { name, member } of eventMembers(body, sf)) {
+      const signature = memberSignature(member, sf)
+      const raw = rawJsDoc(text, member)
+      const { doc, mode } = parseJsDoc(raw)
+      const src = pointer(rel, sf, member)
+      const where = `event '${name}' (${src})`
+      checkTypeLinks(where, member, sf, typeLinkViolations)
+      if (!mode) {
+        violations.push(`${where} is missing an @mode tag. Add '@mode emit|waterfall|parallel|serial' to its JSDoc (see AGENTS.md).`)
       }
+      // Conclusive structural check: a trailing `next: () => …` parameter is a
+      // waterfall. (emit vs parallel vs serial is not structurally
+      // distinguishable, so it is trusted from the tag.)
+      const last = member.parameters.at(-1)
+      const hasNext = !!last && last.name.getText(sf) === 'next'
+      if (mode && hasNext && mode !== 'waterfall') {
+        violations.push(`${where} has a trailing 'next' parameter (structurally a waterfall) but is tagged '@mode ${mode}'. Fix the tag or the signature.`)
+      }
+      if (mode && !hasNext && mode === 'waterfall') {
+        violations.push(`${where} is tagged '@mode waterfall' but has no trailing 'next' parameter. A waterfall delegates via next().`)
+      }
+      if (!doc) violations.push(`${where} has no description prose. Say what happened / what a listener may do, above the block tags.`)
+      // Payload parameters need a non-empty @param. The `this` receiver is not
+      // payload, and a waterfall's trailing `next` is covered by its mode.
+      const { params } = parseTags(raw)
+      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, jsDoc: jsDocText(text, sf, member), mode, doc, source: src })
     }
   }
   reportViolations('gen-cordis-catalog', violations)
+  reportTypeLinkViolations('gen-cordis-catalog', typeLinkViolations)
   return entries
 }
 
@@ -181,6 +351,7 @@ export function collectEvents(scanRoot: string = root): EventEntry[] {
 export function collectServices(scanRoot: string = root): ServiceEntry[] {
   const entries: ServiceEntry[] = []
   const violations: string[] = []
+  const typeLinkViolations: string[] = []
   for (const rel of globSync('packages/*/*/src/index.ts', { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
     const abs = resolve(scanRoot, rel)
     const text = readFileSync(abs, 'utf8')
@@ -188,27 +359,9 @@ export function collectServices(scanRoot: string = root): ServiceEntry[] {
     const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
     const body = cordisModuleBody(sf)
     if (!body) continue
-    // The ctx key → type mapping(s) declared in this file's interface Context.
-    const keyToType = new Map<string, string>()
-    for (const stmt of body.statements) {
-      if (!ts.isInterfaceDeclaration(stmt) || stmt.name.text !== 'Context') continue
-      for (const member of stmt.members) {
-        if (!ts.isPropertySignature(member) || !member.type) continue
-        const key = member.name.getText(sf)
-        keyToType.set(key, member.type.getText(sf))
-      }
-    }
-    if (keyToType.size === 0) continue
-    // Find each service class declared in the same file and emit an entry.
-    for (const [key, type] of keyToType) {
-      const cls = sf.statements.find(
-        (s): s is ts.ClassDeclaration => ts.isClassDeclaration(s) && s.name?.text === type,
-      )
-      if (!cls) continue // a Pick-mixin member (e.g. timer helpers), not a class here
-      const abstract = cls.modifiers?.some(m => m.kind === ts.SyntaxKind.AbstractKeyword) ?? false
-      const clsDoc = parseJsDoc(rawJsDoc(text, cls)).doc
-      if (!clsDoc) violations.push(`service ctx.${key} (${pointer(rel, sf, cls)}): class ${type} has no JSDoc.`)
-      const methods: string[] = []
+    // Resolve each ctx key to its service class (shared walk) and emit an entry.
+    for (const { key, type, cls, abstract, doc: clsDoc } of serviceClasses(body, sf, rel, violations)) {
+      const methods: ServiceMethodEntry[] = []
       for (const member of cls.members) {
         if (!ts.isMethodDeclaration(member)) continue
         // Only instance methods callable through `ctx.<key>` are surface;
@@ -221,9 +374,10 @@ export function collectServices(scanRoot: string = root): ServiceEntry[] {
         if (nonPublic) continue
         const memberName = member.name.getText(sf)
         if (memberName.startsWith('[')) continue // computed/symbol members
-        methods.push(memberSignature(member, sf))
         const where = `service method ctx.${key}.${memberName} (${pointer(rel, sf, member)})`
+        checkTypeLinks(where, member, sf, typeLinkViolations)
         const raw = rawJsDoc(text, member)
+        methods.push({ signature: memberSignature(member, sf), jsDoc: jsDocText(text, sf, member) })
         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)
@@ -245,6 +399,7 @@ export function collectServices(scanRoot: string = root): ServiceEntry[] {
     }
   }
   reportViolations('gen-cordis-catalog', violations)
+  reportTypeLinkViolations('gen-cordis-catalog', typeLinkViolations)
   return entries.sort((a, b) => a.key.localeCompare(b.key))
 }
 
@@ -258,14 +413,14 @@ export function collectServices(scanRoot: string = root): ServiceEntry[] {
  * sibling check is N/A; keep them current on a vendor bump.
  */
 const INHERITED_EVENTS: InheritedEntry[] = [
-  { name: 'internal/plugin', summary: 'A plugin fiber was created.', source: 'vendor/cordis/src/events.ts:197' },
-  { name: 'internal/status', summary: 'A fiber changed lifecycle state.', source: 'vendor/cordis/src/events.ts:198' },
-  { name: 'internal/service', summary: 'Interception hook for a service binding (no core producer).', source: 'vendor/cordis/src/events.ts:199' },
-  { name: 'internal/update', summary: 'Waterfall: a fiber config update is being applied.', source: 'vendor/cordis/src/events.ts:200' },
-  { name: 'internal/get', summary: 'Waterfall: a service is being read from the store.', source: 'vendor/cordis/src/events.ts:201' },
-  { name: 'internal/set', summary: 'Waterfall: a service is being written to the store.', source: 'vendor/cordis/src/events.ts:202' },
-  { name: 'internal/listener', summary: 'A listener was registered.', source: 'vendor/cordis/src/events.ts:203' },
-  { name: 'internal/dispatch', summary: 'An event is being dispatched to listeners.', source: 'vendor/cordis/src/events.ts:204' },
+  { name: 'internal/plugin', summary: 'A plugin fiber was created.', source: 'vendor/cordis/src/events.ts:328' },
+  { name: 'internal/status', summary: 'A fiber changed lifecycle state.', source: 'vendor/cordis/src/events.ts:330' },
+  { name: 'internal/service', summary: 'Interception hook for a service binding (no core producer).', source: 'vendor/cordis/src/events.ts:332' },
+  { name: 'internal/update', summary: 'Waterfall: a fiber config update is being applied.', source: 'vendor/cordis/src/events.ts:334' },
+  { name: 'internal/get', summary: 'Waterfall: a service is being read from the store.', source: 'vendor/cordis/src/events.ts:336' },
+  { name: 'internal/set', summary: 'Waterfall: a service is being written to the store.', source: 'vendor/cordis/src/events.ts:338' },
+  { name: 'internal/listener', summary: 'A listener was registered.', source: 'vendor/cordis/src/events.ts:340' },
+  { name: 'internal/dispatch', summary: 'An event is being dispatched to listeners.', source: 'vendor/cordis/src/events.ts:342' },
   { name: 'hmr/change', summary: 'A watched source file changed on disk.', source: 'vendor/hmr/src/index.ts:20' },
   { name: 'hmr/reload', summary: 'Plugins are being reloaded after a change.', source: 'vendor/hmr/src/index.ts:21' },
   { name: 'exit', summary: 'The process is exiting on a signal.', source: 'vendor/loader/src/index.ts:23' },
@@ -276,12 +431,12 @@ const INHERITED_EVENTS: InheritedEntry[] = [
 ]
 
 export const INHERITED_SERVICES: InheritedEntry[] = [
-  { name: 'ctx.on / ctx.once', summary: 'Register an event listener (disposable).', source: 'vendor/cordis/src/events.ts:29' },
-  { name: 'ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall', summary: 'Dispatch an event (sync / awaited / first-bail / veto-chain).', source: 'vendor/cordis/src/events.ts:29' },
-  { name: 'ctx.plugin / ctx.inject', summary: 'Load a plugin / declare required services.', source: 'vendor/cordis/src/registry.ts:144' },
+  { name: 'ctx.on / ctx.once', summary: 'Register an event listener (disposable).', source: 'vendor/cordis/src/events.ts:34' },
+  { name: 'ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall', summary: 'Dispatch an event (sync / awaited / first-bail / veto-chain).', source: 'vendor/cordis/src/events.ts:34' },
+  { name: 'ctx.plugin / ctx.inject', summary: 'Load a plugin / declare required services.', source: 'vendor/cordis/src/registry.ts:164' },
   { name: 'ctx.effect', summary: 'Register a disposable side effect tied to the fiber.', source: 'vendor/cordis/src/fiber.ts:9' },
   { name: 'ctx.get / ctx.set / ctx.provide / ctx.accessor / ctx.mixin', summary: 'Low-level service-store access and binding.', source: 'vendor/cordis/src/reflect.ts:7' },
-  { name: 'ctx.extend / ctx.isolate / ctx.intercept', summary: 'Derive a child context (scoped services / isolation / interception).', source: 'vendor/cordis/src/context.ts:35' },
+  { name: 'ctx.extend / ctx.isolate / ctx.intercept', summary: 'Derive a child context (scoped services / isolation / interception).', source: 'vendor/cordis/src/context.ts:42' },
   { name: 'ctx.root / ctx.scope / ctx.fiber / ctx.registry / ctx.reflect / ctx.events / ctx.logger', summary: 'Ambient handles onto the running context graph.', source: 'vendor/cordis/src/context.ts:16' },
   { name: 'ctx.timer (+ interval / timeout / throttle / debounce / setTimeout / setInterval)', summary: 'Disposable timer helpers. The `timer` key is provided at runtime; the six helpers are mixed onto ctx directly (declared via Pick).', source: 'vendor/timer/src/index.ts:4' },
   { name: 'ctx.loader', summary: 'The config Loader that booted the app (present under the loader).', source: 'vendor/loader/src/index.ts:30' },
@@ -303,7 +458,7 @@ function typeLinks(signature: string): string {
 function renderEvent(e: EventEntry): string[] {
   const out = [`### \`${e.name}\` — ${e.mode}`, '']
   if (e.doc) out.push(e.doc, '')
-  out.push('```' + FENCE, e.signature, '```', '')
+  out.push('```' + FENCE, e.jsDoc, e.signature, '```', '')
   const links = typeLinks(e.signature)
   if (links) out.push(links, '')
   out.push(`Source: [\`${e.source}\`](../../${e.source.split(':')[0]})`, '')
@@ -316,8 +471,13 @@ function renderService(s: ServiceEntry): string[] {
   const out = [`## \`ctx.${s.key}\` — \`${s.type}\`${kind}`, '']
   if (s.doc) out.push(s.doc, '')
   if (s.methods.length) {
-    out.push('```' + FENCE, ...s.methods, '```', '')
-    const links = typeLinks(s.methods.join('\n'))
+    const declarations = s.methods.flatMap((method, index) => [
+      ...(index > 0 ? [''] : []),
+      method.jsDoc,
+      method.signature,
+    ])
+    out.push('```' + FENCE, ...declarations, '```', '')
+    const links = typeLinks(s.methods.map(method => method.signature).join('\n'))
     if (links) out.push(links, '')
   }
   out.push(`Source: [\`${s.source}\`](../../${s.source.split(':')[0]})`, '')
@@ -332,15 +492,15 @@ const BANNER = [
 ]
 
 /** The shared GENERATED + freshness-gate + fence notice paragraph. */
-const GATE_NOTICE = 'This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence (skipped by doc-typecheck, since a bare signature is not standalone-compilable). Type names in a signature link to the page that documents them.'
+const GATE_NOTICE = 'This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them.'
 
 /** Render the events catalog (pure, deterministic given sorted inputs). */
-function renderEvents(events: EventEntry[]): string {
+export function renderEvents(events: EventEntry[]): string {
   const lines: string[] = [
     ...BANNER,
     '# Cordis Events Catalog',
     '',
-    'Every cordis event a plugin can listen to: exact signature, dispatch mode, and the declaration\'s JSDoc. This is one axis of the **wiring** reference a plugin author works against — the callable `ctx.<key>` surface is the sibling [services catalog](services.md), and [core-data-structures/](../core-data-structures/core.md) catalogs the *data structures* these signatures move around.',
+    'Every cordis event a plugin can listen to: exact signature, dispatch mode, and original declaration JSDoc. This is one axis of the **wiring** reference a plugin author works against — the callable `ctx.<key>` surface is the sibling [services catalog](services.md), and [core-data-structures/](../core-data-structures/core.md) catalogs the *data structures* these signatures move around.',
     '',
     GATE_NOTICE,
     '',
@@ -370,12 +530,12 @@ function renderEvents(events: EventEntry[]): string {
 }
 
 /** Render the services catalog (pure, deterministic given sorted inputs). */
-function renderServices(services: ServiceEntry[]): string {
+export function renderServices(services: ServiceEntry[]): string {
   const lines: string[] = [
     ...BANNER,
     '# Cordis Services Catalog',
     '',
-    'Every `ctx.<key>` service a plugin can call: the exact public interface plus the class JSDoc. This is one axis of the **wiring** reference a plugin author works against — the events a plugin listens to are the sibling [events catalog](events.md), and [core-data-structures/](../core-data-structures/core.md) catalogs the *data structures* these signatures move around. An abstract seam (e.g. `ctx.bash`) is implemented by a separate package; the interface is what consumers code against.',
+    'Every `ctx.<key>` service a plugin can call: the exact public interface with original method JSDoc, plus the class JSDoc. This is one axis of the **wiring** reference a plugin author works against — the events a plugin listens to are the sibling [events catalog](events.md), and [core-data-structures/](../core-data-structures/core.md) catalogs the *data structures* these signatures move around. An abstract seam (e.g. `ctx.bash`) is implemented by a separate package; the interface is what consumers code against.',
     '',
     GATE_NOTICE,
     '',

scripts/gen-doc-graphs.ts

@@ -67,6 +67,7 @@ const GROUP_ORDER = [
   'tasks',
   'workflow',
   'web',
+  'spill',
   'todo',
   'cordis',
   'hooks',
@@ -86,12 +87,20 @@ const SERVICE_ROLES: ServiceRole[] = [
     consumers: ['agent-loop', 'compact-basic'],
     note: 'Adapters register provider implementations; the loop and compaction call the provider-neutral stream service.',
   },
+  {
+    key: 'tokenMeter',
+    pkg: 'token-meter',
+    title: 'Replay token measurement',
+    mode: 'core',
+    consumers: ['compact-basic'],
+    note: 'Owns isolated per-session replay folds; pressure consumers share immutable revisioned measurements.',
+  },
   {
     key: 'sessions',
     pkg: 'session',
     title: 'In-memory session store',
     mode: 'core',
-    consumers: ['agent-loop', 'agent', 'session-persistence', 'session-query', 'subagent-inprocess', 'invariants'],
+    consumers: ['agent-loop', 'agent', 'cli-demo', 'session-persistence', 'session-query', 'subagent-inprocess', 'invariants'],
     note: 'Owns append-only Session instances and emits the durable session event feed.',
   },
   {
@@ -100,15 +109,15 @@ const SERVICE_ROLES: ServiceRole[] = [
     title: 'Durable session persistence seam',
     mode: 'seam',
     implementations: ['session-persistence-jsonl', 'session-persistence-sqlite'],
-    consumers: ['agent-loop', 'acp', 'session-query'],
+    consumers: ['agent-loop', 'tool-bash', 'hooks-claude', 'hooks-codex', 'acp', 'session-query'],
     note: 'Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time.',
   },
   {
     key: 'sessionQuery',
     pkg: 'session-query',
-    title: 'Exact session-history reads',
+    title: 'Exact session-history reads and traces',
     mode: 'seam',
-    note: 'Resolves live and optional persisted logs into one logical corpus for exact reads.',
+    note: 'Resolves live and optional persisted logs into one logical corpus for exact reads and relationship traces.',
   },
   {
     key: 'systemPrompt',
@@ -147,10 +156,10 @@ const SERVICE_ROLES: ServiceRole[] = [
   {
     key: 'agents',
     pkg: 'agent',
-    title: 'Agent registry',
+    title: 'Agent service',
     mode: 'core',
-    consumers: ['agent-loop', 'acp', 'subagent-inprocess', 'stdio-demo', 'invariants'],
-    note: 'Owns live Agent handles and the create/resume factory seam.',
+    consumers: ['agent-loop', 'acp', 'cli-demo', 'subagent-inprocess', 'stdio-demo', 'invariants'],
+    note: 'Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation.',
   },
   {
     key: 'agentLoop',
@@ -169,6 +178,13 @@ const SERVICE_ROLES: ServiceRole[] = [
     consumers: ['tool-bash', 'hooks-claude', 'hooks-codex'],
     note: 'The model-facing bash tools and hook bridges consume this seam; sandboxed or remote executors replace bash-local without touching them.',
   },
+  {
+    key: 'bashEnv',
+    pkg: 'tool-bash',
+    title: 'Managed bash environment registry',
+    mode: 'core',
+    note: 'Plugins declare effect-scoped DSH_* facts; tool-bash collects one trusted snapshot per execution and the executor rebuilds the namespace.',
+  },
   {
     key: 'sandbox',
     pkg: 'sandbox',
@@ -231,14 +247,14 @@ const SERVICE_ROLES: ServiceRole[] = [
     mode: 'seam',
     implementations: ['compact-basic'],
     consumers: ['compact-basic'],
-    note: 'The basic backend currently consumes the pre-step event directly; a model-facing compact tool remains deferred.',
+    note: 'The basic backend consumes post-step pressure and request-error recovery events; a model-facing compact tool remains deferred.',
   },
   {
     key: 'subagents',
     pkg: 'subagent',
     title: 'Subagent provider registry',
     mode: 'seam',
-    implementations: ['subagent-spawn', 'subagent-fork', 'subagent-acp', 'subagent-mock'],
+    implementations: ['subagent-spawn', 'subagent-fork', 'subagent-acp'],
     consumers: ['tool-subagent'],
     note: 'Providers implement transports; tool-subagent exposes one configured provider as a model-facing tool name.',
   },
@@ -259,6 +275,15 @@ const SERVICE_ROLES: ServiceRole[] = [
     consumers: ['tool-web'],
     note: 'Search and fetch providers register into one ctx.web seam; tool-web owns the stable model-facing names.',
   },
+  {
+    key: 'spillStore',
+    pkg: 'spill',
+    title: 'Spill storage seam',
+    mode: 'seam',
+    implementations: ['spill-local'],
+    consumers: ['spill-policy'],
+    note: 'The backend saves oversized tool text and returns a model-facing locator plus retrieval hint; spill-policy is the tools/post-execute consumer that decides when to spill.',
+  },
   {
     key: 'workflows',
     pkg: 'workflow',
@@ -411,12 +436,28 @@ const APP_EXAMPLES = [
     summary: 'The echo demo swaps in a local mock LLM and teaching echo tool, then loads the stdio app package for the shared spine and terminal front door.',
   },
   {
-    id: 'coding',
-    rel: 'examples/coding-agent/composition.md',
-    title: 'Coding Agent App Composition',
-    label: 'examples/coding-agent',
-    config: 'examples/coding-agent/cordis.yml',
-    summary: 'The coding REPL demo adds the real DeepSeek adapter, filesystem tools, todo_write, compaction, and both subagent transports on top of the stdio app package.',
+    id: 'repl',
+    rel: 'examples/repl-agent/composition.md',
+    title: 'REPL Agent App Composition',
+    label: 'examples/repl-agent',
+    config: 'examples/repl-agent/cordis.yml',
+    summary: 'The REPL agent demo adds the real DeepSeek adapter, filesystem tools, todo_write, compaction, and both subagent transports on top of the stdio app package.',
+  },
+  {
+    id: 'tui',
+    rel: 'examples/tui-agent/composition.md',
+    title: 'TUI Agent App Composition',
+    label: 'examples/tui-agent',
+    config: 'examples/tui-agent/cordis.yml',
+    summary: 'The TUI agent reuses the repl-agent backend and tool composition while fixing the shared terminal app to the full-screen dsh-tui front door.',
+  },
+  {
+    id: 'headless',
+    rel: 'examples/headless-agent/composition.md',
+    title: 'Headless Agent App Composition',
+    label: 'examples/headless-agent',
+    config: 'examples/headless-agent/cordis.yml',
+    summary: 'The headless demo combines the real DeepSeek adapter and coding capabilities with the one-shot app package, format-pure stdout, and one fresh persisted top-level session.',
   },
   {
     id: 'cordis',
@@ -438,13 +479,20 @@ const APP_EXAMPLES = [
 
 type AppExample = typeof APP_EXAMPLES[number]
 
-function renderAppExpansion(lines: string[], appNode: string, pluginName: string): void {
+function renderAppExpansion(lines: string[], appNode: string, pluginName: string, exampleId: string): void {
   const agentCore = nodeId('bundle', 'agent_core')
   const jsonl = nodeId('bundle', 'jsonl')
   lines.push(`  ${appNode} --> ${agentCore}["@deepseek-ai/dsh-agent-spine-demo"]`)
   lines.push(`  ${appNode} --> ${jsonl}["@deepseek-ai/dsh-session-persistence-jsonl"]`)
   if (pluginName === '@deepseek-ai/dsh-stdio-demo') {
-    lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'stdio')}["readline UI<br/>console logger<br/>pre-created main agent"]`)
+    const frontDoor = exampleId === 'tui'
+      ? '@deepseek-ai/dsh-tui<br/>pre-created main agent'
+      : exampleId === 'repl'
+        ? '@deepseek-ai/dsh-stdio<br/>pre-created main agent'
+        : 'dsh-tui (TTY) / dsh-stdio (pipes)<br/>pre-created main agent'
+    lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'stdio')}["${frontDoor}"]`)
+  } else if (pluginName === '@deepseek-ai/dsh-cli-demo') {
+    lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'cli')}["one-shot driver<br/>format-pure stdout<br/>fresh top-level agent"]`)
   } else if (pluginName === '@deepseek-ai/dsh-acp-demo') {
     lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'acp')}["@deepseek-ai/dsh-acp<br/>JSON-RPC stdio bridge<br/>sessions created by client"]`)
   }
@@ -471,8 +519,8 @@ function renderAppComposition(example: AppExample): string {
     const pluginNode = nodeId(`plugin_${example.id}`, plugin.id)
     lines.push(`  ${pluginNode}["${escLabel(plugin.id)}<br/>${escLabel(plugin.name)}"]`)
     lines.push(`  cfg --> ${pluginNode}`)
-    if (plugin.name === '@deepseek-ai/dsh-stdio-demo' || plugin.name === '@deepseek-ai/dsh-acp-demo') {
-      renderAppExpansion(lines, pluginNode, plugin.name)
+    if (plugin.name === '@deepseek-ai/dsh-stdio-demo' || plugin.name === '@deepseek-ai/dsh-cli-demo' || plugin.name === '@deepseek-ai/dsh-acp-demo') {
+      renderAppExpansion(lines, pluginNode, plugin.name, example.id)
     }
   }
   lines.push(
@@ -829,19 +877,40 @@ function renderLifecycle(): string {
     '  LLM-->>Driver: StreamChunk*',
     `  Driver->>Session: ${mermaidCode('assistant/chunk')}*`,
     `  Session-->>SDK: ${mermaidCode('session/event')} ${mermaidCode('assistant/chunk')}*`,
+    '  alt final adapter or terminal in-band request failure',
+    `    Driver->>Session: ${mermaidCode('step/end')}`,
+    `    Driver->>Hooks: ${mermaidCode('agent/request-error')} waterfall`,
+    '    Hooks-->>Driver: retry in a new step or preserve the original error',
+    '  else model request succeeded',
     `  Driver->>Hooks: ${mermaidCode('agent/step-result')} waterfall`,
     `  Driver->>Session: ${mermaidCode('assistant/message')}`,
-    `  Driver->>Session: ${mermaidCode('tool/call')}`,
-    '  Driver->>Tools: execute through pre and post waterfalls',
-    '  Tools-->>Session: tool-owned events when applicable',
-    `  Driver->>Session: ${mermaidCode('tool/result')} and ${mermaidCode('step/end')}`,
+    '  Driver->>Tools: classify pending call by executionMode',
+    '  loop barriers and bounded rolling pool, reclassify before start',
+    '    opt call starts',
+    `      Driver->>Session: ${mermaidCode('tool/call')}`,
+    '      Driver->>Tools: ordered pre, concurrent execute',
+    '      Tools-->>Session: tool-owned events when applicable',
+    '    end',
+    '    opt next model-order result ready',
+    '      Driver->>Tools: ordered post',
+    `      Driver->>Session: ${mermaidCode('tool/result')}`,
+    '    end',
+    '  end',
+    '  Driver->>Session: post-tool context and steering',
+    `  Driver->>Hooks: ${mermaidCode('agent/post-step')} serial checkpoint`,
+    `  Driver->>Session: ${mermaidCode('step/end')}`,
     `  Driver->>Hooks: ${mermaidCode('agent/turn-continuation')} waterfall`,
     `  Driver->>Hooks: ${mermaidCode('agent/turn-stop')} serial terminal checkpoint`,
+    '  end',
     `  Driver->>Session: ${mermaidCode('turn/end')}`,
     `  Driver->>Persistence: ${mermaidCode('session/flush')} parallel checkpoint`,
     `  Driver-->>SDK: ${mermaidCode('agent/status')} idle`,
     '```',
     '',
+    'The `assistant/message` edge records every successful provider call, including content-less and `max-tokens` finishes. Empty content stays out of derived history while the durable anchor retains usage and exact chunk provenance, including an explicit empty source set.',
+    '',
+    '`dsh-compact-basic` uses `agent/post-step` for pressure after those durable facts and `agent/request-error` only for canonical context overflow. Recovery compacts between the closed failed step and a fresh retry step, and returns retry only when the surface replacement generation advances; otherwise the original request error remains authoritative.',
+    '',
     'SDK users that need replayable transcript data should consume `session/event`; `agent/*` is the live coordination surface for queue/status, prompt interception, request shaping, steering, continuation, and errors.',
     '',
     ...maintenanceFooter(maintenance),
@@ -869,9 +938,9 @@ function renderToolPipeline(): string {
     `  owned["Tool-owned session events<br/>${mermaidCode('todo/write')}, ${mermaidCode('fs/observed')}, ${mermaidCode('hook/invoked')}, ${mermaidCode('hook/result')}, ${mermaidCode('tool/code-dispatch')}"]`,
     `  post["${mermaidCode('tools/post-execute')} waterfall<br/>accept, block, replace, add context"]`,
     `  final["${mermaidCode('tools/result')} synchronous notification<br/>frozen authoritative outcome"]`,
-    '  context["Buffered additionalContext<br/>context/message after all tool results"]',
+    '  context["Active-batch additionalContexts FIFO<br/>context/message after recorded tool results"]',
     `  toolResult["Session event: ${mermaidCode('tool/result')}<br/>single model-facing outcome"]`,
-    '  allResults["All calls in the step settled<br/>and tool/result events recorded"]',
+    '  allResults["Tool batch settled<br/>recorded tool/result events complete"]',
     '  presentResult["UI completed card<br/>presentResult(args, result)"]',
     '  model --> toolCall',
     '  toolCall --> presentCall',
@@ -897,7 +966,7 @@ function renderToolPipeline(): string {
     '  allResults --> context',
     '```',
     '',
-    'Filesystem read-before-edit checks stay below `tool-fs` on `fs/*` events. Generic pre/post waterfalls host hooks and approval policy; `ctx.approval` resolves asks before monotonic guards, and owner policy that must not be reordered remains a registered guard. Around-dispatch concerns such as timeouts wrap `tools/execute`, while `tools/result` observes the immutable outcome after transforms, lossless-JSON validation, and outer error normalization. This lets hooks span tool families without coupling the tools to one policy service. Code Mode sends both the reserved `run_code` transport and its serialized sub-calls through the pipeline; sub-calls carry the parent token, log `tool/code-dispatch`, surface denials as binding rejections, and omit `additionalContext` to preserve call/result adjacency.',
+    'Filesystem read-before-edit checks stay below `tool-fs` on `fs/*` events. Generic pre/post waterfalls host hooks and approval policy; `ctx.approval` resolves asks before monotonic guards, and owner policy that must not be reordered remains a registered guard. Around-dispatch concerns such as timeouts wrap `tools/execute`, while `tools/result` observes the immutable outcome after transforms, lossless-JSON validation, and outer error normalization. This lets hooks span tool families without coupling the tools to one policy service. Code Mode sends both the reserved `run_code` transport and its serialized sub-calls through the pipeline; sub-calls carry the parent token, log `tool/code-dispatch`, surface denials as binding rejections, and omit `additionalContexts` to preserve call/result adjacency.',
     '',
     ...maintenanceFooter(maintenance),
   ].join('\n')
@@ -916,14 +985,14 @@ function renderSnapshotReplay(): string {
     '  participant Workspace',
     '  participant Replay as llm-replay adapter',
     '  participant ACP as acp-agent subprocess',
-    '  participant Golden as stdout golden',
+    '  participant Expected as stdout expected output',
     '  Recorder->>Fixture: session.jsonl + workspace inputs',
     '  Fixture->>Workspace: seed files and hook configs',
     '  Fixture->>Replay: recorded StreamChunk script',
     `  Replay->>ACP: deterministic ${mermaidCode('llm/stream')} chunks`,
     '  ACP->>Workspace: bash, fs, and hook side effects',
-    '  ACP->>Golden: normalized sessionUpdate stream',
-    '  Golden-->>ACP: diff must be empty',
+    '  ACP->>Expected: normalized sessionUpdate stream',
+    '  Expected-->>ACP: diff must be empty',
     '```',
     '',
     'The fs and hook snapshot matrix is valuable because it proves world state, hook decisions, and failed tool-card rendering, not just that replay returns text.',
@@ -950,7 +1019,9 @@ function renderIndex(docs: GraphDoc[]): string {
   const labels: Record<string, string> = {
     'docs/capability-seams.md': 'capability seams and core services',
     'examples/echo-agent/composition.md': 'echo-agent app composition',
-    'examples/coding-agent/composition.md': 'coding-agent app composition',
+    'examples/repl-agent/composition.md': 'repl-agent app composition',
+    'examples/headless-agent/composition.md': 'headless-agent app composition',
+    'examples/tui-agent/composition.md': 'tui-agent app composition',
     'examples/cordis-agent/composition.md': 'cordis-agent app composition',
     'examples/acp-agent/composition.md': 'acp-agent app composition',
     'docs/event-producer-consumer.md': 'event producer/consumer matrix',
@@ -961,7 +1032,9 @@ function renderIndex(docs: GraphDoc[]): string {
   const modes: Record<string, string> = {
     'docs/capability-seams.md': 'hybrid generated',
     'examples/echo-agent/composition.md': 'hybrid generated',
-    'examples/coding-agent/composition.md': 'hybrid generated',
+    'examples/repl-agent/composition.md': 'hybrid generated',
+    'examples/headless-agent/composition.md': 'hybrid generated',
+    'examples/tui-agent/composition.md': 'hybrid generated',
     'examples/cordis-agent/composition.md': 'hybrid generated',
     'examples/acp-agent/composition.md': 'hybrid generated',
     'docs/event-producer-consumer.md': 'hybrid generated',
@@ -982,7 +1055,7 @@ function renderIndex(docs: GraphDoc[]): string {
     ...generatedHeader('Documentation Graph Index'),
     'These diagrams are the relationship layer above the generated catalogs. Use them to navigate package topology, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type shapes still live in the generated [events](cordis-catalog/events.md) / [services](cordis-catalog/services.md) catalogs, [tool-catalog.md](tool-catalog.md), and [core-data-structures/](core-data-structures/core.md).',
     '',
-    'The process decision behind this index is recorded in [the documentation graph RFC](rfc/implemented/process/2026-07-03-documentation-graph-atlas.md).',
+    'The process decision behind this index is recorded in [the documentation graph Agent Note](../.agents/notes/implemented/process/2026-07-03-documentation-graph-atlas.md).',
     '',
     '| Graph | Mode |',
     '| --- | --- |',

scripts/gen-module-graph.ts

@@ -27,6 +27,7 @@ const GROUP_ORDER = [
   'compact',
   'subagent',
   'web',
+  'spill',
   'timeout',
   'todo',
   'cordis',

scripts/gen-persistence-catalog.ts

@@ -1,7 +1,7 @@
 /**
  * Generate `docs/persistence-catalog.md` from every `SessionEventMap` merge and
- * the owning `SurfaceEventType` union. This is the durable-record vocabulary,
- * not the live Cordis bus. Event declarations must be unique, explicitly typed,
+ * the owning event-envelope types. This is the durable-record vocabulary, not
+ * the live Cordis bus. Event declarations must be unique, explicitly typed,
  * documented, inheritance-free, and free of Cordis-only `@mode` tags; every
  * surface-union member must resolve to one. `--check` verifies the artifact.
  */
@@ -14,13 +14,23 @@ import { parseJsDoc, pointer, rawJsDoc, reportViolations } from './jsdoc.ts'
 const root = resolve(import.meta.dirname, '..')
 const OUT = 'docs/persistence-catalog.md'
 
-/** The fenced-block info string for generated payload blocks (skipped by
- * doc-typecheck, since a bare payload fragment is not standalone-compilable). */
+/** The fenced-block info string for generated declaration blocks (skipped by
+ * doc-typecheck, since their imported types are not standalone-compilable). */
 const FENCE = 'ts persistence-catalog'
 
 /** The package whose module id plugin merges augment (`declare module '…'`). */
 const SESSION_MODULE = '@deepseek-ai/dsh-session'
 
+/** Event-envelope declarations rendered before the per-event vocabulary. */
+const EVENT_ENVELOPE_TYPE_NAMES = [
+  'SessionEventType',
+  'SurfaceEventType',
+  'SurfaceOp',
+  'SessionEvent',
+] as const
+
+type EventEnvelopeTypeName = typeof EVENT_ENVELOPE_TYPE_NAMES[number]
+
 /** Primary core-data-structures page for linked payload types. */
 const LINK_MAP: Record<string, string> = {
   CallId: 'core.md',
@@ -41,6 +51,8 @@ export interface LogEventEntry {
   scope: string
   /** Payload type text (the member's type annotation, whitespace-collapsed). */
   payload: string
+  /** Source member declaration and complete JSDoc, dedented from its container. */
+  declaration: string
   /** Description prose (the member's JSDoc), one line per paragraph. */
   doc: string
   /** Source pointer `packages/…/file.ts:line` of the declaration. */
@@ -53,6 +65,16 @@ export interface AnnotatedLogEventEntry extends LogEventEntry {
   surface: boolean
 }
 
+/** One owning event-envelope declaration pasted into the generated catalog. */
+export interface EventEnvelopeTypeEntry {
+  /** Exported declaration name. */
+  name: EventEnvelopeTypeName
+  /** Verbatim type declaration, including its complete leading JSDoc. */
+  declaration: string
+  /** Source pointer `packages/…/file.ts:line` of the declaration. */
+  source: string
+}
+
 const printer = ts.createPrinter({ removeComments: true })
 
 /**
@@ -67,6 +89,24 @@ function payloadText(type: ts.TypeNode, sf: ts.SourceFile): string {
     .trim()
 }
 
+/**
+ * Copy a declaration from its leading JSDoc through its closing token while
+ * removing only the indentation imposed by its containing interface/module.
+ */
+function declarationText(text: string, sf: ts.SourceFile, node: ts.Node): string {
+  const raw = rawJsDoc(text, node)
+  const nodeStart = node.getStart(sf)
+  const start = raw ? text.lastIndexOf(raw, nodeStart) : nodeStart
+  const { line } = sf.getLineAndCharacterOfPosition(start)
+  const lineStart = sf.getPositionOfLineAndCharacter(line, 0)
+  const indent = text.slice(lineStart, start)
+  return text.slice(lineStart, node.end)
+    .split('\n')
+    .map(lineText => lineText.startsWith(indent) ? lineText.slice(indent.length) : lineText)
+    .join('\n')
+    .trimEnd()
+}
+
 /**
  * Every `interface SessionEventMap` declaration in a source file: the owning
  * top-level declaration (in `@deepseek-ai/dsh-session`) and any declaration
@@ -177,7 +217,8 @@ export function collectLogEvents(scanRoot: string = root): LogEventEntry[] {
         if (!doc) {
           violations.push(`${where} has no description prose. Say what the event records and what its payload means — the JSDoc becomes the catalog entry.`)
         }
-        entries.push({ name, scope: name.split('/')[0] ?? name, payload, doc, source: src })
+        const declaration = declarationText(text, sf, member)
+        entries.push({ name, scope: name.split('/')[0] ?? name, payload, declaration, doc, source: src })
       }
     }
   }
@@ -185,6 +226,51 @@ export function collectLogEvents(scanRoot: string = root): LogEventEntry[] {
   return entries
 }
 
+/**
+ * Collect the exported declarations that compose the persisted event envelope,
+ * preserving their source JSDoc and declaration text.
+ */
+export function collectEventEnvelopeTypes(scanRoot: string = root): EventEnvelopeTypeEntry[] {
+  const found = new Map<EventEnvelopeTypeName, EventEnvelopeTypeEntry>()
+  const violations: string[] = []
+  const wanted = new Set<string>(EVENT_ENVELOPE_TYPE_NAMES)
+  for (const rel of globSync('packages/*/*/src/**/*.ts', { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
+    const abs = resolve(scanRoot, rel)
+    const text = readFileSync(abs, 'utf8')
+    if (!EVENT_ENVELOPE_TYPE_NAMES.some(name => text.includes(name))) continue
+    if (packageNameFor(rel, scanRoot) !== SESSION_MODULE) continue
+    const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
+    for (const stmt of sf.statements) {
+      if (!ts.isTypeAliasDeclaration(stmt) || !wanted.has(stmt.name.text)) continue
+      const name = stmt.name.text as EventEnvelopeTypeName
+      const src = pointer(rel, sf, stmt)
+      const where = `event-envelope type '${name}' (${src})`
+      const prior = found.get(name)
+      if (prior) {
+        violations.push(`${where} is already declared at ${prior.source}; the persisted envelope type has exactly one owner.`)
+        continue
+      }
+      if (!(stmt.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) ?? false)) {
+        violations.push(`${where} is not exported.`)
+      }
+      const { doc, hasMode } = parseJsDoc(rawJsDoc(text, stmt))
+      if (hasMode) violations.push(`${where} carries an @mode tag, but a persisted type has no dispatch mode.`)
+      if (!doc) violations.push(`${where} has no description prose. The full JSDoc is part of the generated catalog.`)
+      found.set(name, { name, declaration: declarationText(text, sf, stmt), source: src })
+    }
+  }
+  const missing = EVENT_ENVELOPE_TYPE_NAMES.filter(name => !found.has(name))
+  if (missing.length > 0) {
+    violations.push(`missing event-envelope declaration(s): ${missing.join(', ')}.`)
+  }
+  reportViolations('gen-persistence-catalog', violations)
+  return EVENT_ENVELOPE_TYPE_NAMES.map((name) => {
+    const entry = found.get(name)
+    if (!entry) throw new Error(`gen-persistence-catalog: missing checked event-envelope declaration '${name}'.`)
+    return entry
+  })
+}
+
 /**
  * Parse the `SurfaceEventType` union — the surface-eligible subset of event
  * types — from source. Hard-errors when the alias is missing, declared more
@@ -246,8 +332,7 @@ function typeLinks(payload: string): string {
 /** Render one log event entry. */
 function renderEvent(e: AnnotatedLogEventEntry): string[] {
   const out = [`#### \`${e.name}\` — ${e.surface ? 'surface' : 'log-only'}`, '']
-  if (e.doc) out.push(e.doc, '')
-  out.push('```' + FENCE, `'${e.name}': ${e.payload}`, '```', '')
+  out.push('```' + FENCE, e.declaration, '```', '')
   const links = typeLinks(e.payload)
   if (links) out.push(links, '')
   out.push(`Source: [\`${e.source}\`](../${e.source.split(':')[0]})`, '')
@@ -255,18 +340,26 @@ function renderEvent(e: AnnotatedLogEventEntry): string[] {
 }
 
 /** Render the full catalog (pure, deterministic given the collected inputs). */
-export function render(events: AnnotatedLogEventEntry[]): string {
+export function render(events: AnnotatedLogEventEntry[], envelopeTypes: EventEnvelopeTypeEntry[]): string {
   const lines: string[] = [
     '<!-- Generated by scripts/gen-persistence-catalog.ts — do not edit by hand.',
     '     Run `pnpm run gen-persistence-catalog` to regenerate. -->',
     '',
-    '# Persistence Log Event Catalog',
+    '# Session Persistence Event Catalog',
     '',
-    'Every event type that can appear in a session\'s durable event log: each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with the payload it carries, its surface badge, and the declaration it comes from. It complements [session.md](core-data-structures/session.md) (the `SessionEvent` envelope, surface list, and `deriveMessages()` projection), [persistence.md](core-data-structures/persistence.md) (how the log is made durable), and the [cordis events catalog](cordis-catalog/events.md) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).',
+    'Every event type that can appear in a session\'s durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](core-data-structures/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](core-data-structures/persistence.md) (how the log is made durable), and the [cordis events catalog](cordis-catalog/events.md) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).',
     '',
-    'This file is GENERATED from source (`scripts/gen-persistence-catalog.ts`) and verified fresh by `pnpm run verify-persistence-catalog` (part of `doc-sync`) — do not edit it by hand. Payload blocks use a `ts persistence-catalog` fence (skipped by doc-typecheck, since a bare payload fragment is not standalone-compilable). Type names in a payload link to the page that documents them. See [the persistence-log-catalog RFC](rfc/implemented/process/2026-07-04-persistence-log-catalog.md).',
+    'This file is GENERATED from source (`scripts/gen-persistence-catalog.ts`) and verified fresh by `pnpm run verify-persistence-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks retain the source declaration and nested property JSDoc, removing only the indentation imposed by a containing interface/module, and use a `ts persistence-catalog` fence (skipped by doc-typecheck because declarations reference types from their owning modules). Type names in a payload link to the page that documents them. See [the persistence-log-catalog Agent Note](../.agents/notes/implemented/process/2026-07-04-persistence-log-catalog.md).',
     '',
-    'The on-disk envelope around every payload is `SessionEvent` — `type`, monotonic `seq`, epoch-ms `time`, the `data` documented here, plus `surfaceOp`/`sourceEventSeqs` on **surface** events only ([envelope](core-data-structures/session.md#sessioneventt--one-log-entry)). **surface** marks a `SurfaceEventType` member: it produces an LLM message and declares how it joins the surface list. **log-only** marks everything else: durable, replayable record with no derived-history contribution. Every payload is JSON-serializable (enforced at `Session.append`), and the whole format is pinned at `SESSION_FORMAT_VERSION = 0` — pre-release, no compatibility implied ([the version stance](core-data-structures/persistence.md)). Scope: the packages in this repo; a downstream plugin can merge further event types, which are outside this catalog by construction.',
+    'The envelope declarations below compose each event\'s `type`, monotonic `seq`, epoch-ms `time`, `data`, and the conditional `surfaceOp`/`sourceEventSeqs` fields. **surface** marks a `SurfaceEventType` member: it produces an LLM message and declares how it joins the surface list. **log-only** marks everything else: a durable, replayable record with no derived-history contribution. Every payload is JSON-serializable (enforced at `Session.append`), and the whole format is pinned at `SESSION_FORMAT_VERSION = 0` — pre-release, no compatibility implied ([the version stance](core-data-structures/persistence.md)). Scope: the packages in this repo; a downstream plugin can merge further event types, which are outside this catalog by construction.',
+    '',
+    '## Event envelope',
+    '',
+    '```' + FENCE,
+    envelopeTypes.map(entry => entry.declaration).join('\n\n'),
+    '```',
+    '',
+    `Sources: ${envelopeTypes.map(entry => `[\`${entry.source}\`](../${entry.source.split(':')[0]})`).join(' · ')}`,
     '',
     '## Events',
     '',
@@ -285,7 +378,7 @@ export function render(events: AnnotatedLogEventEntry[]): string {
  * is stale. Guarded behind an entry-point check so importing this module for
  * tests neither regenerates the committed file nor calls process.exit. */
 function main(): void {
-  const content = render(annotateSurface(collectLogEvents(), collectSurfaceEventTypes()))
+  const content = render(annotateSurface(collectLogEvents(), collectSurfaceEventTypes()), collectEventEnvelopeTypes())
   if (process.argv.includes('--check')) {
     let committed: string | null = null
     try {

scripts/gen-rfc-index.ts

@@ -1,36 +0,0 @@
-/**
- * Regenerate `docs/rfc/INDEX.md` — the fully generated RFC index — from the
- * RFC tree (see [rfc-index.ts](./rfc-index.ts) for the layout contract and
- * rendering rules). The whole file is generated state; the curated prose lives
- * in `docs/rfc/README.md`. Freshness is asserted by
- * `verify-rfc-classification.ts` (a `doc-sync` member), so a stale committed
- * index fails CI.
- *
- * Run: `pnpm run gen-rfc-index`.
- */
-
-import { readFileSync, writeFileSync } from 'node:fs'
-import { resolve } from 'node:path'
-import { renderIndex, rfcRoot, walkRfcTree } from './rfc-index.ts'
-
-const { rfcs, errors } = walkRfcTree()
-if (errors.length > 0) {
-  console.error('gen-rfc-index: refusing to generate from a structurally invalid tree:')
-  for (const e of errors) console.error(`  ${e}`)
-  process.exit(1)
-}
-
-const indexPath = resolve(rfcRoot, 'INDEX.md')
-const next = renderIndex(rfcs)
-let current: string | undefined
-try {
-  current = readFileSync(indexPath, 'utf8')
-} catch {
-  // Missing INDEX.md is the fresh-generation case, not an error: fall through and write it.
-}
-if (next === current) {
-  console.log(`gen-rfc-index: docs/rfc/INDEX.md is up to date (${rfcs.length} RFCs).`)
-} else {
-  writeFileSync(indexPath, next)
-  console.log(`gen-rfc-index: docs/rfc/INDEX.md regenerated (${rfcs.length} RFCs).`)
-}

scripts/gen-tool-catalog.ts

@@ -3,7 +3,7 @@
  * plugin. Runtime registration is the source of truth for computed schemas;
  * the manifest is checked against every on-disk `tool-*` package. `--check`
  * verifies the committed artifact. Rationale and ownership live in
- * `docs/rfc/implemented/process/2026-07-02-tool-schema-catalog.md`.
+ * `.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md`.
  */
 
 import { globSync, readFileSync, writeFileSync } from 'node:fs'
@@ -19,7 +19,7 @@ import WebService from '@deepseek-ai/dsh-web'
 import * as WebSearchExa from '@deepseek-ai/dsh-web-search-exa'
 import * as WebFetchLocal from '@deepseek-ai/dsh-web-fetch-local'
 import SubagentService from '@deepseek-ai/dsh-subagent'
-import * as SubagentMock from '@deepseek-ai/dsh-subagent-mock'
+import type { SubagentProvider } from '@deepseek-ai/dsh-subagent'
 import SkillService from '@deepseek-ai/dsh-skill'
 import * as SkillLocal from '@deepseek-ai/dsh-skill-local'
 import TaskService from '@deepseek-ai/dsh-tasks'
@@ -27,6 +27,7 @@ import * as ToolAskUser from '@deepseek-ai/dsh-tool-ask-user'
 import * as ToolBash from '@deepseek-ai/dsh-tool-bash'
 import * as ToolCordis from '@deepseek-ai/dsh-tool-cordis'
 import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
+import * as ToolFsSearch from '@deepseek-ai/dsh-tool-fs-search'
 import * as ToolSkill from '@deepseek-ai/dsh-tool-skill'
 import * as ToolTasks from '@deepseek-ai/dsh-tool-tasks'
 import * as ToolTodo from '@deepseek-ai/dsh-tool-todo'
@@ -38,6 +39,17 @@ import * as ToolWorkflow from '@deepseek-ai/dsh-tool-workflow'
 const root = resolve(import.meta.dirname, '..')
 const OUT = 'docs/tool-catalog.md'
 
+/** Register the descriptor needed to mount schema-producing consumers. */
+function registerCatalogSubagentProvider(ctx: Context, name: string): void {
+  const provider: SubagentProvider = {
+    name,
+    capabilities: { outputSchema: false, depthLimit: false, toolFilter: false, persona: false },
+    inheritsParentContext: false,
+    start: () => Promise.reject(new Error('tool-catalog provider cannot start a child')),
+  }
+  ctx.subagents.registerProvider(provider)
+}
+
 /**
  * Tool package plus its hand-maintained boot recipe. The caller mounts the
  * prompt and registry; each recipe supplies only package-specific seams and
@@ -107,7 +119,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
     toolsConfig: { mode: 'code' },
     async mount() {},
     note:
-      'Owned by the tool registry as a reserved transport outside filterable capability layers under `mode: code` / `mode: both` (see the Code Mode RFC). Under `code` it is the registry\'s only wire contribution; the other visible capabilities are declared in a generated TypeScript SDK section, and a program calls them through serialized bindings that re-enter the complete guarded tool pipeline and link each nested execution to this outer result.',
+      'Owned by the tool registry as a reserved transport outside filterable capability layers under `mode: code` / `mode: both` (see the Code Mode Agent Note). Under `code` it is the registry\'s only wire contribution; the other visible capabilities are declared in a generated TypeScript SDK section, and a program calls them through serialized bindings that re-enter the complete guarded tool pipeline and link each nested execution to this outer result.',
   },
   {
     pkg: '@deepseek-ai/dsh-tool-bash',
@@ -132,7 +144,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
       await ctx.plugin(ToolCordis)
     },
     note:
-      'Ships in examples/cordis-agent only (a deliberate opt-in — mounted code gets the real ctx, see docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins the model mounts may register ADDITIONAL model-visible tools at runtime; the request-header ToolsDelta logs those tool-set changes.',
+      'Ships in examples/cordis-agent only (a deliberate opt-in — mounted code gets the real ctx, see .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins the model mounts may register ADDITIONAL model-visible tools at runtime; a full changed request header logs those tool-set changes.',
   },
   {
     pkg: '@deepseek-ai/dsh-tool-fs',
@@ -149,6 +161,23 @@ const TOOL_PACKAGES: ToolPackage[] = [
     note:
       'The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-policy` (an `fs/*` event-gate plugin, no schema change); a deployment that loads these tools is expected to also load it. The tool schemas above are identical with or without the policy plugin.',
   },
+  {
+    pkg: '@deepseek-ai/dsh-tool-fs-search',
+    dir: 'tool-fs-search',
+    source: 'packages/fs/tool-fs-search/src/index.ts',
+    requires: ['ctx.tools', 'ctx.bash', 'ctx.systemPrompt'],
+    writes: ['tool/call', 'tool/result'],
+    async mount(ctx) {
+      // The tools inject `bash` (search executes fixed `rg` commands through
+      // the executor seam, not ctx.fs); boot the local executor to satisfy it.
+      // `ctx.spillStore` is optional (read via ctx.get) and does not affect the
+      // schemas, so no spill backend is mounted.
+      await ctx.plugin(LocalBashExecutor)
+      await ctx.plugin(ToolFsSearch)
+    },
+    note:
+      'glob and grep are bash-backed discovery tools: they run fixed ripgrep commands through ctx.bash as ordinary foreground calls (never background tasks). Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments.',
+  },
   {
     pkg: '@deepseek-ai/dsh-tool-skill',
     dir: 'tool-skill',
@@ -173,12 +202,11 @@ const TOOL_PACKAGES: ToolPackage[] = [
     shippedNames: ['subagent', 'subagent_fork'],
     async mount(ctx) {
       await ctx.plugin(SubagentService)
-      // Register a scripted provider under the name the tool delegates to.
-      await ctx.plugin(SubagentMock, { name: 'mock' })
+      registerCatalogSubagentProvider(ctx, 'mock')
       await ctx.plugin(ToolSubagent, { provider: 'mock' })
     },
     note:
-      'The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `examples/coding-agent/cordis.yml` and `examples/acp-agent/cordis.yml`.',
+      'The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `examples/repl-agent/cordis.yml` and `examples/acp-agent/cordis.yml`.',
   },
   {
     pkg: '@deepseek-ai/dsh-tool-tasks',
@@ -216,7 +244,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
       // subagent provider to satisfy it. The schema does not depend on which
       // provider backs the engine.
       await ctx.plugin(SubagentService)
-      await ctx.plugin(SubagentMock, { name: 'mock' })
+      registerCatalogSubagentProvider(ctx, 'mock')
       await ctx.plugin(VmWorkflowEngine, { provider: 'mock' })
       await ctx.plugin(ToolWorkflow)
     },
@@ -339,7 +367,7 @@ export function render(catalog: ToolCatalog): string {
     '',
     'Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the cordis [events](cordis-catalog/events.md) & [services](cordis-catalog/services.md) catalogs (the wiring a plugin listens to and calls) and [core-data-structures/](core-data-structures/core.md) (the types those signatures move) — this page is the *tools* the agent is offered.',
     '',
-    'This file is GENERATED and verified fresh by `pnpm run verify-tool-catalog` (part of `doc-sync`) — do not edit it by hand. Unlike the cordis catalog (a pure source-AST pass), this generator BOOTS each tool plugin on a real context and reads `ctx.tools.schemas()`, because a tool schema is not statically knowable (runtime-spread enums, concatenated descriptions, config-driven names, raw-JSON-Schema MCP tools). A completeness guard globs `packages/*/tool-*` and fails if any package is missing from the generator\'s boot manifest, so a new tool cannot be silently undocumented. See [the tool-schema-catalog RFC](rfc/implemented/process/2026-07-02-tool-schema-catalog.md).',
+    'This file is GENERATED and verified fresh by `pnpm run verify-tool-catalog` (part of `doc-sync`) — do not edit it by hand. Unlike the cordis catalog (a pure source-AST pass), this generator BOOTS each tool plugin on a real context and reads `ctx.tools.schemas()`, because a tool schema is not statically knowable (runtime-spread enums, concatenated descriptions, config-driven names, raw-JSON-Schema MCP tools). A completeness guard globs `packages/*/tool-*` and fails if any package is missing from the generator\'s boot manifest, so a new tool cannot be silently undocumented. See [the tool-schema-catalog Agent Note](../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md).',
     '',
     'Scope: shipped product tools under `packages/*/tool-*`, each booted with its DEFAULT config. The registered tool NAME can be a load-time config (e.g. `tool-subagent`\'s `toolName`), so a deployment may surface a package under a different or additional name — a per-package note records those shipped aliases where they exist. The `examples/` demo tools (e.g. `echo`) are excluded, matching the cordis catalog\'s packages-only scope.',
     '',

scripts/gen-website-api.ts

@@ -0,0 +1,757 @@
+/**
+ * Generate (and verify) the website API reference under `website/zh-CN/api/`.
+ *
+ * The website's API section is FULLY GENERATED from source — never hand-edit
+ * it. The hand-written hub `api/index.md` sits OUTSIDE the generated subdirs
+ * (`api/cordis/`, `api/harness/`), so the orphan sweep never touches it. Two tiers:
+ *
+ * - `api/cordis/*` — the vendored cordis framework surface (Context, Events,
+ *   Fiber, Registry, Service), driven by the CORDIS_PAGES manifest below.
+ *   Members come from the real class declarations and the `declare module
+ *   './context.ts'` interface merges (the typed `ctx.*` surface a plugin
+ *   author actually sees).
+ * - `api/harness/*` — one page per `ctx.<key>` harness service (walked from
+ *   every `declare module 'cordis'` Context merge under `packages/<group>/<pkg>/src`),
+ *   plus `events.md` listing every harness event grouped by scope.
+ *
+ * Prose comes from the JSDoc; the generator HARD-ERRORS (aggregated) when a
+ * rendered member lacks a summary, a parameter lacks `@param`, or a non-void
+ * annotated return lacks `@returns` — so a vendor sync or a new service method
+ * cannot land undocumented without CI going red. Pages are English (the
+ * planned zh translation flow arrives separately; see docs/i18n/README.md).
+ *
+ * Signature fences use the ` ```ts website-api ` info string and retain the
+ * declaration's original source JSDoc. doc-typecheck only processes its known
+ * info strings, so these bare (non-compilable) fragments are skipped there,
+ * while VitePress still highlights the `ts` token. The sidebar fragment
+ * `website/.vitepress/config/api-sidebar.json` is generated alongside so
+ * navigation can never drift from the page set.
+ *
+ *   `tsx scripts/gen-website-api.ts`          → write pages + sidebar
+ *   `tsx scripts/gen-website-api.ts --check`  → exit 1 if committed copies are
+ *                                               stale (doc-sync / CI gate)
+ */
+
+import { globSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import ts from 'typescript'
+import { checkParams, checkReturns, parseJsDoc, parseTags, pointer, rawJsDoc, reportViolations, type Mode } from './jsdoc.ts'
+import { cordisModuleBody, eventMembers, serviceClasses } from './cordis-walk.ts'
+
+const root = resolve(import.meta.dirname, '..')
+
+/** Output roots: generated pages and the generated sidebar fragment. */
+const PAGES_DIR = 'website/zh-CN/api'
+const SIDEBAR_OUT = 'website/.vitepress/config/api-sidebar.json'
+
+/** GitHub blob base for source links on the public site (repo-relative paths
+ * do not resolve on the built site, unlike the in-repo catalogs). */
+const GITHUB = 'https://github.com/deepseek-harness/deepseek-harness/blob/master'
+
+/** Signature-fence info string (skipped by doc-typecheck, highlighted as ts). */
+const FENCE = 'ts website-api'
+
+/** Return sorted repository-relative glob matches with stable URL separators. */
+function repoGlob(pattern: string): string[] {
+  return globSync(pattern, { cwd: root }).map(rel => rel.replaceAll('\\', '/')).sort()
+}
+
+/** One rendered member: a method/property plus its parsed JSDoc. */
+interface MemberDoc {
+  /** Display name, e.g. `on` or `agent/pre-step`. */
+  name: string
+  /** Heading suffix with parameter names, e.g. `(name, listener, options?)`;
+   * empty for properties. */
+  heading: string
+  /** All overload signature lines (bodies stripped). */
+  signatures: string[]
+  /** Original source JSDoc, dedented only from its containing declaration. */
+  jsDoc: string
+  /** Description prose, one paragraph per line. */
+  doc: string
+  /** Parameter name → `@param` text, in declaration order. */
+  params: { name: string; text: string }[]
+  /** `@returns` text, or null for void/undocumented. */
+  returns: string | null
+  /** Repo-relative `file:line` of the (first) declaration. */
+  source: string
+}
+
+/** A cordis-page section: which declarations it renders. */
+type Section =
+  | { kind: 'class'; file: string; symbol: string; prefix?: string; heading?: string }
+  | { kind: 'context-merge'; file: string; heading?: string }
+  | { kind: 'decl'; file: string; symbol: string }
+
+/** One generated cordis page. */
+interface CordisPage {
+  out: string
+  title: string
+  intro: string
+  sections: Section[]
+}
+
+/**
+ * The cordis tier manifest. Deliberately explicit (not a blind walk): the
+ * vendor `Context` mixes true plugin-author surface with internals, and page
+ * grouping is an editorial choice — but every member listed here is still
+ * EXTRACTED, never transcribed, so signatures and docs cannot drift.
+ */
+const CORDIS_PAGES: CordisPage[] = [
+  {
+    out: 'cordis/context.md',
+    title: 'Context',
+    intro: 'The context is the core cordis object: every service, event, and lifecycle API is reached through `ctx`. Event methods (`ctx.on`, `ctx.emit`, …) are documented on [Events](./events.md); `ctx.effect` and `ctx.fiber` on [Fiber](./fiber.md); `ctx.plugin` and `ctx.inject` on [Registry](./registry.md).',
+    sections: [
+      { kind: 'class', file: 'vendor/cordis/src/context.ts', symbol: 'Context', prefix: 'ctx.' },
+      { kind: 'context-merge', file: 'vendor/cordis/src/reflect.ts', heading: 'Service store and mixins' },
+    ],
+  },
+  {
+    out: 'cordis/events.md',
+    title: 'Events',
+    intro: 'The event system mixed into every context. Harness-defined events are cataloged on [Harness events](../harness/events.md).',
+    sections: [
+      { kind: 'context-merge', file: 'vendor/cordis/src/events.ts' },
+      { kind: 'decl', file: 'vendor/cordis/src/events.ts', symbol: 'EventOptions' },
+      { kind: 'decl', file: 'vendor/cordis/src/events.ts', symbol: 'DispatchMode' },
+    ],
+  },
+  {
+    out: 'cordis/fiber.md',
+    title: 'Fiber',
+    intro: 'A fiber is one loaded plugin instance: its lifecycle state, validated config, and registered effects. `ctx.fiber` is the current fiber; `ctx.effect()` delegates to it.',
+    sections: [
+      { kind: 'context-merge', file: 'vendor/cordis/src/fiber.ts' },
+      { kind: 'class', file: 'vendor/cordis/src/fiber.ts', symbol: 'Fiber', heading: 'The Fiber class' },
+      { kind: 'decl', file: 'vendor/cordis/src/fiber.ts', symbol: 'Effect' },
+      { kind: 'decl', file: 'vendor/cordis/src/fiber.ts', symbol: 'Disposable' },
+      { kind: 'decl', file: 'vendor/cordis/src/fiber.ts', symbol: 'EffectMeta' },
+      { kind: 'decl', file: 'vendor/cordis/src/fiber.ts', symbol: 'CordisError' },
+      { kind: 'decl', file: 'vendor/cordis/src/fiber.ts', symbol: 'ValidationError' },
+    ],
+  },
+  {
+    out: 'cordis/registry.md',
+    title: 'Registry',
+    intro: 'Plugin loading and dependency injection.',
+    sections: [
+      { kind: 'context-merge', file: 'vendor/cordis/src/registry.ts' },
+      { kind: 'decl', file: 'vendor/cordis/src/registry.ts', symbol: 'Plugin' },
+      { kind: 'decl', file: 'vendor/cordis/src/registry.ts', symbol: 'Inject' },
+    ],
+  },
+  {
+    out: 'cordis/service.md',
+    title: 'Service',
+    intro: 'Base class for context services: subclass it and load the subclass as a plugin to register `ctx.<name>`.',
+    sections: [
+      { kind: 'class', file: 'vendor/cordis/src/service.ts', symbol: 'Service' },
+    ],
+  },
+]
+// ---------------------------------------------------------------------------
+// Extraction
+// ---------------------------------------------------------------------------
+
+const sfCache = new Map<string, { sf: ts.SourceFile; text: string }>()
+
+/** Parse (and cache) one repo-relative source file. */
+function load(rel: string): { sf: ts.SourceFile; text: string } {
+  const cached = sfCache.get(rel)
+  if (cached) return cached
+  const text = readFileSync(resolve(root, rel), 'utf8')
+  const sf = ts.createSourceFile(rel, text, ts.ScriptTarget.Latest, true)
+  const entry = { sf, text }
+  sfCache.set(rel, entry)
+  return entry
+}
+// The module-merge walk (cordisModuleBody / eventMembers / serviceClasses) is
+// shared with gen-cordis-catalog.ts via cordis-walk.ts.
+
+/** Original JSDoc with only the source container's indentation removed. */
+function sourceJSDoc(text: string, sf: ts.SourceFile, node: ts.Node): string {
+  const raw = rawJsDoc(text, node)
+  if (raw === '') return ''
+  const { line } = sf.getLineAndCharacterOfPosition(node.getStart(sf))
+  const lineStart = sf.getPositionOfLineAndCharacter(line, 0)
+  const indent = text.slice(lineStart, node.getStart(sf))
+  return raw.split('\n')
+    .map((sourceLine, index) => index > 0 && sourceLine.startsWith(indent)
+      ? sourceLine.slice(indent.length)
+      : sourceLine)
+    .join('\n')
+}
+
+/** Signature text of a member: full text minus body/initializer, whitespace
+ * collapsed, trailing semicolon stripped. */
+function signatureOf(member: ts.Node, sf: ts.SourceFile): string {
+  const full = member.getText(sf)
+  const tail = (member as { body?: ts.Node; initializer?: ts.Node }).body
+    ?? (member as { initializer?: ts.Node }).initializer
+  const sig = tail ? full.slice(0, full.length - tail.getText(sf).length).replace(/[=\s]+$/, '') : full
+  return sig.replace(/\s*;?\s*$/, '').replace(/\s+/g, ' ').trim()
+}
+
+/** `(a, b?, ...rest)` heading suffix from a parameter list, `this` dropped. */
+function headingParams(parameters: readonly ts.ParameterDeclaration[], sf: ts.SourceFile): string {
+  const names = parameters
+    .filter(p => !(ts.isIdentifier(p.name) && p.name.text === 'this'))
+    .map((p) => {
+      const dots = p.dotDotDotToken ? '...' : ''
+      const opt = p.questionToken || p.initializer ? '?' : ''
+      return `${dots}${p.name.getText(sf)}${opt}`
+    })
+  return `(${names.join(', ')})`
+}
+
+/** Whether a class member is renderable public API (non-static half). */
+function isPublicInstance(member: ts.ClassElement): boolean {
+  const mods = ts.getCombinedModifierFlags(member)
+  if (mods & (ts.ModifierFlags.Private | ts.ModifierFlags.Protected | ts.ModifierFlags.Static)) return false
+  if (!member.name) return false
+  if (ts.isComputedPropertyName(member.name) || ts.isPrivateIdentifier(member.name)) return false
+  return !member.name.getText().startsWith('_')
+}
+
+/** Whether a class member is renderable public STATIC API. */
+function isPublicStatic(member: ts.ClassElement): boolean {
+  const mods = ts.getCombinedModifierFlags(member)
+  if (mods & (ts.ModifierFlags.Private | ts.ModifierFlags.Protected)) return false
+  if (!(mods & ts.ModifierFlags.Static)) return false
+  if (!member.name || ts.isComputedPropertyName(member.name) || ts.isPrivateIdentifier(member.name)) return false
+  return !member.name.getText().startsWith('_')
+}
+
+/** Build a MemberDoc from a declaration group (overloads share one entry),
+ * collecting completeness violations for everything rendered. */
+function memberDoc(
+  where: string,
+  name: string,
+  group: (ts.MethodDeclaration | ts.MethodSignature | ts.PropertyDeclaration | ts.PropertySignature | ts.GetAccessorDeclaration)[],
+  rel: string,
+  violations: string[],
+): MemberDoc {
+  const { sf, text } = load(rel)
+  const first = group[0]
+  if (!first) throw new Error(`gen-website-api: empty member group for ${name}`)
+  // Doc from the first overload that carries JSDoc prose.
+  const rawDocs = group.map(m => sourceJSDoc(text, sf, m))
+  const docIndex = rawDocs.findIndex(r => parseJsDoc(r).doc !== '')
+  const raw = docIndex === -1 ? '' : (rawDocs[docIndex] ?? '')
+  const doc = parseJsDoc(raw).doc
+  if (!doc) violations.push(`${where} has no JSDoc prose.`)
+  const { params: tags, returns } = parseTags(raw)
+  const params: { name: string; text: string }[] = []
+  let returnsText: string | null = null
+  const funcLike = group.filter((m): m is ts.MethodDeclaration | ts.MethodSignature => ts.isMethodDeclaration(m) || ts.isMethodSignature(m))
+  const docCarrier = funcLike[docIndex === -1 ? 0 : docIndex]
+  if (docCarrier) {
+    checkParams(where, 'website-api', docCarrier.parameters, tags, sf,
+      p => ts.isIdentifier(p.name) && p.name.text === 'this', violations)
+    if (docCarrier.type) {
+      checkReturns(where, docCarrier.type, returns, sf, violations)
+    } else if (!returns && ts.isMethodDeclaration(docCarrier)) {
+      // Comment-only vendor policy: we cannot add a return type annotation to
+      // pinned upstream source, so an unannotated rendered method must carry
+      // an explicit @returns describing the result instead.
+      violations.push(`${where} has no return type annotation; document the result with @returns.`)
+    }
+    for (const p of docCarrier.parameters) {
+      if (ts.isIdentifier(p.name) && p.name.text === 'this') continue
+      const pname = p.name.getText(sf)
+      const tag = tags.get(pname)
+      if (tag) params.push({ name: pname, text: tag })
+    }
+    returnsText = returns
+  }
+  const headingSource = docCarrier ?? funcLike[0]
+  return {
+    name,
+    heading: headingSource ? headingParams(headingSource.parameters, sf) : '',
+    signatures: (ts.isMethodDeclaration(first) && funcLike.length > 1
+      ? funcLike.filter(m => ts.isMethodDeclaration(m) && !m.body)
+      : group).map(m => signatureOf(m, sf)),
+    jsDoc: raw,
+    doc,
+    params,
+    returns: returnsText,
+    source: pointer(rel, sf, first),
+  }
+}
+
+/** Resolve an `extends Pick<Class, 'a' | 'b'>` heritage clause on the Context
+ * merge to the named members of `Class` declared in the same file — the fiber
+ * merge (`interface Context extends Pick<Fiber, 'effect'>`) is the motivating
+ * case: without this, `ctx.effect` had no documented signature anywhere. */
+function heritageMembers(
+  stmt: ts.InterfaceDeclaration,
+  sf: ts.SourceFile,
+  groups: Map<string, (ts.MethodSignature | ts.PropertySignature | ts.MethodDeclaration)[]>,
+): void {
+  for (const clause of stmt.heritageClauses ?? []) {
+    for (const type of clause.types) {
+      if (!ts.isIdentifier(type.expression) || type.expression.text !== 'Pick') continue
+      const [target, keys] = type.typeArguments ?? []
+      if (!target || !keys || !ts.isTypeReferenceNode(target)) continue
+      const targetName = target.typeName.getText(sf)
+      const cls = sf.statements.find(
+        (s): s is ts.ClassDeclaration => ts.isClassDeclaration(s) && s.name?.text === targetName,
+      )
+      if (!cls) continue
+      const picked = new Set<string>()
+      const collect = (node: ts.TypeNode): void => {
+        if (ts.isLiteralTypeNode(node) && ts.isStringLiteral(node.literal)) picked.add(node.literal.text)
+        if (ts.isUnionTypeNode(node)) node.types.forEach(collect)
+      }
+      collect(keys)
+      for (const member of cls.members) {
+        if (!ts.isMethodDeclaration(member)) continue
+        const name = member.name.getText(sf)
+        if (!picked.has(name)) continue
+        const group = groups.get(name) ?? []
+        group.push(member)
+        groups.set(name, group)
+      }
+    }
+  }
+}
+
+/** Members of the `interface Context` merge in `rel`, overloads grouped;
+ * `Pick<…>` heritage resolved to the picked class members. */
+function contextMergeMembers(rel: string, violations: string[]): MemberDoc[] {
+  const { sf } = load(rel)
+  const body = cordisModuleBody(sf)
+  if (!body) throw new Error(`gen-website-api: ${rel} has no context module merge`)
+  const groups = new Map<string, (ts.MethodSignature | ts.PropertySignature | ts.MethodDeclaration)[]>()
+  for (const stmt of body.statements) {
+    if (!ts.isInterfaceDeclaration(stmt) || stmt.name.text !== 'Context') continue
+    heritageMembers(stmt, sf, groups)
+    for (const member of stmt.members) {
+      if (!ts.isMethodSignature(member) && !ts.isPropertySignature(member)) continue
+      if (ts.isComputedPropertyName(member.name)) continue
+      const name = member.name.getText(sf)
+      const group = groups.get(name) ?? []
+      group.push(member)
+      groups.set(name, group)
+    }
+  }
+  return [...groups.entries()].map(([name, group]) =>
+    memberDoc(`ctx.${name} (${rel})`, name, group, rel, violations))
+}
+
+/** Instance + static members of one class, as two rendered lists. The class's
+ * same-named top-level interface half (declaration merging — vendor Context
+ * declares `root`/`events`/`logger`/… on the interface) is folded into the
+ * instance list, so neither half of a merged symbol goes undocumented. */
+function classMembers(rel: string, className: string, violations: string[]): {
+  doc: string
+  instance: MemberDoc[]
+  statics: MemberDoc[]
+  source: string
+} {
+  const { sf, text } = load(rel)
+  const cls = sf.statements.find(
+    (s): s is ts.ClassDeclaration => ts.isClassDeclaration(s) && s.name?.text === className,
+  )
+  if (!cls) throw new Error(`gen-website-api: class ${className} not found in ${rel}`)
+  const clsDoc = parseJsDoc(rawJsDoc(text, cls)).doc
+  if (!clsDoc) violations.push(`class ${className} (${pointer(rel, sf, cls)}) has no JSDoc.`)
+  type Renderable = ts.MethodDeclaration | ts.PropertyDeclaration | ts.GetAccessorDeclaration | ts.PropertySignature
+  const instance = new Map<string, Renderable[]>()
+  const statics = new Map<string, (ts.MethodDeclaration | ts.PropertyDeclaration)[]>()
+  for (const member of cls.members) {
+    const renderable = ts.isMethodDeclaration(member) || ts.isPropertyDeclaration(member) || ts.isGetAccessorDeclaration(member)
+    if (!renderable) continue
+    const name = member.name.getText(sf)
+    if (isPublicInstance(member)) {
+      const group = instance.get(name) ?? []
+      group.push(member)
+      instance.set(name, group)
+    } else if (isPublicStatic(member) && !ts.isGetAccessorDeclaration(member)) {
+      const group = statics.get(name) ?? []
+      group.push(member)
+      statics.set(name, group)
+    }
+  }
+  const iface = sf.statements.find(
+    (s): s is ts.InterfaceDeclaration => ts.isInterfaceDeclaration(s) && s.name.text === className,
+  )
+  for (const member of iface?.members ?? []) {
+    if (!ts.isPropertySignature(member)) continue
+    if (ts.isComputedPropertyName(member.name)) continue
+    const name = member.name.getText(sf)
+    const group = instance.get(name) ?? []
+    group.push(member)
+    instance.set(name, group)
+  }
+  const toDocs = (groups: Map<string, Renderable[]>, prefix: string): MemberDoc[] =>
+    [...groups.entries()].map(([name, group]) =>
+      memberDoc(`${prefix}${name} (${rel})`, name, group, rel, violations))
+  return {
+    doc: clsDoc,
+    instance: toDocs(instance, `${className}#`),
+    statics: toDocs(statics, `${className}.`),
+    source: pointer(rel, sf, cls),
+  }
+}
+
+/** Splice every function-like BODY out of a declaration's text, leaving the
+ * signature (`) {` → `)`). A reference paste shows shapes, not implementation;
+ * property initializers (e.g. an `as const` code table) are data and stay. */
+function stripBodies(node: ts.Node, sf: ts.SourceFile): string {
+  const cuts: { start: number; end: number }[] = []
+  const visit = (n: ts.Node): void => {
+    const funcLike = ts.isMethodDeclaration(n) || ts.isConstructorDeclaration(n)
+      || ts.isFunctionDeclaration(n) || ts.isGetAccessorDeclaration(n) || ts.isSetAccessorDeclaration(n)
+    if (funcLike && n.body) {
+      // Cut from just after the parameter close (or return-type end) through
+      // the body, so `foo(a: string) { … }` renders as `foo(a: string)`.
+      const sigEnd = (n.type ?? n.parameters[n.parameters.length - 1] ?? n).getEnd()
+      // Find the `)` (and optional `: Type`) boundary: body start is exact.
+      cuts.push({ start: sigEnd, end: n.body.getEnd() })
+      return // nothing renderable inside the body
+    }
+    n.forEachChild(visit)
+  }
+  visit(node)
+  const base = node.getStart(sf)
+  let out = node.getText(sf)
+  for (const cut of cuts.sort((a, b) => b.start - a.start)) {
+    const head = out.slice(0, cut.start - base)
+    // Keep everything of the signature up to the closing paren / return type,
+    // drop ` { … }`. The head may end mid-signature (last param), so retain
+    // the source between sigEnd and the body's `{` MINUS trailing space.
+    const between = out.slice(cut.start - base, cut.end - base)
+    const bodyBrace = between.indexOf('{')
+    out = head + between.slice(0, bodyBrace).trimEnd() + out.slice(cut.end - base)
+  }
+  return out
+}
+
+/** Verbatim declaration paste: every top-level statement named `symbol`
+ * (class + merged namespace both), with leading JSDoc prose extracted and
+ * function bodies stripped (a reference shows shapes, not implementation). */
+function declPaste(rel: string, symbol: string): { doc: string; code: string; source: string } {
+  const { sf, text } = load(rel)
+  const matches = sf.statements.filter((s) => {
+    const named = ts.isInterfaceDeclaration(s) || ts.isTypeAliasDeclaration(s)
+      || ts.isClassDeclaration(s) || ts.isEnumDeclaration(s) || ts.isModuleDeclaration(s)
+    return named && s.name?.getText(sf) === symbol
+  })
+  if (matches.length === 0) throw new Error(`gen-website-api: declaration ${symbol} not found in ${rel}`)
+  const first = matches[0]
+  if (!first) throw new Error(`gen-website-api: declaration ${symbol} not found in ${rel}`)
+  const firstJSDoc = sourceJSDoc(text, sf, first)
+  const doc = parseJsDoc(firstJSDoc).doc
+  const code = matches.map((statement) => {
+    const jsDoc = sourceJSDoc(text, sf, statement)
+    const declaration = stripBodies(statement, sf).replace(/^export\s+(default\s+)?/, '')
+    return jsDoc === '' ? declaration : `${jsDoc}\n${declaration}`
+  }).join('\n\n')
+  return { doc, code, source: pointer(rel, sf, first) }
+}
+
+/** One harness service with member-level detail. */
+interface HarnessService {
+  key: string
+  type: string
+  abstract: boolean
+  doc: string
+  members: MemberDoc[]
+  source: string
+  /** Owning npm package name (from the package.json beside the entry). */
+  pkg: string
+}
+
+/** Walk every harness `declare module 'cordis'` Context merge → services. */
+function collectHarnessServices(violations: string[]): HarnessService[] {
+  const services: HarnessService[] = []
+  for (const rel of repoGlob('packages/*/*/src/index.ts')) {
+    const { sf, text } = load(rel)
+    if (!text.includes('interface Context')) continue
+    const body = cordisModuleBody(sf)
+    if (!body) continue
+    const pkgJson = resolve(root, dirname(dirname(rel)), 'package.json')
+    // Manifest shape is repo-owned; `name` is the one field read here.
+    const manifest = JSON.parse(readFileSync(pkgJson, 'utf8')) as { name: string }
+    const pkg = manifest.name
+    for (const { key, type, cls, abstract, doc: clsDoc } of serviceClasses(body, sf, rel, violations)) {
+      const groups = new Map<string, (ts.MethodDeclaration | ts.PropertyDeclaration | ts.GetAccessorDeclaration)[]>()
+      for (const member of cls.members) {
+        // Public properties are API too: ctx.codeRuntime.language/isolation
+        // are readonly descriptors consumers key presentation off.
+        const renderable = ts.isMethodDeclaration(member) || ts.isPropertyDeclaration(member) || ts.isGetAccessorDeclaration(member)
+        if (!renderable) continue
+        if (!isPublicInstance(member)) continue
+        const name = member.name.getText(sf)
+        const group = groups.get(name) ?? []
+        group.push(member)
+        groups.set(name, group)
+      }
+      const members = [...groups.entries()].map(([name, group]) =>
+        memberDoc(`ctx.${key}.${name} (${rel})`, name, group, rel, violations))
+      services.push({ key, type, abstract, doc: clsDoc, members, source: pointer(rel, sf, cls), pkg })
+    }
+  }
+  return services.sort((a, b) => a.key.localeCompare(b.key))
+}
+
+/** One harness event with member-level detail. */
+interface HarnessEvent {
+  name: string
+  scope: string
+  mode: Mode | null
+  signature: string
+  /** Original source event JSDoc, dedented from its module/interface. */
+  jsDoc: string
+  doc: string
+  params: { name: string; text: string }[]
+  source: string
+}
+
+/** Walk every harness `interface Events` merge → events. */
+function collectHarnessEvents(violations: string[]): HarnessEvent[] {
+  const events: HarnessEvent[] = []
+  for (const rel of repoGlob('packages/*/*/src/*.ts')) {
+    const { sf, text } = load(rel)
+    if (!text.includes('interface Events')) continue
+    const body = cordisModuleBody(sf)
+    if (!body) continue
+    for (const { name, member } of eventMembers(body, sf)) {
+      const raw = sourceJSDoc(text, sf, member)
+      const { doc, mode } = parseJsDoc(raw)
+      if (!mode) violations.push(`event '${name}' (${pointer(rel, sf, member)}) is missing @mode.`)
+      if (!doc) violations.push(`event '${name}' (${pointer(rel, sf, member)}) has no JSDoc prose.`)
+      const { params: tags } = parseTags(raw)
+      const last = member.parameters.at(-1)
+      const hasNext = !!last && last.name.getText(sf) === 'next'
+      checkParams(`event '${name}' (${pointer(rel, sf, member)})`, 'website-api', member.parameters, tags, sf,
+        p => (ts.isIdentifier(p.name) && p.name.text === 'this') || (hasNext && p === last), violations)
+      const params: { name: string; text: string }[] = []
+      for (const p of member.parameters) {
+        const pname = p.name.getText(sf)
+        const tag = tags.get(pname)
+        if (tag) params.push({ name: pname, text: tag })
+      }
+      events.push({ name, scope: name.split('/')[0] ?? name, mode, signature: signatureOf(member, sf), jsDoc: raw, doc, params, source: pointer(rel, sf, member) })
+    }
+  }
+  return events.sort((a, b) => a.name.localeCompare(b.name))
+}
+
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+
+const BANNER = '<!-- Generated by scripts/gen-website-api.ts — do not edit by hand. Run `pnpm run gen-website-api` to regenerate. -->'
+
+/** GitHub source link for a `file:line` pointer. */
+function sourceLink(source: string): string {
+  const [file, line] = source.split(':')
+  return `[Source](${GITHUB}/${file}#L${line})`
+}
+
+/** Normalize JSDoc inline `{@link X}` / `{@link X|label}` / `{@link X label}`
+ * tags to plain Markdown code spans — left verbatim they leak into the built
+ * page as literal `{@link …}` text. */
+function unlink(text: string): string {
+  return text.replace(/\{@link\s+([^}|\s]+)\s*(?:[|\s]\s*([^}]*))?\}/g, (_m, target: string, label?: string) => {
+    const name = label?.trim()
+    return name && name !== '' ? name : `\`${target}\``
+  })
+}
+
+/** Render prose paragraphs (one per line of `doc`), JSDoc links normalized. */
+function prose(doc: string): string[] {
+  return unlink(doc).split('\n').filter(l => l.trim() !== '')
+}
+
+/** Render one member section at heading depth 3. */
+function renderMember(prefix: string, m: MemberDoc): string[] {
+  const lines: string[] = []
+  const call = m.heading === '' ? '' : m.heading
+  lines.push(`### ${prefix}${m.name}${call}`, '')
+  lines.push('```' + FENCE)
+  lines.push(m.jsDoc)
+  for (const sig of m.signatures) lines.push(sig)
+  lines.push('```', '')
+  lines.push(...prose(m.doc), '')
+  if (m.params.length > 0) {
+    for (const p of m.params) lines.push(`- \`${p.name}\` — ${unlink(p.text)}`)
+    lines.push('')
+  }
+  if (m.returns) lines.push(`**Returns** ${unlink(m.returns)}`, '')
+  lines.push(sourceLink(m.source), '')
+  return lines
+}
+
+/** Render one cordis-tier page from its manifest entry. */
+function renderCordisPage(page: CordisPage, violations: string[]): string {
+  const lines: string[] = [BANNER, '', `# ${page.title}`, '', page.intro, '']
+  for (const section of page.sections) {
+    if (section.kind !== 'decl' && section.heading) lines.push(`## ${section.heading}`, '')
+    if (section.kind === 'context-merge') {
+      for (const m of contextMergeMembers(section.file, violations)) {
+        lines.push(...renderMember('ctx.', m))
+      }
+    } else if (section.kind === 'class') {
+      const cls = classMembers(section.file, section.symbol, violations)
+      lines.push(...prose(cls.doc), '', sourceLink(cls.source), '')
+      const instancePrefix = section.prefix ?? `${section.symbol.toLowerCase()}.`
+      for (const m of cls.instance) lines.push(...renderMember(instancePrefix, m))
+      if (cls.statics.length > 0) {
+        lines.push('## Static members', '')
+        for (const m of cls.statics) lines.push(...renderMember(`${section.symbol}.`, m))
+      }
+    } else {
+      const decl = declPaste(section.file, section.symbol)
+      lines.push(`## ${section.symbol}`, '')
+      if (decl.doc) lines.push(...prose(decl.doc), '')
+      lines.push('```' + FENCE, decl.code, '```', '', sourceLink(decl.source), '')
+    }
+  }
+  return `${lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd()}\n`
+}
+
+/** kebab-case a ctx key: `agentLoop` → `agent-loop`. */
+function kebab(key: string): string {
+  return key.replace(/[A-Z]/g, c => `-${c.toLowerCase()}`)
+}
+
+/** Render one harness service page. */
+function renderServicePage(svc: HarnessService): string {
+  const seam = svc.abstract ? ' (abstract seam)' : ''
+  const lines: string[] = [
+    BANNER, '',
+    `# ctx.${svc.key}`, '',
+    `\`${svc.type}\`${seam} — provided by \`${svc.pkg}\`.`, '',
+    ...prose(svc.doc), '',
+    sourceLink(svc.source), '',
+  ]
+  for (const m of svc.members) lines.push(...renderMember(`ctx.${svc.key}.`, m))
+  return `${lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd()}\n`
+}
+
+/** Render the harness events page, grouped by scope. */
+function renderEventsPage(events: HarnessEvent[]): string {
+  const lines: string[] = [
+    BANNER, '',
+    '# Harness events', '',
+    `Every event the harness packages declare on the cordis event bus (${events.length} total), grouped by scope. The **mode** is the dispatch semantics (\`emit\` fire-and-forget, \`parallel\` awaited, \`serial\` first-bail, \`waterfall\` veto-chain — a waterfall listener MUST call \`next()\` to delegate).`, '',
+  ]
+  const scopes = [...new Set(events.map(e => e.scope))].sort()
+  for (const scope of scopes) {
+    lines.push(`## ${scope}/*`, '')
+    for (const e of events.filter(ev => ev.scope === scope)) {
+      lines.push(`### ${e.name}`, '')
+      lines.push(`**Mode:** \`${e.mode ?? 'unknown'}\``, '')
+      lines.push('```' + FENCE, e.jsDoc, e.signature, '```', '')
+      lines.push(...prose(e.doc), '')
+      if (e.params.length > 0) {
+        for (const p of e.params) lines.push(`- \`${p.name}\` — ${unlink(p.text)}`)
+        lines.push('')
+      }
+      lines.push(sourceLink(e.source), '')
+    }
+  }
+  return `${lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd()}\n`
+}
+
+// ---------------------------------------------------------------------------
+// Assembly + CLI
+// ---------------------------------------------------------------------------
+
+/** Build every generated file as `relPath → content`. */
+export function generate(): Map<string, string> {
+  const violations: string[] = []
+  const files = new Map<string, string>()
+
+  for (const page of CORDIS_PAGES) {
+    files.set(`${PAGES_DIR}/${page.out}`, renderCordisPage(page, violations))
+  }
+
+  const services = collectHarnessServices(violations)
+  for (const svc of services) {
+    files.set(`${PAGES_DIR}/harness/${kebab(svc.key)}.md`, renderServicePage(svc))
+  }
+
+  const events = collectHarnessEvents(violations)
+  files.set(`${PAGES_DIR}/harness/events.md`, renderEventsPage(events))
+
+  for (const [rel, content] of files) {
+    if (!rel.endsWith('.md')) continue
+    for (const match of content.matchAll(/^```ts website-api\n([\s\S]*?)\n```$/gm)) {
+      const body = match[1] ?? ''
+      if (!body.startsWith('/**')) {
+        violations.push(`${rel}: a ts website-api fence does not begin with original source JSDoc.`)
+      }
+    }
+  }
+
+  reportViolations('gen-website-api', violations)
+
+  const sidebar = {
+    cordis: CORDIS_PAGES.map(p => ({
+      text: p.title,
+      link: `/zh-CN/api/${p.out.replace(/\.md$/, '')}`,
+    })),
+    harness: [
+      ...services.map(s => ({ text: `ctx.${s.key}`, link: `/zh-CN/api/harness/${kebab(s.key)}` })),
+      { text: 'Events', link: '/zh-CN/api/harness/events' },
+    ],
+  }
+  files.set(SIDEBAR_OUT, `${JSON.stringify(sidebar, null, 2)}\n`)
+  return files
+}
+
+/** CLI entry: default writes, `--check` fails on stale/orphan files. Guarded
+ * behind an entry-point check so tests can import `generate()`. */
+function main(): void {
+  const check = process.argv.includes('--check')
+  const files = generate()
+
+  // Orphan detection: a generated-dir page that generate() no longer emits
+  // (e.g. a service was renamed) must be deleted, not left to rot.
+  const expected = new Set([...files.keys()])
+  // Orphans live in the generated subdirs only; the hand-written api/index.md
+  // is one level up and never matches this glob.
+  const onDisk = repoGlob(`${PAGES_DIR}/{cordis,harness}/*.md`)
+  const orphans = onDisk.filter(rel => !expected.has(rel))
+
+  if (check) {
+    const stale: string[] = []
+    for (const [rel, content] of files) {
+      let current: string | null = null
+      try {
+        current = readFileSync(resolve(root, rel), 'utf8')
+      } catch {
+        // Missing file: reported as stale below; readFileSync is the probe.
+      }
+      if (current !== content) stale.push(rel)
+    }
+    if (stale.length > 0 || orphans.length > 0) {
+      console.error('gen-website-api: website API reference is stale. Run `pnpm run gen-website-api` and commit the result.')
+      for (const rel of stale) console.error(`  stale: ${rel}`)
+      for (const rel of orphans) console.error(`  orphan (delete): ${rel}`)
+      process.exit(1)
+    }
+    console.log(`gen-website-api: ${files.size} generated file(s) fresh.`)
+    return
+  }
+
+  for (const [rel, content] of files) {
+    const abs = resolve(root, rel)
+    mkdirSync(dirname(abs), { recursive: true })
+    writeFileSync(abs, content)
+  }
+  for (const rel of orphans) {
+    console.log(`gen-website-api: orphan page ${rel} — delete it (no longer generated).`)
+  }
+  console.log(`gen-website-api: wrote ${files.size} file(s).`)
+}
+
+// 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()
+}

scripts/md-fences.ts

@@ -0,0 +1,55 @@
+/**
+ * Shared fenced-code-block extractor for the Markdown doc gates
+ * (`doc-typecheck.ts`, `verify-website-yaml.ts`). One scanner, per-gate
+ * classification: each gate maps a fence info string (` ```ts `,
+ * ` ```yaml ignore-check `, …) to its own kind tag and receives every
+ * classified block with its 1-based opening-fence line.
+ */
+
+import { readFileSync } from 'node:fs'
+
+/** One extracted fenced block, classified by the caller's `classify`. */
+export interface Fence<K> {
+  /** 1-based line of the opening fence. */
+  line: number
+  kind: K
+  code: string
+}
+
+/**
+ * Extract every fenced block of `absPath` whose info string `classify` maps
+ * to a kind. Blocks classified `null` are skipped (their bodies are still
+ * consumed, so an unrelated fence can never leak into a tracked one).
+ *
+ * @param absPath — absolute path of the Markdown file.
+ * @param classify — info string (trimmed, e.g. `ts ignore-check`) → kind, or
+ *   null for fences this gate does not track.
+ * @returns the classified blocks in document order.
+ */
+export function extractFences<K>(absPath: string, classify: (info: string) => K | null): Fence<K>[] {
+  const lines = readFileSync(absPath, 'utf8').split('\n')
+  const blocks: Fence<K>[] = []
+  let open: { line: number; kind: K; body: string[] } | null = null
+  let skipping = false
+
+  lines.forEach((raw, i) => {
+    const fence = /^```(\s*)(\S.*)?$/.exec(raw)
+    if (!fence) {
+      if (open) open.body.push(raw)
+      return
+    }
+    if (open) {
+      blocks.push({ line: open.line, kind: open.kind, code: open.body.join('\n') })
+      open = null
+      return
+    }
+    if (skipping) {
+      skipping = false
+      return
+    }
+    const kind = classify((fence[2] ?? '').trim())
+    if (kind !== null) open = { line: i + 1, kind, body: [] }
+    else skipping = true
+  })
+  return blocks
+}

scripts/rfc-index.ts

@@ -1,130 +0,0 @@
-/**
- * Shared source of truth for the RFC index: the tree walker (structure rules) and the README
- * table renderer. `gen-rfc-index.ts` writes the generated regions;
- * `verify-rfc-classification.ts` checks structure and asserts the committed regions are fresh.
- * Lifecycle and class sets are closed under `docs/rfc/README.md`; rows derive
- * from path, H1, and filename date and sort deterministically. Import is pure.
- */
-
-import { readFileSync, readdirSync } from 'node:fs'
-import { resolve, sep } from 'node:path'
-import { globSync } from 'node:fs'
-
-export const rfcRoot = resolve(import.meta.dirname, '../docs/rfc')
-
-/** The closed set of RFC lifecycles (top-level folders under docs/rfc/). */
-const LIFECYCLES = ['proposed', 'implemented', 'rejected'] as const
-
-/**
- * The closed set of RFC classes (nested folder under each lifecycle). Adding a
- * class is a deliberate act: extend this list AND the README's Classification
- * section. The gate rejects any folder not listed here.
- */
-const CLASSES = ['feature', 'bug-fix', 'simplification', 'architecture', 'process', 'testing'] as const
-
-/** Non-RFC Markdown allowed to sit directly at a lifecycle root. */
-const ROOT_ALLOWLIST = new Set(['AGENTS.md', 'CLAUDE.md'])
-
-/** Title-case a class/lifecycle folder name for a README heading. */
-const heading = (s: string): string => s.charAt(0).toUpperCase() + s.slice(1)
-
-/** One RFC file, as discovered by the walker. */
-export interface Rfc {
-  lifecycle: string
-  cls: string
-  base: string
-  /** Path relative to docs/rfc — the README link target. */
-  rel: string
-  /** H1 text with any `RFC: ` prefix stripped — the README row title. */
-  title: string
-  /** `yyyy-mm-dd` from the filename — the "First proposed" column. */
-  date: string
-}
-
-/**
- * Walk the RFC tree, enforcing the structure rules. Returns every valid RFC
- * plus one error string per violation (unknown lifecycle or class folder, bad
- * depth, bad filename, missing/malformed H1). Callers treat a non-empty error
- * list as fatal — the index is only generated from a structurally valid tree.
- */
-export function walkRfcTree(): { rfcs: Rfc[]; errors: string[] } {
-  const rfcs: Rfc[] = []
-  const errors: string[] = []
-  // The lifecycle set is closed too: any directory under docs/rfc/ that is not
-  // a known lifecycle would otherwise hold RFCs invisible to the walk below.
-  for (const entry of readdirSync(rfcRoot, { withFileTypes: true })) {
-    if (entry.isDirectory() && !(LIFECYCLES as readonly string[]).includes(entry.name)) {
-      errors.push(`structure: ${entry.name}/ — unknown lifecycle folder (allowed: ${LIFECYCLES.join(', ')})`)
-    }
-  }
-  for (const lifecycle of LIFECYCLES) {
-    for (const match of globSync(`${lifecycle}/**/*.md`, { cwd: rfcRoot }).map(path => path.split(sep).join('/')).sort()) {
-      const segs = match.split('/')
-      // Allowlisted file directly at the lifecycle root (e.g. implemented/AGENTS.md).
-      if (segs.length === 2 && ROOT_ALLOWLIST.has(segs[1] ?? '')) continue
-      // A Chinese counterpart (foo.zh.md, docs/i18n/README.md) is the SAME RFC,
-      // indexed via its English filename; the pairing gate owns its consistency.
-      if (match.endsWith('.zh.md')) continue
-      const cls = segs[1]
-      const base = segs[2]
-      if (segs.length !== 3 || cls === undefined || base === undefined) {
-        errors.push(`structure: ${match} — expected {lifecycle}/{class}/file.md (got depth ${segs.length})`)
-        continue
-      }
-      if (!(CLASSES as readonly string[]).includes(cls)) {
-        errors.push(`structure: ${match} — unknown class folder "${cls}" (allowed: ${CLASSES.join(', ')})`)
-        continue
-      }
-      if (!/^\d{4}-\d{2}-\d{2}-.+\.md$/.test(base)) {
-        errors.push(`structure: ${match} — filename must be yyyy-mm-dd-topic.md`)
-        continue
-      }
-      const firstLine = readFileSync(resolve(rfcRoot, match), 'utf8').split('\n', 1)[0] ?? ''
-      const h1 = /^#\s+(?:RFC:\s+)?(.+?)\s*$/.exec(firstLine)
-      if (!h1?.[1]) {
-        errors.push(`title: ${match} — first line must be an H1 (\`# RFC: <title>\` or \`# <title>\`), got: ${JSON.stringify(firstLine)}`)
-        continue
-      }
-      rfcs.push({ lifecycle, cls, base, rel: match, title: h1[1], date: base.slice(0, 10) })
-    }
-  }
-  return { rfcs, errors }
-}
-
-/**
- * Render one lifecycle's section body: a `### {Class}` heading plus a
- * `| Title | First proposed |` table for every non-empty class, in CLASSES
- * order, rows sorted by date then filename.
- */
-function renderLifecycle(rfcs: Rfc[], lifecycle: string): string {
-  const sections: string[] = []
-  for (const cls of CLASSES) {
-    const rows = rfcs
-      .filter(r => r.lifecycle === lifecycle && r.cls === cls)
-      .sort((a, b) => a.date.localeCompare(b.date) || a.base.localeCompare(b.base))
-    if (rows.length === 0) continue
-    const table = rows.map(r => `| [${r.title}](${r.rel}) | ${r.date} |`).join('\n')
-    sections.push(`### ${heading(cls)}\n\n| Title | First proposed |\n|---|---|\n${table}`)
-  }
-  return sections.join('\n\n')
-}
-
-/**
- * Render the complete `docs/rfc/INDEX.md` content: a generated-file banner
- * followed by one `## {Lifecycle}` section per lifecycle in canonical order.
- * The whole file is generated state — there is no curated region to preserve.
- */
-export function renderIndex(rfcs: Rfc[]): string {
-  const parts = [
-    '# RFC index',
-    '',
-    'Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; `verify-rfc-classification` fails when this file is stale. The curated front door — layout, classification, when to write one, and the in-file format — is [README.md](README.md).',
-  ]
-  for (const lifecycle of LIFECYCLES) {
-    parts.push('', `## ${heading(lifecycle)}`, '', renderLifecycle(rfcs, lifecycle))
-  }
-  return `${parts.join('\n')}\n`
-}
-
-/** Matches an index-shaped table row (a `| [title](lifecycle/…) |` line) — generated state that must not appear in curated prose. */
-export const INDEX_ROW = /^\|\s*\[[^\]]+\]\((?:proposed|implemented|rejected)\//

scripts/run-gates.ts

@@ -24,6 +24,7 @@ type GateStatus = 'pending' | 'running' | 'passed' | 'failed' | 'skipped'
 interface Gate {
   id: string
   label: string
+  displayCommand: string
   command: string
   args: string[]
   needs?: string[]
@@ -38,22 +39,39 @@ interface GateResult {
   durationMs: number
   stdout: string
   stderr: string
+  output: GateOutputChunk[]
   exitCode: number | null
   error?: string
 }
 
+interface GateOutputChunk {
+  stream: 'stdout' | 'stderr'
+  text: string
+}
+
 interface RunningGate {
   gate: Gate
   promise: Promise<GateResult>
 }
 
+interface ConcurrencyDefault {
+  workers: number
+  source: string
+}
+
 const root = resolve(import.meta.dirname, '..')
 const mode = parseMode(process.argv[2])
 const gates = gatesForMode(mode)
-const maxConcurrency = concurrencyFromEnv('DSH_GATE_CONCURRENCY', defaultConcurrency(gates.length))
+const concurrencyDefault = defaultConcurrency(mode, gates.length)
+const concurrencyOverride = process.env.DSH_GATE_CONCURRENCY
+const maxConcurrency = concurrencyFromEnv('DSH_GATE_CONCURRENCY', concurrencyDefault.workers)
+const verbose = process.env.DSH_GATE_VERBOSE === '1'
 const startedAt = performance.now()
 
-console.log(`run-gates: ${mode} running ${gates.length} gate(s) with ${maxConcurrency} worker(s).`)
+const concurrencySource = concurrencyOverride === undefined || concurrencyOverride === ''
+  ? concurrencyDefault.source
+  : '$DSH_GATE_CONCURRENCY'
+console.log(`run-gates: ${mode} running ${gates.length} gate(s) with ${maxConcurrency} worker(s) from ${concurrencySource}.`)
 
 const results = await runGates(gates, maxConcurrency)
 printSummary(results, performance.now() - startedAt)
@@ -78,8 +96,15 @@ function parseMode(raw: string | undefined): Mode {
   }
 }
 
-function defaultConcurrency(total: number): number {
-  return Math.min(total, Math.max(4, availableParallelism()))
+function defaultConcurrency(selectedMode: Mode, total: number): ConcurrencyDefault {
+  const available = availableParallelism()
+  const modeLimit = selectedMode === 'pre-push' ? Math.min(4, available) : available
+  return {
+    workers: Math.min(total, modeLimit),
+    source: selectedMode === 'pre-push'
+      ? `${available} available CPU(s), pre-push cap 4`
+      : `${available} available CPU(s)`,
+  }
 }
 
 function concurrencyFromEnv(name: string, fallback: number): number {
@@ -96,6 +121,7 @@ function pnpmScript(id: string, script: string, options: Partial<Gate> = {}): Ga
   return {
     id,
     label: options.label ?? script,
+    displayCommand: `pnpm run ${script}`,
     ...pnpmInvocation(['run', script]),
     ...options,
   }
@@ -105,6 +131,7 @@ function pnpmExec(id: string, args: string[], options: Partial<Gate> = {}): Gate
   return {
     id,
     label: options.label ?? `pnpm exec ${args.join(' ')}`,
+    displayCommand: `pnpm exec ${args.join(' ')}`,
     ...pnpmInvocation(['exec', ...args]),
     ...options,
   }
@@ -136,11 +163,13 @@ function gatesForMode(selected: Mode): Gate[] {
       ]
     case 'ci-coverage':
       return [
+        pnpmScript('build', 'build'),
         coverageGate(),
       ]
     case 'ci-snapshot':
       return [
-        pnpmScript('snapshot', 'test:snapshot'),
+        pnpmScript('build', 'build'),
+        snapshotGate(),
       ]
     case 'ci-artifacts':
       return ciArtifactGates()
@@ -159,10 +188,13 @@ function gatesForMode(selected: Mode): Gate[] {
         pnpmScript('cordis-config', 'verify-cordis-config', { label: 'Cordis config' }),
         pnpmScript('test', 'test'),
         pnpmScript('duplication', 'duplication'),
-        pnpmScript('snapshot', 'test:snapshot'),
+        snapshotGate(),
         pnpmScript('build', 'build'),
         ...hygieneLeafGates({ artifactNeeds: ['build'] }),
-        ...docSyncLeafGates(),
+        ...docSyncLeafGates({
+          docTypecheckNeeds: ['build'],
+          docTypecheckEnv: { DSH_DOC_TYPECHECK_USE_BUILD_OUTPUT: '1' },
+        }),
         pnpmScript('module-graph', 'verify-module-graph', { label: 'module graph' }),
       ]
   }
@@ -177,11 +209,12 @@ function ciPrimaryGates(): Gate[] {
     lintGate(),
     pnpmScript('duplication', 'duplication'),
     coverageGate(),
-    pnpmScript('snapshot', 'test:snapshot'),
+    snapshotGate(),
     demoSmokeGate({ needs: ['lint'] }),
     ...docSyncLeafGates(),
     pnpmScript('module-graph', 'verify-module-graph', { label: 'module graph' }),
     pnpmScript('knip', 'knip'),
+    pnpmScript('website-build', 'website:build', { label: 'website build' }),
     pnpmScript('build', 'build', { needs: ['typecheck'] }),
     pnpmScript('publint', 'publint', { needs: ['build'] }),
     pnpmScript('node-next-types', 'verify-node-next-types', {
@@ -201,6 +234,7 @@ function ciStaticGates(): Gate[] {
     ...docSyncLeafGates(),
     pnpmScript('module-graph', 'verify-module-graph', { label: 'module graph' }),
     pnpmScript('knip', 'knip'),
+    pnpmScript('website-build', 'website:build', { label: 'website build' }),
   ]
 }
 
@@ -249,6 +283,18 @@ function coverageGate(): Gate {
     ...positiveIntArg('DSH_COVERAGE_MAX_WORKERS', '--maxWorkers'),
   ], {
     label: 'test:coverage',
+    env: { DSH_EXAMPLE_MODE: 'lib' },
+    needs: ['build'],
+  })
+}
+
+// The snapshot suite boots the example bins in `lib` mode (built artifact under plain Node,
+// plugins via real exports) — CI and pre-push already build, so they exercise what ships rather
+// than the tsx/source path dev uses. It therefore waits on `build`.
+function snapshotGate(): Gate {
+  return pnpmScript('snapshot', 'test:snapshot', {
+    env: { DSH_EXAMPLE_MODE: 'lib' },
+    needs: ['build'],
   })
 }
 
@@ -275,9 +321,15 @@ function hygieneLeafGates(options: { artifactNeeds?: string[] } = {}): Gate[] {
   ]
 }
 
-function docSyncLeafGates(): Gate[] {
+function docSyncLeafGates(options: {
+  docTypecheckNeeds?: string[]
+  docTypecheckEnv?: Record<string, string | undefined>
+} = {}): Gate[] {
+  const docTypecheckOptions: Partial<Gate> = {}
+  if (options.docTypecheckNeeds !== undefined) docTypecheckOptions.needs = options.docTypecheckNeeds
+  if (options.docTypecheckEnv !== undefined) docTypecheckOptions.env = options.docTypecheckEnv
   return [
-    pnpmScript('doc-typecheck', 'doc-typecheck'),
+    pnpmScript('doc-typecheck', 'doc-typecheck', docTypecheckOptions),
     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' }),
@@ -285,19 +337,21 @@ function docSyncLeafGates(): Gate[] {
     pnpmScript('persistence-catalog', 'verify-persistence-catalog', { label: 'persistence catalog' }),
     pnpmScript('doc-graphs', 'verify-doc-graphs', { label: 'doc graphs' }),
     pnpmScript('scoped-events', 'verify-scoped-events', { label: 'scoped events' }),
+    pnpmScript('website-api', 'verify-website-api', { label: 'website api' }),
     pnpmScript('markdown-wrap', 'verify-md-wrap', { label: 'markdown wrap' }),
     pnpmScript('markdown-links', 'verify-md-links', { label: 'markdown links' }),
     pnpmScript('doc-refs', 'verify-doc-refs', { label: 'doc refs' }),
     pnpmScript('package-paths', 'verify-package-paths', { label: 'package paths' }),
     pnpmScript('package-readme-model-experience', 'verify-package-readme-model-experience', { label: 'package README model experience' }),
     pnpmScript('mermaid', 'verify-mermaid'),
-    pnpmScript('rfc-classification', 'verify-rfc-classification', { label: 'rfc classification' }),
-    pnpmScript('rfc-format', 'verify-rfc-format', { label: 'rfc format' }),
+    pnpmScript('agent-note-classification', 'verify-agent-note-classification', { label: 'agent note classification' }),
+    pnpmScript('agent-note-format', 'verify-agent-note-format', { label: 'agent note format' }),
     pnpmScript('type-equivalence', 'verify-type-equiv', { label: 'type equivalence' }),
     pnpmScript('translation-prompt', 'verify-translation-prompt', { label: 'translation prompt' }),
     pnpmScript('translation-pairing', 'verify-translation-pairing', { label: 'translation pairing' }),
     pnpmScript('doc-budgets', 'verify-doc-budgets', { label: 'doc budgets' }),
     pnpmScript('package-readme-limitations', 'verify-package-readme-limitations', { label: 'package README limitations' }),
+    pnpmScript('website-yaml', 'verify-website-yaml', { label: 'website yaml' }),
   ]
 }
 
@@ -306,6 +360,7 @@ function demoSmokeGate(options: { needs?: string[] } = {}): Gate {
   return {
     id: 'demo-smoke',
     label: 'demo smoke',
+    displayCommand: 'pnpm run demo:echo',
     ...pnpmInvocation(['run', 'demo:echo']),
     input: 'echo ci smoke\n',
     ...dependencyOptions,
@@ -344,7 +399,9 @@ function builtBinSmokeGate(): Gate {
     '--config',
     'vitest.e2e.config.ts',
     'packages/examples/stdio-demo/tests/built-bin.e2e.ts',
+    'packages/examples/cli-demo/tests/built-bin.e2e.ts',
     'packages/examples/acp-demo/tests/built-bin.e2e.ts',
+    'packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts',
     // The worker-entry packages' built bundles: the only automated proof
     // that lib/index.js resolves its sibling lib/worker.cjs under plain node
     // (the e2e lane runs unbuilt, so these files self-skip there).
@@ -382,6 +439,7 @@ async function runGates(allGates: Gate[], maxActive: number): Promise<GateResult
           durationMs: 0,
           stdout: '',
           stderr: '',
+          output: [],
           exitCode: null,
           error: `dependency failed or skipped: ${failedDeps.join(', ')}`,
         }
@@ -416,8 +474,10 @@ async function runGate(gate: Gate): Promise<GateResult> {
   const started = performance.now()
   let stdout = ''
   let stderr = ''
+  const output: GateOutputChunk[] = []
+  let spawnError: string | undefined
 
-  const exitCode = await new Promise<number | null>((resolveExit, reject) => {
+  const exitCode = await new Promise<number | null>((resolveExit) => {
     const child = spawn(gate.command, gate.args, {
       cwd: root,
       env: { ...process.env, ...gate.env },
@@ -425,19 +485,28 @@ async function runGate(gate: Gate): Promise<GateResult> {
     })
     child.stdout.setEncoding('utf8')
     child.stderr.setEncoding('utf8')
-    child.stdout.on('data', (chunk: string) => { stdout += chunk })
-    child.stderr.on('data', (chunk: string) => { stderr += chunk })
-    child.on('error', reject)
+    child.stdout.on('data', (chunk: string) => {
+      stdout += chunk
+      output.push({ stream: 'stdout', text: chunk })
+    })
+    child.stderr.on('data', (chunk: string) => {
+      stderr += chunk
+      output.push({ stream: 'stderr', text: chunk })
+    })
+    child.on('error', (error) => {
+      spawnError = `failed to start command: ${error.message}`
+      resolveExit(null)
+    })
     child.on('close', resolveExit)
     if (gate.input !== undefined) child.stdin.end(gate.input)
     else child.stdin.end()
   })
 
-  let status: GateStatus = exitCode === 0 ? 'passed' : 'failed'
-  let error: string | undefined
+  let status: GateStatus = exitCode === 0 && spawnError === undefined ? 'passed' : 'failed'
+  let error = spawnError
   if (status === 'passed' && gate.verify !== undefined) {
     try {
-      await gate.verify({ gate, status, durationMs: performance.now() - started, stdout, stderr, exitCode })
+      await gate.verify({ gate, status, durationMs: performance.now() - started, stdout, stderr, output, exitCode })
     } catch (verifyError: unknown) {
       status = 'failed'
       error = verifyError instanceof Error ? verifyError.message : String(verifyError)
@@ -450,6 +519,7 @@ async function runGate(gate: Gate): Promise<GateResult> {
     durationMs: performance.now() - started,
     stdout,
     stderr,
+    output,
     exitCode,
   }
   if (error !== undefined) result.error = error
@@ -458,9 +528,16 @@ async function runGate(gate: Gate): Promise<GateResult> {
 
 function printResult(result: GateResult): void {
   const seconds = (result.durationMs / 1000).toFixed(2)
-  console.log(`\n== ${result.status.toUpperCase()} ${result.gate.label} (${seconds}s) ==`)
-  process.stdout.write(result.stdout)
-  process.stderr.write(result.stderr)
+  if (result.status === 'passed' && !verbose) {
+    console.log(`run-gates: PASS ${result.gate.label} (${seconds}s)`)
+    return
+  }
+
+  const heading = `${result.status.toUpperCase()} ${result.gate.label} (${seconds}s)`
+  const writeHeading = result.status === 'passed' ? console.log : console.error
+  writeHeading(`\n== ${heading} ==`)
+  if (result.status !== 'passed') console.error(`command: ${result.gate.displayCommand}`)
+  printOutput(result.output)
   if (result.error !== undefined) console.error(result.error)
 }
 
@@ -470,4 +547,22 @@ function printSummary(results: GateResult[], durationMs: number): void {
   const skipped = results.filter(result => result.status === 'skipped').length
   const seconds = (durationMs / 1000).toFixed(2)
   console.log(`\nrun-gates: ${passed} passed, ${failed} failed, ${skipped} skipped in ${seconds}s.`)
+
+  const unsuccessful = results.filter(result => result.status === 'failed' || result.status === 'skipped')
+  if (unsuccessful.length === 0) return
+
+  console.error('run-gates: unsuccessful gates:')
+  for (const result of unsuccessful) {
+    const duration = (result.durationMs / 1000).toFixed(2)
+    const reason = result.error ?? (result.exitCode === null ? 'no exit code' : `exit ${result.exitCode}`)
+    console.error(`  - ${result.status.toUpperCase()} ${result.gate.label} (${duration}s, ${reason})`)
+    console.error(`    ${result.gate.displayCommand}`)
+  }
+}
+
+function printOutput(output: GateOutputChunk[]): void {
+  for (const chunk of output) {
+    if (chunk.stream === 'stdout') process.stdout.write(chunk.text)
+    else process.stderr.write(chunk.text)
+  }
 }

scripts/smoke-python-runtime.py

@@ -57,6 +57,7 @@ CUSTOM_CORDIS = """\
 - id: agent-core
   name: '@deepseek-ai/dsh-agent-spine-demo'
   config:
+    workspaceContext: false
     tools:
       mode: both
 - id: sessions
@@ -379,6 +380,7 @@ def smoke_sdk_default(base_url: str) -> None:
         root = Path(temporary).resolve()
         sessions = root / "sessions"
         with DeepSeekHarness(
+            provider="deepseek",
             model="smoke-model",
             cwd=str(root),
             session_root=str(sessions),
@@ -401,6 +403,7 @@ def smoke_sdk_custom(base_url: str, executable: Path) -> None:
         cordis = root / "cordis.yml"
         cordis.write_text(CUSTOM_CORDIS)
         with DeepSeekHarness(
+            provider="deepseek",
             model="smoke-model",
             cwd=str(root),
             session_root=str(sessions),
@@ -432,6 +435,7 @@ def smoke_sdk_snapshot(base_url: str, executable: Path, update_snapshots: bool)
         cordis = root / "cordis.yml"
         cordis.write_text(CUSTOM_CORDIS)
         with DeepSeekHarness(
+            provider="deepseek",
             model="smoke-model",
             cwd=str(root),
             session_root=str(sessions),
@@ -481,7 +485,7 @@ def smoke_direct(base_url: str, executable: Path) -> None:
         }
         peer = RuntimePeer([str(executable)], root, environment)
         try:
-            peer.send({"jsonrpc": "2.0", "id": "initialize", "method": "initialize", "params": {"cwd": str(root), "model": "smoke-model"}})
+            peer.send({"jsonrpc": "2.0", "id": "initialize", "method": "initialize", "params": {"cwd": str(root), "provider": "deepseek", "model": "smoke-model"}})
             peer.read_until(lambda message: message.get("id") == "initialize")
             peer.send({
                 "jsonrpc": "2.0",
@@ -624,7 +628,7 @@ def build_snapshot_files(
     child_ids: list[str],
     cwd: Path,
 ) -> dict[str, str]:
-    """Render the SDK result and three persisted logs into stable goldens."""
+    """Render the SDK result and three persisted logs into stable expected outputs."""
     replacements = [(str(cwd), "{{cwd}}"), (SNAPSHOT_SESSION_ID, "{{parent}}")]
     for index, child_id in enumerate(child_ids, start=1):
         replacements.append((child_id, f"{{{{child-{index}}}}}"))
@@ -703,7 +707,7 @@ def normalize_snapshot_value(
 
 
 def scrub_snapshot_header(value: dict[object, object]) -> None:
-    """Tokenize request-header bulk while retaining delta tool names."""
+    """Tokenize full request-header bulk while retaining tool names."""
     data = value.get("data")
     if not isinstance(data, dict):
         return
@@ -721,29 +725,6 @@ def scrub_snapshot_header(value: dict[object, object]) -> None:
             ]
         if isinstance(header.get("messagePrefix"), list):
             header["messagePrefix"] = ["{{messagePrefix}}" for _ in header["messagePrefix"]]
-        return
-    if value.get("type") != "request/header-delta":
-        return
-    system = data.get("system")
-    if isinstance(system, dict) and isinstance(system.get("insert"), list):
-        system["insert"] = ["{{system}}" for _ in system["insert"]]
-    tools = data.get("tools")
-    if isinstance(tools, dict):
-        for key in ("added", "changed"):
-            if isinstance(tools.get(key), list):
-                tools[key] = [scrub_snapshot_tool_schema(tool) for tool in tools[key]]
-    if isinstance(data.get("messagePrefix"), list):
-        data["messagePrefix"] = ["{{messagePrefix}}" for _ in data["messagePrefix"]]
-
-
-def scrub_snapshot_tool_schema(value: object) -> object:
-    """Keep a changed tool's name while tokenizing its schema bulk."""
-    if not isinstance(value, dict):
-        return value
-    return {
-        key: item if key == "name" else "{{tools}}"
-        for key, item in value.items()
-    }
 
 
 def render_jsonl(records: list[object]) -> str:

scripts/snapshots/python-sdk-single-exe/advanced/result.json

@@ -253,7 +253,7 @@
             "workflow"
           ]
         },
-        "reason": "fallback"
+        "reason": "change"
       }
     },
     {
@@ -915,22 +915,29 @@
       }
     },
     {
-      "type": "request/header-delta",
+      "type": "request/header",
       "seq": 56,
       "time": 0,
       "data": {
-        "system": {
-          "keepStart": 62,
-          "keepEnd": 34,
-          "insert": []
+        "header": {
+          "config": {
+            "model": "smoke-model"
+          },
+          "system": "{{system}}",
+          "tools": [
+            "bash",
+            "bash_kill",
+            "bash_output",
+            "cordis_inspect",
+            "cordis_mount",
+            "cordis_unmount",
+            "run_code",
+            "skill",
+            "subagent",
+            "workflow"
+          ]
         },
-        "tools": {
-          "added": [],
-          "removed": [
-            "snapshot_double"
-          ],
-          "changed": []
-        }
+        "reason": "change"
       }
     },
     {
@@ -1396,7 +1403,7 @@
                 "workflow"
               ]
             },
-            "reason": "fallback"
+            "reason": "change"
           }
         }
       }
@@ -2358,22 +2365,29 @@
       "payload": {
         "sessionId": "{{parent}}",
         "event": {
-          "type": "request/header-delta",
+          "type": "request/header",
           "seq": 56,
           "time": 0,
           "data": {
-            "system": {
-              "keepStart": 62,
-              "keepEnd": 34,
-              "insert": []
+            "header": {
+              "config": {
+                "model": "smoke-model"
+              },
+              "system": "{{system}}",
+              "tools": [
+                "bash",
+                "bash_kill",
+                "bash_output",
+                "cordis_inspect",
+                "cordis_mount",
+                "cordis_unmount",
+                "run_code",
+                "skill",
+                "subagent",
+                "workflow"
+              ]
             },
-            "tools": {
-              "added": [],
-              "removed": [
-                "snapshot_double"
-              ],
-              "changed": []
-            }
+            "reason": "change"
           }
         }
       }

scripts/snapshots/python-sdk-single-exe/advanced/session.jsonl

@@ -13,7 +13,7 @@
 {"type":"tool/result","seq":11,"time":0,"data":{"turn":1,"step":1,"callId":"advanced-mount","content":[{"type":"text","text":"mounted dyn-1 (plugin \"<anonymous>\", state: active)"}],"isError":false},"sourceEventSeqs":[10],"surfaceOp":"append"}
 {"type":"step/end","seq":12,"time":0,"data":{"turn":1,"step":1}}
 {"type":"step/start","seq":13,"time":0,"data":{"turn":1,"step":2}}
-{"type":"request/header","seq":14,"time":0,"data":{"header":{"config":{"model":"smoke-model"},"system":"{{system}}","tools":["bash","bash_kill","bash_output","cordis_inspect","cordis_mount","cordis_unmount","run_code","skill","snapshot_double","subagent","workflow"]},"reason":"fallback"}}
+{"type":"request/header","seq":14,"time":0,"data":{"header":{"config":{"model":"smoke-model"},"system":"{{system}}","tools":["bash","bash_kill","bash_output","cordis_inspect","cordis_mount","cordis_unmount","run_code","skill","snapshot_double","subagent","workflow"]},"reason":"change"}}
 {"type":"assistant/chunk","seq":15,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
 {"type":"assistant/chunk","seq":16,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-code","name":"run_code","argumentsDelta":"{\"code\": \"return await tools.snapshot_double({ value: 21 })\"}"}}}
 {"type":"assistant/chunk","seq":17,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-code","name":"run_code","arguments":"{\"code\": \"return await tools.snapshot_double({ value: 21 })\"}"}}}}
@@ -55,7 +55,7 @@
 {"type":"tool/result","seq":53,"time":0,"data":{"turn":1,"step":5,"callId":"advanced-unmount","content":[{"type":"text","text":"unmounted dyn-1 (plugin \"<anonymous>\")"}],"isError":false},"sourceEventSeqs":[52],"surfaceOp":"append"}
 {"type":"step/end","seq":54,"time":0,"data":{"turn":1,"step":5}}
 {"type":"step/start","seq":55,"time":0,"data":{"turn":1,"step":6}}
-{"type":"request/header-delta","seq":56,"time":0,"data":{"system":{"keepStart":62,"keepEnd":34,"insert":[]},"tools":{"added":[],"removed":["snapshot_double"],"changed":[]}}}
+{"type":"request/header","seq":56,"time":0,"data":{"header":{"config":{"model":"smoke-model"},"system":"{{system}}","tools":["bash","bash_kill","bash_output","cordis_inspect","cordis_mount","cordis_unmount","run_code","skill","subagent","workflow"]},"reason":"change"}}
 {"type":"assistant/chunk","seq":57,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
 {"type":"assistant/chunk","seq":58,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"text-delta","index":0,"text":"ADVANCED_EXECUTABLE_OK"}}}
 {"type":"assistant/chunk","seq":59,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"ADVANCED_EXECUTABLE_OK"}}}}

scripts/translation-pairing.manifest.json

@@ -11,13 +11,15 @@
     "docs/development.md",
     "docs/i18n/README.md",
     "docs/i18n/translation-rules.md",
-    "docs/rfc/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md",
-    "docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md",
+    ".agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md",
+    ".agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md",
     "python/README.md",
     "python/sdk-runtime/README.md",
     "python/sdk/README.md"
   ],
   "excluded": [
+    ".agents/notes/AGENTS.md",
+    ".agents/notes/implemented/AGENTS.md",
     "docs/AGENTS.md",
     "docs/config-catalog.md",
     "docs/cordis-catalog/",

scripts/translation-pairing.spec.ts

@@ -50,13 +50,13 @@ describe('date-based pairing frontier', () => {
   const cutoff = '2026-07-14'
 
   it('enforces the cutoff day and every later day, but not the preceding day', () => {
-    expect(requiresPairByDate('docs/rfc/2026-07-13-before.md', cutoff)).toBe(false)
-    expect(requiresPairByDate('docs/rfc/2026-07-14-at-cutoff.md', cutoff)).toBe(true)
-    expect(requiresPairByDate('docs/rfc/2026-07-15-after.md', cutoff)).toBe(true)
+    expect(requiresPairByDate('.agents/notes/2026-07-13-before.md', cutoff)).toBe(false)
+    expect(requiresPairByDate('.agents/notes/2026-07-14-at-cutoff.md', cutoff)).toBe(true)
+    expect(requiresPairByDate('.agents/notes/2026-07-15-after.md', cutoff)).toBe(true)
   })
 
   it('matches only a date at the start of the basename', () => {
-    expect(datedDocumentDate('docs/rfc/2026-07-14-proposal.md')).toBe('2026-07-14')
+    expect(datedDocumentDate('.agents/notes/2026-07-14-proposal.md')).toBe('2026-07-14')
     expect(datedDocumentDate('docs/release-notes-2026-07-14-alpha.md')).toBeUndefined()
     expect(requiresPairByDate('docs/release-notes-2026-07-14-alpha.md', cutoff)).toBe(false)
   })

scripts/type-equiv.manifest.json

@@ -1,19 +1,25 @@
 {
-  "comment": "Maps each ` ```ts type-equiv ` block (by doc + declared symbol) to the source symbol it must match verbatim. verify-type-equiv.ts enforces a 1:1 correspondence: every type-equiv block has exactly one entry here, and every entry resolves to exactly one block. Add an entry when you add a type-equiv block; remove it when you remove the block.",
+  "comment": "Maps each ` ```ts type-equiv ` or ` ```ts public-api ` block (by doc + declared symbol + projection) to the source declaration and original JSDoc it must match. Omit projection for the complete declaration; use public-api with a ` ```ts public-api ` block for a body-stripped public class declaration. verify-type-equiv.ts enforces a 1:1 correspondence: every source-equivalence block has exactly one entry here, and every entry resolves to exactly one block. Add an entry when you add a source-equivalence block; remove it when you remove the block.",
   "entries": [
     { "doc": "docs/core-data-structures/core.md", "symbol": "Branded", "source": "packages/util/brand/src/index.ts" },
     { "doc": "docs/core-data-structures/core.md", "symbol": "ContentBlockMap", "source": "packages/llm/llm/src/types.ts" },
+    { "doc": "docs/core-data-structures/core.md", "symbol": "AssistantProvenance", "source": "packages/llm/llm/src/types.ts" },
     { "doc": "docs/core-data-structures/core.md", "symbol": "Message", "source": "packages/llm/llm/src/types.ts" },
     { "doc": "docs/core-data-structures/core.md", "symbol": "MessageSourceMap", "source": "packages/llm/llm/src/types.ts" },
     { "doc": "docs/core-data-structures/core.md", "symbol": "FinishReasonMap", "source": "packages/llm/llm/src/types.ts" },
+    { "doc": "docs/core-data-structures/core.md", "symbol": "LlmProviderInfo", "source": "packages/llm/llm/src/types.ts" },
+    { "doc": "docs/core-data-structures/core.md", "symbol": "LlmModelInfo", "source": "packages/llm/llm/src/types.ts" },
     { "doc": "docs/core-data-structures/core.md", "symbol": "GenerateOptions", "source": "packages/llm/llm/src/types.ts" },
     { "doc": "docs/core-data-structures/core.md", "symbol": "ToolSchema", "source": "packages/llm/llm/src/types.ts" },
     { "doc": "docs/core-data-structures/core.md", "symbol": "LlmCallConfig", "source": "packages/llm/llm/src/call-config.ts" },
     { "doc": "docs/core-data-structures/core.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" },
+    { "doc": "docs/core-data-structures/core.md", "symbol": "InjectOptions", "source": "packages/core/agent/src/types.ts" },
     { "doc": "docs/core-data-structures/core.md", "symbol": "Agent", "source": "packages/core/agent/src/types.ts" },
     { "doc": "docs/core-data-structures/core.md", "symbol": "HookContext", "source": "packages/core/agent/src/types.ts" },
     { "doc": "docs/core-data-structures/core.md", "symbol": "PromptDecision", "source": "packages/core/agent/src/types.ts" },
     { "doc": "docs/core-data-structures/core.md", "symbol": "ContinuationDecision", "source": "packages/core/agent/src/types.ts" },
+    { "doc": "docs/core-data-structures/core.md", "symbol": "RequestError", "source": "packages/core/agent/src/types.ts" },
+    { "doc": "docs/core-data-structures/core.md", "symbol": "RequestErrorDecision", "source": "packages/core/agent/src/types.ts" },
     { "doc": "docs/core-data-structures/core.md", "symbol": "ContinuationStop", "source": "packages/core/agent/src/types.ts" },
     { "doc": "docs/core-data-structures/core.md", "symbol": "SessionStartSource", "source": "packages/core/agent/src/types.ts" },
 
@@ -29,7 +35,13 @@
     { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "TokenUsage", "source": "packages/llm/llm/src/types.ts" },
     { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "ContentBlockMap", "source": "packages/llm/llm/src/types.ts" },
     { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "AppIdentity", "source": "packages/llm/llm/src/attribution.ts" },
+    { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "BlockAssembler", "source": "packages/llm/llm/src/assembler.ts", "projection": "public-api" },
+    { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "LlmAdapter", "source": "packages/llm/llm/src/index.ts", "projection": "public-api" },
 
+    { "doc": "docs/core-data-structures/token-meter.md", "symbol": "TokenMeasurement", "source": "packages/llm/token-meter/src/types.ts" },
+    { "doc": "docs/core-data-structures/token-meter.md", "symbol": "TokenSurfaceNode", "source": "packages/llm/token-meter/src/types.ts" },
+
+    { "doc": "docs/core-data-structures/session.md", "symbol": "ContextEnvelope", "source": "packages/core/session/src/types.ts" },
     { "doc": "docs/core-data-structures/session.md", "symbol": "SessionEventMap", "source": "packages/core/session/src/types.ts" },
     { "doc": "docs/core-data-structures/session.md", "symbol": "EpochHeader", "source": "packages/core/session/src/types.ts" },
     { "doc": "docs/core-data-structures/session.md", "symbol": "TodoItem", "source": "packages/core/session/src/types.ts" },
@@ -39,19 +51,25 @@
     { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceEventType", "source": "packages/core/session/src/types.ts" },
     { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceOp", "source": "packages/core/session/src/types.ts" },
     { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceIntent", "source": "packages/core/session/src/types.ts" },
-    { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceNode", "source": "packages/core/session/src/surface.ts" },
+    { "doc": "docs/core-data-structures/session.md", "symbol": "SessionSurface", "source": "packages/core/session/src/surface.ts" },
     { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceFoldReplacement", "source": "packages/core/session/src/surface.ts" },
     { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceFoldResult", "source": "packages/core/session/src/surface.ts" },
+    { "doc": "docs/core-data-structures/session.md", "symbol": "Session", "source": "packages/core/session/src/index.ts", "projection": "public-api" },
 
     { "doc": "docs/core-data-structures/persistence.md", "symbol": "SessionHeader", "source": "packages/core/session/src/types.ts" },
     { "doc": "docs/core-data-structures/persistence.md", "symbol": "CreateSessionOptions", "source": "packages/core/session/src/types.ts" },
+    { "doc": "docs/core-data-structures/persistence.md", "symbol": "SessionLocation", "source": "packages/session-persistence/session-persistence/src/index.ts" },
 
     { "doc": "docs/core-data-structures/session-query.md", "symbol": "SessionEventSurface", "source": "packages/session-query/session-query/src/types.ts" },
     { "doc": "docs/core-data-structures/session-query.md", "symbol": "SessionRecord", "source": "packages/session-query/session-query/src/types.ts" },
     { "doc": "docs/core-data-structures/session-query.md", "symbol": "SessionEventRecord", "source": "packages/session-query/session-query/src/types.ts" },
+    { "doc": "docs/core-data-structures/session-query.md", "symbol": "SessionLineageNode", "source": "packages/session-query/session-query/src/types.ts" },
+    { "doc": "docs/core-data-structures/session-query.md", "symbol": "SessionLineageTrace", "source": "packages/session-query/session-query/src/types.ts" },
     { "doc": "docs/core-data-structures/session-query.md", "symbol": "SessionQueryErrorCode", "source": "packages/session-query/session-query/src/config.ts" },
     { "doc": "docs/core-data-structures/session-query.md", "symbol": "SessionEventReadRequest", "source": "packages/session-query/session-query/src/types.ts" },
     { "doc": "docs/core-data-structures/session-query.md", "symbol": "SessionEventWindow", "source": "packages/session-query/session-query/src/types.ts" },
+    { "doc": "docs/core-data-structures/session-query.md", "symbol": "SessionEventTraceRequest", "source": "packages/session-query/session-query/src/types.ts" },
+    { "doc": "docs/core-data-structures/session-query.md", "symbol": "SessionEventTrace", "source": "packages/session-query/session-query/src/types.ts" },
 
     { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolDefinition", "source": "packages/core/tools/src/index.ts" },
     { "doc": "docs/core-data-structures/tools.md", "symbol": "SchemaProp", "source": "packages/core/tools/src/schema.ts" },
@@ -60,6 +78,8 @@
     { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolExecutionToken", "source": "packages/core/tools/src/index.ts" },
     { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolExecutionInput", "source": "packages/core/tools/src/index.ts" },
     { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolExecution", "source": "packages/core/tools/src/index.ts" },
+    { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolExecutionMode", "source": "packages/core/tools/src/index.ts" },
+    { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolRunContext", "source": "packages/core/tools/src/index.ts" },
     { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolGuard", "source": "packages/core/tools/src/index.ts" },
     { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolRestriction", "source": "packages/core/tools/src/index.ts" },
     { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolExecutionResult", "source": "packages/core/tools/src/index.ts" },
@@ -83,6 +103,8 @@
     { "doc": "docs/core-data-structures/approval.md", "symbol": "ApprovalPolicy", "source": "packages/ui/user-approval/src/index.ts" },
     { "doc": "docs/core-data-structures/approval.md", "symbol": "ApprovalRequest", "source": "packages/ui/user-approval/src/index.ts" },
 
+    { "doc": "docs/core-data-structures/bash.md", "symbol": "DshEnvironmentKey", "source": "packages/bash/bash/src/types.ts" },
+    { "doc": "docs/core-data-structures/bash.md", "symbol": "DshEnvironment", "source": "packages/bash/bash/src/types.ts" },
     { "doc": "docs/core-data-structures/bash.md", "symbol": "BashExecRequest", "source": "packages/bash/bash/src/types.ts" },
     { "doc": "docs/core-data-structures/bash.md", "symbol": "BashExecSpec", "source": "packages/bash/bash/src/types.ts" },
     { "doc": "docs/core-data-structures/bash.md", "symbol": "BashRunResult", "source": "packages/bash/bash/src/types.ts" },
@@ -114,6 +136,7 @@
     { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsTargetKey", "source": "packages/fs/fs/src/types.ts" },
     { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsVersion", "source": "packages/fs/fs/src/types.ts" },
     { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsInfo", "source": "packages/fs/fs/src/types.ts" },
+    { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsPathInfo", "source": "packages/fs/fs/src/types.ts" },
     { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsDirEntry", "source": "packages/fs/fs/src/types.ts" },
     { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsWriteIntent", "source": "packages/fs/fs/src/types.ts" },
     { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsWriteOutcome", "source": "packages/fs/fs/src/types.ts" },
@@ -134,6 +157,7 @@
     { "doc": "docs/core-data-structures/skills.md", "symbol": "Config", "source": "packages/skill/skill/src/index.ts" },
 
     { "doc": "docs/core-data-structures/compaction.md", "symbol": "CompactionResult", "source": "packages/compact/compact/src/types.ts" },
+    { "doc": "docs/core-data-structures/compaction.md", "symbol": "CompactionTrigger", "source": "packages/compact/compact/src/index.ts" },
 
     { "doc": "docs/core-data-structures/subagent.md", "symbol": "SubagentCapabilities", "source": "packages/subagent/subagent/src/types.ts" },
     { "doc": "docs/core-data-structures/subagent.md", "symbol": "SubagentStartRequest", "source": "packages/subagent/subagent/src/types.ts" },
@@ -149,6 +173,12 @@
     { "doc": "docs/core-data-structures/web.md", "symbol": "WebFetchResult", "source": "packages/web/web/src/types.ts" },
     { "doc": "docs/core-data-structures/web.md", "symbol": "WebFetchBody", "source": "packages/web/web/src/types.ts" },
 
+    { "doc": "docs/core-data-structures/spill.md", "symbol": "SaveTextSpill", "source": "packages/spill/spill/src/types.ts" },
+    { "doc": "docs/core-data-structures/spill.md", "symbol": "SpillOwner", "source": "packages/spill/spill/src/types.ts" },
+    { "doc": "docs/core-data-structures/spill.md", "symbol": "SpillSource", "source": "packages/spill/spill/src/types.ts" },
+    { "doc": "docs/core-data-structures/spill.md", "symbol": "SpillRef", "source": "packages/spill/spill/src/types.ts" },
+    { "doc": "docs/core-data-structures/spill.md", "symbol": "SpillLocator", "source": "packages/spill/spill/src/types.ts" },
+
     { "doc": "docs/core-data-structures/workflow.md", "symbol": "WorkflowStartRequest", "source": "packages/workflow/workflow/src/types.ts" },
     { "doc": "docs/core-data-structures/workflow.md", "symbol": "WorkflowMeta", "source": "packages/workflow/workflow/src/types.ts" },
     { "doc": "docs/core-data-structures/workflow.md", "symbol": "WorkflowResult", "source": "packages/workflow/workflow/src/types.ts" },

scripts/verify-agent-note-classification.ts

@@ -0,0 +1,27 @@
+/**
+ * Enforce Agent Note lifecycle/class paths and dated filenames. Structural rules
+ * are shared with `agent-note-tree.ts`; the closed classification contract lives
+ * in `.agents/notes/README.md`.
+ */
+
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { walkAgentNoteTree } from './agent-note-tree.ts'
+
+const { notes, errors } = walkAgentNoteTree()
+
+// Keep the former homes unavailable so new notes cannot silently escape this tree.
+for (const legacyRoot of ['docs/rfc', 'docs/rfcs']) {
+  if (existsSync(resolve(import.meta.dirname, '..', legacyRoot))) {
+    errors.push(`legacy-path: ${legacyRoot}/ is forbidden — put Agent Notes under .agents/notes/`)
+  }
+}
+
+if (errors.length === 0) {
+  console.log(`verify-agent-note-classification: ${notes.length} Agent Note(s) checked, structure consistent.`)
+  process.exit(0)
+}
+
+console.error('verify-agent-note-classification: violations found:')
+for (const e of errors) console.error(`  ${e}`)
+process.exit(1)

scripts/verify-agent-note-format.ts

@@ -1,22 +1,22 @@
 /**
- * Enforce RFC headers, lifecycle-specific sections, alternatives, and retired
+ * Enforce Agent Note headers, lifecycle-specific sections, alternatives, and retired
  * marker rules. Classification and filenames belong to the sibling tree gate;
  * translation structure belongs to the pairing gate. Exact format and
- * grandfathering rules live in `docs/rfc/README.md`.
+ * grandfathering rules live in `.agents/notes/README.md`.
  */
 
 import { readFileSync } from 'node:fs'
 import { resolve } from 'node:path'
-import { rfcRoot, walkRfcTree } from './rfc-index.ts'
+import { agentNoteRoot, walkAgentNoteTree } from './agent-note-tree.ts'
 
 /** The date the format contract landed; the grandfather comment is valid only before it. */
 const FORMAT_ADOPTED = '2026-07-05'
 
-/** The exact comment a pre-format RFC carries in place of `## Alternatives considered`. */
-const GRANDFATHER = '<!-- rfc-format: alternatives-not-recorded (pre-format RFC) -->'
+/** The exact comment a pre-format Agent Note carries in place of `## Alternatives considered`. */
+const GRANDFATHER = '<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->'
 
 /** The retired debt marker that flagged pre-format bodies; banned so it cannot creep back. */
-const LEGACY_MARKER = 'XXX: legacy ADR/RFC body format'
+const LEGACY_MARKERS = ['XXX: legacy ADR/RFC body format', 'XXX: legacy ADR/Agent Note body format']
 
 /** Status-line grammar per lifecycle folder. */
 const STATUS: Record<string, RegExp> = {
@@ -35,13 +35,13 @@ const REQUIRED: Record<string, string[]> = {
 /** Headings banned in `implemented/` — proposal-era spec-speak per the slop checklist. */
 const BANNED_IMPLEMENTED = /^## (?:Proposal\b|Plan\b|Migration plan\b|Acceptance criteria\b)/i
 
-const { rfcs, errors } = walkRfcTree()
+const { notes, errors } = walkAgentNoteTree()
 
-for (const rfc of rfcs) {
+for (const note of notes) {
   const fail = (msg: string): void => {
-    errors.push(`format: ${rfc.rel} — ${msg}`)
+    errors.push(`format: ${note.rel} — ${msg}`)
   }
-  const lines = readFileSync(resolve(rfcRoot, rfc.rel), 'utf8').split('\n')
+  const lines = readFileSync(resolve(agentNoteRoot, note.rel), 'utf8').split('\n')
   // Format tokens inside fenced examples are not document structure.
   let inFence = false
   const prose = lines.filter((l) => {
@@ -52,11 +52,11 @@ for (const rfc of rfcs) {
     return !inFence
   })
 
-  if (!/^# RFC: \S/.test(lines[0] ?? '')) fail('line 1 must be `# RFC: <title>`')
+  if (!/^# Agent Note: \S/.test(lines[0] ?? '')) fail('line 1 must be `# Agent Note: <title>`')
   if (lines[1] !== '') fail('line 2 must be blank')
-  const status = STATUS[rfc.lifecycle]
+  const status = STATUS[note.lifecycle]
   if (status !== undefined && !status.test(lines[2] ?? '')) {
-    fail(`line 3 must match the ${rfc.lifecycle} status grammar (${String(status)})`)
+    fail(`line 3 must match the ${note.lifecycle} status grammar (${String(status)})`)
   }
   if (lines[3] !== '') fail('line 4 must be blank')
   const statusLines = prose.filter(l => l.startsWith('Status:') && l !== lines[2])
@@ -66,29 +66,29 @@ for (const rfc of rfcs) {
 
   const h2s = prose.filter(l => l.startsWith('## ')).map(l => l.trimEnd())
   if (h2s[0] !== '## Problem') fail(`the first section must be \`## Problem\` (got ${JSON.stringify(h2s[0] ?? '<none>')})`)
-  for (const required of REQUIRED[rfc.lifecycle] ?? []) {
+  for (const required of REQUIRED[note.lifecycle] ?? []) {
     if (!h2s.includes(required)) fail(`missing the required \`${required}\` section`)
   }
-  if (rfc.lifecycle === 'implemented') {
+  if (note.lifecycle === 'implemented') {
     for (const h2 of h2s.filter(h => BANNED_IMPLEMENTED.test(h))) {
-      fail(`\`${h2}\` is a proposal-era heading; an implemented RFC states what is (fold it into Decision/Consequences/Testing)`)
+      fail(`\`${h2}\` is a proposal-era heading; an implemented Agent Note states what is (fold it into Decision/Consequences/Testing)`)
     }
   }
 
   const hasSection = h2s.includes('## Alternatives considered')
   const hasGrandfather = prose.includes(GRANDFATHER)
   if (hasSection && hasGrandfather) fail('carries both `## Alternatives considered` and the grandfather comment — drop the comment')
-  if (!hasSection && !hasGrandfather) fail('missing `## Alternatives considered` (a pre-format RFC whose alternatives are not reconstructible carries the grandfather comment instead — see docs/rfc/README.md § The file format)')
-  if (hasGrandfather && rfc.date >= FORMAT_ADOPTED) fail(`the grandfather comment is only valid for RFCs dated before ${FORMAT_ADOPTED}`)
+  if (!hasSection && !hasGrandfather) fail('missing `## Alternatives considered` (a pre-format Agent Note whose alternatives are not reconstructible carries the grandfather comment instead — see .agents/notes/README.md § The file format)')
+  if (hasGrandfather && note.date >= FORMAT_ADOPTED) fail(`the grandfather comment is only valid for Agent Notes dated before ${FORMAT_ADOPTED}`)
 
-  if (prose.some(l => l.includes(LEGACY_MARKER))) fail('carries the retired legacy-format debt marker')
+  if (prose.some(line => LEGACY_MARKERS.some(marker => line.includes(marker)))) fail('carries the retired legacy-format debt marker')
 }
 
 if (errors.length === 0) {
-  console.log(`verify-rfc-format: ${rfcs.length} RFC(s) checked, all conform to docs/rfc/README.md § The file format.`)
+  console.log(`verify-agent-note-format: ${notes.length} Agent Note(s) checked, all conform to .agents/notes/README.md § The file format.`)
   process.exit(0)
 }
 
-console.error('verify-rfc-format: violations found:')
+console.error('verify-agent-note-format: violations found:')
 for (const e of errors) console.error(`  ${e}`)
 process.exit(1)

scripts/verify-cordis-config.ts

@@ -1,18 +1,32 @@
 /**
- * Reject JavaScript expressions in Cordis Loader entry metadata.
+ * Validate Cordis Loader entry metadata and example package resolution.
  *
  * The Loader interpolates only a plugin entry's `config`; expression objects in
  * fields such as `disabled` remain truthy data and silently change composition.
+ * Example configs run from built packages, so every named package must resolve
+ * from the examples workspace and every local package must be in the root
+ * TypeScript project graph.
  */
 
 import { globSync, readFileSync } from 'node:fs'
-import { resolve } from 'node:path'
+import { dirname, relative, resolve } from 'node:path'
 import * as yaml from 'js-yaml'
+import ts from 'typescript'
 
 interface JsExpr {
   __jsExpr: string
 }
 
+interface PackageManifest {
+  name?: string
+  dependencies?: Record<string, string>
+}
+
+interface PluginReference {
+  file: string
+  name: string
+}
+
 const root = resolve(import.meta.dirname, '..')
 const metadataFields = ['id', 'name', 'group', 'disabled', 'inject', 'intercept', 'isolate'] as const
 const jsExprType = new yaml.Type('tag:yaml.org,2002:js', {
@@ -30,6 +44,7 @@ const files = globSync(['**/*cordis*.yml', '**/*cordis*.yaml'], {
   exclude: ['.claude/**', 'node_modules/**', 'vendor/**'],
 }).sort()
 const errors: string[] = []
+const examplePluginReferences: PluginReference[] = []
 
 for (const file of files) {
   const document: unknown = yaml.load(readFileSync(resolve(root, file), 'utf8'), { schema })
@@ -42,8 +57,10 @@ for (const file of files) {
   }
 }
 
+errors.push(...validateExampleResolution())
+
 if (errors.length > 0) {
-  console.error('verify-cordis-config: Loader entry metadata is static; move !!js under plugin config or select an explicit overlay.')
+  console.error('verify-cordis-config: invalid Loader metadata or example package resolution:')
   for (const error of errors) console.error(`- ${error}`)
   process.exitCode = 1
 } else {
@@ -55,6 +72,7 @@ function validateEntry(value: unknown, file: string, path: string): void {
     errors.push(`${file}${path}: entry must be an object`)
     return
   }
+  recordExamplePlugin(value, file)
   validateMetadata(value, file, path)
   if ((value.group === true || value.name === '@cordisjs/plugin-group') && isUnknownArray(value.config)) {
     for (let index = 0; index < value.config.length; index++) {
@@ -68,6 +86,7 @@ function validateEntry(value: unknown, file: string, path: string): void {
     const patch = config.patches[index]
     const patchPath = `${path}.config.patches[${index}]`
     if (!isRecord(patch)) continue
+    recordExamplePlugin(patch, file)
     validateMetadata(patch, file, patchPath)
     if (!isUnknownArray(patch.insert)) continue
     for (let insertIndex = 0; insertIndex < patch.insert.length; insertIndex++) {
@@ -76,6 +95,83 @@ function validateEntry(value: unknown, file: string, path: string): void {
   }
 }
 
+function recordExamplePlugin(entry: Record<string, unknown>, file: string): void {
+  if (file.startsWith('examples/') && typeof entry.name === 'string') {
+    examplePluginReferences.push({ file, name: entry.name })
+  }
+}
+
+function validateExampleResolution(): string[] {
+  const violations: string[] = []
+  const exampleManifest = readManifest('examples/package.json')
+  const dependencies = exampleManifest.dependencies ?? {}
+  const localPackages = localPackageDirectories()
+  const rootReferences = rootProjectReferences()
+  const requiredPackages = new Map<string, Set<string>>()
+
+  for (const reference of examplePluginReferences) {
+    const packageName = packageNameFromSpecifier(reference.name)
+    if (packageName === undefined) continue
+    const locations = requiredPackages.get(packageName) ?? new Set<string>()
+    locations.add(reference.file)
+    requiredPackages.set(packageName, locations)
+  }
+
+  for (const [packageName, locations] of requiredPackages) {
+    if (!(packageName in dependencies)) {
+      violations.push(`${[...locations].join(', ')}: ${packageName} must be declared in examples/package.json dependencies`)
+    }
+  }
+
+  const localExamplePackages = new Set([
+    ...Object.keys(dependencies),
+    ...requiredPackages.keys(),
+  ])
+  for (const packageName of localExamplePackages) {
+    const packageDirectory = localPackages.get(packageName)
+    if (packageDirectory === undefined || rootReferences.has(packageDirectory)) continue
+    const repoPath = relative(root, packageDirectory).replaceAll('\\', '/')
+    violations.push(`tsconfig.json: missing project reference for ${packageName} (${repoPath})`)
+  }
+
+  return violations
+}
+
+function readManifest(path: string): PackageManifest {
+  return JSON.parse(readFileSync(resolve(root, path), 'utf8')) as PackageManifest
+}
+
+function localPackageDirectories(): Map<string, string> {
+  const manifests = globSync(['packages/*/*/package.json', 'vendor/*/package.json'], { cwd: root })
+  const packages = new Map<string, string>()
+  for (const manifestPath of manifests) {
+    const manifest = readManifest(manifestPath)
+    if (manifest.name !== undefined) packages.set(manifest.name, resolve(root, dirname(manifestPath)))
+  }
+  return packages
+}
+
+function rootProjectReferences(): Set<string> {
+  const config = ts.readConfigFile(resolve(root, 'tsconfig.json'), path => ts.sys.readFile(path))
+  if (config.error !== undefined) {
+    throw new Error(ts.flattenDiagnosticMessageText(config.error.messageText, '\n'))
+  }
+  const references = (config.config as { references?: Array<{ path?: unknown }> }).references ?? []
+  return new Set(references.flatMap((reference) => {
+    if (typeof reference.path !== 'string') return []
+    return [resolve(root, reference.path)]
+  }))
+}
+
+function packageNameFromSpecifier(specifier: string): string | undefined {
+  if (specifier.startsWith('.') || specifier.startsWith('/') || specifier.startsWith('file:')) return undefined
+  const segments = specifier.split('/')
+  if (specifier.startsWith('@')) {
+    return segments.length >= 2 ? `${segments[0]}/${segments[1]}` : undefined
+  }
+  return segments[0] || undefined
+}
+
 function validateMetadata(entry: Record<string, unknown>, file: string, path: string): void {
   for (const field of metadataFields) {
     if (!(field in entry)) continue

scripts/verify-doc-refs.ts

@@ -1,7 +1,8 @@
 /**
- * Verify root-relative `docs/*.md` tokens in repo-authored TypeScript. The
- * textual scan requires the extension, checks matching string literals too,
- * and excludes built declarations and vendored source.
+ * Verify root-relative documentation paths in repo-authored TypeScript. The
+ * textual scan covers `docs/*.md` and `.agents/notes/*.md`, requires the
+ * extension, checks matching string literals too, and excludes built
+ * declarations and vendored source.
  */
 
 import { existsSync } from 'node:fs'
@@ -18,9 +19,9 @@ const isExcluded = (p: string): boolean =>
   p.includes('/lib/') || p.endsWith('.d.ts') || p.startsWith('vendor/')
 
 /** Root-relative Markdown path token, excluding trailing prose. */
-const DOC_REF = /\bdocs\/[A-Za-z0-9._/-]+\.md/g
+const DOC_REF = /(?:\bdocs|\.agents\/notes)\/[A-Za-z0-9._/-]+\.md/g
 
-/** Find every broken `docs/….md` reference in one TypeScript file. */
+/** Find every broken root-relative documentation reference in one TypeScript file. */
 function findViolations(absPath: string): Violation[] {
   return findReferenceViolations(root, absPath, DOC_REF, ref => ref, ref => !existsSync(resolve(root, ref)))
 }
@@ -30,11 +31,11 @@ const all = files.flatMap(file => findViolations(file.abs))
 const checked = files.length
 
 if (all.length === 0) {
-  console.log(`verify-doc-refs: ${checked} file(s) checked, all docs/*.md references resolve.`)
+  console.log(`verify-doc-refs: ${checked} file(s) checked, all documentation references resolve.`)
   process.exit(0)
 }
 
-console.error('verify-doc-refs: broken docs/*.md references found in source comments (target does not exist):')
+console.error('verify-doc-refs: broken documentation references found in source comments (target does not exist):')
 for (const v of all) {
   console.error(`  ${v.file}:${v.line}  ${v.ref}`)
 }

scripts/verify-md-links.ts

@@ -17,6 +17,7 @@ const root = resolve(import.meta.dirname, '..')
 const PATTERNS = [
   'README.md',
   'README.zh.md',
+  '.agents/notes/**/*.md',
   'docs/**/*.md',
   'packages/*/*.md',
   'packages/*/*/*.md',

scripts/verify-md-wrap.ts

@@ -13,15 +13,16 @@ import { uniqueRepoFiles } from './repo-files.ts'
 
 const root = resolve(import.meta.dirname, '..')
 
-/** Files to check: doc-typecheck's scope, prompt goldens, and the AGENTS.md pair. */
+/** Files to check: doc-typecheck's scope, system-prompt expected outputs, and the AGENTS.md pair. */
 const PATTERNS = [
   'README.md',
   'README.zh.md',
+  '.agents/notes/**/*.md',
   'docs/**/*.md',
   'packages/*/*.md',
   'packages/*/*/*.md',
-  'examples/**/system-prompt.golden.md',
-  'packages/**/system-prompt.golden.md',
+  'examples/**/system-prompt.expected.md',
+  'packages/**/system-prompt.expected.md',
   'AGENTS.md',
   'packages/AGENTS.md',
 ]

scripts/verify-mermaid.ts

@@ -17,6 +17,7 @@ const root = resolve(import.meta.dirname, '..')
 const PATTERNS = [
   'README.md',
   'README.zh.md',
+  '.agents/notes/**/*.md',
   'docs/**/*.md',
   'packages/*/*.md',
   'packages/*/*/*.md',

scripts/verify-package-paths.ts

@@ -14,6 +14,7 @@ const root = resolve(import.meta.dirname, '..')
 /** Markdown + repo-authored TypeScript that may cite package paths. */
 const PATTERNS = [
   'README.md',
+  '.agents/notes/**/*.md',
   'docs/**/*.md',
   'packages/*/*.md',
   'packages/*/*/*.md',

scripts/verify-package-readme-limitations.ts

@@ -2,7 +2,7 @@
  * Doc-sync gate for the canonical package-README limitations section. It scans
  * package manifests, rejects missing or variant sections, and requires one
  * top-level bullet; audited packages in {@link NO_LIMITATIONS} must omit it.
- * See the [limitations RFC](../docs/rfc/implemented/process/2026-07-10-readme-known-limitations-gate.md).
+ * See the [limitations Agent Note](../.agents/notes/implemented/process/2026-07-10-readme-known-limitations-gate.md).
  */
 
 import { existsSync, globSync, readFileSync } from 'node:fs'

scripts/verify-package-readme-model-experience.ts

@@ -1,8 +1,8 @@
 /**
  * Doc-sync gate for package README Model Experience sections. It validates
- * audited package classifications, context-surface fields, package-owned text
- * blocks, generated-catalog links, and final-section order. See the
- * [Model Experience RFC](../docs/rfc/implemented/process/2026-07-12-package-model-experience-contract.md).
+ * audited package classifications, model/token/KV-cache fields, package-owned
+ * text blocks, generated-catalog links, and final-section order. See the
+ * [Model Experience Agent Note](../.agents/notes/implemented/process/2026-07-12-package-model-experience-contract.md).
  */
 
 import { existsSync, globSync, readFileSync } from 'node:fs'
@@ -12,8 +12,10 @@ import { markdownHeadingLines, markdownProseLines, type MarkdownProseLine } from
 const root = resolve(import.meta.dirname, '..')
 const HEADING = '## Model Experience'
 const LIMITATIONS_HEADING = '## Known Limitations and Deferred Work'
-const MODEL_VIEW_LABEL = '**What the model sees**'
-const TOKEN_EFFECT_LABEL = '**Token effect**'
+const MODEL_VIEW_HEADING = '#### What the model sees'
+const TOKEN_EFFECT_HEADING = '#### Token effect'
+const KV_CACHE_EFFECT_HEADING = '#### KV Cache effect'
+const FIELD_HEADINGS = [MODEL_VIEW_HEADING, TOKEN_EFFECT_HEADING, KV_CACHE_EFFECT_HEADING] as const
 
 type SentenceKind = 'none' | 'indirect'
 
@@ -30,12 +32,13 @@ interface SentenceContract {
 const NO_MODEL_EXPERIENCE_SECTION: Readonly<Record<string, string>> = {
   'packages/core/scope': 'The package is a model-agnostic registration and lifecycle primitive; model-facing consumers own any context selection.',
   'packages/util/brand': 'The package is a type-only primitive erased at compile time.',
+  'packages/util/paths': 'The package only resolves harness-owned host paths; model-facing consumers own any rendered use.',
 }
 
 /**
- * Packages whose Model Experience is simple enough for one gated sentence.
- * Every other package must carry canonical context-surface blocks. A package
- * moves on or off this list with the change to its context behavior.
+ * Packages whose Model Experience is simple enough for one gated sentence plus
+ * a KV-cache field. Every other package must carry canonical context-surface
+ * blocks. A package moves on or off this list with its context behavior.
  */
 const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/bash/bash': { kind: 'indirect', reason: 'The service interface delegates all model rendering to dsh-tool-bash.' },
@@ -48,28 +51,34 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/fs/fs-sandbox': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-fs.' },
   'packages/hooks/hook-protocol': { kind: 'indirect', reason: 'Only the hook bridge plugins render decoded hook output to a model.' },
   'packages/llm/llm': { kind: 'none', reason: 'The adapter registry forwards already-assembled requests unchanged.' },
+  'packages/llm/token-meter': { kind: 'indirect', reason: 'The measurement service leaves model-visible changes to its consumers.' },
   'packages/sandbox/sandbox-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-bash-sandbox and dsh-tool-bash.' },
   'packages/sandbox/sandbox-policy': { kind: 'indirect', reason: 'The policy service holds the mode dsh-tool-bash and dsh-tool-fs render in their denial markers.' },
   'packages/sdk/create-sdk': { kind: 'indirect', reason: 'The initializer only writes project files; selected runtime plugins provide the generated project model surface.' },
   'packages/sdk/helper': { kind: 'none', reason: 'The project domain edits files and registers no live agent or model surface.' },
   'packages/sdk/scripts': { kind: 'indirect', reason: 'The launcher delegates model context to the loaded project plugin tree.' },
+  'packages/sdk/telemetry': { kind: 'none', reason: 'The launcher-side reporter sends developer-cycle telemetry and registers no live agent or model surface.' },
   'packages/session-query/session-query': { kind: 'none', reason: 'The trusted query service exposes cloned records only to callers and registers no model surface.' },
   'packages/skill/skill': { kind: 'indirect', reason: 'The provider registry delegates model rendering to dsh-tool-skill.' },
   'packages/skill/skill-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-skill.' },
+  'packages/spill/spill': { kind: 'indirect', reason: 'The storage seam delegates model rendering to spill consumers.' },
+  'packages/spill/spill-local': { kind: 'indirect', reason: 'The storage backend delegates model rendering to spill consumers.' },
   'packages/subagent/subagent': { kind: 'indirect', reason: 'The provider registry delegates parent-model rendering to dsh-tool-subagent.' },
   'packages/subagent/subagent-subprocess': { kind: 'indirect', reason: 'Only process-based subagent backends compose a child model request.' },
   'packages/support/acp-snapshot': { kind: 'none', reason: 'The test harness observes and normalizes transcripts without changing live requests.' },
+  'packages/support/agent-loop-testkit': { kind: 'none', reason: 'The test helper mounts services but neither drives nor modifies model requests.' },
   'packages/support/invariants': { kind: 'none', reason: 'The observer validates requests but never rewrites their context.' },
   'packages/support/loader-smoke': { kind: 'none', reason: 'The test harness observes child-process streams without changing live requests.' },
   'packages/support/llm-replay': { kind: 'none', reason: 'The keyless adapter invokes no provider model.' },
-  'packages/support/subagent-mock': { kind: 'indirect', reason: 'Only dsh-tool-subagent renders its configured test outcome.' },
   'packages/tasks/tasks': { kind: 'indirect', reason: 'Producer and control-surface plugins own all model rendering over the task registry.' },
   'packages/examples/acp-demo': { kind: 'indirect', reason: 'The app bundle delegates request composition to dsh-agent-spine-demo and dsh-acp.' },
   'packages/ui/app-boot': { kind: 'indirect', reason: 'Only the loaded plugin tree contributes model context.' },
   'packages/examples/jsonrpc-demo': { kind: 'indirect', reason: 'Only the externally configured plugin tree contributes model context.' },
   'packages/ui/permission': { kind: 'indirect', reason: 'The service writes mechanism events rendered by dsh-user-approval and dsh-tool-bash.' },
   'packages/ui/user-interaction': { kind: 'indirect', reason: 'Model-facing consumers render provider answers and seam errors.' },
+  'packages/util/home': { kind: 'indirect', reason: 'Only dsh-tool-bash exposes the resolved home to model commands.' },
   'packages/util/timeout': { kind: 'indirect', reason: 'Only timeout consumers render timeout outcomes.' },
+  'packages/util/retention': { kind: 'indirect', reason: 'Only retention consumers render retained content and omission metadata.' },
   'packages/web/web': { kind: 'indirect', reason: 'The provider registry delegates model rendering to dsh-tool-web.' },
   'packages/web/web-fetch-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-web.' },
   'packages/web/web-search-exa': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-web.' },
@@ -87,35 +96,41 @@ interface ContextSurface {
   heading: Line
   modelView: Line
   tokenEffect: Line
+  kvCacheEffect: Line
   title: string
+  modelViewVerbatimBlocks: number
   verbatimBlocks: number
 }
 
-/** Validate H4-plus-markdown literals nested after one context surface's fields. */
-function validateNestedVerbatim(raw: readonly string[]): { blocks: number; error?: string } {
+interface ParsedField {
+  value: Line
+  verbatimBlocks: number
+}
+
+/** Validate H5-plus-markdown literals nested under one Model Experience field. */
+function validateNestedVerbatim(raw: readonly string[], fragments: Set<string>): { blocks: number; error?: string } {
   let cursor = 0
   while (raw[cursor]?.trim().length === 0) cursor += 1
   if (cursor === raw.length) return { blocks: 0 }
 
   let blocks = 0
-  const fragments = new Set<string>()
   while (true) {
     while (raw[cursor]?.trim().length === 0) cursor += 1
     if (cursor === raw.length) break
-    if (!/^#### \S/.test(raw[cursor] ?? '')) {
-      return { blocks, error: 'content after Token effect must be a titled H4 verbatim block' }
+    if (!/^##### \S/.test(raw[cursor] ?? '')) {
+      return { blocks, error: 'content after a field paragraph must be a titled H5 verbatim block' }
     }
-    const title = (raw[cursor] as string).slice('#### '.length)
+    const title = (raw[cursor] as string).slice('##### '.length)
     const fragment = headingFragment(title)
-    if (fragment.length === 0) return { blocks, error: 'verbatim H4 title must be non-empty' }
+    if (fragment.length === 0) return { blocks, error: 'verbatim H5 title must be non-empty' }
     if (fragments.has(fragment)) {
-      return { blocks, error: `verbatim H4 title ${JSON.stringify(title)} is duplicated within its context surface` }
+      return { blocks, error: `verbatim H5 title ${JSON.stringify(title)} is duplicated within its context surface` }
     }
     fragments.add(fragment)
     cursor += 1
     while (raw[cursor]?.trim().length === 0) cursor += 1
     if (raw[cursor] !== '```markdown') {
-      return { blocks, error: 'each nested verbatim H4 requires an exact ```markdown fence' }
+      return { blocks, error: 'each nested verbatim H5 requires an exact ```markdown fence' }
     }
     cursor += 1
     const contentStart = cursor
@@ -128,7 +143,7 @@ function validateNestedVerbatim(raw: readonly string[]): { blocks: number; error
   return { blocks }
 }
 
-/** GitHub-style fragment for the simple ASCII H4 titles allowed by this contract. */
+/** GitHub-style fragment for the simple ASCII nested titles allowed by this contract. */
 function headingFragment(title: string): string {
   return title.toLowerCase().replaceAll('`', '').replaceAll(/[^a-z0-9 _-]/g, '').trim().replaceAll(/\s+/g, '-')
 }
@@ -161,6 +176,7 @@ let indirectCount = 0
 let verbatimBlockCount = 0
 let systemPromptSurfaceCount = 0
 let toolSchemaSurfaceCount = 0
+let kvCacheEffectCount = 0
 
 for (const [pkg, reason] of Object.entries(NO_MODEL_EXPERIENCE_SECTION)) {
   if (!scannedPackages.has(pkg)) {
@@ -254,13 +270,31 @@ for (const packageJson of packageJsons) {
   if (sentenceContract !== undefined) {
     const pattern = sentenceContract.kind === 'none' ? /^None, as .+\.$/ : /^Indirectly, through .+\.$/
     const rawContent = rawSection.filter(line => line.trim().length > 0)
-    if (content.length !== 1 || rawContent.length !== 1 || !pattern.test(content[0]?.raw ?? '')) {
+    const sentence = content[0]
+    const kvCacheHeading = content[1]
+    const kvCacheEffect = content[2]
+    if (content.length !== 3 || rawContent.length !== 3 || !pattern.test(sentence?.raw ?? '')) {
       const prefix = sentenceContract.kind === 'none' ? 'None, as ' : 'Indirectly, through '
-      failures.push({ path: readme, message: `must contain exactly one sentence beginning ${JSON.stringify(prefix)} and ending with a period` })
+      failures.push({ path: readme, message: `must contain exactly one sentence beginning ${JSON.stringify(prefix)} and ending with a period, followed by ${KV_CACHE_EFFECT_HEADING} and one non-empty paragraph` })
+      continue
+    }
+    if (kvCacheHeading?.raw !== KV_CACHE_EFFECT_HEADING
+      || kvCacheEffect === undefined
+      || /^#{1,6} /.test(kvCacheEffect.raw)
+      || kvCacheEffect.raw.trim().length === 0) {
+      failures.push({ path: readme, message: `line ${kvCacheHeading?.index ?? sentence?.index ?? modelHeading.index}: short Model Experience form requires exact ${KV_CACHE_EFFECT_HEADING} and one non-empty paragraph` })
+      continue
+    }
+    if (sentence === undefined
+      || sentence.index !== modelHeading.index + 2
+      || kvCacheHeading.index !== sentence.index + 2
+      || kvCacheEffect.index !== kvCacheHeading.index + 2) {
+      failures.push({ path: readme, message: 'short Model Experience sentence, KV-cache H4, and paragraph require one blank line between each element' })
       continue
     }
     if (sentenceContract.kind === 'none') explainedNoneCount += 1
     else indirectCount += 1
+    kvCacheEffectCount += 1
     continue
   }
 
@@ -286,8 +320,6 @@ for (const packageJson of packageJsons) {
     const end = surfaceStarts[surfaceIndex + 1]?.index ?? content.length
     const entries = content.slice(start.index, end)
     const heading = entries[0] as Line
-    const modelView = entries[1]
-    const tokenEffect = entries[2]
     const title = heading.raw.slice('### '.length)
     const fragment = headingFragment(title)
     if (fragment.length === 0) {
@@ -300,56 +332,100 @@ for (const packageJson of packageJsons) {
       surfaceError = true
       break
     }
-    if (modelView === undefined || !modelView.raw.startsWith(`${MODEL_VIEW_LABEL}: `) || modelView.raw.slice(`${MODEL_VIEW_LABEL}: `.length).trim().length === 0) {
-      failures.push({ path: readme, message: `line ${modelView?.index ?? heading.index}: context surface requires non-empty ${MODEL_VIEW_LABEL}: text` })
-      surfaceError = true
-      break
-    }
-    if (tokenEffect === undefined || !tokenEffect.raw.startsWith(`${TOKEN_EFFECT_LABEL}: `) || tokenEffect.raw.slice(`${TOKEN_EFFECT_LABEL}: `.length).trim().length === 0) {
-      failures.push({ path: readme, message: `line ${tokenEffect?.index ?? heading.index}: context surface requires non-empty ${TOKEN_EFFECT_LABEL}: text` })
+    const fieldStarts = entries
+      .map((line, index) => ({ line, index }))
+      .filter(entry => /^#### \S/.test(entry.line.raw))
+    if (fieldStarts.length !== FIELD_HEADINGS.length || fieldStarts[0]?.index !== 1) {
+      failures.push({ path: readme, message: `line ${heading.index}: context surface requires exactly three ordered H4 fields: ${FIELD_HEADINGS.join(', ')}` })
       surfaceError = true
       break
     }
     if ((surfaceIndex === 0 && heading.index !== modelHeading.index + 2)
       || rawLines[heading.index - 2]?.trim().length !== 0
-      || modelView.index !== heading.index + 2
-      || tokenEffect.index !== modelView.index + 2) {
-      failures.push({ path: readme, message: `line ${heading.index}: context-surface heading and fields require one blank line between each element` })
+      || fieldStarts[0].line.index !== heading.index + 2) {
+      failures.push({ path: readme, message: `line ${heading.index}: context-surface heading and first field require one blank line between them` })
       surfaceError = true
       break
     }
-    const unexpected = entries.slice(3).find(line => !/^#### \S/.test(line.raw))
-    if (unexpected !== undefined) {
-      failures.push({ path: readme, message: `line ${unexpected.index}: content after ${TOKEN_EFFECT_LABEL} must be a titled H4 plus \`markdown\` fence inside this context surface` })
-      surfaceError = true
-      break
+    const parsedFields: ParsedField[] = []
+    const verbatimFragments = new Set<string>()
+    for (let fieldIndex = 0; fieldIndex < FIELD_HEADINGS.length; fieldIndex += 1) {
+      const fieldStart = fieldStarts[fieldIndex] as { line: Line; index: number }
+      const expectedHeading = FIELD_HEADINGS[fieldIndex] as string
+      if (fieldStart.line.raw !== expectedHeading) {
+        failures.push({ path: readme, message: `line ${fieldStart.line.index}: expected exact field heading ${JSON.stringify(expectedHeading)}, found ${JSON.stringify(fieldStart.line.raw)}` })
+        surfaceError = true
+        break
+      }
+      const fieldEnd = fieldStarts[fieldIndex + 1]?.index ?? entries.length
+      const fieldEntries = entries.slice(fieldStart.index, fieldEnd)
+      const value = fieldEntries[1]
+      if (value === undefined || /^#{1,6} /.test(value.raw) || value.raw.trim().length === 0) {
+        failures.push({ path: readme, message: `line ${fieldStart.line.index}: ${expectedHeading} requires one non-empty paragraph` })
+        surfaceError = true
+        break
+      }
+      if (value.index !== fieldStart.line.index + 2) {
+        failures.push({ path: readme, message: `line ${fieldStart.line.index}: ${expectedHeading} and its paragraph require one blank line between them` })
+        surfaceError = true
+        break
+      }
+      const unexpected = fieldEntries.slice(2).find(line => !/^##### \S/.test(line.raw))
+      if (unexpected !== undefined) {
+        failures.push({ path: readme, message: `line ${unexpected.index}: content after ${expectedHeading} paragraph must be a titled H5 plus \`markdown\` fence owned by that field` })
+        surfaceError = true
+        break
+      }
+      const nextHeadingLine = fieldStarts[fieldIndex + 1]?.line.index
+        ?? surfaceStarts[surfaceIndex + 1]?.line.index
+        ?? nextH2Line
+      if (rawLines[nextHeadingLine - 2]?.trim().length !== 0) {
+        failures.push({ path: readme, message: `line ${nextHeadingLine}: Model Experience headings require a preceding blank line` })
+        surfaceError = true
+        break
+      }
+      const verbatim = validateNestedVerbatim(rawLines.slice(value.index, nextHeadingLine - 1), verbatimFragments)
+      if (verbatim.error !== undefined) {
+        failures.push({ path: readme, message: `line ${value.index}: ${verbatim.error}` })
+        surfaceError = true
+        break
+      }
+      if (fieldEntries.length - 2 !== verbatim.blocks) {
+        failures.push({ path: readme, message: `line ${value.index}: every nested H5 must own exactly one \`markdown\` fence` })
+        surfaceError = true
+        break
+      }
+      parsedFields.push({ value, verbatimBlocks: verbatim.blocks })
     }
-    const nextHeadingLine = surfaceStarts[surfaceIndex + 1]?.line.index ?? nextH2Line
-    const verbatim = validateNestedVerbatim(rawLines.slice(tokenEffect.index, nextHeadingLine - 1))
-    if (verbatim.error !== undefined) {
-      failures.push({ path: readme, message: `line ${tokenEffect.index}: ${verbatim.error}` })
-      surfaceError = true
-      break
-    }
-    if (entries.length - 3 !== verbatim.blocks) {
-      failures.push({ path: readme, message: `line ${tokenEffect.index}: every nested H4 must own exactly one \`markdown\` fence` })
-      surfaceError = true
-      break
-    }
-    if (/\]\(#[^)]+\)/.test(modelView.raw) || /\]\(#[^)]+\)/.test(tokenEffect.raw)) {
-      failures.push({ path: readme, message: `line ${heading.index}: Model Experience fields must not link between local subsections; nest the H4 in its owning H3` })
+    if (surfaceError) break
+    const modelViewField = parsedFields[0] as ParsedField
+    const tokenEffectField = parsedFields[1] as ParsedField
+    const kvCacheEffectField = parsedFields[2] as ParsedField
+    const modelView = modelViewField.value
+    const tokenEffect = tokenEffectField.value
+    const kvCacheEffect = kvCacheEffectField.value
+    if (/\]\(#[^)]+\)/.test(modelView.raw) || /\]\(#[^)]+\)/.test(tokenEffect.raw) || /\]\(#[^)]+\)/.test(kvCacheEffect.raw)) {
+      failures.push({ path: readme, message: `line ${heading.index}: Model Experience fields must not link between local subsections; nest the H5 in its owning H4 field` })
       surfaceError = true
       break
     }
     surfaceFragments.add(fragment)
-    surfaces.push({ heading, modelView, tokenEffect, title, verbatimBlocks: verbatim.blocks })
+    surfaces.push({
+      heading,
+      modelView,
+      tokenEffect,
+      kvCacheEffect,
+      title,
+      modelViewVerbatimBlocks: modelViewField.verbatimBlocks,
+      verbatimBlocks: parsedFields.reduce((total, field) => total + field.verbatimBlocks, 0),
+    })
   }
   if (surfaceError) continue
 
   const promptWithoutVerbatim = surfaces.find(surface => isDirectSystemPromptSurface(surface.title)
-    && surface.verbatimBlocks === 0)
+    && surface.modelViewVerbatimBlocks === 0)
   if (promptWithoutVerbatim !== undefined) {
-    failures.push({ path: readme, message: `line ${promptWithoutVerbatim.heading.index}: system-prompt surface must contain a titled H4 plus verbatim \`markdown\` block` })
+    failures.push({ path: readme, message: `line ${promptWithoutVerbatim.heading.index}: system-prompt surface must contain a titled H5 plus verbatim \`markdown\` block under ${MODEL_VIEW_HEADING}` })
     continue
   }
   const hasConcreteLiteral = surfaces.some(surface => surface.verbatimBlocks > 0
@@ -381,11 +457,12 @@ for (const packageJson of packageJsons) {
   contextSurfaceCount += surfaces.length
   systemPromptSurfaceCount += surfaces.filter(surface => isDirectSystemPromptSurface(surface.title)).length
   toolSchemaSurfaceCount += surfaces.filter(surface => /\bschemas?\b/i.test(surface.title)).length
+  kvCacheEffectCount += surfaces.length
   structuredCount += 1
 }
 
 if (failures.length === 0) {
-  console.log(`verify-package-readme-model-experience: ${packageJsons.length} README(s) checked (${omittedSectionCount} audited omissions, ${structuredCount} structured, ${contextSurfaceCount} context surfaces, ${systemPromptSurfaceCount} fenced system-prompt surfaces, ${toolSchemaSurfaceCount} catalog-linked tool-schema surfaces, ${explainedNoneCount} explained none, ${indirectCount} indirect, ${verbatimBlockCount} verbatim markdown blocks), all conform.`)
+  console.log(`verify-package-readme-model-experience: ${packageJsons.length} README(s) checked (${omittedSectionCount} audited omissions, ${structuredCount} structured, ${contextSurfaceCount} context surfaces, ${kvCacheEffectCount} KV-cache fields, ${systemPromptSurfaceCount} fenced system-prompt surfaces, ${toolSchemaSurfaceCount} catalog-linked tool-schema surfaces, ${explainedNoneCount} explained none, ${indirectCount} indirect, ${verbatimBlockCount} verbatim markdown blocks), all conform.`)
   process.exit(0)
 }
 

scripts/verify-rfc-classification.ts

@@ -1,39 +0,0 @@
-/**
- * Enforce RFC lifecycle/class paths, dated filenames, and titles; verify the
- * generated index and reject index rows in the curated README. Structural rules
- * and rendering are shared with `rfc-index.ts`; the closed classification
- * contract lives in `docs/rfc/README.md`.
- */
-
-import { readFileSync } from 'node:fs'
-import { resolve } from 'node:path'
-import { INDEX_ROW, renderIndex, rfcRoot, walkRfcTree } from './rfc-index.ts'
-
-const { rfcs, errors } = walkRfcTree()
-
-if (errors.length === 0) {
-  let index: string | undefined
-  try {
-    index = readFileSync(resolve(rfcRoot, 'INDEX.md'), 'utf8')
-  } catch {
-    // A missing INDEX.md is reported below as staleness, exactly like a drifted one.
-  }
-  if (renderIndex(rfcs) !== index) {
-    errors.push('index: docs/rfc/INDEX.md is stale or missing — run `pnpm run gen-rfc-index` and commit the result')
-  }
-  const readme = readFileSync(resolve(rfcRoot, 'README.md'), 'utf8')
-  for (const line of readme.split('\n')) {
-    if (INDEX_ROW.test(line)) {
-      errors.push(`readme: index-shaped row in the curated README (the list lives in INDEX.md): ${JSON.stringify(line.slice(0, 80))}`)
-    }
-  }
-}
-
-if (errors.length === 0) {
-  console.log(`verify-rfc-classification: ${rfcs.length} RFC(s) checked, structure and index consistent.`)
-  process.exit(0)
-}
-
-console.error('verify-rfc-classification: violations found:')
-for (const e of errors) console.error(`  ${e}`)
-process.exit(1)

scripts/verify-translation-pairing.ts

@@ -24,8 +24,18 @@ const root = resolve(import.meta.dirname, '..')
 const listMode = process.argv.includes('--list')
 const writeMode = process.argv.includes('--write')
 
-/** Scope of the bilingual contract: the root README, the docs tree, and the Python SDK tree. */
-const SCOPE_PATTERNS = ['README.md', 'README.zh.md', 'README.i18n.yaml', 'docs/**/*.md', 'docs/**/*.i18n.yaml', 'python/**/*.md', 'python/**/*.i18n.yaml']
+/** Scope of the bilingual contract: root docs, Agent Notes, the docs tree, and the Python SDK tree. */
+const SCOPE_PATTERNS = [
+  'README.md',
+  'README.zh.md',
+  'README.i18n.yaml',
+  '.agents/notes/**/*.md',
+  '.agents/notes/**/*.i18n.yaml',
+  'docs/**/*.md',
+  'docs/**/*.i18n.yaml',
+  'python/**/*.md',
+  'python/**/*.i18n.yaml',
+]
 
 const manifest = parseTranslationPairingManifest(readFileSync(join(root, 'scripts/translation-pairing.manifest.json'), 'utf8'))
 
@@ -121,8 +131,8 @@ for (const req of manifest.required) {
   }
 }
 
-// 2. Date-named documents (RFCs) dated on/after the requiredSince cutoff merge
-// bilingual: a new RFC lands with its pair or not at all. Deterministic from
+// 2. Date-named documents (Agent Notes) dated on/after the requiredSince cutoff merge
+// bilingual: a new Agent Note lands with its pair or not at all. Deterministic from
 // the filename alone — no git history, so it holds on shallow CI checkouts.
 for (const source of sources) {
   if (isExcluded(source)) continue

scripts/verify-type-equiv.ts

@@ -1,7 +1,10 @@
 /**
- * Verify every `ts type-equiv` block against the source symbol named by the
- * manifest. Blocks and entries have a one-to-one relationship; comparison
- * ignores comments and whitespace but preserves declaration structure.
+ * Verify every `ts type-equiv` and `ts public-api` block against the source
+ * symbol named by the manifest. Ordinary entries preserve the complete
+ * declaration; `public-api` entries preserve a class's body-stripped public
+ * declaration. Blocks and entries have a one-to-one relationship; comparison
+ * ignores whitespace and non-JSDoc comments but preserves declaration
+ * structure and every original JSDoc comment.
  */
 
 import { globSync, readFileSync, existsSync } from 'node:fs'
@@ -11,35 +14,35 @@ import ts from 'typescript'
 const root = resolve(import.meta.dirname, '..')
 
 /** Scan doc-typecheck's full Markdown scope so unmanifested blocks also fail. */
-const MARKDOWN_GLOBS = ['README.md', 'docs/**/*.md', 'packages/*/*.md', 'packages/*/*/*.md']
+const MARKDOWN_GLOBS = ['README.md', '.agents/notes/**/*.md', 'docs/**/*.md', 'packages/*/*.md', 'packages/*/*/*.md', 'website/zh-CN/**/*.md']
 
-/** One manifest entry: a documented type-equiv block and its source symbol. */
+/** One manifest entry: a source-equivalence block and its source symbol. */
 interface ManifestEntry {
-  /** Doc file (repo-relative) containing the ` ```ts type-equiv ` block. */
+  /** Doc file (repo-relative) containing the source-equivalence block. */
   doc: string
   /** The declared symbol the block must match (e.g. `SessionEvent`). */
   symbol: string
   /** Source file (repo-relative) that exports the symbol. */
   source: string
+  /** Complete declaration (default), or a body-stripped public class API. */
+  projection?: 'public-api'
 }
 
-/** One extracted ` ```ts type-equiv ` block. */
+/** One extracted ` ```ts type-equiv ` or ` ```ts public-api ` block. */
 interface EquivBlock {
   doc: string
   /** 1-based line of the opening fence (for diagnostics). */
   line: number
   /** Symbol name parsed from the block's declaration. */
   symbol: string
+  /** Complete declaration (default), or a body-stripped public class API. */
+  projection?: 'public-api'
   /** Block body (the pasted declaration). */
   code: string
 }
 
-/**
- * Remove comments and normalize whitespace so prose-only edits do not drift
- * structural copies. This is intentionally not a general tokenizer: repo type
- * declarations do not contain comment delimiters inside string literals.
- */
-function normalize(code: string): string {
+/** Normalize declaration structure independently of comments and whitespace. */
+function normalizeStructure(code: string): string {
   return code
     .replace(/\/\*[\s\S]*?\*\//g, '')
     .replace(/(^|[^:])\/\/.*$/gm, '$1')
@@ -47,23 +50,38 @@ function normalize(code: string): string {
     .trim()
 }
 
+/**
+ * Extract normalized JSDoc comments in source order. Type declarations in this
+ * repository do not contain comment delimiters inside string literals.
+ */
+function normalizeJSDoc(code: string): string[] {
+  return [...code.matchAll(/\/\*\*[\s\S]*?\*\//g)]
+    .map(match => match[0].replace(/\s+/g, ' ').trim())
+}
+
 /** Strip source-only export modifiers. */
 function stripExport(code: string): string {
   return code.replace(/^export\s+(default\s+)?/, '')
 }
 
-/** Parse the declared symbol name from a type-equiv block body. */
+/** Parse the declared symbol name from a source-equivalence block body. */
 function blockSymbol(code: string): string | null {
-  const m = /(?:export\s+(?:default\s+)?)?(?:abstract\s+)?(?:interface|type|class|enum)\s+([A-Za-z0-9_]+)/.exec(code)
-  return m?.[1] ?? null
+  const sf = ts.createSourceFile('type-equiv.ts', code, ts.ScriptTarget.Latest, /* setParentNodes */ false, ts.ScriptKind.TS)
+  for (const stmt of sf.statements) {
+    const named =
+      ts.isInterfaceDeclaration(stmt) || ts.isTypeAliasDeclaration(stmt)
+      || ts.isClassDeclaration(stmt) || ts.isEnumDeclaration(stmt)
+    if (named && stmt.name) return stmt.name.text
+  }
+  return null
 }
 
-/** Extract every ` ```ts type-equiv ` block from one Markdown file. */
+/** Extract every source-equivalence block from one Markdown file. */
 function extractEquivBlocks(docRel: string): EquivBlock[] {
   const text = readFileSync(resolve(root, docRel), 'utf8')
   const lines = text.split('\n')
   const blocks: EquivBlock[] = []
-  let open: { line: number; body: string[] } | null = null
+  let open: { line: number; body: string[]; projection?: 'public-api' } | null = null
 
   for (let i = 0; i < lines.length; i++) {
     const raw = lines[i] ?? ''
@@ -78,21 +96,33 @@ function extractEquivBlocks(docRel: string): EquivBlock[] {
       if (!symbol) {
         throw new Error(`verify-type-equiv: ${docRel}:${open.line} — type-equiv block has no parseable interface/type/class declaration`)
       }
-      blocks.push({ doc: docRel, line: open.line, symbol, code })
+      blocks.push({
+        doc: docRel,
+        line: open.line,
+        symbol,
+        code,
+        ...(open.projection === undefined ? {} : { projection: open.projection }),
+      })
       open = null
       continue
     }
-    if ((fence[2] ?? '').trim() === 'ts type-equiv') open = { line: i + 1, body: [] }
+    const info = (fence[2] ?? '').trim()
+    if (info === 'ts type-equiv public-api') {
+      throw new Error(`verify-type-equiv: ${docRel}:${i + 1} — use the concise \`ts public-api\` fence`)
+    }
+    if (info === 'ts type-equiv') open = { line: i + 1, body: [] }
+    if (info === 'ts public-api') open = { line: i + 1, body: [], projection: 'public-api' }
   }
   if (open) throw new Error(`verify-type-equiv: ${docRel}:${open.line} — unterminated type-equiv block`)
   return blocks
 }
 
-/** The declaration text of `symbol` in `sourceRel`, with `export` stripped, or
+/**
+ * The declaration text of `symbol` in `sourceRel`, with `export` stripped, or
  * null when the symbol is not declared there. Uses the TS parser so it spans
  * interfaces, type aliases (including mapped/generic ones), classes, and enums
- * uniformly, and excludes the leading JSDoc (getStart skips leading trivia)
- * while keeping inline member comments. */
+ * uniformly while including declaration and member JSDoc.
+ */
 function sourceDeclaration(sourceRel: string, symbol: string): string | null {
   const abs = resolve(root, sourceRel)
   const text = readFileSync(abs, 'utf8')
@@ -102,19 +132,89 @@ function sourceDeclaration(sourceRel: string, symbol: string): string | null {
       ts.isInterfaceDeclaration(stmt) || ts.isTypeAliasDeclaration(stmt)
       || ts.isClassDeclaration(stmt) || ts.isEnumDeclaration(stmt)
     if (named && stmt.name?.text === symbol) {
-      return stripExport(stmt.getText(sf))
+      const declarationStart = stmt.getStart(sf)
+      const jsDoc = ts.getJSDocCommentsAndTags(stmt)
+        .filter(ts.isJSDoc)
+        .map(doc => text.slice(doc.pos, doc.end))
+        .join('\n')
+      const declaration = stripExport(text.slice(declarationStart, stmt.getEnd()))
+      return jsDoc === '' ? declaration : `${jsDoc}\n${declaration}`
     }
   }
   return null
 }
 
+/** Leading source JSDoc attached to one declaration or member. */
+function sourceJSDoc(text: string, node: ts.Node): string {
+  return ts.getJSDocCommentsAndTags(node)
+    .filter(ts.isJSDoc)
+    .map(doc => text.slice(doc.pos, doc.end))
+    .join('\n')
+}
+
+/** Whether a class member is part of its public declaration. */
+function isPublicMember(member: ts.ClassElement): boolean {
+  if (ts.isClassStaticBlockDeclaration(member)) return false
+  const name = ts.getNameOfDeclaration(member)
+  if (name && ts.isPrivateIdentifier(name)) return false
+  const modifiers = ts.canHaveModifiers(member) ? ts.getModifiers(member) : undefined
+  return !(modifiers?.some(modifier =>
+    modifier.kind === ts.SyntaxKind.PrivateKeyword
+    || modifier.kind === ts.SyntaxKind.ProtectedKeyword,
+  ) ?? false)
+}
+
+/** Remove an implementation body while retaining the source signature. */
+function bodylessMember(text: string, sf: ts.SourceFile, member: ts.ClassElement): string {
+  const start = member.getStart(sf)
+  let end = member.end
+  if (ts.isConstructorDeclaration(member) || ts.isMethodDeclaration(member)
+    || ts.isGetAccessorDeclaration(member) || ts.isSetAccessorDeclaration(member)) {
+    if (member.body) end = member.body.getStart(sf)
+  }
+  if (ts.isPropertyDeclaration(member) && member.initializer) end = member.initializer.getStart(sf)
+  const signature = text.slice(start, end).trimEnd().replace(/;$/, '').replace(/=\s*$/, '').trimEnd()
+  return `${signature};`
+}
+
+/**
+ * Render a class as an ambient declaration containing only its public fields,
+ * constructor, accessors, and methods. Implementation bodies and private or
+ * protected members are deliberately absent; original class/member JSDoc is
+ * retained so the projection is the source-owned public contract.
+ */
+function sourcePublicApi(sourceRel: string, symbol: string): string | null {
+  const abs = resolve(root, sourceRel)
+  const text = readFileSync(abs, 'utf8')
+  const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, /* setParentNodes */ true)
+  for (const stmt of sf.statements) {
+    if (!ts.isClassDeclaration(stmt) || stmt.name?.text !== symbol) continue
+    const classDoc = sourceJSDoc(text, stmt)
+    const abstract = stmt.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AbstractKeyword) ? 'abstract ' : ''
+    const typeParameters = stmt.typeParameters?.map(parameter => parameter.getText(sf)).join(', ')
+    const heritage = stmt.heritageClauses?.map(clause => clause.getText(sf)).join(' ')
+    const header = `declare ${abstract}class ${symbol}${typeParameters ? `<${typeParameters}>` : ''}${heritage ? ` ${heritage}` : ''} {`
+    const members = stmt.members
+      .filter(isPublicMember)
+      .map((member) => {
+        const jsDoc = sourceJSDoc(text, member)
+        const declaration = bodylessMember(text, sf, member)
+        return jsDoc === '' ? declaration : `${jsDoc}\n${declaration}`
+      })
+    const declaration = [header, ...members.map(member => member.split('\n').map(line => `  ${line}`).join('\n')), '}'].join('\n')
+    return classDoc === '' ? declaration : `${classDoc}\n${declaration}`
+  }
+  return null
+}
+
 const manifestRaw = readFileSync(resolve(root, 'scripts/type-equiv.manifest.json'), 'utf8')
 const manifest = JSON.parse(manifestRaw) as { entries: ManifestEntry[] }
 const entries = manifest.entries
 
-// Key a block/entry by doc + symbol (a symbol may be documented in more than one
-// doc, but at most once per doc).
-const keyOf = (x: { doc: string; symbol: string }): string => `${x.doc}::${x.symbol}`
+// Key a block/entry by doc + symbol + projection. A symbol may be documented in
+// more than one doc, and a doc may carry both complete and projected forms.
+const keyOf = (x: { doc: string; symbol: string; projection?: 'public-api' }): string =>
+  `${x.doc}::${x.symbol}::${x.projection ?? 'declaration'}`
 
 // Collect every type-equiv block across ALL docs in scope — not only the docs
 // the manifest names — so a block in an unmanifested doc is found and reported
@@ -133,7 +233,7 @@ for (const d of [...new Set(entries.map(e => e.doc))]) {
   else if (!docSet.has(d)) errors.push(`manifest references ${d}, which is outside the scanned markdown scope (${MARKDOWN_GLOBS.join(', ')})`)
 }
 
-// Duplicate-block guard: the same symbol twice in one doc is ambiguous.
+// Duplicate-block guard: the same projected symbol twice in one doc is ambiguous.
 const blockByKey = new Map<string, EquivBlock>()
 for (const b of blocks) {
   const k = keyOf(b)
@@ -173,16 +273,25 @@ let verified = 0
 for (const e of entries) {
   const b = blockByKey.get(keyOf(e))
   if (!b) continue // already reported as an orphan entry
-  const decl = sourceDeclaration(e.source, e.symbol)
+  const decl = e.projection === 'public-api'
+    ? sourcePublicApi(e.source, e.symbol)
+    : sourceDeclaration(e.source, e.symbol)
   if (decl === null) {
     errors.push(`symbol ${e.symbol} not found in ${e.source} (manifest entry for ${e.doc})`)
     continue
   }
-  if (normalize(decl) !== normalize(stripExport(b.code))) {
+  const doc = stripExport(b.code)
+  const sourceStructure = normalizeStructure(decl)
+  const docStructure = normalizeStructure(doc)
+  const sourceJSDoc = normalizeJSDoc(decl)
+  const docJSDoc = normalizeJSDoc(doc)
+  if (sourceStructure !== docStructure || JSON.stringify(sourceJSDoc) !== JSON.stringify(docJSDoc)) {
     errors.push(
       `DRIFT: ${e.doc}:${b.line} — type-equiv block for ${e.symbol} does not match ${e.source}.\n`
-      + `    source: ${normalize(decl)}\n`
-      + `    doc:    ${normalize(stripExport(b.code))}`,
+      + `    source structure: ${sourceStructure}\n`
+      + `    doc structure:    ${docStructure}\n`
+      + `    source JSDoc:     ${JSON.stringify(sourceJSDoc)}\n`
+      + `    doc JSDoc:        ${JSON.stringify(docJSDoc)}`,
     )
     continue
   }
@@ -190,7 +299,7 @@ for (const e of entries) {
 }
 
 if (errors.length === 0) {
-  console.log(`verify-type-equiv: ${verified} type-equiv block(s) match source (1:1 with manifest).`)
+  console.log(`verify-type-equiv: ${verified} type-equiv block(s) match source structure and JSDoc (1:1 with manifest).`)
   process.exit(0)
 }
 

scripts/verify-website-yaml.ts

@@ -0,0 +1,269 @@
+/**
+ * Doc-sync gate: verify the fenced ```yaml examples in the website against
+ * the loader and the workspace truth. A `cordis.yml` example that names a
+ * plugin that does not exist, or passes a config key the plugin never
+ * declared, is worse than no example — it fails silently for the reader.
+ *
+ * Scope: `website/zh-CN/**​/*.md`, EXCLUDING `website/zh-CN/api/**` (the api
+ * pages are generator-owned — their yaml examples are verified at generation
+ * time by a later stream, not re-checked here). Blocks opt out with
+ * ` ```yaml ignore-check ` (same philosophy as doc-typecheck's opt-out: the
+ * count is reported, an unchecked block is a visible decision, not a silent
+ * hole — placeholder plugin names in tutorials are the legitimate case).
+ *
+ * Each checked block is parsed with the loader's REAL schema —
+ * `JSON_SCHEMA` extended with the `!!js` scalar type exactly as
+ * vendor/include/src/index.ts declares it — so `!!js process.env.X` parses
+ * here iff it parses at runtime. Then:
+ *
+ * - Root is an ARRAY → a cordis.yml entry list. Every item must be a mapping
+ *   with a string `name` and only the keys `EntryOptions` declares
+ *   (vendor/loader/src/config/entry.ts plus the isolate.ts merge:
+ *   id, name, config, group, disabled, inject, intercept, isolate).
+ *   - `./` / `../` names are illustrative local plugins — existence is not
+ *     checkable, skip. `group:*` names are loader built-ins; their `config`
+ *     is itself an entry list and is recursed into.
+ *   - Any other name must be a real workspace package (`packages/*​/*` and
+ *     `vendor/*` package.json names).
+ *   - For `@deepseek-ai/dsh-*` names the config-catalog generator is the
+ *     truth: kind `config` → the yaml `config`'s top-level keys must be
+ *     properties of the declared config type (member names of the first
+ *     catalog paste ∪ top-level segments of the runtime schema keys);
+ *     config-free kinds → a non-empty `config` mapping is a violation;
+ *     seam/library kinds → name existence only (loading one directly is
+ *     dubious, but that is a docs-prose concern, not this gate's).
+ * - Root is a MAPPING or scalar → a fragment (e.g. a bare `config:` excerpt):
+ *   syntax check only.
+ *
+ * This is a checker, not a fixer: it reports `file:line message` and exits 1.
+ *
+ * Run: `tsx scripts/verify-website-yaml.ts`.
+ */
+
+import { globSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import * as yaml from 'js-yaml'
+import ts from 'typescript'
+import { collectConfigCatalog, type CatalogEntry } from './gen-config-catalog.ts'
+import { extractFences } from './md-fences.ts'
+
+const root = resolve(import.meta.dirname, '..')
+
+/** Mirror of the loader's yaml schema (vendor/include/src/index.ts): the
+ * `!!js` tag parses to an expression wrapper, everything else is JSON. */
+const JsExpr = new yaml.Type('tag:yaml.org,2002:js', {
+  kind: 'scalar',
+  resolve: data => typeof data === 'string',
+  construct: (data: string) => ({ __jsExpr: data }),
+})
+const schema = yaml.JSON_SCHEMA.extend(JsExpr)
+
+/** The exact key set an entry mapping may carry: `EntryOptions` in
+ * vendor/loader/src/config/entry.ts plus the isolate.ts interface merge. */
+const ENTRY_KEYS = ['id', 'name', 'config', 'group', 'disabled', 'inject', 'intercept', 'isolate'] as const
+
+/** One `file:line message` finding. */
+interface Violation {
+  file: string
+  /** 1-based line of the block's opening fence. */
+  line: number
+  message: string
+}
+
+/** One extracted ```yaml block. */
+interface Block {
+  file: string
+  /** 1-based line of the opening fence. */
+  line: number
+  kind: 'check' | 'ignore'
+  code: string
+}
+
+/** Extract every ```yaml / ```yaml ignore-check block from one Markdown file. */
+function extractBlocks(file: string): Block[] {
+  return extractFences(resolve(root, file), info =>
+    info === 'yaml' ? 'check' : info === 'yaml ignore-check' ? 'ignore' : null)
+    .map(f => ({ file, line: f.line, kind: f.kind, code: f.code }))
+}
+
+/** Every workspace package name: `packages/<group>/<pkg>` and `vendor/<pkg>`. */
+function knownPackages(): Set<string> {
+  const names = new Set<string>()
+  for (const pattern of ['packages/*/*/package.json', 'vendor/*/package.json']) {
+    for (const match of globSync(pattern, { cwd: root })) {
+      const pkg: unknown = JSON.parse(readFileSync(resolve(root, match), 'utf8'))
+      if (typeof pkg === 'object' && pkg !== null && 'name' in pkg && typeof pkg.name === 'string') {
+        names.add(pkg.name)
+      }
+    }
+  }
+  return names
+}
+
+/** The catalog, built once on first `@deepseek-ai/dsh-*` name, keyed by pkg. */
+let catalogByPkg: Map<string, CatalogEntry> | null = null
+function catalogFor(pkg: string): CatalogEntry | undefined {
+  catalogByPkg ??= new Map(collectConfigCatalog().map(e => [e.pkg, e]))
+  return catalogByPkg.get(pkg)
+}
+
+/** Top-level property names of the first catalog paste (the verbatim config
+ * type declaration), parsed as source text. */
+function pasteKeys(paste: string): Set<string> {
+  const sf = ts.createSourceFile('paste.ts', paste, ts.ScriptTarget.Latest, true)
+  const keys = new Set<string>()
+  const addMembers = (members: ts.NodeArray<ts.TypeElement>): void => {
+    for (const m of members) {
+      if (ts.isPropertySignature(m) || ts.isMethodSignature(m)) {
+        const name = m.name
+        keys.add(ts.isIdentifier(name) || ts.isStringLiteral(name) ? name.text : name.getText(sf))
+      }
+    }
+  }
+  for (const stmt of sf.statements) {
+    if (ts.isInterfaceDeclaration(stmt)) addMembers(stmt.members)
+    else if (ts.isTypeAliasDeclaration(stmt) && ts.isTypeLiteralNode(stmt.type)) addMembers(stmt.type.members)
+  }
+  return keys
+}
+
+/** The allowed top-level config keys of a kind-`config` catalog entry: the
+ * first paste's member names ∪ the schema keys' top-level segments
+ * (`agents[].id` → `agents`). Cached per entry. */
+const allowedKeysCache = new Map<string, Set<string>>()
+function allowedConfigKeys(entry: CatalogEntry): Set<string> {
+  const cached = allowedKeysCache.get(entry.pkg)
+  if (cached) return cached
+  const keys = pasteKeys(entry.pastes?.[0]?.text ?? '')
+  for (const path of entry.schemaKeys ?? []) {
+    const top = path.split('.')[0]?.replace(/\[\]$/, '')
+    if (top) keys.add(top)
+  }
+  allowedKeysCache.set(entry.pkg, keys)
+  return keys
+}
+
+/** A parsed yaml mapping (arrays and `!!js` wrappers excluded). */
+function asMapping(value: unknown): Record<string, unknown> | null {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return null
+  if ('__jsExpr' in value) return null
+  return value as Record<string, unknown>
+}
+
+/** Check one cordis.yml entry list (recursing into `group:` sub-lists). */
+function checkEntryList(
+  items: unknown[],
+  known: Set<string>,
+  block: Block,
+  violations: Violation[],
+): void {
+  const flag = (message: string): void => {
+    violations.push({ file: block.file, line: block.line, message })
+  }
+  items.forEach((item, index) => {
+    const at = `entry ${index + 1}`
+    const entry = asMapping(item)
+    if (!entry) {
+      flag(`${at}: not a mapping`)
+      return
+    }
+    const name = entry['name']
+    if (typeof name !== 'string') {
+      flag(`${at}: missing string \`name\``)
+      return
+    }
+    for (const key of Object.keys(entry)) {
+      if (!(ENTRY_KEYS as readonly string[]).includes(key)) {
+        flag(`${at} (${name}): unknown entry key \`${key}\` (EntryOptions allows: ${[...ENTRY_KEYS].join(', ')})`)
+      }
+    }
+    // Illustrative local plugin — nothing on disk to check against.
+    if (name.startsWith('./') || name.startsWith('../')) return
+    // A `group:`-style pseudo-name is NOT loadable: tree.import() only
+    // special-cases the `cordis:` prefix, and nothing in this repo registers
+    // loader builtins — reject it and point at the real group plugin.
+    if (name.startsWith('group:')) {
+      flag(`${at}: \`${name}\` is not loadable (no loader builtin is registered); use \`@cordisjs/plugin-group\` with \`group: true\``)
+      return
+    }
+    // The vendored group plugin: its config is a nested entry list.
+    if (name === '@cordisjs/plugin-group') {
+      if (Array.isArray(entry['config'])) checkEntryList(entry['config'], known, block, violations)
+      return
+    }
+    if (!known.has(name)) {
+      flag(`${at}: unknown plugin \`${name}\` (not a workspace package)`)
+      return
+    }
+    if (!name.startsWith('@deepseek-ai/dsh-')) return
+    const catalog = catalogFor(name)
+    if (!catalog) return
+    const config = asMapping(entry['config'])
+    if (catalog.kind === 'config') {
+      if (!config) return
+      const allowed = allowedConfigKeys(catalog)
+      for (const key of Object.keys(config)) {
+        if (!allowed.has(key)) {
+          flag(`${at}: \`${name}\` has no config key \`${key}\` (known keys: ${[...allowed].sort().join(', ')})`)
+        }
+      }
+    } else if (catalog.kind === 'no-config') {
+      if (config && Object.keys(config).length > 0) {
+        flag(`${at}: \`${name}\` declares no config, but the example passes one`)
+      }
+    }
+    // seam / library: loading one directly is dubious, but that is a prose
+    // concern — this gate only vouches for name existence.
+  })
+}
+
+const files = globSync('website/zh-CN/**/*.md', { cwd: root })
+  .filter(f => !f.startsWith('website/zh-CN/api/'))
+  .sort()
+
+const violations: Violation[] = []
+const known = knownPackages()
+let entryLists = 0
+let fragments = 0
+let ignored = 0
+let scanned = 0
+
+for (const file of files) {
+  for (const block of extractBlocks(file)) {
+    scanned++
+    if (block.kind === 'ignore') {
+      ignored++
+      continue
+    }
+    let parsed: unknown
+    try {
+      parsed = yaml.load(block.code, { schema })
+    } catch (error) {
+      const message = error instanceof Error ? error.message.split('\n')[0] ?? 'parse error' : String(error)
+      violations.push({ file: block.file, line: block.line, message: `yaml parse error: ${message}` })
+      continue
+    }
+    if (Array.isArray(parsed)) {
+      entryLists++
+      checkEntryList(parsed, known, block, violations)
+    } else {
+      // Mapping or scalar root: a fragment (e.g. a bare `config:` excerpt) —
+      // syntax is all there is to check.
+      fragments++
+    }
+  }
+}
+
+if (violations.length === 0) {
+  console.log(
+    `verify-website-yaml: ${scanned} yaml block(s) in ${files.length} file(s): `
+    + `${entryLists} entry list(s) + ${fragments} fragment(s) checked, ${ignored} ignore-check skipped.`,
+  )
+  process.exit(0)
+}
+
+console.error('verify-website-yaml: invalid yaml examples found:')
+for (const v of violations) {
+  console.error(`  ${v.file}:${v.line}  ${v.message}`)
+}
+process.exit(1)