@agentskit/doc-bridge 1.7.44 → 1.9.0

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.

package/docs/spec/graph-signals-v1.md

@@ -0,0 +1,92 @@
+---
+title: Graph signals v1
+description: What Doc Bridge computes from the repository graph, what each signal means, and what it deliberately does not claim.
+---
+
+# Graph signals v1
+
+The knowledge snapshot is a graph, and some questions are only answerable as graph questions: which
+document is the entry point, which module every change reaches through, which directories move
+together, where the imports run in a circle.
+
+These are computed with [graphology](https://graphology.github.io) from the snapshot, on demand.
+The graph is a working structure: it is never serialised, `DiscoverySnapshotV1` does not change, and
+graphology's own format never reaches disk. Nodes and edges are inserted in sorted order and every
+score is rounded before it is returned, so two runs over the same snapshot agree exactly — including
+after the input order is shuffled.
+
+## The signals
+
+| Signal | Computed from | Over |
+| --- | --- | --- |
+| **Canonicality** | PageRank | `links-to` and `covers` |
+| **Centrality** | betweenness, normalized | `imports` and `re-exports` |
+| **Proximity** | bounded shortest path | imports, documentation, `mentions`, `depends-on` |
+| **Import cycles** | depth-first search | `imports` and `re-exports` |
+| **Area suggestions** | seeded Louvain communities | `imports` and `re-exports` |
+
+External and unresolved endpoints are left out unless a caller asks for them: a dependency on a
+third-party package is a fact about the repository, not a part of its architecture.
+
+**Canonicality** answers where a reader should start. A page many documents link to, or that covers
+many entities, outranks a leaf note nothing points at — however recently the leaf was edited.
+
+**Centrality** answers how much of the dependency structure runs through one module. It is a review
+signal: a change there reaches further than its diff suggests. It is *not* a statement about runtime
+availability, and the diagnostic says so, because "single point of failure" is a claim about
+deployment that a static import graph cannot make.
+
+**Proximity** answers how many hops apart two entities are, bounded — three by default. Unbounded
+proximity is not useful: at ten hops everything is related to everything. `contains` is excluded on
+purpose. It is hierarchy, and including it puts every module in an area two hops from every other
+one, which is true and tells a reader nothing.
+
+**Import cycles** are reported with every edge that forms them. `graphology-dag` answers whether a
+cycle exists; reporting one needs the path, because a diagnostic whose loop a reader cannot trace is
+a claim rather than a finding. The search is bounded in count, and the cycle is rotated so the
+lexicographically smallest node comes first — the same cycle found from two different entry points
+is one finding.
+
+## Area suggestions are suggestions
+
+A Louvain community is a hypothesis: these modules move together, so perhaps they are one unit. It
+never becomes an [area](./config-v1.md#analysisareas-optional) on its own. An area is derived from
+the repository's own structure or declared by a human, and a clustering algorithm is neither.
+
+Suggestions travel as `coverage` entries with `analyzer: graph`, `scope: area-suggestion:<path>` and
+status `not-analyzed` — the honest status, because the clustering ran but whether the cluster is an
+area is a question nobody has answered. A directory that is already an area produces no suggestion.
+Community detection draws from a seeded generator, so a suggestion is reproducible rather than a
+different guess each run.
+
+## Reading the graph as memory
+
+```ts
+import { createDocBridgeGraphMemory } from '@agentskit/doc-bridge'
+
+const graph = createDocBridgeGraphMemory(snapshot)
+await graph.getNode('module:src/mcp/server.ts')
+await graph.findEdges({ label: 'covers', to: 'area:src/mcp' })
+await graph.neighbors('module:src/mcp/server.ts', { depth: 2 })
+```
+
+This satisfies `GraphMemory` from `@agentskit/memory`, so an agent built on AgentsKit walks
+repository structure with the same three calls it uses for its own memory. A second argument layers
+extra entities and relations over the observation, in the snapshot's own vocabulary, so an approved
+enrichment overlay plugs in unchanged.
+
+Writes are accepted and kept in process. The snapshot is an observation and a caller cannot edit it,
+so `upsertNode` lands in a working layer above the projection and `deleteNode` masks rather than
+erases — an agent can annotate what it is exploring without any of it being mistaken for something
+the repository said. `clear()` drops the working layer and leaves the projection intact.
+
+## What consumes them
+
+`centrality-risk` in the rules engine is betweenness now. It used to count how many
+undocumented-relation findings were attached to an entity, which measures documentation debt and
+calls it architecture: a module every import path runs through scored zero if it happened to be
+documented. Without a graph the rule reports nothing at all, which is better than reporting the
+wrong thing under a name people act on.
+
+The rule's threshold reads as a rank when it is 1 or more — `3` means "flag the three most central
+entities" — and as a minimum betweenness when it is below 1.

package/docs/spec/incremental-scan-v1.md

@@ -0,0 +1,102 @@
+---
+title: Incremental scan v1
+description: How Doc Bridge hashes each file-backed entity, when a second scan may reuse one, and what it refuses to reuse.
+---
+
+# Incremental scan v1
+
+Every `module`, `document` and `package` entity carries the hash of its file in its first evidence
+item. An `external` entity carries none: it is a name in a manifest, not a file on disk.
+
+```json
+{
+  "id": "module:src/query/search.ts",
+  "kind": "module",
+  "evidence": [{ "source": "code", "path": "src/query/search.ts", "contentHash": "…" }]
+}
+```
+
+`EvidenceSchema.contentHash` had existed since the first schema and discovery never filled it, so
+every cache and every overlay could be keyed only on "the whole repository changed" — which is true
+between any two commits and therefore useless. With a hash per file, a consumer can expire one
+entry, and a second scan can skip the expensive part: the TypeScript parse and the Markdown parse,
+where nearly all of discovery's time goes.
+
+A document's hash is taken after a leading byte-order mark is stripped. A mark is not content: a
+file that only gained one parses to the same tree, and should not invalidate anything.
+
+## Reuse
+
+```ts
+const cold = discoverRepository({ root, config })
+const fast = discoverRepository({ root, config, previous: cold })
+```
+
+`previous` is an offer, not an instruction. Discovery reuses an entity only when reuse cannot change
+the answer, and two different things can change it:
+
+- **An entity's own fields depend on its own bytes.** A hash match is enough.
+- **A relation depends on what else exists.** A module importing `./new.js` resolved to nothing
+  before that file was added and resolves to a module after; a document mentioning `rank` points at
+  whichever module declares it. So relation reuse also requires that the universe the references
+  resolve against is identical.
+
+Two fingerprints capture that universe, both derived from the previous snapshot rather than stored
+in it — everything they cover is in the snapshot already, and a stored fingerprint is one more
+thing that can be stale or forged.
+
+| Fingerprint | Covers | Gates |
+| --- | --- | --- |
+| Module universe | module paths, packages, compiler options | reuse of a module's relations |
+| Resolution | the module universe, plus document paths, area paths and which module declares each exported symbol | reuse of a document |
+
+A reused entity's relations are replayed against the entity set the scan is producing. An edge
+whose internal target is gone is dropped rather than carried: the file it pointed at was renamed or
+deleted, and a graph that keeps the edge is lying about the repository. An external or unresolved
+endpoint is re-added instead, because such an entity is in the snapshot only because something
+referenced it, and the thing that referenced it is exactly what was reused.
+
+## What is refused outright
+
+A hash says a file has not changed. It says nothing about whether this code would still read it the
+same way — an analyzer that learns to record a document's headings produces different entities from
+identical bytes, and a configuration change moves area boundaries and runtime-wiring detection. So
+the whole snapshot is refused unless it was produced by this `pipelineVersion`, these
+`analyzerVersions` and this `configurationHash`, and a snapshot that does not declare all three is
+refused as well. Trusting an undeclared input with a repository scan is how a cache becomes a
+source of wrong answers.
+
+A cache that is only usually right is worse than no cache. Reuse either produces the snapshot a
+cold scan would produce, or it does not happen.
+
+A reused entity also replays the per-file `coverage` its analyzer produced, because the aggregate
+entries are derived from those rather than stored. An aggregate that cannot be rebuilt from what
+the snapshot carries is an aggregate a fast scan gets wrong: a fact that lives only in a local
+variable during a parse is a fact the next scan cannot replay. `dynamic-imports:<path>` and
+`runtime-wiring:<path>` therefore record every observed load and wiring call — `complete` when the
+target is statically known, `not-analyzed` when it is not.
+
+## The run explains itself
+
+A run that finishes in a tenth of the time has to be able to say why, or nobody can tell a working
+cache from a broken scan. One `coverage` entry reports it:
+
+```json
+{
+  "analyzer": "repository",
+  "scope": "reused-entities",
+  "status": "complete",
+  "reason": "Reused 102 entities and skipped 102 of 102 parse(s). Nothing needed re-parsing."
+}
+```
+
+`status` is `complete` when everything reusable was reused, `partial` when reuse was refused — the
+reason then names what changed — and `not-applicable` when there was no previous snapshot to reuse.
+
+This entry is the one part of a snapshot that describes the *run* rather than the repository. The
+entities, the relations and every other coverage entry are byte-identical to a cold scan's, which
+is what the tests assert; the snapshot's own `contentHash` covers this entry too, so a warm scan
+and a cold scan of the same tree hash differently. That is why the CLI does not yet pass a previous
+snapshot: the artifacts it writes are compared across runs, and the caching layer has to decide
+what a report keys on before a fast scan starts feeding it. `contentHash` and `sourceRevision`
+semantics are otherwise untouched.

package/docs/spec/markdown-analyzer-v1.md

@@ -0,0 +1,73 @@
+---
+title: Markdown analyzer v1
+description: What Doc Bridge reads from a Markdown document, and the relations it observes from prose.
+---
+
+# Markdown analyzer v1
+
+Documentation is parsed with remark (CommonMark plus GFM), not with regular expressions, so a
+document's own prose becomes evidence. Every relation below is `observed` and carries the file and
+line the claim was made on.
+
+| Relation | From → to | Observed from |
+| --- | --- | --- |
+| `links-to` | document → document | a relative link that resolves to a scanned document |
+| `mentions` | document → module or package | inline code or link text equal to a scanned path or a package name |
+| `mentions-symbol` | document → module | inline code equal to an exported name of exactly one module |
+| `covers` | document → anything | a `docbridge` declaration, unchanged |
+
+A symbol resolves to the module that **declares** it, never to a barrel that re-exports it. When
+two modules declare the same name the reference resolves to neither: the tokens and their lines
+are reported as a `markdown` coverage note instead, because sending an agent to one of two
+possible definitions is worse than sending it nowhere. The same rule governs near-misses — an
+unresolved path-shaped reference is matched with Jaro-Winkler and accepted only at 0.92 or above
+*and* with a single candidate, recorded as `metadata.confidence: "fuzzy"`.
+
+Document entities gain what the parser can see: `title`, headings to depth three with their
+lines, a bounded `summary`, `wordCount`, the frontmatter subset (`type`, `audience`, `owner`,
+`lifecycle`, `tier`), any generated regions, and the file's `contentHash` on its evidence. A
+document declaring `audience` overrides the path heuristic that classifies it; `type` overrides it
+only when it names an audience, since in practice `type` names a document kind.
+
+A document referencing more than 64 entities records `evidenceTruncated` and a coverage note. An
+index page's sixty-fifth link is not knowledge, and an unbounded list is not evidence.
+
+## Generated regions
+
+```markdown
+<!-- doc-bridge:generated hash=8f79947 -->
+…generator output…
+<!-- /doc-bridge:generated -->
+```
+
+Mentions inside a generated region are ignored, so Doc Bridge never reads its own output back in
+as evidence about the repository. An unclosed marker owns the rest of the file. The regions are
+recorded on the document entity, which is what lets the audit report a manual edit inside one.
+
+## The `docbridge` block
+
+The block is real YAML validated by a schema, so quoted lists, flow mappings, anchors and
+multi-line strings work as they do in every other tool. Schema violations report the field:
+`docbridge.relations.0: Unrecognized key: note`. Each `DOCBRIDGE_*` code is preserved — a
+repository failing its build on one keeps failing on the same one — and a block YAML cannot read
+at all falls back to the line-oriented scanner, because on a mangled block a diagnostic per line
+helps the author more than a single parser error.
+
+## The cost of a near-miss
+
+Near-miss resolution is the analyzer's only super-linear step: every unresolved path-shaped
+reference is a query against every document, module and area path in the repository. On a monorepo
+of 4 100 documents and 9 240 modules the naive form of that — rebuilding the candidate list per
+document, then computing Jaro-Winkler against each candidate — did not finish.
+
+Two bounds make it cheap, and both are bounds on Jaro's match count `m` rather than heuristics.
+`m` cannot exceed the shorter string, so `jaro ≤ (m/|a| + m/|b| + 1) / 3`; with the prefix bonus
+bounded by `jw ≤ 0.6·jaro + 0.4`, a threshold of 0.92 admits only candidates whose length is
+within 0.6× to 1.67× the query's. And `m` cannot exceed the number of characters the two strings
+share, which one pass over a 128-slot count vector answers, where a similarity computation costs a
+pass over one string per character of the other.
+
+Both only ever over-estimate `m`, so a candidate they skip could not have matched: the index is a
+speed-up with no effect on results, tied scores included. `MarkdownResolution.pathIndex` carries it,
+built once per run; an analyzer called without one builds its own and produces the same output more
+slowly.

package/docs/spec/mcp-knowledge-tools-v1.md

@@ -0,0 +1,147 @@
+---
+title: MCP knowledge tools v1
+description: One search and one lookup that answer inside a declared token budget, findings in the shape the ecosystem consumes, and a doctor that measures what retrieval can see.
+---
+
+# MCP knowledge tools v1
+
+An agent about to edit `src/mcp` used to need four calls — a search, a handoff, the diagnostics,
+the relations — and got back payloads whose size it could only estimate as `contextBytes / 4`.
+Two tools now answer that question in one bounded response, the existing tools stay as they are,
+and the doctor stops reporting a health it did not measure.
+
+## `knowledge.search`
+
+```json
+{ "query": "where do I add a new MCP tool", "kinds": ["document", "area"], "limit": 5, "explain": true, "budgetTokens": 600 }
+```
+
+Ranks the retrieval projection with the same `searchIndex` the CLI uses, so with no `kinds` the
+`results` are what `ak-docs search <query> --json` prints for the same query and index — a test
+compares the two rather than assuming it. Each result adds the entry's `title` and an `excerpt`,
+the opening of the projected body. `kinds` filters after ranking, from a deeper ranking, so the
+order never changes and a filtered call still returns up to `limit`. `explain` attaches the
+matched terms and every score component, as on the CLI.
+
+## `knowledge.lookup`
+
+```json
+{ "id": "area:src/mcp", "depth": 1, "budgetTokens": 900 }
+```
+
+Accepts an entity id, an ownership id, an alias or a `path`, through the same resolution
+`handoff.resolve` uses. One response carries:
+
+| Section | What it is |
+| --- | --- |
+| `entity` | id, kind, path, title, summary, aliases, symbols, tags, provenance, confidence, content hash, ownership, area, package, PageRank |
+| `neighbours` | every entry within `depth` hops, grouped by relation kind (`covers`, `mentions`, `links-to`, `imports`, `contains`, …), each with direction, confidence, distance and the entry it was reached through |
+| `documents` | the documents that `cover` the entity and those that `mention` it, most canonical first |
+| `handoff` | exactly what `handoff.resolve` returns for the entity, `related` included |
+| `diagnostics` | the open diagnostics of the latest reconciliation report that name the entity or point at its file, with the report hash — or `reportHash: null` when no workflow run exists |
+| `evidence` | the entity's path and content hash, then those of the documents about it, each with an `excerpt` |
+
+`contains` is not a projection edge — it is hierarchy — but an agent asking about an area wants its
+modules listed, so the lookup synthesises it from `areaId` and `packageId`. Neighbours are
+bounded per relation kind and visited in sorted order, so two lookups over the same projection
+produce the same response. `depth` is at most 3.
+
+`format: "text"` on either tool renders the same payload as prose through
+`formatRetrievedDocuments`, for clients that prefer it.
+
+## Budgets
+
+When `budgetTokens` is present, both tools and `handoff.resolve` trim through `compileBudget`:
+each droppable section becomes a message, oldest first in the order it may be dropped, the payload
+with every section removed becomes the last message, and `drop-oldest` with `keepRecent: 1` sheds
+sections from the front until the rest fits. The declared order is
+
+```
+evidenceExcerpts → related → neighbours → summaries
+```
+
+and nothing else is ever dropped: the entity, the evidence paths and hashes, the handoff fields an
+agent acts on and the open diagnostics survive every budget. A payload whose undroppable core
+still exceeds the budget reports `fits: false` with every section dropped, rather than truncating
+what it may not drop. A section a payload does not have — search has no `related`, a handoff has
+no `neighbours` — is absent from the report, never reported dropped.
+
+```json
+{
+  "budget": {
+    "budgetTokens": 900,
+    "tokens": { "total": 790, "budget": 900, "core": 684, "sections": { "evidenceExcerpts": 59, "related": 290, "neighbours": 229, "summaries": 106 } },
+    "fits": true,
+    "order": ["evidenceExcerpts", "related", "neighbours", "summaries"],
+    "kept": ["summaries"],
+    "dropped": ["evidenceExcerpts", "related", "neighbours"],
+    "tokenMethod": "approximate"
+  }
+}
+```
+
+Tokens are counted with `approximateCounter` — four characters per token plus two per message,
+over the serialised sections — and reported as `tokenMethod: "approximate"`. `compileBudget` and
+`approximateCounter` are mirrored in `src/budget/compile.ts` because `@agentskit/core` is an
+optional peer and every query surface answers with no peer installed; a test runs the real
+`compileBudget` over the same messages and asserts the two agree on every token count, every
+dropped message and `fits`. On a handoff the droppable sections are `related` and the note that
+repeats the target's summary; `budget` is an optional field of `AgentHandoffV1`, so a budgeted
+handoff is still a valid handoff.
+
+## Every existing tool keeps working
+
+`handoff.resolve`, `doc.search`, `doc.get`, `gate.status`, `retriever.query`, `memory.*`,
+`registry.topology` and `docbridge.*` keep their names, arguments and payloads. `handoff.resolve`
+gains an optional `budgetTokens`; `docbridge.diagnostics` gains an optional `format`. The new tools
+are appended to the advertised list and to the configuration's `surfaces.mcp.tools` default, so a
+configuration that names its tools explicitly is unchanged until it names them.
+
+## Canonical findings
+
+```
+ak-docs check --json --format finding
+docbridge.diagnostics { "format": "finding" }
+```
+
+Both emit every reconciliation diagnostic as a `Finding` from `@agentskit/core/finding`, with
+severities drawn from `SEVERITY_ORDER`, so Code Review, AKOS and dashboards read Doc Bridge with no
+parser of their own. Internal severities map `error → high`, `warn → medium`, `info → low`,
+`off → info`; nothing is `critical`, because a documentation finding never takes a system down.
+`title` is the code as words, `detail` the message, `category` the status, `location` the first
+evidence path and line, `ref` the code, and `metadata` carries the internal code, status,
+severity, evidence and entity ids, so nothing is lost. `confidence` follows the status: an
+observed relation is certain, a stale declaration less so, a coverage gap least of all. Findings
+are ordered most severe first and by id within a severity.
+
+This is a reporter, not a migration: `KnowledgeDiagnostic`, `RuleFinding` and
+`DocumentationAuditFinding` keep their shapes, and the rule verdict still decides the exit code
+of `check`. A test imports the real package and asserts assignability and the severity order.
+
+## The measured doctor
+
+Three dimensions join the score and can lower the grade:
+
+| Dimension | Measures | Points |
+| --- | --- | --- |
+| Reachability | the share of the snapshot's document entities present in the retrieval projection | 15 |
+| Connectivity | the mean of: areas with at least one covering or mentioning document; documents with at least one edge into code | 15 |
+| Benchmark | hit@3 over the golden suite at `retrieval.benchmark.suite` (`docs/bench/retrieval-suite-v1.json` by default) | 10 |
+
+The existing dimensions — index present and fresh, agent docs, human guides, gates — make up the
+other sixty. A repository with no golden suite reports the benchmark as `not-analyzed`, scores
+nothing for it and says so in the issues; it is never silently omitted.
+
+An A requires all three: reachability at 100 percent, connectivity at 80 percent or more, and a
+measured hit@3 of 80 percent or more. A score of 90 that misses one of them is a B, and the text
+report says which. Reachability must be complete because a document retrieval cannot find is a
+document the product does not deliver; the other two have a floor rather than a ceiling.
+
+On this repository every document is in the projection and the benchmark is at 88.3 percent, but
+20 of 39 areas have no document about them and 55 of 100 documents do not point at code —
+connectivity 47 percent, grade B. That is the honest state. A test proves the other direction on
+the same repository: one document out of the projection is enough to lose the A, and an index
+with no projection at all — what the builder produced before the corpus projection — is at zero.
+
+The doctor's `ok` is unchanged: it is still "no error-severity issue and the gates pass", so a
+CI step that runs `ak-docs doctor --text` fails on a stale index, not on a B.