@agentskit/doc-bridge 1.7.44 → 1.9.0

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

@@ -0,0 +1,229 @@
+---
+title: Measured enrichment v1
+description: What an enrichment run cost, what it invented, whether it improved retrieval at all, and the study measurements — mechanical task expectations, the assisted arm, tokens to first evidence — that decide the same questions for a controlled round.
+---
+
+# Measured enrichment v1
+
+An enrichment stage nobody measures is a stage nobody can defend.
+
+[Enrichment overlay v1](./enrichment-overlay-v1.md) made agent proposals typed, validated and
+bounded. It did not say whether any of it helped. The overlay reported what it accepted, which is
+the one number an agent cannot fail: a curator that proposes a hundred things and has ninety
+rejected looks exactly like one that proposes ten good ones. And the controlled study could not
+answer the question either — its last round recorded zero semantic successes in both arms, because
+a task whose only success criterion is a model's opinion produces no signal, and its third arm has
+been reserved since the first suite without ever running.
+
+This document is the measurement layer: the whole shape of an enrichment run, the retrieval delta
+that can block it, and the study machinery that asks the same questions of a controlled round.
+
+## What the run reports
+
+`EnrichmentStats` in `src/schemas/enrichment.ts` is written by `runEnrichment` and stored on the
+overlay. It is deliberately outside the overlay's content hash — two runs over one unchanged
+repository must agree on their decisions while disagreeing about how long they took.
+
+| Field | Meaning |
+| --- | --- |
+| `byKind` | Per proposal kind: `proposed`, `accepted`, `pending`, `rejected`. Sorted by kind, so two runs produce the same bytes. |
+| `rejectionReasons` | A histogram over the closed list of rejection reasons, sorted by reason. A run's rejections are comparable across runs rather than a log to read. |
+| `inventedReferences` | Rejections that named something the repository does not contain. |
+| `agentRuns`, `inputBytes`, `outputBytes` | What was actually sent and received. Batched packs, so a run is not a call count. |
+| `cacheHits`, `cacheHitRate` | Hits, and hits over hits plus runs, rounded to six places. |
+| `wallTimeMs` | Measured from a monotonic clock, not derived. `runEnrichment` takes a `clock` option so a test can pin it. |
+| `expired` | Entries whose target content hash moved since they were accepted. |
+
+`enrichmentCost(stats)` in `src/enrich/stats.ts` is the same numbers as an object for a reader who
+only wants the bill; `ak-docs enrich --json` reports it under `cost`.
+
+### Invented references
+
+`INVENTED_RELATION_REASONS` is `unknown-endpoint`, `unknown-entity`, `unknown-scope`,
+`unknown-directory`, `unknown-diagnostic`. `inventedReferences` counts exactly those, and it is
+reported next to the rejection total rather than folded into it.
+
+The distinction is not cosmetic. A curator that classifies a document badly is wrong about a
+judgement, and a validator rejecting it is the system working. A curator that proposes a relation
+to a module the repository does not contain is making things up, and that number must trend to
+zero or the agent is unusable. Folding the two together hides the second inside the first.
+
+A schema failure or an unknown kind is a rejection and not an invention: `invalid-kind` is not in
+the list, and a test asserts the counts stay apart.
+
+### Stability
+
+`enrichmentStability(current, previous)` compares a run with the one before it and reports both
+halves of the question at once:
+
+- `overlayHashIdentical` — a deterministic agent over an unchanged repository must reach this. The
+  overlay hash covers decisions, not `acceptedAt` and not `stats`, so a second run that is answered
+  entirely from the cache produces the same hash as the first.
+- `proposalIdShare` — for a live model, which will not reach an identical hash, the share of
+  proposal identifiers present in both runs. The share is over the **union** of the two runs'
+  identifiers, so a run that merely proposes fewer things does not score as more stable.
+
+`sharedProposalIds`, `proposalIds` and `previousProposalIds` are reported next to the share, because
+a share of 0.5 over two identifiers and over two hundred are different facts.
+
+## The retrieval delta
+
+`measureOverlayRetrievalDelta` in `src/bench/overlay-delta.ts` answers the question the rest of the
+statistics cannot: did the overlay make retrieval better?
+
+It runs the golden suite twice over **one snapshot** — once with the accepted overlay projected,
+once with `overlay: 'ignore'` — so the only difference between the two runs is the overlay. Not a
+re-scan, not a different revision, not a different configuration. Neither half needs an index on
+disk: both are projected from the snapshot the caller passes.
+
+The rule is asymmetric on purpose. An overlay may leave retrieval unchanged and it may improve it,
+but it must not lower `hitAt3` (`OVERLAY_BLOCKING_METRIC`): aliases, summaries and rank hints an
+agent proposed exist to help an agent find things. A drop is reported as `regression: true` with
+status `regressed`, and the caller exits non-zero. It is a finding about the agent, never a new
+baseline.
+
+The result carries both metric sets, a per-metric delta with `improved` and `worsened` (lower is
+better for `meanContextBytes`, `meanApproxTokens` and `zeroResultRate`), and — the part that makes a
+regression actionable — `lostCases` and `gainedCases`, the case ids that changed at hit@3.
+
+```bash
+# The overlay on disk, against the configured golden suite.
+ak-docs bench retrieval docs/bench/retrieval-suite-v1.json --overlay --text
+
+# Or as part of the run that produced it.
+ak-docs enrich --retrieval-delta --json
+```
+
+Both exit 1 on a regression. Both report the delta in text and in JSON: `formatOverlayRetrievalDeltaText`
+for a person, `retrievalDelta` (or `overlayDelta`) for a machine. The delta is opt-in because it runs
+the suite twice, which is the right cost for an answer about whether the overlay helped and the wrong
+cost for every routine run.
+
+## Study task expectations
+
+The study's correction is the same idea one level up: state what retrieval is expected to return,
+and check it deterministically.
+
+A task in `docs/study/task-suite-v1.json` may now declare `expectedEntities`, `expectedDocuments`
+and `retrievalQueries`. The references are **opaque** — `primary-entrypoint`, not `docs/alpha.md` —
+because the task suite is publication-bound and a repository path in it is a privacy failure, not a
+convenience. A query with nothing expected is refused by the schema: it would check nothing.
+
+The resolution lives in a second artifact, `StudyExpectationsV1` in `src/study/expectations.ts`,
+which declares `scope: 'local'` and binds to the suite by `taskSuiteHash`. It maps each reference to
+the concrete entity ids or document paths it stands for in one repository on the operator's disk.
+It is never published; putting it under `docs/study/` would fail the privacy gate, which is the
+intended outcome rather than a bug. References resolved against a suite that has moved on are
+refused outright.
+
+`studyRetrievalSuite` turns the pair into an ordinary Open Eval Format suite — one case per task
+query, with the resolved targets as `expectedTargets` and the task, repository and category carried
+in metadata — so the same command, the same ranking and the same metrics that gate this
+repository's retrieval answer the study's mechanical questions. `checkStudyExpectations` runs it:
+
+```bash
+ak-docs study expectations docs/study/task-suite-v1.json \
+  --expectations ./local-study-expectations.json --index .doc-bridge/index.json --text
+```
+
+`ok` requires that every reference resolved **and** every case hit. Two failures are reported rather
+than smoothed over: a task that declares no expectations is listed under `withoutExpectations` as
+unchecked, never counted as a pass, and an unresolved reference fails the check, because an
+expectation nobody resolved is an expectation nobody tested — which is exactly the failure this
+replaces. The command exits 1 when the check does not pass.
+
+`validateStudyTaskSuite(suite, { requireExpectations: true })` names the tasks that cannot be checked
+mechanically. It is off by default: a suite written before expectations existed is still a valid
+suite.
+
+### Where the model adjudicator stops
+
+A rubric item may now be prose, or prose with the mechanical check that decides it
+(`acceptance-checks`, `evidence-coverage`, `retrieval-expectations`). `mechanicalRubricItems` and
+`modelRubricItems` split the rubric on that field, and `adjudicatorRubric(task)` is what the
+adjudicator input carries: `rubric` holds only the items no checker can settle, and the settled ones
+travel next to them as `mechanical` — verdicts, for context, not for review. The instruction says so
+in the same words.
+
+Handing a model an item the runner already measured invites it to disagree with a measurement, which
+is how a study ends up with an opinion where it had a number.
+
+## The assisted arm
+
+`registry-assisted` has been reserved since the first suite and has never executed. It now reports
+its own readiness, and `assistedArmReadiness(plan, providers, suite)` is the only thing that decides
+whether it runs:
+
+| Status | When | Effect |
+| --- | --- | --- |
+| `unavailable` | No assisted scenario in the plan; the scenario names no agent identity and version; no provider CLI for the scenario and a model the suite uses | Its executions are recorded as unavailable observations |
+| `ready` with `undeclared` | The scenario declares no `promptVersion`, or no `agentBudget` | The arm runs; the run says what it could not name |
+| `ready` | Everything declared | The arm runs |
+
+An unavailable arm is **recorded, not skipped**: a scenario absent from a ledger is
+indistinguishable from one that was never planned, and comparing the arms it planned is the study's
+whole purpose. Each such execution lands in the ledger with `execution.status: 'unavailable'`,
+`errorCode: 'registry-unavailable'`, and an automated adjudication of `blocked` carrying the reason.
+A missing Registry is a fact about the environment, not a reason to lose the other two arms —
+`assertRunInputs` skips provider validation for those executions so the rest of the run proceeds.
+
+A missing declaration is the other way round: losing the third arm over an undeclared prompt version
+would be worse than running it without one, so the arm runs and `undeclared` says what a reader
+cannot reconstruct from the ledger — the prompt it used, or the agent's cost apart from the model's.
+The run summary prints the status, the reason and the undeclared fields.
+
+A run plan may declare `promptVersion` and `agentBudget` only on `registry-assisted`: the other two
+arms have no agent to budget.
+
+## Tokens to first evidence
+
+The parent PRD's second claim is that an agent reaches correct grounded evidence for fewer tokens
+than by reading the repository. Total tokens at the end of a task does not test that claim: a run
+that wandered for ten thousand tokens and then found the answer looks the same as one that landed on
+it immediately.
+
+`tokensToFirstEvidence` is a canonical provider measurement — tokens consumed before correct
+grounded evidence was in hand — and the metrics report its p95 per scenario as
+`tokensToFirstEvidenceP95`, rounded up to whole tokens. It is in the improvement list, so a round
+that reaches evidence sooner reads as an improvement, and absent or partial coverage is reported as
+`tokensToFirstEvidence` or `tokensToFirstEvidence-partial` under `missingMetrics` rather than as a
+zero.
+
+The assisted arm's enrichment agent is costed apart from the model: `registryAgentInputTokens`,
+`registryAgentOutputTokens`, `registryAgentCostUsd` and `registryAgentRuns`. `registryAgentCostUsd`
+is added into `totalCostUsd`, so the arm cannot look cheap by charging its work to a line nobody
+adds up, and `missingMetrics` names it when an assisted observation reports no agent cost at all.
+The scenario line in `--text` prints the p95 next to the agent cost and its run count.
+
+## Invariants
+
+- `stats` is outside the overlay's content hash. Cost and timing may differ between two runs that
+  decided identically.
+- `inventedReferences` counts only `INVENTED_RELATION_REASONS`, and is reported separately from the
+  rejection total.
+- `proposalIdShare` is over the union of both runs' identifiers.
+- The retrieval delta builds both indexes from one snapshot. An overlay on disk cannot leak into the
+  baseline half.
+- An overlay that lowers hit@3 is a regression with a non-zero exit, in every mode.
+- A study task's expectations are opaque references. A path or a URL in a publication-bound artifact
+  is a privacy failure, and the privacy gate is what says so.
+- An unresolved reference fails the check; a task without expectations is reported unchecked and is
+  never a pass.
+- A rubric item with a mechanical check never reaches the model adjudicator.
+- An unavailable assisted arm is recorded as unavailable observations, and never fails the study.
+
+## Deviation: the committed study suite
+
+The mechanism above is delivered and tested; the committed 24-task suite, run plan and ledgers are
+**not** rewritten to use it.
+
+Two reasons, both about not making the artifacts worse. The suite's content hash is bound to
+published artifacts — the run plan's `taskSuiteHash`, the observation ledgers, the verification
+binding — and changing it invalidates every one of them. And the concrete targets an expectations
+file would resolve belong to the six study repositories, which are not present in this repository,
+so the references could only be guessed.
+
+An operator adding expectations to a round therefore does three things: add `expectedEntities`,
+`expectedDocuments` and `retrievalQueries` to the tasks, re-seal the suite, and write the local
+expectations file that resolves the references against their checkouts. `ak-docs study expectations`
+then reports which tasks can be answered mechanically and which cannot.

package/docs/spec/public-parity-v1.md

@@ -0,0 +1,119 @@
+---
+title: Public parity v1
+description: A registry of the claims this repository makes in public, the repository facts they stand for, and the gate that fails when a public surface states something the repository has moved past.
+---
+
+# Public parity v1
+
+Documentation drifts silently, and the drift reaches readers before it reaches anyone who could fix it.
+
+Four figures from the published A/B round appear in `README.md` and again in `docs/study/README.md`.
+They agree today. Nothing made them agree: an edit to one of them, or a new round replacing the
+artifact both quote, would leave two public surfaces stating a number the repository no longer
+measures — and the only mechanism for noticing was a person happening to read both pages on the same
+day.
+
+`ak-docs parity` is that mechanism. A registry names each public claim and the repository fact it
+stands for; the checker resolves the fact, finds the claim's occurrences, and reports the difference
+with a file, a line, an owner and a remediation.
+
+## The registry
+
+`docs/parity/public-claims-v1.json` is a sealed artifact — `createPublicClaims` computes its content
+hash, `parsePublicClaims` refuses a tampered one — holding claims and exceptions.
+
+| Field | Meaning |
+| --- | --- |
+| `claimId` | A slug. Stable across rounds, because findings are keyed on it. |
+| `statement` | What the claim asserts, for a reader of the report. Never a path or a URL. |
+| `owner` | Who answers for it: an ownership id, a team, a handle. Every finding carries it. |
+| `valueType` | `number`, `percent`, `semver` or `text`. Decides the capture. |
+| `template` | How the value appears in prose, with exactly one `{value}`. Omitted for a presence claim. |
+| `templates` | Per-surface wording, when one fact is stated differently in different places. |
+| `evidence` | Where the canonical value comes from. Below. |
+| `required` | Surfaces that must state the claim. One that omits it is a `missing` finding. |
+| `optional` | Surfaces that may. Checked when present, never required. |
+| `severity` | `error` blocks the gate; `warn` is reported and does not. |
+| `remediation` | What to do about a finding. Written once, in the registry, not per finding. |
+
+### Evidence
+
+Every resolver is deterministic and local. Nothing reaches the network, and nothing asks a model.
+
+| Kind | Resolves to |
+| --- | --- |
+| `package-field` | A scalar field in `package.json` — `version`, `description`. |
+| `artifact-field` | A dotted path into a committed JSON artifact: `arms.1.completedRate`. |
+| `artifact-sum` | The sum of one numeric field across an array in an artifact: prose states a total where the artifact stores the parts. |
+| `snapshot-count` | Entities of one kind in the snapshot this run produced. |
+| `doctor-metric` | A figure the doctor measured: the grade, the score, reachability, connectivity, hit@3, agent-doc coverage. |
+| `cli-command` | Whether the CLI's own usage offers a command. A presence claim: no template, no value to read. |
+
+A numeric value can be rendered the way prose states it: `round`, `percent-1dp`, `percent-0dp`, and
+two signed transforms. `negative-percent-2dp` and `negative-seconds-2dp` render the magnitude of a
+negative measurement — "18.46% fewer", "39.75 seconds lower" — and **refuse to render a positive
+one**. The direction of those claims lives in a word the checker cannot read, so a measurement that
+turns stops resolving instead of matching the same digits for the opposite result.
+
+## The four outcomes
+
+They are kept apart because they need different actions.
+
+| Code | Meaning | Blocks |
+| --- | --- | --- |
+| `PARITY_STALE` | A surface states a value the repository has moved past. | At `error` |
+| `PARITY_MISSING` | A required surface does not state the claim at all. | At `error` |
+| `PARITY_CONTRADICTION` | Two public surfaces state different values for one claim. | Always |
+| `PARITY_NOT_ANALYZED` | The canonical value could not be resolved. | Never |
+
+A contradiction is decided over the whole claim rather than per surface: two pages disagreeing is a
+finding even when neither matches the repository, and it is the one an agent reading the
+documentation cannot resolve on its own.
+
+`PARITY_NOT_ANALYZED` is reported and never counted as a pass. A claim nobody could check is not a
+claim anybody verified, and passing it quietly is how a parity report becomes decoration.
+
+## Exceptions
+
+An exception accepts a finding for one claim on one surface, and it must carry a `reason` of at
+least eight characters and an `acceptedBy`. The finding still appears in the report, marked
+`accepted` with its reason, and stops blocking. There is no way to silence a claim without saying
+why in the artifact — silence is what drift needs.
+
+## The gate
+
+```bash
+ak-docs parity                         # JSON: { ok, parity }
+ak-docs parity --text                  # one line per finding, with its remediation
+ak-docs parity --claims <file>         # a registry somewhere else
+```
+
+Exit 1 when any finding blocks, 0 otherwise, 2 on a broken registry or an unreadable surface. CI runs
+it in the dogfood step, next to the index, the gate, the doctor and the retrieval benchmark, so a
+pull request that edits a public number and not its siblings fails before review.
+
+The doctor is measured only when a claim asks for one of its figures: that costs an index and a
+benchmark run, and most registries never need it.
+
+## Publication safety
+
+The report is publication-safe by construction. It carries claim ids, repository-relative surface
+paths, line numbers, the stated and canonical values, and a bounded excerpt of the matching line —
+at most 160 characters, with secrets redacted through the same scanner the enrichment validators
+use. It never carries a document's contents and never an absolute path: the registry's surface
+paths are validated as repository-relative, so an operator's home directory cannot reach an
+artifact that is meant to be shareable. A test asserts all of it against a fixture whose README
+contains a secret-shaped string and a four-hundred-character line.
+
+## Invariants
+
+- The registry is sealed; a tampered hash is refused before anything is checked.
+- A template's literal halves are escaped, so a registry cannot smuggle a pattern into the checker,
+  and `{value}` becomes one bounded capture: no nesting, no ambiguity, nothing to backtrack over.
+- A claim that states a value has a template; a presence claim has none. The schema enforces both.
+- An exception needs a reason and an approver, and applies to one claim on one surface.
+- A signed transform refuses a value whose sign no longer matches the prose.
+- Two runs over one unchanged repository produce the same report content hash: findings are sorted,
+  and nothing in the report is a timestamp.
+- `missingSurfaces` names a surface the registry addresses that the checkout does not contain, so a
+  claim cannot pass by pointing at nothing.

package/docs/spec/registry-agents.md

@@ -68,3 +68,9 @@ mergePolicy:
 - `knowledge-promoter` may draft PR content, but must never merge.
 - `code-review` runs after gates so reviewers see deterministic failures first.
 - Future RAG mode should inject `createDocBridgeRetriever(index)` and keep exact handoff resolution ahead of semantic results.
+
+## Grounding and approval boundary
+
+The adapter accepts only a typed `AgentProposalV1` whose base snapshot and report hashes match the supplied artifacts. A proposal must identify the configured Registry agent and exact installed version, reference known diagnostics, and include evidence present in the supplied snapshot or reconciliation report. When `ak-docs suggest --documentation` is used, the bounded documentation-audit context is also supplied; the proposal must bind `baseDocumentationAuditHash` and may reference audit finding IDs and evidence. Unknown diagnostics, out-of-scope evidence, malformed output, timeout, response limits, and token limits fail closed.
+
+The adapter returns advisory evidence only. It does not apply documentation changes, mark findings resolved, or approve its own output. Convert an accepted suggestion into the existing human-gated fix-proposal flow, run post-apply verification, and treat the new source revision as a new evidence run. An alternate Registry agent is selected by changing `intelligence.registry.agentId` and installing matching metadata under `agentRoot`; the common adapter and evidence contract remain unchanged.

package/docs/spec/render-v1.md

@@ -0,0 +1,122 @@
+---
+title: Render v1
+description: The canonical artifacts rendered as Markdown people can read, from templates a project can replace.
+---
+
+# Render v1
+
+Doc Bridge writes JSON for agents and HTML for browsing. `ak-docs render` writes the Markdown for
+people: the same artifacts, through templates rather than string concatenation, so a project can
+change the house style without a code change and every rendering is a function of its inputs.
+
+```bash
+ak-docs render llms.txt
+ak-docs render area --output docs/areas
+ak-docs render ownership --output docs/agent-corpus/generated
+ak-docs render change-digest --data .doc-bridge/previous-snapshot.json
+ak-docs render overlay-review --output review.md
+ak-docs render area --print-template > templates/area.md
+```
+
+Rendering never calls an agent and never reads the Registry. Its inputs are the index, built in
+memory from the working tree or read from the artifact `--data` names, the workflow's last
+reconciliation report and snapshot, and an overlay file. Lists are sorted, nothing carries a
+timestamp, and equal inputs render to equal bytes — every bundled template has a golden file, and
+a test renders the same data twice.
+
+## Templates
+
+| Name | Renders | `--data` |
+| --- | --- | --- |
+| `llms.txt` | the curated reading order for agents, exactly as `ak-docs index` writes it | a `DocBridgeIndex` |
+| `area` | one page per code area: purpose, modules, documents, related areas, checks, open findings | a `DocBridgeIndex` |
+| `ownership` | one sidecar per ownership record: start page, what to read, edit roots, checks, related areas | a `DocBridgeIndex` |
+| `change-digest` | entities and documents whose content hash moved since the last scan, and the documents that should have moved with them | the previous snapshot |
+| `overlay-review` | pending agent proposals with their evidence links, for a human to judge | an enrichment overlay |
+
+Without `--output`, the pages go to standard output; `--json` wraps them as `{ template, source,
+pages: [{ path, content }] }`. With `--output`, a single page is written to that path and a
+multi-page template under it as a directory; the command prints what it wrote.
+
+Templates use [knap](https://github.com/obsidianmd/knap) syntax: `{{ variable }}`, `{% if %}`,
+`{% for item in list %}`, and knap's standard filters. They parse to an abstract syntax tree and
+are interpreted without `eval`; the application computes every variable before rendering, and a
+template cannot call anything. knap renders asynchronously and the index pipeline is synchronous,
+so Doc Bridge walks knap's AST with a synchronous evaluator of its own; a test renders every
+bundled template through knap's engine as well and holds the two to byte-identical output.
+
+## Overriding a template
+
+```json
+{
+  "render": {
+    "templates": {
+      "area": "templates/area.md"
+    }
+  }
+}
+```
+
+The path is relative to the project root. `ak-docs render <name> --print-template` prints the
+bundled template to start from, and the variables each template sees are the exported view types
+(`AreaPageView`, `OwnershipPageView`, `ChangeDigestView`, `OverlayReviewView`, `LlmsTxtVariables`).
+An override replaces the bundled template entirely and is compiled by the same engine, so one that
+does not parse fails before anything is written. The `llms.txt` override is also what
+`ak-docs index` writes and what the documentation-standard profile re-renders to check freshness:
+the two always agree.
+
+## Generated regions
+
+Every Markdown page carries a marker around what the generator owns:
+
+```markdown
+<!-- doc-bridge:generated hash=2dc9b98ec7b986b0 -->
+…
+<!-- /doc-bridge:generated -->
+```
+
+A template places the markers with `{{ region.open }}` and `{{ region.close }}`; a template that
+prints neither is wrapped whole. The hash is the first sixteen hex characters of the SHA-256 of
+the lines between the markers, with line endings normalised, so an editor converting a file to
+CRLF has not changed what the generator wrote.
+
+The marker is what closes the loop with the rest of the pipeline. The Markdown analyzer skips
+mentions and links inside a generated region (`docs/spec/markdown-analyzer-v1.md`), so Doc Bridge
+never reads its own output back in as evidence about the repository. The documentation audit
+recomputes the hash of every region and reports one that no longer matches its marker as
+`GENERATED_REGION_EDITED` under `generated-freshness`, with the region's lines as evidence: a
+manual edit inside a region is a finding, never something a regeneration silently discards. Text
+outside the markers is a person's and is left alone.
+
+`llms.txt` carries no marker. It is a whole-file artifact with consumers of its own — the
+federation retriever and the freshness gate — and its bytes are unchanged from before.
+
+## The change digest
+
+The digest compares two discovery snapshots by the content hash each file-backed entity carries
+(`docs/spec/incremental-scan-v1.md`): an entity in both with a different hash is *changed*, one
+only in the current snapshot is *added*, one only in the previous is *removed*. An entity without
+a hash — an external package, an area — has nothing to move and is not listed.
+
+"Documentation to review" answers which documents this change should have touched: every document
+that covers, mentions, links to or references a symbol of something that moved, and did not move
+itself. A document that changed alongside its subject is in *changed*, not there.
+
+The previous snapshot is the one `--data` names, otherwise the last `ak-docs scan` (the
+workflow's `normalize` output under `.doc-bridge/workflow`). The current one is a cold scan of the
+working tree. Rendering does not move the baseline — only a scan does — so the digest can be
+rendered as many times as a review needs. With no previous snapshot the command says so and
+exits 2.
+
+## The overlay review page
+
+The page reads an enrichment overlay's `pending` proposals — id, kind, entity, reason, confidence
+and evidence locations — and renders each with links of the form `path#L10-L12`. It is
+deliberately loose about the overlay's shape, which the enrichment workstream owns. With no
+overlay it renders an explicit empty state rather than failing; `.doc-bridge/enrich/overlay.json`
+is read when it exists, and `--data` names any other file.
+
+## Boundaries
+
+Nothing under `src/render` imports anything under `src/agents`; a test walks the imports.
+Rendering works with the Registry disabled, because it never consults it.

package/docs/spec/retrieval-index-v1.md

@@ -0,0 +1,164 @@
+---
+title: Retrieval index v1
+description: The retrieval index as a projection of the snapshot, the ranking that reads it, and the handoffs derived from its graph.
+---
+
+# Retrieval index v1
+
+The retrieval index is what search ranks. It is a projection of the discovery snapshot — a pure
+function of the snapshot, the accepted enrichment overlay and the effective configuration — and it
+has no scanner of its own.
+
+That sentence closes a gap that had been in the design since the first index. `buildDocBridgeIndex`
+walked the repository a second time, parsed every module and document again, and produced records
+that shared nothing with the snapshot but a file path. Two views of one repository, built by two
+pipelines, could disagree; the index held eleven sidecars while the snapshot held hundreds of
+entities. Now an entity retrieval can find is an entity discovery observed — same id, same content
+hash, same evidence — and the routes the configuration declares (intents, changes, ownership) are
+projected next to them.
+
+## The artifact
+
+`RetrievalIndexV1` lives inside `DocBridgeIndexV1` as `projection`, so every reader of the index
+receives it with the same freshness check. `knowledge[]` is still written for every reader that
+predates it and now carries every projected document and module — without body text, which lives
+once in the projection.
+
+```json
+{
+  "type": "retrieval-index",
+  "schemaVersion": 1,
+  "contentHash": "…",
+  "snapshotHash": "…",
+  "overlayHash": "…",
+  "configurationHash": "…",
+  "lexiconVersion": 1,
+  "graphMetricsVersion": "1.0.0",
+  "weights": { "title": 4, "headings": 3, "symbols": 3, "path": 2, "aliases": 2, "summary": 2, "body": 1 },
+  "params": { "k1": 1.2, "b": 0.75 },
+  "lexical": { "version": 1, "documentCount": 364, "fieldNames": ["…"], "averageFieldLength": { "…": 0 } },
+  "entries": [
+    {
+      "id": "module:src/query/search.ts",
+      "kind": "module",
+      "path": "src/query/search.ts",
+      "title": "search.ts",
+      "aliases": [],
+      "symbols": ["searchIndex"],
+      "tags": ["module", "ts", "query"],
+      "fields": { "title": "search.ts", "headings": "", "path": "src/query/search.ts", "symbols": "searchIndex", "summary": "", "body": "", "aliases": "module ts query" },
+      "graph": { "pagerank": 0, "inboundLinks": 3, "coveredBy": ["document:docs/agent-corpus/query.md"], "mentionedBy": ["…"], "areaId": "area:src/query", "packageId": "package:@agentskit/doc-bridge", "inbound": [], "outbound": [] },
+      "contentHash": "…",
+      "provenance": "observed",
+      "confidence": "observed",
+      "ownershipId": "doc-bridge-query"
+    }
+  ]
+}
+```
+
+`contentHash` is over the inputs — snapshot hash, overlay hash, configuration hash, lexicon and
+graph-metrics versions, weights and parameters — because the projection is a function: equal
+inputs, equal artifact. `IndexStaleError` keeps working from the same three hashes.
+
+Every entry carries the entity's own `contentHash`, its `provenance`, and a `confidence`. An entry
+kind is one of `document`, `module`, `area`, `package`, `intent`, `change`. An ownership record
+attaches to the entity at its path and lends it its id as an alias; the unit then inherits its
+agent document's title, headings, summary and body, because that document is the documentation of
+that unit. A record whose path matches no entity is projected as a declared `package` entry, so a
+query for it still has an answer.
+
+The postings are not stored. `fields` already is the serialised index: tokenisation is versioned
+(`lexiconVersion`) and deterministic, so the postings a reader rebuilds are the postings the writer
+would have stored, and `lexical` records the shape of the collection so a reader can check it
+rebuilt the same one.
+
+The one thing read from disk is the body of a document the snapshot already names — bounded by the
+same text budget as before — and the read is verified against the entity's content hash. A file
+that changed since the scan is projected from what the snapshot recorded about it, not from what is
+on disk now.
+
+## Ranking
+
+`src/retrieval/rank.ts` replaces the internals of `searchIndex` and keeps its signature. The score
+has named parts:
+
+```
+score = lexical × prior
+      + exactId + exactPath + exactSymbol
+      + graphProximity + canonicality + audienceFit + acceptedAgentSignals
+```
+
+- **lexical** — BM25 over the projected fields, with the weights above. Configurable under
+  `retrieval.weights`; recorded in the artifact.
+- **prior** — the query-shape heuristics, as a multiplier: a curated (agent-audience) document, an
+  ownership record for a routing question, an intent or change route whose title covers the query,
+  a module for a symbol- or path-shaped query. A prior can only amplify evidence that exists.
+- **exactId / exactPath / exactSymbol** — the query names the thing: an alias or id, a path or
+  filename, an exported symbol. Per-token identity applies to queries of at most two tokens; a
+  sentence does not name a thing by containing one of its tokens.
+- **graphProximity** — within two hops of one of the ten strongest lexical hits, over covers,
+  mentions, links and imports. Scaled by the anchor's share of the best score, so a hub page that
+  barely matched cannot lift everything it links to.
+- **canonicality** — log-scaled PageRank over `links-to` and `covers`: the page other pages point
+  at outranks the leaf that mentions the same thing. A tie-breaker among answers, never an answer:
+  it applies only to lexical hits.
+- **audienceFit** — the `--agent` prior for documentation written for an agent.
+- **acceptedAgentSignals** — the overlay hook, carried at zero weight until the overlay workstream
+  lands, so the code path and the explain view already exist.
+
+A result that only a relation surfaced earns proximity and nothing else. Results below a third of
+the best score are dropped; a caller assembling a neighbourhood rather than an answer passes
+`floor: 0`.
+
+**Confidence** on a result is the entry's own when the query matched it directly, and the weaker
+of the entry and the surfacing relation when a relation alone surfaced it — a `fuzzy` mention makes
+a `fuzzy` result. Every result carries evidence (the entity's path and content hash), provenance and
+confidence.
+
+`ak-docs search <term> --explain`, or `explain: true` over the API, attaches the matched terms and
+fields and every component's contribution to each result. Explaining never changes the ranking.
+
+```
+$ ak-docs search "workflow transitions persisted" --explain --text
+  [module] module:src/workflow/engine.ts score=115.27 confidence=observed
+    src/workflow/engine.ts
+    why: lexical=115.27
+    matched: aliases: workflow | path: workflow | symbols: workflow
+```
+
+## Handoffs for any entity
+
+`handoffForEntity(index, id, config, { root })` in `src/query/handoff.ts` answers for a package, an
+area, a module or a document — by entity id, ownership id, alias or path — and replaces
+`handoffForPackage`. `runQuery` and MCP `handoff.resolve` go through it.
+
+| Field | Derived from |
+| --- | --- |
+| `editRoots` | the area or package itself; a module's area; a document's own path |
+| `startHere` | the ownership record's agent document, then documents that `cover` the target, then those that `mention` it, then one `links-to` hop from those, then the corpus index; within each tier the more canonical page first |
+| `readBeforeEditing` | the next two, plus `AGENTS.md` |
+| `checks` | an ownership override, then what the index recorded when it merged frontmatter, package scripts and defaults, then the package-manager default for the unit's package |
+| `related` | the strongest importing and imported areas, with the import that proves each |
+| `explain` | which relation produced each field |
+| `evidence` | the target's path and content hash, and the documents behind `startHere` |
+| `metadata` | `entityId`, `kind`, `checksSource`, `confidence`, `areaId`, `packageId` |
+
+`AgentHandoffV1` stays byte-compatible: `related`, `explain`, `evidence` and `metadata` are optional
+additions, and `target.type` gains `area` and `document`. A handoff written before they existed is
+still a valid handoff.
+
+## The retriever
+
+`createDocBridgeRetriever(index)` returns `RetrievedDocument[]` from `@agentskit/core` — content is
+the projected title, summary and body, `metadata` carries `kind`, `path`, `evidence`, `explain` and
+`confidence` — so `createHybridRetriever`, `createRerankedRetriever` and `formatRetrievedDocuments`
+consume Doc Bridge with no adapter. The contract is mirrored in-repo (the core package is an optional
+peer) and a test asserts assignability against the real package and runs the real hybrid retriever
+over it. `retrieve('query', { limit })` still works.
+
+## Boundaries
+
+Nothing reachable from `search`, `query` or the projection imports anything under `src/agents`; a
+test walks the imports. The deterministic layer is complete on its own, and the enrichment stage
+never sits on its path.