@agentskit/doc-bridge 1.7.45 → 1.9.0

package/docs/adr/0006-registry-semantic-grounding.md

@@ -0,0 +1,20 @@
+---
+title: Registry semantic review grounding boundary
+status: accepted
+date: 2026-08-30
+---
+
+# Registry semantic review grounding boundary
+
+## Decision
+
+Registry agents may classify and explain deterministic documentation findings, but their proposals must be grounded in the exact snapshot and reconciliation report supplied to the adapter. The adapter requires a known diagnostic, at least one matching evidence reference, and the installed Registry agent identity and version. It accepts either the default configured agent or an alternate installed agent through configuration without changing the common engine.
+
+Registry output remains advisory. Human approval is required before a proposal is converted into a fix or considered resolved, and applying a fix requires post-apply verification against the new source revision.
+
+## Consequences
+
+- Unsupported claims and invented evidence fail closed at the adapter boundary.
+- Deterministic facts remain separate from semantic agent judgment.
+- Agent swaps remain configurable and attributable.
+- The existing fix-proposal approval and verification flow remains the single mutation path.

package/docs/adr/0007-longitudinal-study-metrics.md

@@ -0,0 +1,21 @@
+---
+title: Deterministic longitudinal study metrics
+status: accepted
+date: 2026-08-30
+---
+
+# Deterministic longitudinal study metrics
+
+## Decision
+
+Doc Bridge calculates longitudinal study metrics from content-addressed observation ledgers. It exposes subgroup metrics and comparisons for the baseline and current approved round, preserves provider-versus-estimated token provenance, keeps missing measurements explicit, and emits uncertainty for rates. A bounded numeric measurement envelope allows task, documentation, cost, and future operational metrics to be added without changing the observation identity contract.
+
+Efficiency improvements are subordinate to correctness, evidence, acceptance, safety, and rework. A round with cheaper or faster execution but a quality regression is reported as `regressed`.
+
+## Consequences
+
+- The same ledger produces JSON and text reports with the same metric values and content hash.
+- Baseline replacement is outside the calculator and remains an explicit audited operation.
+- Historical data can remain incomplete without being converted into false precision.
+- New metric names can be collected without a schema migration, but interpretation requires a versioned metric contract and documentation.
+- Small samples remain `inconclusive`, so the report supports decisions without overstating evidence.

package/docs/adr/0008-study-verification-boundary.md

@@ -0,0 +1,21 @@
+---
+title: Controlled study verification boundary
+status: accepted
+date: 2026-08-31
+---
+
+# Controlled study verification boundary
+
+## Decision
+
+Controlled study results require a separate content-addressed verification binding. The binding records provenance, artifact hashes, anonymized privacy review, and consumed token/runtime budgets. The result envelope is the only artifact eligible for publication or an enterprise study claim.
+
+Recovery remains delegated to the existing workflow engine and observation-ledger idempotency. The harness is the authority for state, human approval, tracking authorization, and explicit baseline replacement.
+
+## Consequences
+
+- A locally calculated report is distinguishable from a verified result.
+- Privacy and budget failures fail closed without exposing matched values.
+- Interrupted or stale work can resume from valid evidence without duplicating observations.
+- Baselines remain immutable during normal runs and have an auditable replacement path.
+- Publication still requires human review; deterministic scanning cannot approve its own output.

package/docs/adr/0009-study-provider-cli-adapter.md

@@ -0,0 +1,25 @@
+---
+title: Generic CLI adapter for controlled study providers
+status: accepted
+date: 2026-08-31
+---
+
+# Generic CLI adapter for controlled study providers
+
+## Decision
+
+The controlled study invokes explicitly configured model or agent CLIs as fresh child processes. The adapter accepts an executable plus an argument array, never a shell command string, and allowlists environment variables. Each invocation receives bounded input, runtime, output, and retry limits and must return one JSON object on stdout. Logs belong on stderr.
+
+Provider configuration is content-addressed and maps every `(model, scenario)` pair to exactly one command. The adapter does not bundle or require a local model runtime: hosted providers, vendor CLIs, and AgentsKit Registry agents are configured by the study owner. Provider network access is declared per mapping so the run can be audited; repository task network policy remains governed by the study protocol.
+
+## Alternatives considered
+
+- Ollama as the default: rejected because a heavyweight local runtime would create friction and hardware-dependent results.
+- Direct SDK integrations: deferred because they multiply provider-specific dependencies and credential handling in the core package.
+- Shell command strings: rejected because shell interpretation makes argument provenance and isolation weaker.
+
+## Consequences
+
+- A real provider can be selected without changing the runner or ledger schema.
+- A missing executable, malformed JSON, non-zero exit, timeout, or output limit fails closed and is recorded as unavailable, invalid, failed, timed-out, or budget-exceeded evidence.
+- Provider credentials remain outside committed study artifacts; only explicitly allowlisted environment variables are passed to the child.

package/docs/agent-corpus/INDEX.md

@@ -3,8 +3,19 @@ type: module
 id: doc-bridge-index
 editRoot: src/index-builder
 humanDoc: /docs/recipes/index-pipeline
+owner: doc-bridge-maintainers
+lifecycle: active
+sourceOfTruth: src/index-builder
+validationPath: pnpm test && pnpm typecheck && node bin/ak-docs.js index
 ---
 
 # Index builder
 
-Owns corpus scanning, handoffs, hashes, `llms.txt`, and watch mode. Generated output must remain deterministic.
+Owns corpus scanning, handoffs, hashes, `llms.txt`, and watch mode. Generated output must remain deterministic. The retrieval projection inside the index is a function of the discovery snapshot (`src/retrieval/project.ts`); the builder scans nothing for it beyond the snapshot itself, and `knowledge[]` stays in step with it without body text.
+
+`project-corpus.ts` projects every repository document and source module into `index.knowledge`
+so retrieval can see what the discovery snapshot sees; it must walk the same files under the same
+safety limits, which is why both import from `src/discovery/inputs.ts`. One walk produces both the
+entries and the `inputs` fingerprint, so the hash can never describe a different file set than the
+one projected. `llms.txt` stays curated — the renderer filters projected entries out, and the
+conformance profile re-renders to check freshness, so the filter belongs there and nowhere else.

package/docs/agent-corpus/OVERVIEW.md

@@ -2,8 +2,33 @@
 type: index
 purpose: Route coding agents to Doc Bridge ownership sidecars.
 owner: maintainers
+lifecycle: active
+sourceOfTruth: doc-bridge.config.json
+validationPath: node bin/ak-docs.js query ownership doc-bridge --agent
 ---
 
 # Doc Bridge agent corpus
 
 Resolve the requested ownership ID with `ak-docs query ownership <id> --agent`. Read the returned sidecar and its linked human guide before editing.
+
+## Example
+
+```bash
+ak-docs query ownership doc-bridge --agent
+```
+
+The command returns a bounded handoff similar to:
+
+```json
+{
+  "target": { "type": "package", "id": "doc-bridge", "path": "src" },
+  "startHere": "docs/agent-corpus/doc-bridge.md",
+  "readBeforeEditing": ["docs/agent-corpus/doc-bridge.md", "AGENTS.md"],
+  "editRoots": ["src"],
+  "checks": ["pnpm test", "pnpm typecheck"],
+  "humanDoc": "/docs/POSITIONING"
+}
+```
+
+Use `startHere` and `readBeforeEditing` first, edit only within `editRoots`,
+then run the declared `checks`.

package/docs/agent-corpus/chat.md

@@ -3,8 +3,12 @@ type: module
 id: doc-bridge-chat
 editRoot: src/intelligence
 humanDoc: /docs/chat-and-rag
+owner: doc-bridge-maintainers
+lifecycle: active
+sourceOfTruth: src/intelligence
+validationPath: pnpm test && pnpm typecheck && pnpm docs:typecheck
 ---
 
 # Chat and RAG
 
-Owns optional AgentsKit retrieval and chat after deterministic lookup. Conversational UI belongs to AgentsKit Chat; enterprise orchestration belongs to AKOS.
+Owns optional AgentsKit retrieval and chat after deterministic lookup. Conversational UI belongs to the chat surface; enterprise orchestration belongs to the consuming platform.

package/docs/agent-corpus/cli.md

@@ -3,8 +3,24 @@ type: module
 id: doc-bridge-cli
 editRoot: src/cli
 humanDoc: /docs/spec/cli
+owner: doc-bridge-maintainers
+lifecycle: active
+sourceOfTruth: src/cli
+validationPath: pnpm test && pnpm typecheck
 ---
 
 # CLI
 
 Owns public `ak-docs` commands and output modes. Keep JSON output versioned and text output readable.
+
+The documentation audit is a deterministic post-discovery check:
+
+```bash
+ak-docs audit documentation --json
+```
+
+It reports measurable quality, coverage, stale, contradiction, redundancy, and structure-gap signals. `not-analyzed` means semantic evidence is missing; it is not a pass.
+
+`ak-docs enrich` and `check --enrich` are the only commands that call a Registry agent for
+enrichment. A failed, timed-out or malformed enrichment is reported and never changes a check
+result or its exit code; `enrich` exits 2 and writes no overlay.

package/docs/agent-corpus/conformance.md

@@ -3,8 +3,20 @@ type: module
 id: doc-bridge-conformance
 editRoot: src/conformance
 humanDoc: /docs/spec/documentation-standard-v1
+owner: doc-bridge-maintainers
+lifecycle: active
+sourceOfTruth: src/conformance
+validationPath: pnpm test && node bin/ak-docs.js conformance run documentation-standard-v1 --text
 ---
 
 # Conformance
 
 Owns versioned documentation-standard rules and evidence. Do not turn missing evidence into a passing score.
+
+Documentation audits are a separate, configurable check after discovery and reconciliation:
+
+```bash
+ak-docs audit documentation --json
+```
+
+Use the audit metrics and evidence to review quality, coverage, stale declarations, and structure/documentation gaps. Generated documents are freshness-boundary checks only; semantic findings marked `not-analyzed` require the configured Registry agent or a human review.

package/docs/agent-corpus/doc-bridge.md

@@ -3,8 +3,55 @@ type: package
 package: '@agentskit/doc-bridge'
 editRoot: src
 humanDoc: /docs/POSITIONING
+owner: doc-bridge-maintainers
+lifecycle: active
+sourceOfTruth: src
+validationPath: pnpm test && pnpm typecheck
 ---
 
 # Doc Bridge core
 
 Owns the public CLI, index, MCP, gates, and doctor contracts. Preserve deterministic behavior and run `pnpm test && pnpm typecheck`.
+
+Analyzers emit `observed` facts with file and line evidence, and say what they could not resolve
+as coverage rather than guessing: an ambiguous reference produces a note, not an edge. A near-miss
+resolves only at the Jaro-Winkler threshold with a single candidate. Adding an analyzer means
+adding its version to `analyzerVersions` and bumping `pipelineVersion`, never changing the
+`DiscoverySnapshotV1` envelope.
+
+Areas (`area:<dir>`) are the unit between a package and a file. Each module belongs to exactly
+one — the most specific — so containment is a tree and area-scope aggregation has one answer per
+module. An ownership path is an area by declaration even when convention would not derive it.
+
+Graph signals live in `src/graph/` and are computed on demand, never stored: sort node and edge
+insertion before any metric, round every score, and keep graphology's format out of every artifact.
+A clustering result is a suggestion in `coverage`, never an entity. A static signal must not be
+worded as a runtime claim.
+
+A file-backed entity carries its file's hash, and a second scan may reuse an entity whose hash is
+unchanged — but only while the universe its references resolve against is identical, and only from
+a snapshot produced by this pipeline, these analyzers and this configuration. Reuse either
+reproduces a cold scan exactly or it is refused, and the run reports what it reused as `coverage`.
+
+Markdown for people is rendered from templates in `src/render/`, never concatenated: a template
+sees only the variables `src/render/data.ts` computes, sorted and without timestamps, and the
+synchronous evaluator in `src/render/engine.ts` must keep rendering what knap renders. Every
+generated region carries a `<!-- doc-bridge:generated hash=… -->` marker so the analyzer skips it
+and the audit can report a hand edit inside it; `llms.txt` is the exception and stays byte-identical.
+Enrichment (`src/enrich/`, `src/schemas/enrichment.ts`) is advisory by construction. A proposal is
+a typed claim with one deterministic validator per kind; a validator checks, it never judges. An
+accepted entry binds to the content hash of the entity it describes and expires when that moves;
+no entry deletes or alters observed data, and the projection asserts it. The overlay is read only
+while `intelligence.registry.enabled` is true, a read never writes, and a corrupt overlay is no
+overlay. No agent approves anything — not its own output, not another's — and human approvals go
+through the ecosystem approval gate. Adding a proposal kind means a schema, a validator, a policy,
+a valid fixture and a rejection fixture, and a row in `docs/spec/enrichment-overlay-v1.md`.
+
+An enrichment run reports its own shape (`src/enrich/stats.ts`): counts per kind, a rejection
+histogram, invented references counted apart from other rejections, cost, and stability against the
+previous run. `stats` stays outside the overlay's content hash — two runs that decided identically
+must agree on their hash while disagreeing about how long they took. The overlay may leave retrieval
+unchanged or improve it; it may not lower hit@3, and `measureOverlayRetrievalDelta`
+(`src/bench/overlay-delta.ts`) projects both indexes from one snapshot so the only difference
+between the two runs is the overlay. A drop is a finding about the agent, never a new baseline.
+See [Measured enrichment v1](../spec/measured-enrichment-v1.md).

package/docs/agent-corpus/doctor.md

@@ -3,8 +3,16 @@ type: module
 id: doc-bridge-doctor
 editRoot: src/doctor
 humanDoc: /docs/spec/documentation-standard-v1
+owner: doc-bridge-maintainers
+lifecycle: active
+sourceOfTruth: src/doctor
+validationPath: pnpm test && node bin/ak-docs.js doctor --text
 ---
 
 # Doctor
 
 Owns health scoring and remediation guidance. Every point must trace to meaningful repository evidence.
+
+Reachability, connectivity and the retrieval benchmark are measured from the snapshot, the
+projection and the golden suite, never declared; a missing suite is `not-analyzed`, not omitted.
+An A requires all three, and the grade must fall while any document is outside the projection.

package/docs/agent-corpus/gates.md

@@ -3,6 +3,10 @@ type: module
 id: doc-bridge-gates
 editRoot: src/gates
 humanDoc: /docs/spec/documentation-standard-v1
+owner: doc-bridge-maintainers
+lifecycle: active
+sourceOfTruth: src/gates
+validationPath: pnpm test && node bin/ak-docs.js gate run
 ---
 
 # Gates

package/docs/agent-corpus/mcp.md

@@ -3,8 +3,21 @@ type: module
 id: doc-bridge-mcp
 editRoot: src/mcp
 humanDoc: /docs/mcp
+owner: doc-bridge-maintainers
+lifecycle: active
+sourceOfTruth: src/mcp
+validationPath: pnpm test && pnpm typecheck && pnpm smoke:packaged
 ---
 
 # MCP
 
 Owns the stdio server and public tool contracts. Preserve runtime validation and stable response shapes.
+
+`knowledge.search` and `knowledge.lookup` (`src/mcp/knowledge.ts`) read the same projection and
+rank with the same `searchIndex` as the CLI; a test compares the two. A `budgetTokens` drops
+sections only in the declared order — evidence excerpts, related, neighbours, summaries — and
+never the entity, the evidence paths and hashes, the handoff fields or the diagnostics; a payload
+that cannot fit says `fits: false`. Existing tool names, arguments and payloads do not change.
+`docbridge.proposals` carries enrichment review as `enrich-list`, `enrich-approve` and
+`enrich-reject`; a decision goes through `decideEnrichment` and the shared approval gate, never
+through a direct overlay edit.

package/docs/agent-corpus/memory.md

@@ -3,6 +3,10 @@ type: module
 id: doc-bridge-memory
 editRoot: src/memory
 humanDoc: /docs/schemas/memory-candidate-v1
+owner: doc-bridge-maintainers
+lifecycle: active
+sourceOfTruth: src/memory
+validationPath: pnpm test && pnpm typecheck
 ---
 
 # Memory

package/docs/agent-corpus/query.md

@@ -3,8 +3,41 @@ type: module
 id: doc-bridge-query
 editRoot: src/query
 humanDoc: /docs/query
+owner: doc-bridge-maintainers
+lifecycle: active
+sourceOfTruth: src/query
+validationPath: pnpm test && pnpm typecheck
 ---
 
 # Query
 
 Owns deterministic package and document resolution. Prefer an explicit miss over an invented answer.
+
+Ranking (`src/retrieval/rank.ts`) reads the retrieval projection (`src/retrieval/project.ts`),
+which is a function of the snapshot: never add a scanner to the query path, and never import
+anything under `src/agents` from it. The score is field-weighted BM25 times a prior, plus absolute
+boosts for exact identity, plus graph proximity and canonicality; every component is reported by
+`--explain`, and explaining must never change the ranking. Keep the split: a prior must never be
+able to rank a record that matched nothing, an exact id, path or exported symbol must win over
+prose that mentions it, and a result only a relation surfaced earns proximity and nothing else. One
+tokenizer (`searchTokens`) serves both indexing and querying — never tokenize one side differently.
+Changing the stopword lists, folding, or token expansion means bumping `SEARCH_LEXICON_VERSION`,
+because the index records it and the artifact hash depends on it.
+
+Handoffs (`src/query/handoff.ts`) are derived from the projection's graph for any entity — package,
+area, module, document — and every field says which relation produced it. `checks` must report
+their origin in `metadata.checksSource`; `startHere` prefers a document that covers the target over
+one that mentions it.
+
+Re-run `pnpm bench:retrieval` after any ranking change; a hit@3 regression is a blocked change,
+not a judgement call.
+
+Accepted agent signals (`agentSignal` on an entry) are a share of `ACCEPTED_SIGNALS_WEIGHT`, which
+is 15% of the exact-id boost and must stay there: a signal may reorder near-ties among lexical hits
+and must never outrank an exact identifier, path or symbol match. Without an overlay the ranking is
+byte-identical to the ranking before enrichment existed, and the bench baseline must not move.
+
+`ak-docs bench retrieval <suite> --overlay` answers whether the accepted overlay earns its cost:
+the same suite over the same snapshot, once with the overlay projected and once without. It needs
+no index on disk, and it exits non-zero when hit@3 falls. Adding an overlay-consuming ranking
+signal means re-running it, not only `pnpm bench:retrieval`.

package/docs/bench/README.md

@@ -0,0 +1,122 @@
+---
+title: Retrieval benchmark
+description: A deterministic, model-free measurement of whether a query returns the right entity, and the gate that stops a ranking change from making it worse.
+---
+
+# Retrieval benchmark
+
+`ak-docs bench retrieval` answers one question: **does a query return the right thing?** It runs the deterministic retrieval path over a golden query suite, reports hit@1, hit@3, mean reciprocal rank and the context cost of the top three results, and compares the figures with an approved baseline. It uses no model, no network and no API key, and it finishes in well under a second on this repository, so it can gate every pull request.
+
+This is workstream KR-07 of [#169](https://github.com/AgentsKit-io/doc-bridge/issues/169). It exists before the ranking work in KR-01 and KR-06 so those changes have a recorded "before" to improve on, rather than a claim.
+
+## Run it
+
+```bash
+node bin/ak-docs.js index                                   # the benchmark measures the current index
+pnpm bench:retrieval                                        # suite + committed baseline, text output
+node bin/ak-docs.js bench retrieval docs/bench/retrieval-suite-v1.json --json
+```
+
+Exit codes: `0` when the figures hold, `1` on a hit@3 regression or a changed suite, `2` on a usage or input error.
+
+## What it measures
+
+| Metric | Meaning |
+| --- | --- |
+| `hitAt1` | Share of cases whose first result is an expected target |
+| `hitAt3` | Share of cases with an expected target in the top three. **The gated metric** |
+| `meanReciprocalRank` | Mean of `1 / rank`, `0` when no expected target appears |
+| `meanContextBytes` | Mean serialized size of the top-three payload an agent would receive |
+| `meanApproxTokens` | `meanContextBytes / 4`, reported as `tokenMethod: 'approximate'` |
+| `zeroResultRate` | Share of cases where the query returned nothing at all |
+
+Results are also segmented `byLang` and `byKind`, because an aggregate average hides exactly the failures that matter: on the first run, ownership routing scored 100 percent while every exported-symbol query scored zero.
+
+The result artifact carries **no timestamp and no latency**, so two runs over the same index and suite are byte-identical and their content hashes match. Wall time belongs in the terminal, never in a comparable artifact.
+
+## The suite
+
+[`retrieval-suite-v1.json`](./retrieval-suite-v1.json) is a valid [Open Eval Format](https://www.npmjs.com/package/@agentskit/core) document (`evalFormatVersion: 2026-04`), so the same dataset can be read by any runner that speaks the format. 60 cases across four kinds and two languages:
+
+| Kind | Cases | What it asks |
+| --- | --- | --- |
+| `symbol` | 20 | An exported identifier, the way an agent types it: `reconcileKnowledge` |
+| `path` | 8 | A file or directory: `src/mcp/server.ts` |
+| `question` | 26 | Natural language, English and Portuguese |
+| `ownership` | 6 | The routing question a handoff exists to answer |
+
+Each case carries `metadata.expectedTargets`. **A target matches a result by entity id or by repository path**, which is what lets one suite survive the entity-identity changes coming in KR-01 through KR-06: `docs/mcp.md` keeps working when the index starts carrying `document:docs/mcp.md`, and a module target starts working once modules are projected into the index.
+
+Each case also carries a portable `expected.regex` alternation over the same targets, so a generic Open Eval Format runner can compute pass or fail without knowing anything about Doc Bridge. A test asserts the two stay consistent, and another validates the whole suite with the real `validateEvalSuite` from `@agentskit/core/eval-format`, so the locally mirrored format cannot drift from the ecosystem one.
+
+### Adding a case
+
+Add it to the suite, then re-approve the baseline: a changed suite makes the old figures incomparable, so the gate fails closed rather than pretending otherwise.
+
+```bash
+node bin/ak-docs.js bench retrieval docs/bench/retrieval-suite-v1.json \
+  --baseline docs/bench/retrieval-baseline-v1.json \
+  --update-baseline --by "<your name>" --reason "Added three cases for the area entities"
+```
+
+## The baseline and the gate
+
+[`retrieval-baseline-v1.json`](./retrieval-baseline-v1.json) holds the approved figures plus an approval record: who approved them, when, why, and the hashes of the result and index they were measured from. Three properties make it a gate rather than a suggestion:
+
+- **A normal run never writes it.** Recording a baseline requires `--update-baseline` *and* `--by <name>`. Without an approver the command refuses.
+- **It cannot be edited.** The file carries its own content hash; a hand-edited figure is rejected before any comparison happens.
+- **A changed suite fails closed.** Comparing figures measured over different questions would be meaningless, so it is an error that only an explicit re-approval clears.
+
+Only `hitAt3` blocks. Every other metric is reported: an improvement as `improved`, a decline as `warning`. So a change that lifts hit@3 while wrecking hit@1 passes the gate but says so out loud.
+
+## The baselines
+
+### Before KR-01
+
+Measured on `master` at 1.8.0, before any ranking work:
+
+| Metric | Value |
+| --- | --- |
+| hit@1 | 21.7% |
+| hit@3 | 23.3% |
+| Mean reciprocal rank | 0.228 |
+| Zero-result rate | 46.7% |
+| Mean context | 243 bytes (~61 tokens) |
+
+By kind: ownership 100%, question 26.9%, path 12.5%, **symbol 0%**. By language: English 20%, Portuguese 40%.
+
+Those numbers are the diagnosis in the parent PRD turned into measurements. Nearly half of all queries return nothing, and not one of the twenty exported-symbol queries finds its module, because the index holds 11 agent sidecars while the snapshot holds 369 entities. KR-01 and KR-06 have to move these; this file is how anyone can check that they did.
+
+### After KR-01
+
+The current approved baseline, with the repository corpus projected into the index and ranked by
+field-weighted BM25:
+
+| Metric | Before | After |
+| --- | --- | --- |
+| hit@1 | 21.7% | **76.7%** |
+| hit@3 | 23.3% | **83.3%** |
+| Mean reciprocal rank | 0.228 | **0.812** |
+| Zero-result rate | 46.7% | **5.0%** |
+| Mean context | 243 bytes (~61 tokens) | 343 bytes (~86 tokens) |
+
+The figures here are a summary; [`retrieval-baseline-v1.json`](./retrieval-baseline-v1.json) holds
+the approved ones. They move slightly whenever the documentation changes, because the
+documentation *is* part of the corpus being searched — which is why only hit@3 blocks.
+
+By kind: symbol **0% → 100%**, path 12.5% → **100%**, question 26.9% → **61.5%**, ownership 100%
+→ 100%. By language: English 20% → **92%**, Portuguese 40% → 40%.
+
+**On the context figure.** Mean context rose, and that is not a regression hiding in a warning.
+Before, 46.7% of queries returned nothing and cost nothing; the mean was low because retrieval
+was failing. Per *answered* query the cost went down — 243 / 0.533 ≈ 456 bytes before, 343 /
+0.95 ≈ 361 bytes now — while 78% more queries get answered. That is the trade the PRD asked
+for; the metric is reported rather than gated precisely so the shape of such a change stays
+visible.
+
+**On Portuguese.** Unchanged at 40%, and three of the ten cases still return nothing. The lexicon
+now handles Portuguese stopwords, accents and plurals, so a Portuguese query against Portuguese
+documentation ranks by the same rules as English — but this repository's documentation is in
+English, and matching `reconciliação` to `reconciliation` is a cross-language problem that
+lexical retrieval cannot solve. It needs the semantic layer in a later workstream. The suite
+segments by language so the gap stays measured instead of assumed.

package/docs/bench/retrieval-baseline-v1.json

@@ -0,0 +1,28 @@
+{
+  "type": "retrieval-benchmark-baseline",
+  "schemaVersion": 1,
+  "contentHash": "1fd663a565dfc9c1e19a12139d45f11a7a628ad5d0fec4e549c6148056c3ac3a",
+  "contentHashAlgo": "sha256-normalized-v1",
+  "suite": {
+    "name": "doc-bridge-retrieval-v1",
+    "caseCount": 60,
+    "contentHash": "8f789470ce0fca41154474191fed0163869518b278f7c91d6b5370b919cde072"
+  },
+  "metrics": {
+    "caseCount": 60,
+    "hitAt1": 0.783333,
+    "hitAt3": 0.883333,
+    "meanReciprocalRank": 0.827593,
+    "meanContextBytes": 428,
+    "meanApproxTokens": 108,
+    "zeroResultRate": 0.066667,
+    "tokenMethod": "approximate"
+  },
+  "approval": {
+    "approvedAt": "2026-09-14T20:12:19.833Z",
+    "approvedBy": "Emerson Braun",
+    "reason": "KR-06 ranks the retrieval projection of the snapshot with graph signals; hit@3 83.3% to 88.3%",
+    "resultHash": "77dbbd006ede58746913fdaf7741df48856daf5c09815c81eaac187eb9377399",
+    "indexHash": "c5600283b4c6cf5fc2546d0f8a2eb8158dcdd0e670bd1a7a070c68484dad709a"
+  }
+}