@agentskit/doc-bridge 1.7.45 → 1.9.0

package/src/cli/program.ts

@@ -17,6 +17,7 @@ import { scanHumanDocRecords } from '../index-builder/human-adapters/index.js'
 import { retrieveHybridChunks } from '../federation/llms.js'
 import { runGates, type GateId } from '../gates/run-gates.js'
 import { evaluateRules, parseRuleId, parseRuleSeverity, type RuleMode } from '../rules/engine.js'
+import { centrality } from '../graph/build.js'
 import { runChatOnce, startInkChat } from '../intelligence/chat.js'
 import { PeerMissingError, layer1InstallHint } from '../intelligence/peers.js'
 import { createDocBridgeRag } from '../intelligence/rag.js'
@@ -32,23 +33,72 @@ import {
 } from '../doctor/badge.js'
 import { docBridgePatternMarkdown, docBridgePatternPayload } from '../playbook/doc-bridge-pattern.js'
 import { formatDemoText, runDemo, withDemoWorkspace, type DemoFixture } from './demo.js'
-import { formatDoctorText, runDoctor } from '../doctor/run-doctor.js'
+import { DEFAULT_RETRIEVAL_SUITE, formatDoctorText, runDoctor } from '../doctor/run-doctor.js'
 import { installMcpConfig, mcpSnippet } from '../mcp/install.js'
 import { startMcpStdioServer } from '../mcp/server.js'
-import { IndexNotFoundError, loadDocBridgeIndex } from '../query/load-index.js'
+import { measureOverlayRetrievalDelta, formatOverlayRetrievalDeltaText } from '../bench/overlay-delta.js'
+import { enrichmentCost } from '../enrich/stats.js'
+import { checkStudyExpectations, formatStudyExpectationsText, parseStudyExpectations } from '../study/expectations.js'
+import { IndexNotFoundError, loadFreshDocBridgeIndex } from '../query/load-index.js'
 import { runQuery, type QueryKind } from '../query/query.js'
 import { searchIndex } from '../query/search.js'
 import type { DocBridgeIndexV1 } from '../schemas/doc-bridge-index.js'
-import { parseAgentHandoff, parseDocBridgeConfig, parseReconciliationReport } from '../validate.js'
+import { parseAgentHandoff, parseDocBridgeConfig, parseDocBridgeIndex, parseReconciliationReport } from '../validate.js'
 import { parseDiscoverySnapshot } from '../validate.js'
+import { findingsFromDiagnostics } from '../findings/report.js'
+import {
+  formatRetrievalBenchText,
+  parseRetrievalSuite,
+  runRetrievalBench,
+  type RetrievalBenchResultV1,
+} from '../bench/retrieval.js'
+import {
+  compareRetrievalBaseline,
+  createRetrievalBaseline,
+  formatRetrievalComparisonText,
+  parseRetrievalBaseline,
+} from '../bench/baseline.js'
 import { reconcileKnowledge } from '../reconciliation/reconcile.js'
 import type { DiscoverySnapshotV1, ReconciliationReportV1 } from '../schemas/knowledge.js'
 import { sha256NormalizedV1 } from '../index-builder/content-hash.js'
 import { applyFixProposal, approveFixProposal, createArtifactNormalizationProposal, createMarkdownLinkFixProposal } from '../fixes/proposals.js'
 import { createRegistryAgentAdapter, loadRegistryAgentRunner, persistRegistryAgentProposal } from '../agents/registry-adapter.js'
+import { fixApprovalId, recordApproval, FIX_APPROVAL_GATE } from '../enrich/approvals.js'
+import { readEnrichmentOverlay, withAcceptedRelations } from '../enrich/overlay.js'
+import { decideEnrichment, listEnrichment } from '../enrich/review.js'
+import { formatEnrichmentText, runEnrichment, type EnrichmentRunResult } from '../enrich/stage.js'
 import { renderOfflineReportArtifact } from '../report/html.js'
 import { benchmarkFixture, formatBenchmarkText, measureBenchmark } from '../metrics/benchmark.js'
 import { PACKAGE_VERSION } from '../version.js'
+import { auditDocumentation, formatDocumentationAuditText } from '../audit/documentation.js'
+import { renderArtifact, writeRenderedPages } from '../render/render.js'
+import { CLI_COMMAND_USAGE } from './usage.js'
+import { checkPublicParity, formatPublicParityText } from '../parity/check.js'
+import { parsePublicClaims } from '../parity/claims.js'
+import { resolveTemplateSource } from '../render/template-source.js'
+import { RENDER_TEMPLATE_NAMES, RENDER_TEMPLATES, isRenderTemplateName } from '../render/templates.js'
+import {
+  formatHistoricalEvidenceText,
+  formatStudyProtocolText,
+  parseHistoricalEvidenceRegistry,
+  parseStudyProtocol,
+  validateHistoricalEvidenceRegistry,
+} from '../study/protocol.js'
+import {
+  formatStudyTaskSuiteText,
+  parseStudyTaskSuite,
+  selectTaskExecutions,
+} from '../study/task-suite.js'
+import {
+  formatControlledStudyRunPlanText,
+  parseControlledStudyLedger,
+  parseControlledStudyRunPlan,
+} from '../study/runner.js'
+import { formatControlledStudyRunText, parseStudyRepositoryConfig, runControlledStudy } from '../study/execution.js'
+import { independentlyAdjudicateStudyLedger, persistIndependentlyAdjudicatedLedger } from '../study/adjudication.js'
+import { formatStudyProviderCliText, parseStudyProviderCliConfig } from '../study/provider-cli.js'
+import { calculateStudyMetrics, formatStudyMetricsText } from '../study/metrics.js'
+import { formatStudyVerificationText, parseStudyVerificationBinding } from '../study/verification.js'
 
 type Command =
   | 'help'
@@ -62,12 +112,15 @@ type Command =
   | 'registry'
   | 'discover'
   | 'benchmark'
+  | 'bench'
+  | 'study'
   | 'scan'
   | 'reconcile'
   | 'check'
   | 'map'
   | 'fix'
   | 'suggest'
+  | 'enrich'
   | 'index'
   | 'gate'
   | 'rules'
@@ -82,48 +135,11 @@ type Command =
   | 'rag'
   | 'list'
   | 'conformance'
+  | 'audit'
+  | 'parity'
+  | 'render'
 
-const usage = `ak-docs — human↔agent documentation bridge (@agentskit/doc-bridge)
-
-Core (no API key):
-  ak-docs init [--demo] [--scaffold-workspaces]
-  ak-docs demo [--fixture example|monorepo] [--text] [--in-project]
-  ak-docs doctor [--text] [--badge] [--write-badge]
-  ak-docs index [--watch]
-  ak-docs discover [--text|--json]
-  ak-docs benchmark <fixture.json> <observation.json> [--text|--json]
-  ak-docs scan | reconcile | check | map [--text|--json] [--html] [--report-threshold <bytes>]
-  ak-docs fix propose links|normalize <artifact> [--output <file>]
-  ak-docs fix approve|apply <proposal.json> [--by <name>]
-  ak-docs suggest [--json|--text]   run the configured local Registry agent
-  ak-docs query [package|ownership|intent|change] <id> [--agent] [--text]
-  ak-docs search <term> [--agent] [--text]
-  ak-docs list <packages|intents|changes|knowledge> [--text]
-  ak-docs ask [question]          local consult (no LLM)
-  ak-docs gate run [gate-id]
-  ak-docs rules run <report.json> [--preset default|recommended|strict] [--severity rule=level] [--ignore rule]
-  ak-docs conformance run documentation-standard-v1 [--text|--json]
-  ak-docs mcp
-  ak-docs mcp install --cursor | --claude
-  ak-docs memory ingest|classify|promote [--pr] [--dry-run]
-  ak-docs bootstrap agent-docs
-  ak-docs validate-config | validate-handoff <file>
-
-Intelligence (optional AgentsKit peers):
-  ak-docs rag ingest|search <query>
-  ak-docs chat                    terminal chat (Ink + RAG)
-  ak-docs ask <question> --chat   one-shot grounded answer
-
-Advanced / ecosystem:
-  ak-docs retrieve <query>
-  ak-docs registry topology
-  ak-docs playbook draft | pattern [--text]
-
-Global flags:
-  -h, --help   --version
-  --config <path>   (project root = config file directory)
-  --agent   --json   --text   --chat   --demo
-`
+const usage = CLI_COMMAND_USAGE
 
 const QUERY_KINDS = new Set<QueryKind>(['package', 'ownership', 'intent', 'change', 'search'])
 const LIST_KINDS = new Set(['packages', 'intents', 'changes', 'knowledge'])
@@ -148,6 +164,12 @@ const parseArgs = (argv: readonly string[]) => {
       i += 1
       continue
     }
+    if (arg === '--mode' || arg === '--context-budget') {
+      const value = argv[i + 1]
+      if (value !== undefined && !value.startsWith('-')) flags.add(`${arg}=${value}`)
+      i += 1
+      continue
+    }
     if (arg.startsWith('-')) {
       flags.add(arg)
       continue
@@ -167,12 +189,15 @@ const parseArgs = (argv: readonly string[]) => {
   else if (positional[0] === 'registry') command = 'registry'
   else if (positional[0] === 'discover') command = 'discover'
   else if (positional[0] === 'benchmark') command = 'benchmark'
+  else if (positional[0] === 'bench') command = 'bench'
+  else if (positional[0] === 'study') command = 'study'
   else if (positional[0] === 'scan') command = 'scan'
   else if (positional[0] === 'reconcile') command = 'reconcile'
   else if (positional[0] === 'check') command = 'check'
   else if (positional[0] === 'map') command = 'map'
   else if (positional[0] === 'fix') command = 'fix'
   else if (positional[0] === 'suggest') command = 'suggest'
+  else if (positional[0] === 'enrich') command = 'enrich'
   else if (positional[0] === 'index') command = 'index'
   else if (positional[0] === 'gate') command = 'gate'
   else if (positional[0] === 'rules') command = 'rules'
@@ -187,6 +212,9 @@ const parseArgs = (argv: readonly string[]) => {
   else if (positional[0] === 'rag') command = 'rag'
   else if (positional[0] === 'list') command = 'list'
   else if (positional[0] === 'conformance') command = 'conformance'
+  else if (positional[0] === 'audit') command = 'audit'
+  else if (positional[0] === 'parity') command = 'parity'
+  else if (positional[0] === 'render') command = 'render'
 
   return { command, flags, configPath, positional }
 }
@@ -219,6 +247,10 @@ const writeJson = (payload: unknown): void => {
   process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`)
 }
 
+const writeAgentJson = (payload: unknown): void => {
+  process.stdout.write(`${JSON.stringify(payload)}\n`)
+}
+
 const writeLines = (lines: readonly string[]): void => {
   process.stdout.write(lines.length ? `${lines.join('\n')}\n` : '')
 }
@@ -270,10 +302,23 @@ const formatSearchMatch = (match: {
   readonly path: string
   readonly summary?: string
   readonly score?: number
+  readonly confidence?: string
+  readonly explain?: { readonly matched: Readonly<Record<string, readonly string[]>>; readonly components: Readonly<Record<string, number>>; readonly surfacedBy?: { readonly kind: string; readonly id: string } }
 }): string => {
   const summary = match.summary ? match.summary.replace(/\s+/g, ' ').slice(0, 100) : ''
   const score = typeof match.score === 'number' ? ` score=${match.score}` : ''
-  return `  [${match.type}] ${match.id}${score}\n    ${match.path}${summary ? `\n    ${summary}` : ''}`
+  const confidence = match.confidence ? ` confidence=${match.confidence}` : ''
+  const lines = [`  [${match.type}] ${match.id}${score}${confidence}`, `    ${match.path}`, ...(summary ? [`    ${summary}`] : [])]
+  if (match.explain) {
+    // Every component with a contribution, so a wrong ranking is reportable with numbers.
+    const parts = Object.entries(match.explain.components).filter(([name, value]) => value !== 0 && name !== 'prior').map(([name, value]) => `${name}=${value}`)
+    if (match.explain.components.prior !== undefined && match.explain.components.prior !== 1) parts.push(`prior=×${match.explain.components.prior}`)
+    const matched = Object.entries(match.explain.matched).map(([field, terms]) => `${field}: ${terms.join(', ')}`)
+    lines.push(`    why: ${parts.join(' ') || 'no scoring component'}`)
+    if (matched.length) lines.push(`    matched: ${matched.join(' | ')}`)
+    if (match.explain.surfacedBy) lines.push(`    via: ${match.explain.surfacedBy.kind} from ${match.explain.surfacedBy.id}`)
+  }
+  return lines.join('\n')
 }
 
 const writeTextSearch = (
@@ -367,7 +412,7 @@ const writeAsk = (
 }
 
 const readIndexedDoc = (root: string, config: DocBridgeConfigV1, idOrPath: string): string => {
-  const index = loadDocBridgeIndex(root, config)
+  const index = loadFreshDocBridgeIndex(root, config)
   const entry = index.knowledge.find((doc) => doc.id === idOrPath || doc.path === idOrPath)
   if (!entry) throw new Error(`Unknown indexed doc "${idOrPath}". Try: search ${idOrPath}`)
 
@@ -380,7 +425,7 @@ const readIndexedDoc = (root: string, config: DocBridgeConfigV1, idOrPath: strin
 }
 
 const runAskRepl = async (root: string, config: DocBridgeConfigV1): Promise<number> => {
-  const index = loadDocBridgeIndex(root, config)
+  const index = loadFreshDocBridgeIndex(root, config)
   const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true })
   try {
     for (;;) {
@@ -465,7 +510,7 @@ const workflowOptions = (
   root: string,
   config: DocBridgeConfigV1,
   sourceRevision: string,
-  stage: 'collect' | 'normalize' | 'reconcile' | 'evaluate' | 'report',
+  stage: 'collect' | 'normalize' | 'reconcile' | 'enrich' | 'evaluate' | 'report',
   handlers: Parameters<typeof runWorkflow>[0]['handlers'],
   versions?: Pick<Parameters<typeof runWorkflow>[0], 'pipelineVersion' | 'analyzerVersions'>,
 ): Parameters<typeof runWorkflow>[0] => ({
@@ -491,6 +536,12 @@ const documentationInputs = (root: string, snapshot: DiscoverySnapshotV1) => sna
   .filter((entity) => entity.kind === 'document' && entity.path)
   .map((entity) => ({ path: entity.path as string, content: readFileSync(resolve(root, entity.path as string), 'utf8') }))
 
+/** Ownership records as reconciliation sees them, so a path matching nothing gets reported. */
+const ownershipOptions = (config: DocBridgeConfigV1): { readonly ownership?: readonly { readonly id: string; readonly path: string }[] } => {
+  const ownership = Object.entries(config.routing?.options?.ownership ?? {}).map(([id, record]) => ({ id, path: record.path }))
+  return ownership.length ? { ownership } : {}
+}
+
 const reconcileWorkflow = (root: string, config: DocBridgeConfigV1): WorkflowExecutionResult => {
   const scanned = scanWorkflow(root, config)
   const snapshot = parseDiscoverySnapshot(loadWorkflowStepOutput(scanned.stateDir, 'normalize'))
@@ -502,15 +553,51 @@ const reconcileWorkflow = (root: string, config: DocBridgeConfigV1): WorkflowExe
     ...(config.reconciliation?.requiredRelationKinds === undefined ? {} : { requiredRelationKinds: config.reconciliation.requiredRelationKinds }),
     ...(config.reconciliation?.requiredRelationTargets === undefined ? {} : { requiredRelationTargets: config.reconciliation.requiredRelationTargets }),
     ...(config.reconciliation?.includeOrphanedDocuments === undefined ? {} : { includeOrphanedDocuments: config.reconciliation.includeOrphanedDocuments }),
+    ...ownershipOptions(config),
   })
   return runWorkflow(workflowOptions(root, config, snapshot.sourceRevision, 'reconcile', { reconcile: () => report }, { pipelineVersion: snapshot.pipelineVersion, analyzerVersions: snapshot.analyzerVersions }))
 }
 
-const checkWorkflow = (root: string, config: DocBridgeConfigV1): WorkflowExecutionResult => {
-  const reconciled = reconcileWorkflow(root, config)
+/**
+ * Record the overlay as the enrich step of the current run.
+ *
+ * The step's input names the overlay it attaches, not only the report it was made from: a person
+ * approving a proposal changes the overlay without changing the report, and the engine refuses a
+ * step whose input has not moved but whose output has. Keying on the overlay's own hash keeps that
+ * rule honest — same overlay, same artifact; a new overlay, a new one.
+ */
+const attachEnrichmentStage = (root: string, config: DocBridgeConfigV1, report: ReconciliationReportV1, result: EnrichmentRunResult): WorkflowExecutionResult =>
+  runWorkflow({
+    ...workflowOptions(root, config, report.sourceRevision, 'enrich', { enrich: () => result.overlay }, { pipelineVersion: report.pipelineVersion, analyzerVersions: report.analyzerVersions }),
+    inputs: { enrich: { reportHash: report.contentHash, overlayHash: result.overlay.contentHash } },
+  })
+
+/**
+ * The enrich stage, run only on request. Its failure is reported, never propagated: a `check`
+ * that asked for enrichment and did not get it is still a `check`, with the same result.
+ */
+const enrichWorkflow = async (root: string, config: DocBridgeConfigV1, reconciled: WorkflowExecutionResult): Promise<{ readonly status: 'ok' | 'failed'; readonly result?: EnrichmentRunResult; readonly error?: string }> => {
+  try {
+    const snapshot = parseDiscoverySnapshot(loadWorkflowStepOutput(reconciled.stateDir, 'normalize'))
+    const report = parseReconciliationReport(loadWorkflowStepOutput(reconciled.stateDir, 'reconcile'))
+    const result = await runEnrichment({ root, config, snapshot, report })
+    attachEnrichmentStage(root, config, report, result)
+    return { status: 'ok', result }
+  } catch (error) {
+    return { status: 'failed', error: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+const checkWorkflow = (root: string, config: DocBridgeConfigV1, reconciled = reconcileWorkflow(root, config)): WorkflowExecutionResult => {
   const report = parseReconciliationReport(loadWorkflowStepOutput(reconciled.stateDir, 'reconcile'))
   const versions = { pipelineVersion: report.pipelineVersion, analyzerVersions: report.analyzerVersions }
-  runWorkflow(workflowOptions(root, config, report.sourceRevision, 'evaluate', { evaluate: () => evaluateRules(report, { ...(config.rules ? { config: config.rules } : {}) }) }, versions))
+  // `centrality-risk` needs betweenness over the import graph, which only the snapshot can give.
+  const snapshot = parseDiscoverySnapshot(loadWorkflowStepOutput(reconciled.stateDir, 'normalize'))
+  const evaluate = () => evaluateRules(report, {
+    ...(config.rules ? { config: config.rules } : {}),
+    centrality: centrality(snapshot),
+  })
+  runWorkflow(workflowOptions(root, config, report.sourceRevision, 'evaluate', { evaluate }, versions))
   return runWorkflow(workflowOptions(root, config, report.sourceRevision, 'report', { report: ({ input }) => input }, versions))
 }
 
@@ -592,14 +679,85 @@ const runWorkflowCommand = (
   flags: ReadonlySet<string>,
   configPath: string | undefined,
   argv: readonly string[],
-): number => {
+): number | Promise<number> => {
+  /*
+   * Validated before anything runs, and for every path: `--enrich` returns early, and a run that
+   * ends up printing findings must have been allowed to ask for them.
+   */
+  const format = optionValues(argv, '--format')[0]
+  if (format !== undefined && format !== 'json' && format !== 'finding') {
+    process.stderr.write('--format must be json or finding.\n')
+    return 2
+  }
+  if (format === 'finding' && command !== 'check') {
+    process.stderr.write('--format finding is only available for ak-docs check.\n')
+    return 2
+  }
+
+  if (command === 'check' && flags.has('--enrich')) {
+    return (async () => {
+      try {
+        const { config, root } = loadProject(configPath)
+        const reconciled = reconcileWorkflow(root, config)
+        const enrichment = await enrichWorkflow(root, config, reconciled)
+        return finishWorkflowCommand(command, flags, argv, config, root, checkWorkflow(root, config, reconciled), {
+          enrichment: enrichment.status === 'ok' && enrichment.result
+            ? { status: 'ok', overlayHash: enrichment.result.overlay.contentHash, agentCalls: enrichment.result.agentCalls, cacheHits: enrichment.result.cacheHits, accepted: enrichment.result.overlay.accepted.length, pending: enrichment.result.overlay.pending.length, rejected: enrichment.result.overlay.rejected.length }
+            : { status: 'failed', error: enrichment.error },
+        })
+      } catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+        return 2
+      }
+    })()
+  }
   try {
     const { config, root } = loadProject(configPath)
     const result = command === 'scan' ? scanWorkflow(root, config) : command === 'reconcile' ? reconcileWorkflow(root, config) : checkWorkflow(root, config)
-    const output = workflowOutput(result)
+    return finishWorkflowCommand(command, flags, argv, config, root, result, {})
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+    return 2
+  }
+}
+
+const finishWorkflowCommand = (
+  command: 'scan' | 'reconcile' | 'check' | 'map',
+  flags: ReadonlySet<string>,
+  argv: readonly string[],
+  config: DocBridgeConfigV1,
+  root: string,
+  result: WorkflowExecutionResult,
+  extra: Record<string, unknown>,
+): number => {
+  try {
+    const output = { ...workflowOutput(result), ...extra }
     if (command === 'map') output.kind = 'architecture-map'
+    // Read from argv rather than taken as an argument: every caller already passes argv, and the
+    // flag is validated where the command is dispatched.
+    if (optionValues(argv, '--format')[0] === 'finding') {
+      /*
+       * The canonical shape the ecosystem consumes: every reconciliation diagnostic as a `Finding`
+       * with a severity from `SEVERITY_ORDER`. The rule verdict still decides the exit code, so a
+       * dashboard reading findings and a CI job reading the exit code agree on what failed.
+       */
+      const diagnostics = Array.isArray(output.diagnostics) ? (output.diagnostics as Parameters<typeof findingsFromDiagnostics>[0]) : []
+      writeJson({
+        ok: output.ok,
+        runId: output.runId,
+        state: output.state,
+        ...(output.snapshotHash ? { snapshotHash: output.snapshotHash } : {}),
+        ...(output.reportHash ? { reportHash: output.reportHash } : {}),
+        format: 'finding',
+        findings: findingsFromDiagnostics(diagnostics),
+      })
+      const exitCode = output.rules && typeof output.rules === 'object' && 'exitCode' in output.rules && (output.rules as { exitCode?: unknown }).exitCode === 1 ? 1 : 0
+      return result.run.state === 'failed' ? 1 : exitCode
+    }
     if (command === 'map' && flags.has('--html')) {
-      const snapshot = parseDiscoverySnapshot(loadWorkflowStepOutput(result.stateDir, 'normalize'))
+      const observed = parseDiscoverySnapshot(loadWorkflowStepOutput(result.stateDir, 'normalize'))
+      // Accepted proposed relations render as dashed edges; nothing observed is removed or redrawn.
+      const snapshot = config.intelligence?.registry?.enabled ? withAcceptedRelations(observed, readEnrichmentOverlay(root)) : observed
       const report = parseReconciliationReport(loadWorkflowStepOutput(result.stateDir, 'reconcile'))
       const outputPath = optionValues(argv, '--output')[0] ?? '.doc-bridge/report.html'
       const htmlPath = resolve(root, outputPath)
@@ -622,6 +780,187 @@ const runWorkflowCommand = (
   }
 }
 
+const buildDocumentationAuditReport = (root: string, config: DocBridgeConfigV1) => {
+  const scanned = scanWorkflow(root, config)
+  const snapshot = parseDiscoverySnapshot(loadWorkflowStepOutput(scanned.stateDir, 'normalize'))
+  const analysis = applyDocumentationDeclarations(snapshot, documentationInputs(root, snapshot), { agentRoot: config.corpus.agent.root })
+  const reconciliation = reconcileKnowledge(snapshot, analysis.snapshot, {
+    ...(config.reconciliation?.scope === undefined ? {} : { scope: config.reconciliation.scope }),
+    ...(config.reconciliation?.requiredRelationKinds === undefined ? {} : { requiredRelationKinds: config.reconciliation.requiredRelationKinds }),
+    ...(config.reconciliation?.requiredRelationTargets === undefined ? {} : { requiredRelationTargets: config.reconciliation.requiredRelationTargets }),
+    includeOrphanedDocuments: config.reconciliation?.includeOrphanedDocuments ?? true,
+    ...ownershipOptions(config),
+  })
+  return auditDocumentation({
+    root,
+    snapshot,
+    declared: analysis.snapshot,
+    reconciliation,
+    declarationDiagnostics: analysis.diagnostics,
+    ...(config.audit?.documentation ? { config: config.audit.documentation } : {}),
+  })
+}
+
+const BENCH_USAGE = [
+  'Usage: ak-docs bench retrieval <suite.json> [--index <file>] [--baseline <file>] [--limit <n>] [--text|--json]',
+  '       ak-docs bench retrieval <suite.json> --baseline <file> --update-baseline --by <name> [--reason <text>]',
+].join('\n')
+
+const runBenchCommand = (
+  flags: ReadonlySet<string>,
+  positional: readonly string[],
+  configPath: string | undefined,
+  argv: readonly string[],
+): number => {
+  if (positional[1] !== 'retrieval' || !positional[2]) {
+    process.stderr.write(`${BENCH_USAGE}\n`)
+    return 1
+  }
+  try {
+    const { config, root } = loadProject(configPath)
+    const suite = parseRetrievalSuite(JSON.parse(readFileSync(resolve(root, positional[2]), 'utf8')) as unknown)
+
+    const limitOption = optionValues(argv, '--limit')[0]
+    const limit = limitOption === undefined ? undefined : Number(limitOption)
+    if (limit !== undefined && (!Number.isInteger(limit) || limit <= 0)) {
+      throw new Error('--limit must be a positive integer.')
+    }
+
+    if (flags.has('--overlay')) {
+      /*
+       * Does the accepted overlay earn its cost? The same suite over the same snapshot, once with
+       * the overlay projected and once without. A drop in hit@3 exits non-zero: an overlay that
+       * makes retrieval worse is a finding about the agent, not a new baseline.
+       *
+       * Both indexes are projected here, from the snapshot, so this answer needs no index on disk.
+       */
+      const overlay = readEnrichmentOverlay(root)
+      if (!overlay) throw new Error('No enrichment overlay at .doc-bridge/enrich/overlay.json. Run: ak-docs enrich')
+      const stateDir = resolve(root, config.workflow?.stateDir ?? '.doc-bridge/workflow')
+      const snapshot = (() => {
+        try { return parseDiscoverySnapshot(loadWorkflowStepOutput(stateDir, 'normalize')) }
+        catch { return discoverRepository({ root, config }) }
+      })()
+      const delta = measureOverlayRetrievalDelta({ root, config, snapshot, overlay, suite, ...(limit === undefined ? {} : { limit }) })
+      if (wantsTextOutput(flags, config)) writeLines(formatOverlayRetrievalDeltaText(delta))
+      else writeJson({ ok: !delta.regression, overlayDelta: delta })
+      return delta.regression ? 1 : 0
+    }
+
+    const indexOption = optionValues(argv, '--index')[0]
+    const index = indexOption
+      ? parseDocBridgeIndex(JSON.parse(readFileSync(resolve(root, indexOption), 'utf8')) as unknown)
+      : loadFreshDocBridgeIndex(root, config)
+
+    const result: RetrievalBenchResultV1 = runRetrievalBench({
+      index,
+      suite,
+      ...(limit === undefined ? {} : { limit }),
+    })
+
+    const baselineOption = optionValues(argv, '--baseline')[0]
+    const baselinePath = baselineOption ? resolve(root, baselineOption) : undefined
+
+    if (flags.has('--update-baseline')) {
+      const approvedBy = optionValues(argv, '--by')[0]
+      if (!baselinePath) throw new Error('--update-baseline requires --baseline <file>.')
+      if (!approvedBy) throw new Error('--update-baseline requires --by <name>: a baseline is an approved figure, not a side effect of a run.')
+      const reason = optionValues(argv, '--reason')[0]
+      const baseline = createRetrievalBaseline({ result, approvedBy, ...(reason ? { reason } : {}) })
+      mkdirSync(dirname(baselinePath), { recursive: true })
+      writeFileSync(baselinePath, `${JSON.stringify(baseline, null, 2)}\n`, 'utf8')
+      if (wantsTextOutput(flags, config)) {
+        writeLines([...formatRetrievalBenchText(result), `Baseline written: ${relative(root, baselinePath)} (approved by ${approvedBy})`])
+      } else writeJson({ ok: true, result, baseline, baselinePath })
+      return 0
+    }
+
+    if (baselinePath && !existsSync(baselinePath)) {
+      throw new Error(
+        `No baseline at ${relative(root, baselinePath)}. Record the current figures with: ak-docs bench retrieval ${positional[2]} --baseline ${baselineOption} --update-baseline --by <name>`,
+      )
+    }
+    const comparison = baselinePath
+      ? compareRetrievalBaseline(result, parseRetrievalBaseline(JSON.parse(readFileSync(baselinePath, 'utf8')) as unknown))
+      : undefined
+
+    if (wantsTextOutput(flags, config)) {
+      writeLines([...formatRetrievalBenchText(result), ...(comparison ? formatRetrievalComparisonText(comparison) : [])])
+    } else {
+      writeJson({ ok: !comparison?.blocking, result, ...(comparison ? { comparison } : {}) })
+    }
+    return comparison?.blocking ? 1 : 0
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+    return 2
+  }
+}
+
+const runDocumentationAuditCommand = (
+  flags: ReadonlySet<string>,
+  positional: readonly string[],
+  configPath: string | undefined,
+): number => {
+  if (positional[1] !== 'documentation') {
+    process.stderr.write('Usage: ak-docs audit documentation [--text|--json]\n')
+    return 1
+  }
+  try {
+    const { config, root } = loadProject(configPath)
+    const report = buildDocumentationAuditReport(root, config)
+    if (wantsTextOutput(flags, config)) writeLines(formatDocumentationAuditText(report))
+    else writeJson({ ok: report.status !== 'blocked', report })
+    return report.status === 'blocked' ? 1 : 0
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+    return 2
+  }
+}
+
+const RENDER_USAGE = [
+  `Usage: ak-docs render <${RENDER_TEMPLATE_NAMES.join('|')}> [--data <artifact>] [--output <path>] [--print-template] [--json]`,
+  ...RENDER_TEMPLATE_NAMES.map((name) => `  ${name.padEnd(16)} ${RENDER_TEMPLATES[name].description} (--data: ${RENDER_TEMPLATES[name].data})`),
+].join('\n')
+
+const runRenderCommand = (
+  flags: ReadonlySet<string>,
+  positional: readonly string[],
+  configPath: string | undefined,
+  argv: readonly string[],
+): number => {
+  // parseArgs files option values as positionals; the template name is the first one no option consumed.
+  const dataPath = optionValues(argv, '--data')[0]
+  const outputPath = optionValues(argv, '--output')[0]
+  const consumed = new Set([dataPath, outputPath].filter(Boolean))
+  const name = positional.slice(1).find((value) => !consumed.has(value))
+  if (!name || !isRenderTemplateName(name)) {
+    process.stderr.write(`${name ? `Unknown template "${name}".\n` : ''}${RENDER_USAGE}\n`)
+    return 1
+  }
+  try {
+    const { config, root } = loadProject(configPath)
+    if (flags.has('--print-template')) {
+      process.stdout.write(resolveTemplateSource(name, config, root).source)
+      return 0
+    }
+    const result = renderArtifact({ root, config, template: name, ...(dataPath ? { dataPath } : {}) })
+    if (outputPath) {
+      const written = writeRenderedPages(result, resolve(root, outputPath), root)
+      writeJson({ ok: true, template: name, source: result.origin, written })
+      return 0
+    }
+    if (flags.has('--json')) {
+      writeJson({ ok: true, template: name, source: result.origin, pages: result.pages })
+      return 0
+    }
+    process.stdout.write(result.pages.map((page) => page.content).join('\n'))
+    return 0
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+    return 2
+  }
+}
+
 const runRulesCommand = (
   argv: readonly string[],
   flags: ReadonlySet<string>,
@@ -672,7 +1011,7 @@ const runRulesCommand = (
   }
 }
 
-const runFixCommand = (argv: readonly string[], positional: readonly string[], configPath: string | undefined): number => {
+const runFixCommand = async (argv: readonly string[], positional: readonly string[], configPath: string | undefined): Promise<number> => {
   try {
     const { config, root } = loadProject(configPath)
     const action = positional[1]
@@ -693,8 +1032,12 @@ const runFixCommand = (argv: readonly string[], positional: readonly string[], c
     const file = resolve(root, proposalPath)
     const proposal = JSON.parse(readFileSync(file, 'utf8')) as unknown
     const result = action === 'approve' ? approveFixProposal(proposal, optionValues(argv, '--by')[0] ?? 'human') : applyFixProposal(root, proposal, { currentRevision: sourceRevision })
+    // An approval is recorded through the ecosystem gate too, bound to the proposal and its exact content hash.
+    const recorded = action === 'approve' && result.approval
+      ? await recordApproval(root, { id: fixApprovalId(result.proposalId, result.approval.proposalHash), name: FIX_APPROVAL_GATE, payload: { proposalId: result.proposalId, proposalHash: result.approval.proposalHash }, decision: 'approved', by: result.approval.approvedBy })
+      : undefined
     writeFileSync(file, `${JSON.stringify(result, null, 2)}\n`, 'utf8')
-    writeJson({ ok: true, proposal: result, proposalPath: file })
+    writeJson({ ok: true, proposal: result, proposalPath: file, ...(recorded ? { approvalId: recorded.approval.id } : {}) })
     return 0
   } catch (error) {
     process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
@@ -702,17 +1045,128 @@ const runFixCommand = (argv: readonly string[], positional: readonly string[], c
   }
 }
 
+const runEnrichCommand = async (flags: ReadonlySet<string>, positional: readonly string[], argv: readonly string[], configPath: string | undefined): Promise<number> => {
+  try {
+    const { config, root } = loadProject(configPath)
+    const action = positional[1]
+    if (action === 'list') {
+      const review = listEnrichment(root)
+      if (wantsTextOutput(flags, config)) {
+        writeLines(review
+          ? [`Overlay: ${review.overlayHash}`, `Accepted: ${review.accepted.length}  Pending: ${review.pending.length}  Rejected: ${review.rejected.length}`, ...review.pending.map((entry) => `  pending ${entry.proposal.proposalId.slice(0, 16)} ${entry.proposal.kind} ${entry.proposal.entity}${entry.note ? ` (${entry.note})` : ''}`)]
+          : ['No enrichment overlay. Run `ak-docs enrich` first.'])
+      } else writeJson({ ok: true, enrichment: review ?? null })
+      return 0
+    }
+    if (action === 'approve' || action === 'reject') {
+      const proposalId = positional[2]
+      const by = optionValues(argv, '--by')[0]
+      if (!proposalId || !by) throw new Error('Usage: ak-docs enrich approve|reject <proposalId> --by <name> [--reason <text>]')
+      const stateDir = resolve(root, config.workflow?.stateDir ?? '.doc-bridge/workflow')
+      const snapshot = (() => { try { return parseDiscoverySnapshot(loadWorkflowStepOutput(stateDir, 'normalize')) } catch { return undefined } })()
+      const reason = optionValues(argv, '--reason')[0]
+      const decided = await decideEnrichment({ root, proposalId, decision: action === 'approve' ? 'approved' : 'rejected', by, ...(reason ? { reason } : {}), ...(snapshot ? { snapshot } : {}) })
+      const decidedId = 'proposal' in decided.entry ? decided.entry.proposal.proposalId : decided.entry.proposalId
+      if (wantsTextOutput(flags, config)) writeLines([`${action === 'approve' ? 'Approved' : 'Rejected'}: ${decidedId}`, `Approval: ${decided.approvalId} (${decided.gateSource})`, `Overlay: ${decided.overlay.contentHash}`])
+      else writeJson({ ok: true, approvalId: decided.approvalId, gate: decided.gateSource, entry: decided.entry, overlayHash: decided.overlay.contentHash })
+      return 0
+    }
+    if (action !== undefined) throw new Error('Usage: ak-docs enrich [list | approve <proposalId> --by <name> | reject <proposalId> --by <name>] [--json|--text]')
+    const reconciled = reconcileWorkflow(root, config)
+    const snapshot = parseDiscoverySnapshot(loadWorkflowStepOutput(reconciled.stateDir, 'normalize'))
+    const report = parseReconciliationReport(loadWorkflowStepOutput(reconciled.stateDir, 'reconcile'))
+    const result = await runEnrichment({ root, config, snapshot, report })
+    attachEnrichmentStage(root, config, report, result)
+    /*
+     * The retrieval delta is opt-in: it runs the golden suite twice, which is the right cost for
+     * an answer about whether the overlay helped and the wrong cost for every routine run.
+     */
+    const delta = flags.has('--retrieval-delta')
+      ? measureOverlayRetrievalDelta({
+          root,
+          config,
+          snapshot,
+          overlay: result.overlay,
+          suite: parseRetrievalSuite(JSON.parse(readFileSync(resolve(root, config.retrieval?.benchmark?.suite ?? DEFAULT_RETRIEVAL_SUITE), 'utf8')) as unknown),
+        })
+      : undefined
+    if (wantsTextOutput(flags, config)) writeLines([...formatEnrichmentText(result), ...(delta ? formatOverlayRetrievalDeltaText(delta) : [])])
+    else writeJson({
+      ok: !delta?.regression,
+      overlayPath: result.overlayPath,
+      overlayHash: result.overlay.contentHash,
+      baseSnapshotHash: result.overlay.baseSnapshotHash,
+      roles: result.roles,
+      packs: result.packs,
+      agentCalls: result.agentCalls,
+      cacheHits: result.cacheHits,
+      rerun: result.rerun,
+      expired: result.expired,
+      stats: result.overlay.stats,
+      cost: enrichmentCost(result.overlay.stats),
+      stability: result.stability,
+      accepted: result.overlay.accepted.length,
+      pending: result.overlay.pending.length,
+      rejected: result.overlay.rejected.length,
+      ...(delta ? { retrievalDelta: delta } : {}),
+    })
+    return delta?.regression ? 1 : 0
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+    return 2
+  }
+}
+
+/** Where the claim registry lives unless a caller points somewhere else. */
+export const DEFAULT_PUBLIC_CLAIMS = 'docs/parity/public-claims-v1.json'
+
+/**
+ * `ak-docs parity`: what this repository says in public, against what it can prove.
+ *
+ * The gate fails on a blocking finding — a stale or contradictory claim nobody accepted — and
+ * leaves warnings and unresolved claims visible without failing, so a repository can adopt the
+ * registry one claim at a time. The doctor runs only when a claim asks for one of its figures:
+ * measuring it costs an index and a benchmark, and most registries never need it.
+ */
+const runParityCommand = (flags: ReadonlySet<string>, configPath: string | undefined, argv: readonly string[]): number => {
+  try {
+    const { config, root } = loadProject(configPath)
+    const claimsPath = optionValues(argv, '--claims')[0] ?? DEFAULT_PUBLIC_CLAIMS
+    const registry = parsePublicClaims(JSON.parse(readFileSync(resolve(root, claimsPath), 'utf8')) as unknown)
+    const snapshot = discoverRepository({ root, config })
+    const doctor = registry.claims.some((claim) => claim.evidence.kind === 'doctor-metric') ? runDoctor(root, config) : undefined
+    const report = checkPublicParity({
+      root,
+      config,
+      registry,
+      snapshot,
+      ...(doctor ? { doctor } : {}),
+      project: { name: snapshot.project.name },
+      sourceRevision: snapshot.sourceRevision,
+      sourceRevisionKind: snapshot.sourceRevisionKind,
+    })
+    if (wantsTextOutput(flags, config)) writeLines(formatPublicParityText(report))
+    else writeJson({ ok: report.metrics.blocking === 0, parity: report })
+    return report.metrics.blocking ? 1 : 0
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+    return 2
+  }
+}
+
 const runSuggestCommand = async (flags: ReadonlySet<string>, configPath: string | undefined): Promise<number> => {
   try {
     const { config, root } = loadProject(configPath)
     const stateDir = resolve(root, config.workflow?.stateDir ?? '.doc-bridge/workflow')
     const snapshot = parseDiscoverySnapshot(loadWorkflowStepOutput(stateDir, 'normalize'))
     const report = parseReconciliationReport(loadWorkflowStepOutput(stateDir, 'reconcile'))
-    const adapter = createRegistryAgentAdapter(root, config, await loadRegistryAgentRunner(root, config))
-    const proposal = await adapter.run(snapshot, report)
+    const runner = config.intelligence?.registry?.cli ? undefined : await loadRegistryAgentRunner(root, config)
+    const adapter = createRegistryAgentAdapter(root, config, runner)
+    const documentation = flags.has('--documentation') ? buildDocumentationAuditReport(root, config) : undefined
+    const proposal = await adapter.run(snapshot, report, undefined, documentation)
     const proposalPath = persistRegistryAgentProposal(stateDir, proposal)
-    if (flags.has('--text')) writeLines([`Agent: ${adapter.metadata.id}`, `Proposal: ${proposal.proposalId}`, `Hash: ${proposal.contentHash}`, `Saved: ${proposalPath}`])
-    else writeJson({ ok: true, proposal, proposalPath })
+    if (flags.has('--text')) writeLines([`Agent: ${adapter.metadata.id}`, ...(documentation ? [`Documentation audit: ${documentation.contentHash}`] : []), `Proposal: ${proposal.proposalId}`, `Hash: ${proposal.contentHash}`, `Saved: ${proposalPath}`])
+    else writeJson({ ok: true, ...(documentation ? { documentationAuditHash: documentation.contentHash } : {}), proposal, proposalPath })
     return 0
   } catch (error) {
     process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
@@ -901,6 +1355,143 @@ const registryTopology = () => ({
   mergePolicy: { autoMerge: false, requiresHuman: true },
 })
 
+const runStudyCommand = async (flags: ReadonlySet<string>, positional: readonly string[], argv: readonly string[], configPath: string | undefined): Promise<number> => {
+  const action = positional[1]
+  const inputPath = positional[2]
+  if (!inputPath || !['protocol', 'history', 'tasks', 'select', 'plan', 'providers', 'run', 'adjudicate', 'ledger', 'metrics', 'verification', 'expectations'].includes(action ?? '')) {
+    process.stderr.write('Usage: ak-docs study protocol|history|tasks|select|plan|providers|run|adjudicate|ledger|metrics|verification|expectations <artifact.json> [--protocol <protocol.json>] [--providers <provider-cli.json>] [--adjudicator <provider-cli.json>] [--repositories <repositories.json>] [--ledger <ledger.json>] [--output <ledger.json>] [--run-id <id>] [--limit <n>] [--round <id>] [--dry-run] [--baseline-round <id>] [--current-round <id>] [--expectations <expectations.json>] [--index <index.json>] [--repository <id>] [--text|--json]\n')
+    return 1
+  }
+  try {
+    if (action === 'expectations') {
+      /*
+       * The mechanical half of the study, checked by the same benchmark that gates this
+       * repository's retrieval. The suite carries opaque references; the local expectations file
+       * resolves them to entities and documents, which is why it is never published.
+       */
+      const expectationsPath = optionValues(argv, '--expectations')[0]
+      if (!expectationsPath) throw new Error('Study expectations require --expectations <expectations.json>.')
+      const suite = parseStudyTaskSuite(JSON.parse(readFileSync(resolve(inputPath), 'utf8')) as unknown)
+      const expectations = parseStudyExpectations(JSON.parse(readFileSync(resolve(expectationsPath), 'utf8')) as unknown)
+      const repositoryId = optionValues(argv, '--repository')[0]
+      const indexOption = optionValues(argv, '--index')[0]
+      const { config, root } = loadProject(configPath)
+      const index = indexOption
+        ? parseDocBridgeIndex(JSON.parse(readFileSync(resolve(root, indexOption), 'utf8')) as unknown)
+        : loadFreshDocBridgeIndex(root, config)
+      const check = checkStudyExpectations({ taskSuite: suite, expectations, index, ...(repositoryId ? { repositoryId } : {}) })
+      if (flags.has('--text')) writeLines(formatStudyExpectationsText(check))
+      else writeJson({ ok: check.ok, expectations: check })
+      return check.ok ? 0 : 1
+    }
+    if (action === 'run') {
+      const taskSuitePath = positional[3]
+      const providersPath = optionValues(argv, '--providers')[0]
+      const repositoriesPath = optionValues(argv, '--repositories')[0]
+      const ledgerPath = optionValues(argv, '--ledger')[0]
+      if (!taskSuitePath || !providersPath || !repositoriesPath || !ledgerPath) throw new Error('Study run requires a task suite, --providers, --repositories, and --ledger.')
+      const summary = await runControlledStudy({
+        plan: parseControlledStudyRunPlan(JSON.parse(readFileSync(resolve(inputPath), 'utf8')) as unknown),
+        suite: parseStudyTaskSuite(JSON.parse(readFileSync(resolve(taskSuitePath), 'utf8')) as unknown),
+        providers: parseStudyProviderCliConfig(JSON.parse(readFileSync(resolve(providersPath), 'utf8')) as unknown),
+        repositories: parseStudyRepositoryConfig(JSON.parse(readFileSync(resolve(repositoriesPath), 'utf8')) as unknown),
+        ledgerPath: resolve(ledgerPath),
+        ...(optionValues(argv, '--round')[0] === undefined ? {} : { round: optionValues(argv, '--round')[0] }),
+        ...(flags.has('--dry-run') ? { dryRun: true } : {}),
+      })
+      if (flags.has('--text')) writeLines(formatControlledStudyRunText(summary))
+      else writeJson({ ok: summary.status === 'dry-run' || summary.status === 'completed', summary })
+      return 0
+    }
+    if (action === 'adjudicate') {
+      const taskSuitePath = positional[3]
+      const adjudicatorConfigPath = optionValues(argv, '--adjudicator')[0]
+      const outputPath = optionValues(argv, '--output')[0]
+      if (!taskSuitePath || !adjudicatorConfigPath || !outputPath) throw new Error('Study adjudication requires a task suite, --adjudicator with an adjudicator, and --output.')
+      const config = parseStudyProviderCliConfig(JSON.parse(readFileSync(resolve(adjudicatorConfigPath), 'utf8')) as unknown)
+      if (!config.adjudicator) throw new Error('Study provider config must declare an adjudicator.')
+      const ledger = parseControlledStudyLedger(JSON.parse(readFileSync(resolve(inputPath), 'utf8')) as unknown)
+      const suite = parseStudyTaskSuite(JSON.parse(readFileSync(resolve(taskSuitePath), 'utf8')) as unknown)
+      const limitValue = optionValues(argv, '--limit')[0]
+      const limit = limitValue === undefined ? undefined : Number(limitValue)
+      const offsetValue = optionValues(argv, '--offset')[0]
+      const offset = offsetValue === undefined ? undefined : Number(offsetValue)
+      const result = await independentlyAdjudicateStudyLedger({ ledger, taskSuite: suite, config: config.adjudicator, configurationHash: config.contentHash, cwd: process.cwd(), maxRuntimeMs: suite.maxRuntimeMsPerTask, ...(optionValues(argv, '--run-id')[0] === undefined ? {} : { runId: optionValues(argv, '--run-id')[0] }), ...(offset === undefined ? {} : { offset }), ...(limit === undefined ? {} : { limit }) })
+      persistIndependentlyAdjudicatedLedger(outputPath, result)
+      if (flags.has('--text')) writeLines([`Adjudicated observations: ${result.observations.length}`, `Ledger: ${resolve(outputPath)}`, `Content hash: ${result.contentHash}`])
+      else writeJson({ ok: true, ledger: result })
+      return 0
+    }
+    const input = JSON.parse(readFileSync(resolve(inputPath), 'utf8')) as unknown
+    if (action === 'protocol') {
+      const protocol = parseStudyProtocol(input)
+      if (flags.has('--text')) writeLines(formatStudyProtocolText(protocol))
+      else writeJson({ ok: true, protocol })
+      return 0
+    }
+    if (action === 'tasks') {
+      const suite = parseStudyTaskSuite(input)
+      if (flags.has('--text')) writeLines(formatStudyTaskSuiteText(suite))
+      else writeJson({ ok: true, suite })
+      return 0
+    }
+    if (action === 'select') {
+      const suite = parseStudyTaskSuite(input)
+      const executions = selectTaskExecutions(suite)
+      if (flags.has('--text')) writeLines([`Selected executions: ${executions.length}`, `First execution: ${executions[0]?.taskId ?? 'none'} / ${executions[0]?.variantId ?? 'none'}`])
+      else writeJson({ ok: true, executions })
+      return 0
+    }
+    if (action === 'plan') {
+      const plan = parseControlledStudyRunPlan(input)
+      if (flags.has('--text')) writeLines(formatControlledStudyRunPlanText(plan))
+      else writeJson({ ok: true, plan })
+      return 0
+    }
+    if (action === 'providers') {
+      const providers = parseStudyProviderCliConfig(input)
+      if (flags.has('--text')) writeLines(formatStudyProviderCliText(providers))
+      else writeJson({ ok: true, providers })
+      return 0
+    }
+    if (action === 'ledger') {
+      const ledger = parseControlledStudyLedger(input)
+      if (flags.has('--text')) writeLines([`Ledger: ${ledger.ledgerVersion}`, `Observations: ${ledger.observations.length}`, `Content hash: ${ledger.contentHash}`])
+      else writeJson({ ok: true, ledger })
+      return 0
+    }
+    if (action === 'metrics') {
+      const ledger = parseControlledStudyLedger(input)
+      const baselineRound = optionValues(argv, '--baseline-round')[0]
+      const currentRound = optionValues(argv, '--current-round')[0]
+      const baselineRunId = optionValues(argv, '--baseline-run-id')[0]
+      const currentRunId = optionValues(argv, '--current-run-id')[0]
+      const report = calculateStudyMetrics(ledger.observations, { ...(baselineRound === undefined ? {} : { baselineRound }), ...(currentRound === undefined ? {} : { currentRound }), ...(baselineRunId === undefined ? {} : { baselineRunId }), ...(currentRunId === undefined ? {} : { currentRunId }) })
+      if (flags.has('--text')) writeLines(formatStudyMetricsText(report))
+      else writeJson({ ok: true, report })
+      return report.comparisons.some((comparison) => comparison.status === 'regressed') && !flags.has('--allow-regressions') ? 1 : 0
+    }
+    if (action === 'verification') {
+      const binding = parseStudyVerificationBinding(input)
+      if (flags.has('--text')) writeLines(formatStudyVerificationText(binding))
+      else writeJson({ ok: true, binding })
+      return 0
+    }
+    const registry = parseHistoricalEvidenceRegistry(input)
+    const protocolPath = optionValues(argv, '--protocol')[0]
+    if (protocolPath) {
+      const protocol = parseStudyProtocol(JSON.parse(readFileSync(resolve(protocolPath), 'utf8')) as unknown)
+      validateHistoricalEvidenceRegistry(registry, protocol)
+    }
+    if (flags.has('--text')) writeLines(formatHistoricalEvidenceText(registry))
+    else writeJson({ ok: true, registry })
+    return 0
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+    return 2
+  }
+}
+
 export const runCli = (argv: readonly string[]): number | undefined | Promise<number> => {
   const { command, flags, configPath, positional } = parseArgs(argv)
 
@@ -990,12 +1581,19 @@ export const runCli = (argv: readonly string[]): number | undefined | Promise<nu
     }
   }
 
+  if (command === 'study') return runStudyCommand(flags, positional, argv, configPath)
+
   if (command === 'scan' || command === 'reconcile' || command === 'check' || command === 'map') {
     return runWorkflowCommand(command, flags, configPath, argv)
   }
+  if (command === 'audit') return runDocumentationAuditCommand(flags, positional, configPath)
+  if (command === 'parity') return runParityCommand(flags, configPath, argv)
+  if (command === 'render') return runRenderCommand(flags, positional, configPath, argv)
+  if (command === 'bench') return runBenchCommand(flags, positional, configPath, argv)
 
   if (command === 'fix') return runFixCommand(argv, positional, configPath)
   if (command === 'suggest') return runSuggestCommand(flags, configPath)
+  if (command === 'enrich') return runEnrichCommand(flags, positional, argv, configPath)
 
   if (command === 'init') {
     const root = process.cwd()
@@ -1066,7 +1664,7 @@ export const runCli = (argv: readonly string[]): number | undefined | Promise<nu
         writeJson({ ok: true, count: candidates.length, candidates })
         return 0
       }
-      const index = loadDocBridgeIndex(root, config)
+      const index = loadFreshDocBridgeIndex(root, config)
       const classifications = classifyMemoryCandidates(candidates, index)
       if (positional[1] === 'classify') {
         writeJson({ ok: true, count: classifications.length, classifications })
@@ -1124,7 +1722,7 @@ export const runCli = (argv: readonly string[]): number | undefined | Promise<nu
     }
     try {
       const { config, root } = loadProject(configPath)
-      const index = loadDocBridgeIndex(root, config)
+      const index = loadFreshDocBridgeIndex(root, config)
       const draft = draftMemoryPromotion(classifyMemoryCandidates(ingestMemoryCandidates(root), index))
       writeJson({
         ...draft,
@@ -1329,9 +1927,10 @@ export const runCli = (argv: readonly string[]): number | undefined | Promise<nu
     }
     try {
       const { config, root } = loadProject(configPath)
-      const index = loadDocBridgeIndex(root, config)
-      const result = runQuery(index, config, { kind, id, agent: flags.has('--agent') })
+      const index = loadFreshDocBridgeIndex(root, config)
+      const result = runQuery(index, config, { kind, id, agent: flags.has('--agent') }, { root })
       if (wantsTextOutput(flags, config)) writeTextQuery(result)
+      else if (flags.has('--agent')) writeAgentJson(result)
       else writeJson(result)
       return 0
     } catch (error) {
@@ -1348,12 +1947,23 @@ export const runCli = (argv: readonly string[]): number | undefined | Promise<nu
     }
     try {
       const { config, root } = loadProject(configPath)
-      const index = loadDocBridgeIndex(root, config)
+        const index = loadFreshDocBridgeIndex(root, config)
+      const explain = flags.has('--explain')
       if (flags.has('--agent')) {
-        const result = runQuery(index, config, { kind: 'search', term, agent: true })
-        writeJson(result)
+        const mode = optionValues(argv, '--mode')[0]
+        const budgetValue = optionValues(argv, '--context-budget')[0]
+        const contextBudgetTokens = budgetValue === undefined ? undefined : Number(budgetValue)
+        const result = runQuery(index, config, {
+          kind: 'search',
+          term,
+          agent: true,
+          ...(explain ? { explain: true } : {}),
+          ...(mode === undefined ? {} : { mode: mode as 'discovery' | 'editing' | 'debugging' | 'documentation' }),
+          ...(contextBudgetTokens === undefined ? {} : { contextBudgetTokens }),
+        })
+        writeAgentJson(result)
       } else {
-        const matches = searchIndex(index, term)
+        const matches = searchIndex(index, term, 20, explain ? { explain: true } : {})
         if (wantsTextOutput(flags, config)) writeTextSearch(term, matches)
         else writeJson({ term, count: matches.length, matches })
       }
@@ -1377,7 +1987,7 @@ export const runCli = (argv: readonly string[]): number | undefined | Promise<nu
     return (async () => {
       try {
         const { config, root } = loadProject(configPath)
-        const index = loadDocBridgeIndex(root, config)
+        const index = loadFreshDocBridgeIndex(root, config)
         writeJson({ query, chunks: await retrieveHybridChunks(root, config, index, query) })
         return 0
       } catch (error) {
@@ -1396,7 +2006,7 @@ export const runCli = (argv: readonly string[]): number | undefined | Promise<nu
     return (async () => {
       try {
         const { config, root } = loadProject(configPath)
-        const index = loadDocBridgeIndex(root, config)
+        const index = loadFreshDocBridgeIndex(root, config)
         const rag = await createDocBridgeRag(root, config, index)
         if (action === 'ingest') {
           const result = await rag.ingest()
@@ -1433,7 +2043,7 @@ export const runCli = (argv: readonly string[]): number | undefined | Promise<nu
           )
           return 1
         }
-        const index = loadDocBridgeIndex(root, config)
+        const index = loadFreshDocBridgeIndex(root, config)
         await startInkChat(root, config, index)
         return 0
       } catch (error) {
@@ -1465,7 +2075,7 @@ export const runCli = (argv: readonly string[]): number | undefined | Promise<nu
         }
         return (async () => {
           try {
-            const index = loadDocBridgeIndex(root, config)
+            const index = loadFreshDocBridgeIndex(root, config)
             const result = await runChatOnce(root, config, index, question)
             writeLines([result.content])
             return 0
@@ -1484,7 +2094,7 @@ export const runCli = (argv: readonly string[]): number | undefined | Promise<nu
         process.stderr.write('Usage: ak-docs ask <question>, or run ak-docs ask in an interactive terminal.\n')
         return 1
       }
-      const index = loadDocBridgeIndex(root, config)
+      const index = loadFreshDocBridgeIndex(root, config)
       writeAsk(question, searchIndex(index, question, 8), index, config)
       return 0
     } catch (error) {
@@ -1501,7 +2111,7 @@ export const runCli = (argv: readonly string[]): number | undefined | Promise<nu
     }
     try {
       const { config, root } = loadProject(configPath)
-      const index = loadDocBridgeIndex(root, config)
+      const index = loadFreshDocBridgeIndex(root, config)
 
       if (kind === 'packages') {
         const items = index.lookup?.packages ?? []