diff --git a/package.json b/package.json
index e4b071718a..652a8d88c4 100644
--- a/package.json
+++ b/package.json
@@ -47,6 +47,8 @@
     "gen-cordis-catalog": "tsx scripts/gen-cordis-catalog.ts",
     "gen-rfc-index": "tsx scripts/gen-rfc-index.ts",
     "verify-cordis-catalog": "tsx scripts/gen-cordis-catalog.ts --check",
+    "gen-cordis-api": "tsx scripts/gen-cordis-api.ts",
+    "verify-cordis-api": "tsx scripts/gen-cordis-api.ts --check",
     "verify-export-jsdoc": "tsx scripts/verify-export-jsdoc.ts",
     "gen-tool-catalog": "tsx scripts/gen-tool-catalog.ts",
     "verify-tool-catalog": "tsx scripts/gen-tool-catalog.ts --check",
@@ -59,7 +61,7 @@
     "gen-module-graph": "tsx scripts/gen-module-graph.ts",
     "verify-module-graph": "tsx scripts/gen-module-graph.ts --check",
     "constraints": "tsx scripts/check-workspace-constraints.ts",
-    "doc-sync": "pnpm run doc-typecheck && pnpm run verify-cordis-catalog && pnpm run verify-export-jsdoc && pnpm run verify-tool-catalog && pnpm run verify-config-catalog && pnpm run verify-persistence-catalog && pnpm run verify-doc-graphs && pnpm run verify-md-wrap && pnpm run verify-md-links && pnpm run verify-doc-refs && pnpm run verify-package-paths && pnpm run verify-mermaid && pnpm run verify-rfc-classification && pnpm run verify-rfc-format && pnpm run verify-type-equiv && pnpm run verify-translation-pairing && pnpm run verify-doc-budgets",
+    "doc-sync": "pnpm run doc-typecheck && pnpm run verify-cordis-catalog && pnpm run verify-cordis-api && pnpm run verify-export-jsdoc && pnpm run verify-tool-catalog && pnpm run verify-config-catalog && pnpm run verify-persistence-catalog && pnpm run verify-doc-graphs && pnpm run verify-md-wrap && pnpm run verify-md-links && pnpm run verify-doc-refs && pnpm run verify-package-paths && pnpm run verify-mermaid && pnpm run verify-rfc-classification && pnpm run verify-rfc-format && pnpm run verify-type-equiv && pnpm run verify-translation-pairing && pnpm run verify-doc-budgets",
     "hygiene": "pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-node-next-types",
     "demo:echo": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/echo-agent/cordis.yml",
     "demo:repl": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/coding-agent/cordis.yml",
diff --git a/scripts/gen-cordis-api.ts b/scripts/gen-cordis-api.ts
new file mode 100644
index 0000000000..34583d2ead
--- /dev/null
+++ b/scripts/gen-cordis-api.ts
@@ -0,0 +1,247 @@
+/**
+ * Generate (and verify) the runtime cordis API catalog the `cordis_inspect`
+ * tool serves to the model: packages/cordis/tool-cordis/src/api-catalog.ts.
+ *
+ * The artifact is the machine-readable sibling of docs/cordis-catalog: it
+ * reuses `collectServices` / `collectEvents` from `gen-cordis-catalog.ts` (the
+ * same JSDoc-completeness-enforcing AST walk), so the API the model reads at
+ * runtime and the API the docs render cannot diverge. Emitted as a typed
+ * TypeScript data module (not JSON): it compiles under the package tsconfig,
+ * passes lint and the export-JSDoc gate, and is trivially covered by import.
+ *
+ * The data is trimmed for a model-facing text surface: per service the
+ * `ctx.<key>` name, the first sentence of the class doc, and the raw method
+ * signatures; per event the name, `@mode`, signature, and first sentence of
+ * doc; the SHAPES of every exported interface/type-alias the service
+ * signatures reference (transitively — so a model can see that e.g. a
+ * `BashRunResult.stdout` is `{ text, truncated }`, not a string); plus the
+ * curated inherited `ctx` surface shared with the docs catalog. Source
+ * pointers are dropped (a `file:line` means nothing to the model) and entries
+ * are sorted deterministically.
+ *
+ *   `tsx scripts/gen-cordis-api.ts`          → write the artifact
+ *   `tsx scripts/gen-cordis-api.ts --check`  → exit 1 if the committed file is
+ *                                              stale (CI / pre-push gate)
+ */
+
+import { globSync, readFileSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import ts from 'typescript'
+import { collectEvents, collectServices, INHERITED_SERVICES } from './gen-cordis-catalog.ts'
+
+const root = resolve(import.meta.dirname, '..')
+const OUT = 'packages/cordis/tool-cordis/src/api-catalog.ts'
+
+/** Declarations longer than this render as a truncated stub — a shape the model cannot skim teaches nothing. */
+const MAX_DECL_CHARS = 1500
+
+/** The first sentence of a (possibly multi-line) JSDoc prose block. */
+function firstSentence(doc: string): string {
+  const line = doc.split('\n', 1)[0] ?? ''
+  const match = /^(.*?[.!?])(?:\s|$)/.exec(line)
+  return (match?.[1] ?? line).trim()
+}
+
+/** Render a string as a single-quoted, lint-clean TS literal. */
+function quote(value: string): string {
+  return `'${value.replace(/\\/g, '\\\\').replace(/'/g, '\\\'').replace(/\n/g, '\\n')}'`
+}
+
+/**
+ * Every exported `interface` / `type` declaration under `packages/<group>/<pkg>/src`,
+ * printed without comments, keyed by name. A name declared in more than one
+ * package (e.g. each plugin's `Config`) is ambiguous and dropped entirely —
+ * serving the wrong package's shape is worse than serving none.
+ */
+function collectTypeDecls(scanRoot: string = root): Map<string, string> {
+  const printer = ts.createPrinter({ removeComments: true })
+  const decls = new Map<string, string>()
+  const ambiguous = new Set<string>()
+  for (const rel of globSync('packages/*/*/src/*.ts', { cwd: scanRoot }).sort()) {
+    const abs = resolve(scanRoot, rel)
+    const sf = ts.createSourceFile(abs, readFileSync(abs, 'utf8'), ts.ScriptTarget.Latest, true)
+    for (const stmt of sf.statements) {
+      if (!ts.isInterfaceDeclaration(stmt) && !ts.isTypeAliasDeclaration(stmt)) continue
+      if (!(stmt.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) ?? false)) continue
+      const name = stmt.name.text
+      if (decls.has(name)) {
+        ambiguous.add(name)
+        continue
+      }
+      const printed = printer.printNode(ts.EmitHint.Unspecified, stmt, sf).replace(/\r/g, '')
+      decls.set(name, printed.length > MAX_DECL_CHARS
+        ? `${printed.slice(0, MAX_DECL_CHARS)} /* …truncated — full shape in source */`
+        : printed)
+    }
+  }
+  for (const name of ambiguous) decls.delete(name)
+  return decls
+}
+
+/**
+ * The transitive closure of type names referenced by the seed texts: every
+ * collected declaration whose name appears (word-bounded) in a seed or in an
+ * already-included declaration, sorted by name.
+ */
+function referencedTypes(seeds: string[], decls: Map<string, string>): { name: string; declaration: string }[] {
+  const included = new Map<string, string>()
+  let frontier = seeds
+  while (frontier.length > 0) {
+    const next: string[] = []
+    for (const [name, declaration] of decls) {
+      if (included.has(name)) continue
+      const pattern = new RegExp(`\\b${name}\\b`)
+      if (frontier.some(text => pattern.test(text))) {
+        included.set(name, declaration)
+        next.push(declaration)
+      }
+    }
+    frontier = next
+  }
+  return [...included].map(([name, declaration]) => ({ name, declaration })).sort((a, b) => a.name.localeCompare(b.name))
+}
+
+/** Render the whole generated module (pure, deterministic given sorted collector output). */
+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 lines: string[] = [
+    '/**',
+    ' * Generated by scripts/gen-cordis-api.ts — do not edit by hand; run',
+    ' * `pnpm run gen-cordis-api` to regenerate (freshness-gated by',
+    ' * `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',
+    ' * 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. */',
+    '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[]',
+    '}',
+    '',
+    '/** One harness event: its dispatch mode, exact signature, and one-line summary. */',
+    'export interface EventApiEntry {',
+    '  /** The scoped event name, e.g. `agent/status`. */',
+    '  name: string',
+    '  /** The dispatch mode from the declaration\'s `@mode` tag. */',
+    '  mode: string',
+    '  /** The exact listener signature, whitespace-normalized. */',
+    '  signature: string',
+    '  /** First sentence of the event JSDoc. */',
+    '  summary: string',
+    '}',
+    '',
+    '/** One inherited (cordis core + loader/hmr/timer) `ctx` member group with its summary. */',
+    'export interface InheritedApiEntry {',
+    '  /** The `ctx` member name(s), e.g. `ctx.on / ctx.once`. */',
+    '  name: string',
+    '  /** One-line summary of what the member does. */',
+    '  summary: string',
+    '}',
+    '',
+    '/** One named type shape the service signatures reference. */',
+    'export interface TypeApiEntry {',
+    '  /** The exported type/interface name, e.g. `BashRunResult`. */',
+    '  name: string',
+    '  /** The full declaration text, comments stripped. */',
+    '  declaration: string',
+    '}',
+    '',
+    '/** Every harness `ctx.<key>` service, sorted by key. */',
+    'export const SERVICE_API: readonly ServiceApiEntry[] = [',
+  ]
+  for (const service of services) {
+    lines.push('  {')
+    lines.push(`    key: ${quote(service.key)},`)
+    lines.push(`    summary: ${quote(firstSentence(service.doc))},`)
+    if (service.methods.length === 0) {
+      lines.push('    methods: [],')
+    } else {
+      lines.push('    methods: [')
+      for (const method of service.methods) lines.push(`      ${quote(method)},`)
+      lines.push('    ],')
+    }
+    lines.push('  },')
+  }
+  lines.push(
+    ']',
+    '',
+    '/** Every harness event, sorted by name. */',
+    'export const EVENT_API: readonly EventApiEntry[] = [',
+  )
+  for (const event of events) {
+    lines.push('  {')
+    lines.push(`    name: ${quote(event.name)},`)
+    lines.push(`    mode: ${quote(event.mode)},`)
+    lines.push(`    signature: ${quote(event.signature)},`)
+    lines.push(`    summary: ${quote(firstSentence(event.doc))},`)
+    lines.push('  },')
+  }
+  lines.push(
+    ']',
+    '',
+    '/** Shapes of every exported type the SERVICE_API signatures reference (transitively), sorted by name. */',
+    'export const TYPE_API: readonly TypeApiEntry[] = [',
+  )
+  for (const type of types) {
+    lines.push('  {')
+    lines.push(`    name: ${quote(type.name)},`)
+    lines.push(`    declaration: ${quote(type.declaration)},`)
+    lines.push('  },')
+  }
+  lines.push(
+    ']',
+    '',
+    '/** The inherited `ctx` surface (cordis core + loader/hmr/timer), in curated order. */',
+    'export const INHERITED_CTX_API: readonly InheritedApiEntry[] = [',
+  )
+  for (const inherited of INHERITED_SERVICES) {
+    lines.push(`  { name: ${quote(inherited.name)}, summary: ${quote(inherited.summary)} },`)
+  }
+  lines.push(']', '')
+  return lines.join('\n')
+}
+
+/** CLI entry: default writes the artifact, `--check` fails if the committed
+ * copy 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()
+  if (process.argv.includes('--check')) {
+    let committed: string | null = null
+    try {
+      committed = readFileSync(resolve(root, OUT), 'utf8')
+    } catch {
+      // Only ENOENT (not yet generated) is expected; a present-but-unreadable
+      // file is not a state this repo produces. Either way the remedy is the
+      // same — regenerate — so treat a read failure as "stale".
+      committed = null
+    }
+    if (committed === content) {
+      console.log(`gen-cordis-api: ${OUT} is up to date.`)
+      process.exit(0)
+    }
+    console.error(`gen-cordis-api: ${OUT} is stale. Run \`pnpm run gen-cordis-api\` and commit ${OUT}.`)
+    process.exit(1)
+  }
+
+  writeFileSync(resolve(root, OUT), content)
+  console.log(`gen-cordis-api: wrote ${OUT}.`)
+}
+
+// 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()
+}
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 6220006ede..9b8141807e 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -327,7 +327,7 @@ const INHERITED_EVENTS: InheritedEntry[] = [
   { name: 'loader/patch-context', summary: 'A context is being patched during a reload.', source: 'vendor/loader/src/index.ts:27' },
 ]
 
-const INHERITED_SERVICES: 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' },