@agentskit/doc-bridge 1.7.45 → 1.9.0

package/docs/spec/cli.md

@@ -5,7 +5,7 @@ description: Complete command reference for indexing, querying, gates, doctor, m
 
 # ak-docs CLI
 
-Command-line interface for **`@agentskit/doc-bridge`**. The npm package is scoped; the **only published binary** is `ak-docs`.
+Command-line interface for **`@agentskit/doc-bridge`**. The package publishes two executables: `ak-docs` is the product CLI and `ak-verify` is the verification-harness wrapper.
 
 ## Naming
 
@@ -13,11 +13,17 @@ Command-line interface for **`@agentskit/doc-bridge`**. The npm package is scope
 |------|------|
 | npm package | `@agentskit/doc-bridge` |
 | CLI binary | `ak-docs` |
-| Config file | `doc-bridge.config.ts` |
+| Verification binary | `ak-verify` |
+| Primary config filename | `doc-bridge.config.ts` |
 | GitHub repo | `AgentsKit-io/doc-bridge` |
 
 Install the package, run `ak-docs` — not `doc-bridge` on the shell.
 
+The primary filename is shown for readability. Discovery also accepts
+`doc-bridge.config.mts`, `.js`, `.mjs`, `.json`, and the `docBridge` field in
+`package.json`; see the [configuration contract](./config-v1.md#discovery-order)
+for the authoritative order.
+
 ## Why a separate binary
 
 | Choice | Rationale |
@@ -39,7 +45,8 @@ pnpm add -D @agentskit/doc-bridge
 {
   "name": "@agentskit/doc-bridge",
   "bin": {
-    "ak-docs": "./bin/ak-docs.js"
+    "ak-docs": "./bin/ak-docs.js",
+    "ak-verify": "./bin/ak-verify.js"
   }
 }
 ```
@@ -58,8 +65,8 @@ pnpm add -D @agentskit/doc-bridge
 | `ak-docs doctor [--text] [--badge] [--write-badge]` | Coverage score, gaps, gates, shields.io badge |
 | `ak-docs index` | Build `DocBridgeIndex` + optional `llms.txt` |
 | `ak-docs index --watch` | Debounced rebuild on agent/human doc changes |
-| `ak-docs query <target> [--agent] [--text]` | Resolve package/module/intent/change → handoff JSON or text |
-| `ak-docs search <term> [--agent] [--text]` | Full-text search over index |
+| `ak-docs query <target> [--agent] [--text]` | Resolve package/area/module/document/intent/change → handoff JSON or text |
+| `ak-docs search <term> [--agent] [--explain] [--mode=<mode>] [--context-budget=<tokens>] [--text]` | Ranked search over the retrieval projection; `--explain` names every scoring component and the matched terms, and agent mode bounds the context it returns to a task-specific budget |
 | `ak-docs ask <question>` | Human-readable local consult mode: search + best match + next handoff commands; no LLM |
 | `ak-docs ask` | Interactive local REPL in a TTY; commands: `search <term>`, `read <id-or-path>`, `open <id-or-path>`, `resolve <id>`, `gate [id]`, `exit` |
 | `ak-docs retrieve <query>` | Hybrid local/federated retriever chunks; deterministic local first |
@@ -68,13 +75,26 @@ pnpm add -D @agentskit/doc-bridge
 | `ak-docs memory ingest` | Normalize local memory files (`.agent-memory/**/*.md`, `.cursor/rules/*.mdc`) into `MemoryCandidate[]` |
 | `ak-docs memory classify` | Deterministically route candidates to agent/human/playbook/discard |
 | `ak-docs memory promote` | Build draft-only promotion body with safety scan; never auto-merges |
-| `ak-docs memory promote --pr [--dry-run] [--force]` | Write draft + open GitHub draft PR via `gh` |
+| `ak-docs memory promote --pr --dry-run [--force]` | Write a local draft and print the `git`/`gh` commands; does not execute them |
+| `ak-docs memory promote --pr [--force]` | Write the draft, commit/push it, and open a GitHub draft PR via `gh` |
 | `ak-docs registry topology` | Print the `doc-curator` topology for AgentsKit/Registry composition |
+| `ak-docs suggest [--documentation] --json` | Run the configured Registry agent module or CLI and persist its typed proposal; optionally include the bounded documentation-audit context |
+| `ak-docs enrich [--json\|--text]` | Run the enrichment stage: context packs to the configured Registry roles, deterministic validators, the overlay at `.doc-bridge/enrich/overlay.json`. Zero agent calls over an unchanged repository |
+| `ak-docs enrich list \| approve <proposalId> --by <name> \| reject <proposalId> --by <name> [--reason <text>]` | Review pending enrichment proposals; a decision is recorded through the ecosystem approval gate under `.doc-bridge/approvals/`, bound to the proposal id and the target content hash |
+| `ak-docs check --enrich` | `check` with the `enrich` stage between `reconcile` and `evaluate`; a failed enrichment is reported in `enrichment` and never changes the check result |
+| `ak-docs enrich --retrieval-delta [--json\|--text]` | `enrich`, then the golden suite with and without the accepted overlay on the same snapshot. Exits 1 when the overlay lowers hit@3 |
+| `ak-docs bench retrieval <suite.json> --overlay [--json\|--text]` | The overlay on disk measured against a suite: both indexes projected from one snapshot, no index on disk required. Exits 1 on a hit@3 regression |
+| `ak-docs study expectations <task-suite.json> --expectations <local.json> [--index <index.json>] [--repository <id>]` | Check a study round's mechanical retrieval expectations through the benchmark. Exits 1 when a reference does not resolve or a case misses |
 | `ak-docs playbook draft` | Build a draft Playbook feedback payload from local memory candidates |
 | `ak-docs playbook pattern [--text]` | Export published Doc Bridge Playbook pattern (OKF markdown / JSON) |
 | `ak-docs list <kind> [--text]` | List packages, apps, intents, … |
-| `ak-docs gate run [index-freshness]` | Check generated index freshness |
+| `ak-docs gate run [gate-id]` | Run resolved configured documentation gates; an optional id narrows the run to one gate |
 | `ak-docs conformance run documentation-standard-v1 [--text\|--json]` | Run the stable ecosystem documentation profile with evidence and remediation |
+| `ak-docs audit documentation [--text\|--json]` | Measure documentation quality and compare documentation claims with the observed project graph |
+| `ak-docs parity [--claims <file>] [--json\|--text]` | Check the public claim registry against what the repository can prove: stale, missing, contradictory and not-analyzed claims, each with an owner, an exact source and a remediation. Exits 1 on a blocking finding |
+| `ak-docs render <llms.txt\|area\|ownership\|change-digest\|overlay-review> [--data <artifact>] [--output <path>] [--print-template] [--json]` | Render the canonical artifacts as Markdown from bundled or project templates (`render.templates`); deterministic, no agent. See [Render v1](./render-v1.md) |
+| `ak-docs bench retrieval <suite.json> [--index <file>] [--baseline <file>] [--limit <n>] [--text\|--json]` | Measure retrieval quality against a golden query suite: hit@1, hit@3, mean reciprocal rank, context bytes and approximate tokens. Exits non-zero on a hit@3 regression against the baseline. No model, no network |
+| `ak-docs bench retrieval <suite.json> --baseline <file> --update-baseline --by <name> [--reason <text>]` | Record the measured figures as the approved baseline. A normal run never writes one |
 | `ak-docs mcp` | Start MCP server (stdio default) |
 | `ak-docs mcp install --cursor \| --claude` | Write MCP server config for Cursor or Claude Desktop |
 
@@ -94,7 +114,7 @@ Peers: `@agentskit/rag`, `@agentskit/ink`, `@agentskit/adapters`, `@agentskit/me
 | Flag | Description |
 |------|-------------|
 | `--config <path>` | Config file (default: auto-discover) |
-| `--json` / `--text` | Output format for non-agent commands (default: json); `--agent` always emits agent JSON |
+| `--json` / `--text` | Output format for non-agent commands (default: formatted json); `--agent` emits compact machine-readable JSON, while `--text` remains human-readable |
 | `--chat` | Request planned intelligence-backed ask mode; errors clearly until `intelligence.adapter` and RAG/chat support are configured |
 | `--help` | Command help |
 
@@ -104,7 +124,7 @@ Peers: `@agentskit/rag`, `@agentskit/ink`, `@agentskit/adapters`, `@agentskit/me
 ak-docs index
 ak-docs query ownership auth --agent
 ak-docs query ownership auth --text
-ak-docs search "sidecar transport" --agent
+ak-docs search "sidecar transport" --agent --mode=discovery --context-budget=256
 ak-docs list packages --text
 ak-docs gate run
 ak-docs mcp
@@ -141,7 +161,7 @@ CLI is a thin wrapper over the same exports.
 pnpm docs:internal:query …   # private dogfood wrapper → ak-docs query …
 ```
 
-Private repo wrappers stay private. `ak-docs` is the only public binary.
+`ak-docs` is the primary product CLI. `ak-verify` is the portable verification-harness entry point used to prove repository work against a declared contract.
 
 ## See also
 

package/docs/spec/config-v1.md

@@ -5,7 +5,7 @@ description: Configure documentation corpora, ownership routing, conformance, an
 
 # doc-bridge config contract v1
 
-`doc-bridge.config.ts` (or `.js`, `.mjs`, `.json`, or `package.json` → `docBridge`) is the alpha integration point for any project. Layer 0 fields are sufficient to run `index`, `query`, and MCP without an LLM.
+`doc-bridge.config.ts` (or `.js`, `.mjs`, `.json`, or `package.json` → `docBridge`) is the v1 integration point for any project. Layer 0 fields are sufficient to run `index`, `query`, and MCP without an LLM.
 
 Reconciliation summaries also expose deterministic `diagnosticsByCode` and
 `diagnosticsByStatus` maps. They are additive rollups for agents and dashboards;
@@ -36,7 +36,7 @@ doc-bridge.config.json
 package.json → "docBridge" field (subset, JSON only)
 ```
 
-TypeScript/JavaScript configs are static in v0.1 alpha: `defineConfig` imports are supported, but arbitrary imports are not. YAML config files are planned.
+TypeScript/JavaScript configs are static in v1: `defineConfig` imports are supported, but arbitrary imports are not. YAML config files are planned.
 
 Dynamic-loading coverage is evidence-backed. Literal strings, constant aliases,
 parenthesized strings, and string concatenations are resolved without executing
@@ -88,9 +88,15 @@ export default {
   /** Optional reconciliation scope and orphan-document policy */
   reconciliation?: ReconciliationConfig
 
+  /** Optional retrieval tuning: corpus projection, field weights, BM25 parameters */
+  retrieval?: RetrievalConfig
+
   /** Optional resumable workflow state */
   workflow?: WorkflowConfig
 
+  /** Optional project templates for `ak-docs render`, by template name */
+  render?: RenderConfig
+
   /** Optional report publication privacy; private is the default */
   report?: { privacy?: 'private' | 'anonymized' }
 } satisfies DocBridgeConfigV1
@@ -301,7 +307,9 @@ by Nx plugins are intentionally not inferred by this read-only adapter.
 | Screen / feature | `id` in `screens/` or `features/` | MDX slug |
 | Flow / recipe | `id` in `flows/` | docs slug |
 
-Plugins document their join convention; gates fail on orphan links.
+Plugins document their join convention. The orphan-link gate only runs when the
+corresponding gate is enabled (for example, `human-guide-links`); the `minimal`
+preset does not enable that gate.
 
 ---
 
@@ -347,14 +355,14 @@ type GateId =
 | Preset | Gates |
 |--------|-------|
 | `minimal` | `index-freshness` |
-| `standard` | + `human-guide-links` in v0.1 alpha |
-| `strict` | + `okf-type` in v0.1 alpha |
+| `standard` | + `human-guide-links` in v1 |
+| `strict` | + `okf-type` in v1 |
 
 Implemented gates include `index-freshness`, `human-guide-links`, `okf-type`, `docs-style`, and the opt-in `documentation-standard-v1`. For v1 compatibility, `link-rot`, `routing-currency`, and `bootstrap-size` remain accepted as reserved IDs; including one emits `AK_DOCS_RESERVED_GATE` and does not claim that the gate ran. Unknown IDs are rejected.
 
 ### Structural vs style validation
 
-Alpha gates are deterministic lint checks, not editorial grading:
+These gates are deterministic lint checks, not editorial grading:
 
 | Gate | Kind | What it proves |
 |------|------|----------------|
@@ -363,7 +371,7 @@ Alpha gates are deterministic lint checks, not editorial grading:
 | `okf-type` | OKF lint | Agent docs have required `type:` frontmatter when strict/required |
 | `docs-style` | style lint | Opt-in deterministic profile checks for title, purpose, audience, examples, owner/source, task orientation, and stale wording |
 
-`docs-style` supports `google-dev-docs`, `playbook-okf`, and `custom` profiles. It is not part of the default alpha path and does not grade prose quality; it checks for explicit structural signals. LLM critique remains planned optional behavior.
+`docs-style` supports `google-dev-docs`, `playbook-okf`, and `custom` profiles. It is not part of the default path and does not grade prose quality; it checks for explicit structural signals. LLM critique remains planned optional behavior.
 
 ---
 
@@ -413,7 +421,7 @@ report status, commands, and the recorded stable-publication HITL decision.
 ```ts
 type ReconciliationConfig = {
   /** Semantic comparison level; discovery still preserves raw file relations. */
-  scope?: 'file' | 'module' | 'package'
+  scope?: 'file' | 'module' | 'area' | 'package'
   /** Observed relation kinds that require documentation declarations. */
   requiredRelationKinds?: string[]
   /** Limit missing-declaration findings to relations between internal project entities. */
@@ -425,6 +433,12 @@ type ReconciliationConfig = {
 
 Use `scope: 'package'` for monorepos where file imports should be compared as package-level architecture evidence. Omit `requiredRelationKinds` to require all observed kinds; an empty array intentionally disables undocumented-relation findings and must be treated as an explicit exemption.
 
+Use `scope: 'area'` for a single-package repository. At package scope such a repository aggregates
+every internal relation into one self-loop, which the comparison skips — a thousand observed
+relations and nothing to report. At area scope the same relations become edges between
+directories, which a declaration can confirm or fail to. On this repository that is the difference
+between zero diagnostics and 177.
+
 Use `requiredRelationTargets: 'internal'` when the repository wants package or module architecture declarations without requiring Markdown to enumerate every external library import. External relations remain in the raw snapshot and report as evidence; they simply do not generate missing-declaration findings.
 
 The reconciliation documentation summary reports package health separately from
@@ -456,6 +470,107 @@ report?: {
 
 `private` is the default and keeps local evidence useful for debugging. `anonymized` is intended for reports shared outside the repository: it preserves counts, relation kinds, topology, and coverage status while removing project-specific identity and evidence content. The generated HTML and every lazy chunk use the same mode.
 
+## `analysis.areas` (optional)
+
+```ts
+areas?: {
+  /** Directory levels below a source root that form an area. Default 1. */
+  depth?: number
+  /** Directories that contain areas rather than being one. */
+  roots?: string[]
+}
+```
+
+An **area** is the unit of architecture between a package and a file: a directory that groups
+modules. `src` is not an area in any useful sense; `src/query` is. So `roots` names the
+directories that hold areas — by default `src`, `lib`, `app`, `source`, `server`, `client`,
+`packages`, `apps` — and `depth` says how many levels below such a root an area sits.
+
+Areas are derived, never declared, with one exception that matters: **any path an ownership record
+names becomes an area**, whatever the convention says. A configuration that reads
+`path: "src/mcp"` is a human stating that the directory is a unit, and the graph should have an
+entity for it. Such an area carries `metadata.ownershipId`, which is what lets an agent document
+declaring `id` plus `editRoot` resolve to the thing it owns.
+
+Each module belongs to exactly one area — the most specific one containing it — so containment
+stays a tree and an aggregation at area scope has one answer per module. Nested areas keep their
+shape: `area:src` holds what sits directly in `src`, with `area:src/query` recorded as its child.
+
+An ownership path that no observed module or document lives under is reported as
+`OWNERSHIP_PATH_UNOBSERVED` with status `stale-or-unverified`. A renamed directory is otherwise
+invisible: the handoff still resolves, it just points an agent somewhere that no longer holds what
+it claims.
+
+## `retrieval` (optional)
+
+```ts
+type RetrievalConfig = {
+  corpus?: {
+    /** Project repository documents and modules into `index.knowledge`. Default: true. */
+    enabled?: boolean
+  }
+  /** Per-field BM25 multipliers. Unknown field names are ignored. */
+  weights?: {
+    id?: number
+    symbols?: number
+    title?: number
+    path?: number
+    tags?: number
+    description?: number
+    body?: number
+  }
+  /** BM25 parameters: `k1` term-frequency saturation, `b` length-normalization strength (0–1). */
+  params?: { k1?: number; b?: number }
+}
+```
+
+Search ranks records with field-weighted BM25 plus boosts for exact identity, so an agent that
+types an exported symbol, a file path or a package name lands on that thing rather than on
+whatever mentions it most. The defaults are:
+
+| Field | Weight | Why |
+| --- | --- | --- |
+| `id` | 8 | The query names the record |
+| `symbols` | 7 | An agent that types an exported name wants the module that defines it |
+| `title` | 6 | A heading is what a document is about |
+| `path` | 4 | Location is identity for a module |
+| `tags` | 3 | Audience and kind |
+| `description` | 2 | A summary a human wrote |
+| `body` | 1 | A passing mention is the weakest evidence |
+
+Tuning is configuration, not code: the resolved weights, parameters and stopword-lexicon version
+are recorded in `index.retrieval`, so a retuned ranking is a different artifact with a different
+content hash rather than a silent behaviour change. Re-run `ak-docs index` after changing them,
+and re-approve the [retrieval benchmark](../bench/README.md) baseline if you gate on it.
+
+`corpus.enabled: false` keeps the index to the curated agent corpus only. The index is then
+smaller and builds faster, at the cost of the retrieval it exists for: an exported-symbol or
+file-path query has nothing to resolve against. Turn it off only for a repository whose source is
+not the thing agents ask about.
+
+## `render` (optional)
+
+```ts
+type RenderConfig = {
+  /** Project templates that replace the bundled ones, by name, as paths relative to the project root. */
+  templates?: Partial<Record<'llms.txt' | 'area' | 'ownership' | 'change-digest' | 'overlay-review', string>>
+}
+```
+
+`ak-docs render <name>` renders the canonical artifacts as Markdown from a bundled template; a
+path under `templates` replaces that template entirely, without a code change. Templates use
+knap syntax and see only the variables Doc Bridge computes — see [Render v1](./render-v1.md) for
+each template's variables and `ak-docs render <name> --print-template` for the bundled source.
+The `llms.txt` override is also what `ak-docs index` writes.
+
+```json
+{
+  "render": {
+    "templates": { "area": "templates/area.md" }
+  }
+}
+```
+
 ## `safety` (optional)
 
 ```ts
@@ -610,14 +725,38 @@ type IntelligenceConfig = {
     agentId?: string
     agentRoot?: string
     runnerModule?: string
+    cli?: {
+      /** Executable name or absolute path; arguments are passed without a shell. */
+      command: string
+      args?: string[]
+    }
     deterministic?: boolean
+    maxInputBytes?: number
     timeoutMs?: number
     maxTokens?: number
     maxResponseBytes?: number
     maxConcurrency?: number
+    /** Byte budget of one enrichment context pack. Default 65536 (4096..4000000). */
+    maxPackBytes?: number
+    /**
+     * Which installed agent plays which enrichment role (see Enrichment overlay v1).
+     * Default: the configured agent as curator only. The adjudicator must be a
+     * different identity from the curator and the reviewer.
+     */
+    roles?: {
+      curator?: EnrichmentRole
+      reviewer?: EnrichmentRole
+      adjudicator?: EnrichmentRole
+    }
   }
 }
 
+type EnrichmentRole = {
+  enabled?: boolean               // default: true when the role is declared; curator on by default
+  agentId?: string                // default: intelligence.registry.agentId
+  promptVersion?: string          // default: '1'; part of every proposal id and cache key
+}
+
 type MemoryAdapterId =
   | 'playbook-memory'              // .agent-memory/MEMORY.md layout
   | 'cursor-rules'                 // .cursor/rules/*.mdc

package/docs/spec/documentation-audit-v1.md

@@ -0,0 +1,61 @@
+---
+title: Documentation audit v1
+description: Configurable deterministic checks for documentation quality and agreement with repository structure.
+---
+
+# Documentation audit v1
+
+Run the repository audit after discovery and reconciliation:
+
+```bash
+ak-docs audit documentation --json
+ak-docs audit documentation --text
+```
+
+The JSON report is versioned and content-hashed. It includes criterion-level evidence, metrics, blocking findings, generated-document freshness boundaries, and limitations.
+
+## Configuration
+
+Configure the optional `audit.documentation` block in `doc-bridge.config.json`:
+
+```json
+{
+  "audit": {
+    "documentation": {
+      "criticalPaths": ["src/cli/**", "src/mcp/**"],
+      "generatedPaths": ["docs/generated/**"],
+      "minWords": 20,
+      "requiredSections": ["Usage", "Examples"],
+      "requireExamples": true,
+      "exactDuplicates": true,
+      "defaultTier": "tier-2",
+      "tierRules": [
+        { "pattern": "docs/agent-corpus/**", "tier": "tier-0", "critical": true },
+        { "pattern": "docs/adr/**", "tier": "tier-1" }
+      ],
+      "requiredCriticalMetadata": ["owner", "lifecycle", "sourceOfTruth", "validationPath"]
+    }
+  }
+}
+```
+
+- `criticalPaths` makes high-confidence contradictions and missing structure documentation blocking.
+- `generatedPaths` excludes generated documents from manual quality checks and reports freshness as `not-analyzed`; configure the generator's real check separately.
+- `requiredSections`, `minWords`, and `requireExamples` are opt-in to avoid false positives for indexes and short reference files.
+- `exactDuplicates` detects identical normalized bodies. It does not claim that similar prose is redundant.
+- `defaultTier` and ordered `tierRules` classify every included document as `tier-0`, `tier-1`, or `tier-2`. A document may override the configured tier with `tier` frontmatter; `critical: true` frontmatter or a rule marks it critical.
+- Critical documents are checked for `owner`, `lifecycle`, `sourceOfTruth`, and `validationPath` metadata. `requiredCriticalMetadata` can reduce this list for a declared project profile.
+
+The audit reuses the canonical discovery snapshot and reconciliation report. A finding is not proof that prose is wrong unless its evidence and confidence say so. `not-analyzed` is intentional and includes semantic contradiction, unnecessary content, and agent-review boundaries. A document title is satisfied by a Markdown level-one heading, a `title` frontmatter field, or a visible HTML `<h1>` used by README-style documents.
+
+## Independent quality dimensions
+
+Each document receives an assessment instead of one opaque quality score. The machine-readable report exposes `documentAssessments` and independent status counts for:
+
+- correctness: deterministic reconciliation can expose evidence, but semantic correctness remains `not-analyzed` until code, configuration, tests, and applicable runtime behavior are reviewed;
+- completeness: structural signals such as title and configured required sections are reported as `partial`, never as semantic completeness;
+- clarity: title and basic structure are measurable, while human readability remains `not-analyzed`;
+- agent efficiency: title and example presence are signals only; retrieval usefulness and task success require the controlled study;
+- maintainability: owner, lifecycle, source-of-truth, and validation-path metadata are directly measurable.
+
+Example presence and example correctness are separate. The audit reports `example.present`; `example.validation` remains `not-analyzed` unless a real validation flow supplies evidence. Similar prose, unnecessary content, and document/document semantic contradictions are intentionally deferred to the Registry-agent and human-adjudication path.

package/docs/spec/enrichment-overlay-v1.md

@@ -0,0 +1,241 @@
+---
+title: Enrichment overlay v1
+description: Typed agent proposals, the deterministic validators that decide them, the overlay that stores the decisions, and how little of it the deterministic layer is allowed to feel.
+---
+
+# Enrichment overlay v1
+
+A Registry agent may enrich the knowledge graph. It may never become an authority over it.
+
+`AgentProposalV1` could say "review this finding". It could not say that a document is canonical
+for an area, that an alias should resolve to an entity, or that a relation exists with a given
+confidence — and nothing stored what it said, nothing consumed it, the deterministic cache was an
+in-process `Map`, and `ak-docs suggest` sent the whole redacted snapshot, 740 KB on this
+repository, in one call. This document is the replacement: proposals typed per claim, decided by
+validators that have no judgement to exercise, stored in an overlay bound to the content hash of
+what each entry describes, and projected into retrieval with an influence that is bounded by
+construction.
+
+## Typed proposals
+
+`EnrichmentProposalV1` in `src/schemas/enrichment.ts` is a discriminated union on `kind`. The
+envelope is the same for every kind:
+
+| Field | Meaning |
+| --- | --- |
+| `proposalId` | The hash of kind, entity, target content hash, agent identity, prompt version — and, for kinds one entity can carry several of, the payload field that tells them apart (`alias`, `phrase`, the relation's `to` and `kind`, `against`, `with`, `area` and `missing`, `directories`). A re-run over unchanged inputs produces the same id; a summary is a slot, an alias is a set. |
+| `entity` | Must exist in the snapshot the proposal was made against. |
+| `targetContentHash` | The entity's content hash at proposal time: the file hash for a file-backed entity, a hash of the entity as recorded for an area. The entry expires when it moves. |
+| `confidence`, `reason` | 0..1, and up to 1 000 characters. |
+| `evidence` | At least one item, and every item present — by source, path and lines — in the snapshot or the report. |
+| `relatedDiagnosticIds` | Optional; every id must exist in the report. |
+| `origin` | `agentId`, `agentVersion`, `promptVersion`, and optionally `model` and `provider`. |
+| `baseSnapshotHash` | The snapshot it was made against. |
+| `payload` | Per kind, below. |
+
+| Kind | Payload | Deterministic validator | Policy |
+| --- | --- | --- | --- |
+| `classify-document` | `type`, `audience`, `lifecycle`, `criticality` | enumerated values; the entity is a document | accept by policy |
+| `summarize` | `summary` ≤ 400 chars, `language` | length; redaction scan; differs from the current summary | accept by policy |
+| `add-alias` | `alias` ≤ 64 chars | no collision with an id, name, title, filename stem or alias — exact, or Jaro-Winkler ≥ 0.95 | accept by policy |
+| `add-intent` | `phrase` ≤ 120 chars, `language` | length; language tag present | accept by policy |
+| `mark-canonical` | `scope` | the scope exists; the entity is a document; at most one canonical document per scope after the merge — a second one is a `canonical-conflict` | human approval |
+| `propose-relation` | `from`, `to`, `kind`, `detection` | both endpoints exist; the kind is one of `covers`, `mentions`, `links-to`, `depends-on`, `related-to`, `documents`; not already observed; every evidence item lies inside one endpoint | human approval |
+| `flag-contradiction` | `against`, `claim`, `observed` | both entities exist; evidence inside both | human approval |
+| `flag-redundancy` | `with` | both are documents; not already exact duplicates | human approval |
+| `flag-gap` | `area`, `missing` | the area exists; not already flagged with the same text | accepted as a finding, never as a fact |
+| `rank-hint` | `relevance`: `strong` or `weak` | the entity exists | accept by policy, bounded weight |
+| `suggest-area` | `directories`, `name` | every directory exists; no overlap with an existing area | human approval, then configuration, never an entity |
+
+Any other kind is recorded as rejected with reason `invalid-kind`. The full reason list is
+`ENRICHMENT_REJECTION_REASONS`; every rejection carries one of them, so a run's rejections are a
+histogram and not a log.
+
+Envelope checks run before the kind's own rule, in a fixed order: `invalid-kind`, `no-evidence`,
+`schema`, `base-snapshot-mismatch`, `unknown-entity`, `stale-target`, `unknown-diagnostic`,
+`evidence-outside-artifacts`, `proposal-id-mismatch`. A proposal that fails the envelope never
+reaches a kind validator.
+
+## The overlay
+
+`EnrichmentOverlayV1` lives at `.doc-bridge/enrich/overlay.json`:
+
+```json
+{
+  "type": "enrichment-overlay",
+  "schemaVersion": 1,
+  "contentHash": "…",
+  "baseSnapshotHash": "…",
+  "accepted": [{ "proposal": { "…": "…" }, "acceptedAt": "2026-09-14T00:00:00.000Z", "acceptedBy": "policy" }],
+  "pending": [{ "proposal": { "…": "…" }, "approvalId": "…", "note": "canonical-conflict" }],
+  "rejected": [{ "proposalId": "…", "kind": "propose-relation", "entity": "…", "reason": "unknown-endpoint", "detail": "…" }],
+  "stats": { "byKind": { "summarize": { "proposed": 4, "accepted": 4, "pending": 0, "rejected": 0 } }, "rejectionReasons": {}, "agentRuns": 1, "cacheHits": 0, "packs": 4, "inputBytes": 0, "outputBytes": 0, "expired": 0 }
+}
+```
+
+`acceptedBy` is `policy` for accept-by-policy kinds and a person's name otherwise; the schema
+refuses `policy` on a human-approval kind and refuses an `acceptedBy` equal to the proposal's
+`origin.agentId`. `contentHash` is over the decisions — every accepted, pending and rejected entry
+and the hashes they bind to — and not over `acceptedAt` or `stats`, because two runs over one
+unchanged repository must produce one overlay hash and a timestamp is not a fact about the
+repository.
+
+Reading never writes. `readEnrichmentOverlay` returns nothing for a missing, unreadable, malformed
+or hash-mismatched file, and a reader that got nothing behaves as if there were no overlay.
+
+**Staleness is per entry.** At projection time an accepted entry whose `targetContentHash` no
+longer matches its entity — or whose other endpoint no longer exists — is expired in the result
+and excluded from ranking; its siblings for unchanged entities survive. The file is untouched by a
+read; the next `ak-docs enrich` moves the expired entries to `rejected` with reason `expired`.
+
+**Reproducible acceptance.** `revalidateEnrichmentOverlay` re-runs the validators over the stored
+proposals and returns the partition they produce; a test asserts it equals the stored one. An
+overlay whose partition does not reproduce was edited by hand or outlived its validators, and
+either way it is no longer evidence of a decision.
+
+## The stage
+
+`enrich` is a workflow stage between `reconcile` and `evaluate`, run only by `ak-docs enrich` or
+`ak-docs check --enrich`. A plain `check` leaves its step pending and `evaluate` reads a null
+previous output. A missing, failed, timed-out or stale enrichment never changes a `check` result:
+`check --enrich` reports `enrichment.status: failed` with the error and carries on.
+
+```
+$ ak-docs enrich --text
+Roles: curator=ecosystem-doc-bridge-corpus-scanner
+Packs: 92 (agent calls 3, cache hits 89, re-run 3)
+Accepted: 180  Pending: 4  Rejected: 7  Expired: 3
+  summarize: accepted 89, pending 0, rejected 1
+  …
+Overlay: 7c1e… (overlay.json)
+```
+
+The stage:
+
+1. builds one context pack per target entity for each configured role and batches them by area;
+2. answers each pack from the cache or from the agent, caching what the agent said per pack —
+   including nothing, so silence is not asked for twice;
+3. validates everything through the partition against the snapshot, the report and the overlay
+   already on disk; policy kinds are accepted, human kinds are requested from the approval gate;
+4. adjudicates what two roles could not settle, if a third identity is configured;
+5. merges with the stored overlay — decisions people made survive while their target does — and
+   writes it.
+
+The step's workflow input names the overlay it attaches (`{ reportHash, overlayHash }`), because
+an approval changes the overlay without changing the report, and the engine refuses a step whose
+input did not move but whose output did.
+
+## Context packs and the cache
+
+Agents never receive the snapshot. `buildContextPacks` in `src/enrich/context-pack.ts` builds
+one pack per target entity:
+
+| Section | Content | Bound |
+| --- | --- | --- |
+| `target` | id, kind, name, path, content hash, aliases, its own evidence items, bounded metadata | — |
+| `neighbours` | the other end of every relation touching the target, with kind, path, content hash, the relation and its direction; sorted by kind then id | 32 |
+| `diagnostics` | open diagnostics naming the target or citing its file | 16 |
+| `evidence` | the target's own file, redacted, read only if it still hashes to what the snapshot recorded | 12 KB |
+| `budget` | `maxBytes`, `bytes`, `dropped` | 64 KB default, `intelligence.registry.maxPackBytes` |
+
+Over budget, sections are dropped in a declared order — excerpt bytes (halved until it fits, then
+dropped), then diagnostics from the end, then neighbours from the end — and the target is never
+dropped. This mirrors `compileBudget` from `@agentskit/core` with a byte counter and the
+`drop-oldest` strategy over sections ordered least-important-first; a test cross-checks the two,
+and the mirror is what runs, because a pack must be the same pack whether or not an optional peer
+is installed. Every string in a pack passes `redactSecrets`, asserted by test.
+
+`packHash` covers the target's and every neighbour's content hash and nothing else. The cache key
+is the hash of task, agent identity and version, prompt version and pack hash; entries live under
+`.doc-bridge/enrich/cache/<key>.json`. An unchanged repository therefore makes zero agent calls,
+and a one-document change re-runs only the packs whose hash moved — the changed document's, and
+any pack it was a neighbour of.
+
+## Protocol v2
+
+The adapter (`src/agents/registry-adapter.ts`) keeps `run` for `AgentProposalV1` over protocol
+`doc-bridge.registry-agent.v1` — `ak-docs suggest` still works — and gains `enrich(task, packs)`
+over `doc-bridge.registry-agent.v2`:
+
+```json
+{ "protocol": "doc-bridge.registry-agent.v2", "task": "curate", "role": "curator", "promptVersion": "1", "packs": [ … ], "capabilities": ["pack.read", "proposal.write"], "network": false, "shell": false, "deterministic": true }
+```
+
+The answer is one JSON object `{ "proposals": [ … ] }`. `task` is `curate`, `review` or
+`adjudicate`; for `adjudicate` the packs are followed by one `adjudication-request` item listing
+the disputed proposals, and `proposals` carries `EnrichmentAdjudicationV1` values. The adapter
+checks transport and budget and returns the raw array; grounding is the validators' job, and
+keeping it there is what makes a stored overlay reproducible from its proposals. The same CLI or
+local runner module serves both protocols and tells them apart by `protocol`.
+
+## Roles
+
+| Role | Task | Targets | Kinds it is for |
+| --- | --- | --- | --- |
+| curator | `curate` | documents | classification, summaries, aliases, intents, canonical markers, redundancy, gaps |
+| reviewer | `review` | documents, areas | relations, contradictions, gaps, rank hints, area suggestions |
+| adjudicator | `adjudicate` | the disputed entities | canonical conflicts and disputed contradictions only |
+
+Roles are configuration under `intelligence.registry.roles`; the default is the configured agent
+as curator only. The adjudicator must be a different agent identity from both others —
+`resolveEnrichmentRoles` refuses the configuration otherwise — and the validator rejects any
+adjudication whose origin matches a proposal it judges as `self-adjudication`. An adjudication
+judges; it never approves: the losers are rejected as `adjudicated`, the winner stays pending for
+the person the kind's policy requires, and a settled dispute is not reopened by the cache
+replaying the proposals that caused it.
+
+## Approvals
+
+Human approval goes through `createApprovalGate` from `@agentskit/core/hitl` over a file-backed
+`ApprovalStore` under `.doc-bridge/approvals/`, one JSON record per approval. The gate contract is
+mirrored in-repo (`src/enrich/approvals.ts`) for the same reason every ecosystem contract is —
+`@agentskit/core` is an optional peer — and the real gate is used through `importPeer` when it is
+installed; a test writes through both over one store and reads the same records.
+
+An approval id is the hash of `proposalId` and `targetContentHash`, so an approval given for one
+version of a document cannot be replayed against the next. `ak-docs enrich approve <proposalId>
+--by <name>`, MCP `docbridge.proposals { action: "enrich-approve" }` and a rendered review page
+call the same `decideEnrichment`: the gate decides first, the overlay moves second, and if the
+gate refuses — already decided, unknown — the overlay is untouched. An approver equal to the
+proposal's author is refused; `policy` is not a person. `ak-docs fix approve` records its
+approval through the same gate under `doc-bridge.fix`, bound to the fix proposal id and its
+content hash.
+
+## Projection and bounded influence
+
+`projectEnrichmentOverlay(overlay, snapshot)` turns the live accepted set into what
+`projectRetrievalIndex` reads:
+
+| Accepted kind | Effect in the projection |
+| --- | --- |
+| `add-alias` | one more alias on the entry |
+| `summarize` | the entry's summary, only when the entity has none of its own |
+| `add-intent` | an `intent` entry with `provenance: proposed` |
+| `mark-canonical` | the `canonical` tag, and 0.8 of the signal |
+| `rank-hint` | 1 (strong) or 0.5 (weak) of the signal |
+| `propose-relation` | one more edge with `confidence: proposed`; a `covers` edge counts toward `coveredBy` and canonicality |
+| `flag-*`, `suggest-area` | nothing: findings and suggestions are for a reviewer, not for ranking |
+
+The signal is a per-entry share in 0..1, carried on the entry as `agentSignal`, and the ranker
+multiplies it by `ACCEPTED_SIGNALS_WEIGHT` = 15% of the exact-id boost (30 of 200). It applies to
+lexical hits only, like every other tie-breaker. An accepted signal can therefore reorder near-ties
+and can never lift an entry past one the query named exactly — asserted by test. Without an
+overlay, `ACCEPTED_SIGNALS_WEIGHT × 0` is what it always was, and the projection is byte-identical.
+
+The projection's `overlayHash` is the hash of the live accepted set — `EMPTY_OVERLAY_HASH` when
+nothing is live — so it is part of the projection's identity and `IndexStaleError` sees a changed
+overlay. `withAcceptedRelations` merges live proposed relations into a snapshot for the graph, the
+HTML report and the memory view, and `assertObservedSurvive` checks that every observed entity and
+relation is present and unchanged afterwards; the report draws a proposed edge dashed.
+
+The index builder consults the overlay only while `intelligence.registry.enabled` is true:
+switching the Registry off restores the deterministic baseline exactly.
+
+## What never happens
+
+- No overlay entry deletes or alters observed data. The projection asserts that every observed
+  entity and relation survives enrichment.
+- No agent is called from `check`, `index`, `search`, `query`, `render` or MCP. The enrich stage
+  runs only on request, and nothing reachable from the query path imports `src/agents`.
+- No agent approves anything — its own output, another agent's, or an adjudication's winner.
+- No read writes. A corrupt overlay is no overlay.