@agentskit/doc-bridge 1.7.45 → 1.10.0

package/docs/chat-and-rag.md

@@ -49,8 +49,9 @@ flowchart LR
 ## Trust model
 
 1. **`handoffFirst`** (default): if the question mentions a known package id, attach deterministic AgentHandoff context before the model answers.
-2. RAG retrieves from the indexed agent corpus (and configured sources).
-3. CI gates still decide merge truth — chat never auto-writes docs.
+2. Deterministic local and federated retrieval use token-boundary matching (with CJK-aware handling), so substring-only decoys do not consume model context.
+3. RAG retrieves from the indexed agent corpus (and configured sources).
+4. CI gates still decide merge truth — chat never auto-writes docs.
 
 ## Commands
 

package/docs/for-agents.md

@@ -13,6 +13,14 @@ ak-docs query ownership <id> --agent
 
 The response supplies four things: `startHere`, `readBeforeEditing`, `editRoots`, and `checks`.
 
+For a documentation change, inspect the deterministic audit before editing:
+
+```bash
+ak-docs audit documentation --json
+```
+
+Treat `blocked` as a stop condition. Treat `not-analyzed` as missing evidence, not as a pass. When a report explicitly documents a limitation, preserve that limitation as `not-analyzed`; do not reinterpret it as a successful check or silently upgrade it to a defect. Agent proposals remain advisory until a human approves them.
+
 ```mermaid
 flowchart LR
   Q["Resolve ownership"] --> R["Read startHere"]
@@ -36,4 +44,4 @@ flowchart LR
 - [AgentHandoff schema](./schemas/agent-handoff-v1.md)
 - [Skill text](./skills/doc-bridge.md)
 
-If the task is conversational UI, continue with [AgentsKit Chat](https://chat.agentskit.io). For verification before merge, use [AgentsKit Code Review](https://github.com/AgentsKit-io/code-review-cli). For enterprise orchestration, governance, and audit, continue with [AKOS](https://akos.agentskit.io).
+If the task is conversational UI, continue with [AgentsKit Chat](https://chat.agentskit.io). For verification before merge, use [AgentsKit Code Review](https://github.com/AgentsKit-io/code-review). For enterprise orchestration, governance, and audit, follow the repository's configured team workflow.

package/docs/getting-started.md

@@ -26,14 +26,7 @@ pnpm add -D @agentskit/doc-bridge
 
 CLI binary: **`ak-docs`**.
 
-## 60-second demo (zero setup)
-
-```bash
-npx ak-docs demo --text
-npx ak-docs demo --fixture monorepo --text   # auth + billing monorepo
-```
-
-Prints before/after, a real handoff, gate red→green, and the MCP snippet.
+For the canonical zero-setup proof, see the [README's 60-second proof](../README.md#60-second-proof).
 
 ## Two-minute path (no API key)
 
@@ -62,7 +55,7 @@ ak-docs mcp
 
 ## Configuration
 
-Default: `doc-bridge.config.json` (also `.ts` / `.js` / `package.json#docBridge`).
+Configuration is discovered in the order defined by the configuration specification; `doc-bridge.config.json` is the simplest supported fallback (along with `.ts`, `.js`, and `package.json#docBridge`).
 
 **Required:** `schemaVersion: 1` + `corpus.agent.root`.
 
@@ -82,7 +75,7 @@ See [config-v1](./spec/config-v1.md) and [examples](./examples.md).
 |---------|-------------|---------|
 | CLI | You want to inspect or debug the bridge yourself | `ak-docs query package <id> --agent` |
 | MCP | You want coding agents to resolve handoffs before editing | `ak-docs mcp install --cursor` |
-| CI | You want stale indexes and broken links to fail PRs | `ak-docs index && ak-docs gate run` |
+| CI | You want stale indexes and explicitly configured documentation gates to fail PRs | `ak-docs gate run` (the PR action checks the committed index) |
 | Adapters | You already have Fumadocs, Docusaurus, or markdown docs | configure `corpus.human` |
 | Memory pipeline | You want agent notes turned into reviewable docs | `ak-docs memory promote --pr --dry-run` |
 | Optional RAG/chat | You want a terminal assistant grounded in the same index | `ak-docs rag ingest && ak-docs chat` |
@@ -118,7 +111,7 @@ ak-docs bootstrap agent-docs         # draft agent docs from human site
 ak-docs memory ingest
 ak-docs memory classify
 ak-docs memory promote              # prints a safe draft body
-ak-docs memory promote --pr --dry-run
+ak-docs memory promote --pr --dry-run  # writes a local draft and prints commands only
 ak-docs memory promote --pr         # opens a GitHub draft PR via gh
 ```
 

package/docs/guides/gate-ci.md

@@ -38,13 +38,23 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: AgentsKit-io/doc-bridge@v1.4.0
+      - uses: AgentsKit-io/doc-bridge@ee756a13c006c597445c31e2643c1e8cece715d7 # v1.7.45
         with:
           config-path: doc-bridge.config.json
+          package-version: 1.7.45
 ```
 
+This example pins both the published stable Action release and its matching
+published package version at `v1.7.45`; the checked-in package version is
+`1.8.0` and is intentionally not used by this published-release example.
+
 The composite Action verifies the **committed** index and configured gates — it does **not** silently rebuild and hide drift.
 
+The Action runs the gates selected by the consumer's configuration. To fail on
+broken human-document links, include the `human-guide-links` gate explicitly;
+the minimal preset enables `index-freshness` by default, and this repository
+adds `documentation-standard-v1` through `gates.include`.
+
 If the Action fails:
 
 1. Run `ak-docs index` locally  

package/docs/guides/install-and-run.md

@@ -1,78 +1,22 @@
 ---
-title: Install and run
-description: Install Doc Bridge, run the demo, and index your repository in minutes.
+title: Continue the development loop
+description: Continue indexing and querying after the first Doc Bridge setup.
 ---
 
 # Install and run
 
-Get a deterministic AgentHandoff from your own docs — no API key required for Layer 0.
+The [Getting started guide](../getting-started.md) is the canonical install,
+demo, and first-index path. This page keeps the configuration and development
+loop details that follow that first run.
 
-## Install
+## Development loop
 
-```bash
-pnpm add -D @agentskit/doc-bridge
-# or
-npm i -D @agentskit/doc-bridge
-```
-
-CLI binary: **`ak-docs`**.
-
-## Prove it in 60 seconds (no project setup)
-
-```bash
-npx ak-docs demo --text
-npx ak-docs demo --fixture monorepo --text
-```
-
-You should see handoffs, a gate red→green path, and an MCP install snippet.
-
-## Two-minute path on your repo
-
-```bash
-cd your-repo
-ak-docs init                 # config + optional demo ownership + AGENTS.md tip
-ak-docs index                # build .doc-bridge/index.json
-ak-docs query package example --agent
-ak-docs doctor --text
-ak-docs gate run
-```
-
-Expected handoff fields:
-
-| Field | Meaning |
-| --- | --- |
-| `startHere` | What the agent reads first |
-| `editRoots` | Where edits are allowed |
-| `checks` | Commands that prove the change |
-| `humanDoc` | Human guide for the same ownership |
-
-## Minimal config
-
-`doc-bridge.config.json`:
-
-```json
-{
-  "schemaVersion": 1,
-  "corpus": {
-    "agent": { "root": "docs/for-agents" }
-  }
-}
-```
-
-**Required:** `schemaVersion: 1` and `corpus.agent.root`.
-
-Ownership comes from (first match wins):
-
-1. `routing.options.ownership` in config  
-2. Frontmatter on agent docs (`package`, `editRoot`, `checks`)  
-3. Monorepo plugin discovery (`pnpm-monorepo`)
-
-## Dev loop
+After the canonical setup, use the watch command while editing. The complete
+install, index, query, and gate sequence remains in the [Getting started
+guide](../getting-started.md#two-minute-path-no-api-key).
 
 ```bash
 ak-docs index --watch
-ak-docs list packages --text
-ak-docs ask "where do I change auth?"
 ```
 
 ## Related

package/docs/index.md

@@ -26,6 +26,27 @@ Doc Bridge keeps **one repository** useful to people and coding agents. Pick the
 | Every CLI command | [CLI map](./guides/cli-map.md) · [CLI reference](./spec/cli.md) |
 | Config sketches | [Examples](./examples.md) |
 | Optional chat / RAG | [Chat and RAG](./chat-and-rag.md) · [Ollama demo](./ollama-demo.md) |
+| Study and measurement | [Study overview and anonymized data](./study/README.md) · [Study protocol v1](./spec/study-protocol-v1.md) |
+| Controlled task suite | [Study task suite v1](./spec/study-task-suite-v1.md) |
+| Phase 3 task coverage | [Task coverage contract v1](./study/phase3-task-coverage-v1.json) |
+| Controlled study runner | [Study runner v1](./spec/study-runner-v1.md) |
+| Provider CLI adapter | [Study provider CLI v1](./spec/study-provider-cli-v1.md) |
+| Round 1 instrumentation | [Instrumentation plan v1](./study/round-1-instrumentation-plan-v1.md) · [adjudicated smoke ledger](./study/round-1-adjudicated-smoke-v1.json) |
+| Longitudinal measurements | [Study metrics v1](./spec/study-metrics-v1.md) |
+| Study verification | [Study verification v1](./spec/study-verification-v1.md) |
+| A/B baseline result | [A/B baseline result 2026-08-31](./study/ab-baseline-result-v1.json) · [analysis](./study/ab-baseline-analysis-v1.md) |
+| Documentation quality audit | [Documentation audit v1](./spec/documentation-audit-v1.md) |
+| What is read from a Markdown document | [Markdown analyzer v1](./spec/markdown-analyzer-v1.md) |
+| Canonicality, centrality, cycles and the graph as memory | [Graph signals v1](./spec/graph-signals-v1.md) |
+| Per-file hashes and reuse between scans | [Incremental scan v1](./spec/incremental-scan-v1.md) |
+| The index as a projection, explainable ranking, handoffs for any entity | [Retrieval index v1](./spec/retrieval-index-v1.md) |
+| Budgeted `knowledge.search` / `knowledge.lookup`, canonical findings, the measured doctor | [MCP knowledge tools v1](./spec/mcp-knowledge-tools-v1.md) |
+| Markdown renderings from templates: area pages, sidecars, change digest, overlay review | [Render v1](./spec/render-v1.md) |
+| Typed agent proposals, validators, the overlay and bounded influence | [Enrichment overlay v1](./spec/enrichment-overlay-v1.md) |
+| What the overlay cost, whether it helped, and the study measurements | [Measured enrichment v1](./spec/measured-enrichment-v1.md) |
+| The claims this repository makes in public, and the gate that keeps them true | [Public parity v1](./spec/public-parity-v1.md) |
+| Current documentation audit snapshot | [Audit round 2026-08-31](./study/documentation-audit-round-2026-08-31.json) |
+| Controlled pilot evidence | [Pilot round 2026-08-31](./study/pilot-round-2026-08-31.json) |
 
 ## How it works
 
@@ -55,4 +76,4 @@ Machine surfaces: [llms.txt](/llms.txt) · [llms-full.txt](/llms-full.txt) · [r
 
 ## Ecosystem
 
-Part of AgentsKit — next to [AgentsKit](https://www.agentskit.io), [Registry](https://registry.agentskit.io), [Chat](https://chat.agentskit.io), [Playbook](https://playbook.agentskit.io), and [AKOS](https://akos.agentskit.io).
+Part of AgentsKit — next to [AgentsKit](https://www.agentskit.io), [Registry](https://registry.agentskit.io), [Chat](https://chat.agentskit.io), and [Playbook](https://playbook.agentskit.io).

package/docs/knowledge-engine-runbook.md

@@ -1,3 +1,10 @@
+---
+owner: doc-bridge-maintainers
+lifecycle: active
+sourceOfTruth: src
+validationPath: pnpm test && pnpm typecheck
+---
+
 # Knowledge Engine Runbook
 
 Doc Bridge is deterministic by default. It turns repository structure and Markdown declarations into versioned snapshot, reconciliation, rule, report, and workflow artifacts. Optional Registry assistance is explicit and never changes deterministic results.
@@ -34,10 +41,30 @@ Install the configured local Registry agent, then configure a local runner modul
 
 ```bash
 npx agentskit add ecosystem-doc-bridge-corpus-scanner
-ak-docs suggest --json
+ak-docs suggest --documentation --json
+```
+
+Set `intelligence.registry.enabled: true` and either `runnerModule` or the generic `cli` adapter in `doc-bridge.config.json`. The runner receives redacted immutable snapshot/report/evidence context and must return `AgentProposalV1`. Network, shell, direct file mutation, and automatic approval are not available to a module runner. A CLI receives the same context as a JSON envelope on stdin and must write exactly one `AgentProposalV1` JSON object to stdout; configure the executable and argument array without shell syntax:
+
+```json
+{
+  "intelligence": {
+    "registry": {
+      "enabled": true,
+      "agentId": "ecosystem-doc-bridge-corpus-scanner",
+      "cli": {
+        "command": "codex",
+        "args": ["exec", "--json"]
+      },
+      "timeoutMs": 120000,
+      "maxInputBytes": 8000000,
+      "maxResponseBytes": 262144
+    }
+  }
+}
 ```
 
-Set `intelligence.registry.enabled: true` and `runnerModule` in `doc-bridge.config.json`. The runner receives redacted immutable snapshot/report/evidence context and must return `AgentProposalV1`. Network, shell, direct file mutation, and automatic approval are not available.
+The child runs with the project root as its working directory, never through a shell, and inherits the parent environment so the CLI can use its own login. Doc Bridge enforces timeout, output and proposal-schema limits, rejects non-zero exits, non-JSON output, mismatched hashes, and invalid origins. The CLI is an explicit trust boundary: its own network and filesystem permissions are controlled by the operator, not by Doc Bridge.
 
 ## Recovery and CI
 
@@ -45,6 +72,14 @@ Rerunning an unchanged command reuses valid stage artifacts. A changed source re
 
 The first implementation analyzes JavaScript/TypeScript and Markdown. Other languages should add analyzers that emit the same canonical entity, relation, evidence, coverage, and hash contracts.
 
+## What the Markdown analyzer reads
+
+Documentation is parsed with remark (CommonMark plus GFM), so a document's own prose becomes
+evidence: links between documents, paths and package names in inline code, and exported names all
+become `observed` relations carrying the line they were claimed on. The contract — relation kinds,
+the ambiguity and near-miss rules, generated regions, the document fields and the `docbridge`
+schema — is [Markdown analyzer v1](./spec/markdown-analyzer-v1.md).
+
 ## Relation coverage policy
 
 Agent documents under the configured `corpus.agent.root` may use the conventional
@@ -52,7 +87,7 @@ Agent documents under the configured `corpus.agent.root` may use the conventiona
 `humanDoc` field. This is intentionally separate from the human bridge: `humanDoc`
 still reports whether an agent has a resolvable human-facing guide.
 
-Missing declarations are configurable because not every implementation import is useful documentation. In the root configuration, `reconciliation.scope` selects the semantic comparison level while `reconciliation.requiredRelationKinds` selects the observed relation kinds that must be declared in Markdown. Raw file relations remain available in the snapshot and report for evidence and exploration:
+Missing declarations are configurable because not every implementation import is useful documentation. In the root configuration, `reconciliation.scope` selects the semantic comparison level while `reconciliation.requiredRelationKinds` selects the observed relation kinds that must be declared in Markdown. A single-package repository wants `scope: "area"`: at package scope its internal relations aggregate into one self-loop the comparison skips, so nothing is reported. See [areas](./spec/config-v1.md#analysisareas-optional). Raw file relations remain available in the snapshot and report for evidence and exploration:
 
 ```json
 {

package/docs/landing/assets/context-payload-reduction.svg

@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 520" role="img" aria-labelledby="title desc">
+  <title id="title">Estimated context payload (not tokens)</title>
+  <desc id="desc">Historical anonymized dogfooding · validation-cycle-02 · Doc Bridge 1.7.20</desc>
+  <rect width="1200" height="520" rx="24" fill="#0b0f14"/>
+  <g font-family="Inter, ui-sans-serif, system-ui, sans-serif" fill="#e8eef6">
+    <text x="64" y="76" font-size="32" font-weight="700">Estimated context payload (not tokens)</text>
+    <text x="64" y="112" font-size="18" fill="#8fa3b8">Historical anonymized dogfooding · validation-cycle-02 · Doc Bridge 1.7.20</text>
+    
+    <text x="64" y="192" font-size="20" font-weight="600">Repository corpus</text>
+    <text x="1136" y="192" text-anchor="end" font-size="24" font-weight="700">100%</text>
+    <rect x="64" y="216" width="1072" height="38" rx="19" fill="#1e2a38"/>
+    <rect x="64" y="216" width="1072" height="38" rx="19" fill="#3d9cf5"/>
+    <text x="64" y="326" font-size="20" font-weight="600">Estimated P95 agent context payload</text>
+    <text x="1136" y="326" text-anchor="end" font-size="24" font-weight="700">1%</text>
+    <rect x="64" y="350" width="1072" height="38" rx="19" fill="#1e2a38"/>
+    <rect x="64" y="350" width="11" height="38" rx="19" fill="#3ecf8e"/>
+    <text x="64" y="454" font-size="34" font-weight="700" fill="#3ecf8e">Up to 99% less context payload</text>
+    <text x="64" y="486" font-size="16" fill="#8fa3b8">Estimated payload reduction; provider tokens and correctness are separate measures.</text>
+  
+  </g>
+</svg>

package/docs/landing/assets/controlled-ab-comparison.svg

@@ -0,0 +1,30 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 620" role="img" aria-labelledby="title desc">
+  <title id="title">Controlled A/B signal (operational)</title>
+  <desc id="desc">96 anonymized executions · 24 tasks · 2 pinned models · one replicate · bounded adjudication</desc>
+  <rect width="1200" height="620" rx="24" fill="#0b0f14"/>
+  <g font-family="Inter, ui-sans-serif, system-ui, sans-serif" fill="#e8eef6">
+    <text x="64" y="76" font-size="32" font-weight="700">Controlled A/B signal (operational)</text>
+    <text x="64" y="112" font-size="18" fill="#8fa3b8">96 anonymized executions · 24 tasks · 2 pinned models · one replicate · bounded adjudication</text>
+    
+    <line x1="600" y1="158" x2="600" y2="548" stroke="#526579" stroke-width="2"/>
+    <text x="600" y="142" text-anchor="middle" font-size="16" fill="#8fa3b8">repository-only baseline</text>
+    <text x="64" y="214" font-size="20" font-weight="600">Paired provider tokens</text>
+    <text x="1136" y="214" text-anchor="end" font-size="24" font-weight="700" fill="#3ecf8e">−18.46%</text>
+    <rect x="64" y="234" width="1072" height="14" rx="7" fill="#1e2a38"/>
+    <rect x="470" y="234" width="130" height="14" rx="7" fill="#3ecf8e"/>
+<text x="64" y="298" font-size="20" font-weight="600">P95 latency</text>
+    <text x="1136" y="298" text-anchor="end" font-size="24" font-weight="700" fill="#3ecf8e">−39.75 s</text>
+    <rect x="64" y="318" width="1072" height="14" rx="7" fill="#1e2a38"/>
+    <rect x="320" y="318" width="280" height="14" rx="7" fill="#3ecf8e"/>
+<text x="64" y="382" font-size="20" font-weight="600">Operational completion</text>
+    <text x="1136" y="382" text-anchor="end" font-size="24" font-weight="700" fill="#3ecf8e">+12.50 pp</text>
+    <rect x="64" y="402" width="1072" height="14" rx="7" fill="#1e2a38"/>
+    <rect x="600" y="402" width="88" height="14" rx="7" fill="#3ecf8e"/>
+<text x="64" y="466" font-size="20" font-weight="600">Evidence quality</text>
+    <text x="1136" y="466" text-anchor="end" font-size="24" font-weight="700" fill="#3ecf8e">−2.08 pp</text>
+    <rect x="64" y="486" width="1072" height="14" rx="7" fill="#1e2a38"/>
+    <rect x="580" y="486" width="20" height="14" rx="7" fill="#3ecf8e"/>
+    <text x="64" y="584" font-size="16" fill="#8fa3b8">Directional signal; see the full study for denominators and limitations.</text>
+  
+  </g>
+</svg>

package/docs/landing/index.html

@@ -5,6 +5,7 @@
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <title>doc-bridge — docs your agents can act on</title>
   <meta name="description" content="Turn human docs into executable handoffs for agents, and turn agent memory into reviewable documentation drafts. MCP, CLI, CI. No API key required." />
+  <link rel="icon" href="data:," />
   <link rel="preconnect" href="https://fonts.googleapis.com" />
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
   <link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600;700&display=swap" rel="stylesheet" />
@@ -121,6 +122,61 @@
       border-radius: var(--radius);
       box-shadow: 0 18px 50px rgba(0, 0, 0, 0.28);
     }
+    .metrics {
+      display: grid;
+      gap: 1rem;
+      margin: 2rem 0 0;
+    }
+    .metrics-card {
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: var(--radius);
+      padding: 1rem;
+    }
+    .metrics-card img { display: block; width: 100%; height: auto; border-radius: 8px; }
+    .metrics-note { color: var(--muted); font-size: 0.85rem; margin-top: 0.75rem; }
+    .metric-kicker,
+    .finding-kicker {
+      color: var(--green);
+      font-family: var(--mono);
+      font-size: 0.72rem;
+      font-weight: 600;
+      letter-spacing: 0.08em;
+      text-transform: uppercase;
+    }
+    .quality-grid { display: grid; grid-template-columns: 1.15fr 0.85fr; gap: 1.25rem; align-items: start; }
+    .finding {
+      background: #0d1219;
+      border: 1px solid var(--border);
+      border-radius: var(--radius);
+      padding: 1.25rem;
+      font-family: var(--mono);
+      font-size: 0.86rem;
+      line-height: 1.7;
+      overflow-x: auto;
+    }
+    .finding strong { color: var(--red); font-weight: 600; }
+    .finding span { color: var(--muted); }
+    .contributor-cta { margin-top: 2rem; padding-top: 2rem; border-top: 1px solid var(--border); }
+    .contributor-cta p { color: var(--muted); max-width: 62ch; margin: 0.5rem 0 1rem; }
+    .metric-mobile-summary { display: none; }
+    @media (max-width: 480px) {
+      .metrics-card img { display: none; }
+      .metric-mobile-summary {
+        display: grid;
+        grid-template-columns: repeat(2, minmax(0, 1fr));
+        gap: 0.75rem;
+        margin-top: 1rem;
+      }
+      .metric-mobile-summary div {
+        padding: 0.9rem;
+        border: 1px solid var(--border);
+        border-radius: 8px;
+        background: #0d1219;
+      }
+      .metric-mobile-summary strong { display: block; color: var(--green); font-size: 1.35rem; line-height: 1.1; }
+      .metric-mobile-summary span { display: block; color: var(--muted); font-size: 0.78rem; margin-top: 0.35rem; }
+    }
     .t-dim { color: var(--muted); }
     .t-ok { color: var(--green); }
     .t-bad { color: var(--red); }
@@ -129,7 +185,7 @@
     h2 { font-size: 1.5rem; letter-spacing: -0.02em; margin-bottom: 0.5rem; }
     .section-lead { color: var(--muted); margin-bottom: 2rem; max-width: 60ch; }
     .grid-2 { display: grid; grid-template-columns: 1fr 1fr; gap: 1.25rem; }
-    @media (max-width: 720px) { .grid-2 { grid-template-columns: 1fr; } .nav-links { display: none; } }
+    @media (max-width: 720px) { .grid-2, .quality-grid { grid-template-columns: 1fr; } .nav-links { display: none; } }
     .card {
       background: var(--surface);
       border: 1px solid var(--border);
@@ -197,6 +253,7 @@
       <div class="logo">doc-bridge <span>/ ak-docs</span></div>
       <nav class="nav-links">
         <a href="#demo">Demo</a>
+        <a href="#quality">Quality</a>
         <a href="#loops">Loops</a>
         <a href="#used-by">Used by</a>
         <a href="https://github.com/AgentsKit-io/doc-bridge">GitHub</a>
@@ -256,6 +313,57 @@
             </div>
           </div>
         </div>
+        <div class="metrics" aria-labelledby="measured-impact-title">
+          <div class="metrics-card">
+            <h2 id="measured-impact-title">Measured context efficiency</h2>
+            <div class="metric-kicker">Estimated · historical benchmark</div>
+            <p class="section-lead">Anonymized dogfooding estimated up to 99% less context payload between the scanned repository corpus and the P95 agent payload. This is not a provider-token measurement.</p>
+            <img src="assets/context-payload-reduction.svg" alt="Estimated context payload reduction from 100 percent of the repository corpus to 1 percent of the agent context payload" />
+            <div class="metric-mobile-summary" aria-label="Estimated context efficiency summary">
+              <div><strong>99%</strong><span>less context payload</span></div>
+              <div><strong>1%</strong><span>estimated P95 payload</span></div>
+            </div>
+            <p class="metrics-note">Doc Bridge 1.7.20 · estimated payload reduction, not a guaranteed token reduction or correctness result.</p>
+          </div>
+          <div class="metrics-card">
+            <h2>Controlled A/B signal</h2>
+            <div class="metric-kicker">Operational · 46 token-complete pairs</div>
+            <p class="section-lead">Across 96 anonymized executions, the deterministic workflow showed fewer paired provider token-equivalent units, lower P95 latency, and higher operational completion. A bounded adjudicator found no semantic successes in either arm, so this remains an inconclusive directional signal.</p>
+            <img src="assets/controlled-ab-comparison.svg" alt="Controlled A/B comparison showing 18.46 percent fewer paired provider token-equivalent units, 39.75 seconds lower P95 latency, and 12.5 percentage points more operationally completed executions" />
+            <div class="metric-mobile-summary" aria-label="Controlled A/B signal summary">
+              <div><strong>−18.46%</strong><span>token-equivalent units</span></div>
+              <div><strong>−39.75 s</strong><span>P95 latency</span></div>
+            </div>
+            <p class="metrics-note"><a href="https://github.com/AgentsKit-io/doc-bridge/blob/master/docs/study/README.md">Read the methodology and anonymized data.</a></p>
+          </div>
+        </div>
+      </div>
+    </section>
+
+    <section id="quality">
+      <div class="wrap">
+        <h2>Find the gap between docs and reality.</h2>
+        <p class="section-lead">Doc Bridge compares declared documentation and ownership with the observed project graph, then keeps every finding tied to evidence and a reviewable action.</p>
+        <div class="quality-grid">
+          <div class="finding" aria-label="Anonymized documentation contradiction finding">
+            <div class="finding-kicker">Anonymized finding</div>
+            <div><strong>CONTRADICTION · high confidence</strong></div>
+            <div>Documentation declaration differs from the observed project relation</div>
+            <div><span>Evidence: 4 source files + 1 documentation declaration</span></div>
+            <div><span>Action: review ownership and update the canonical document</span></div>
+          </div>
+          <div>
+            <h3>What the deterministic audit can show</h3>
+            <table class="surface-table">
+              <tbody>
+                <tr><td>Coverage</td><td>Missing package or ownership documentation</td></tr>
+                <tr><td>Freshness</td><td>Stale declared relations and generated-document boundaries</td></tr>
+                <tr><td>Quality</td><td>Titles, examples, required sections, metadata, and exact duplicates</td></tr>
+                <tr><td>Limits</td><td>Natural-language correctness and semantic redundancy remain review work</td></tr>
+              </tbody>
+            </table>
+          </div>
+        </div>
       </div>
     </section>
 
@@ -304,7 +412,7 @@
           <div class="card">
             <div class="loop-tag">Explain</div>
             <h3>Local consult</h3>
-            <p><code>ask</code> · optional Ollama chat</p>
+            <p><code>ask</code> · optional provider-backed review</p>
           </div>
         </div>
       </div>
@@ -312,8 +420,8 @@
 
     <section id="used-by">
       <div class="wrap">
-        <h2>Used by AgentsKit (public)</h2>
-        <p class="section-lead">Dogfooded on open surfaces — not private monorepo claims.</p>
+        <h2>Public dogfood surfaces</h2>
+        <p class="section-lead">Open AgentsKit surfaces used for validation — not independent customer or private-monorepo claims.</p>
         <div class="used-by">
           <a href="https://www.agentskit.io/docs/for-agents">AgentsKit for-agents</a>
           <a href="https://registry.agentskit.io/">AgentsKit Registry</a>
@@ -326,6 +434,12 @@
           <img src="https://img.shields.io/badge/handoff_coverage-ready-2ea44f?style=flat-square" alt="handoff coverage" />
           <img src="https://img.shields.io/github/actions/workflow/status/AgentsKit-io/doc-bridge/ci.yml?branch=master&style=flat-square&label=CI" alt="CI" />
         </div>
+        <div class="contributor-cta">
+          <h3>Help make repository knowledge verifiable.</h3>
+          <p>Reproduce the anonymized study, add an analyzer, contribute a documentation rule, or create a fixture for a stale relation or structured contradiction.</p>
+          <a class="btn btn-primary" href="https://github.com/AgentsKit-io/doc-bridge/blob/master/docs/study/README.md">Reproduce the study</a>
+          <a class="btn btn-ghost" href="https://github.com/AgentsKit-io/doc-bridge/blob/master/CONTRIBUTING.md">Contribute</a>
+        </div>
       </div>
     </section>
 
@@ -337,7 +451,7 @@
           <div class="terminal-bar"><span class="dot dot-r"></span><span class="dot dot-y"></span><span class="dot dot-g"></span></div>
           <div class="terminal-body">
             <div class="t-dim"># .github/workflows/pr.yml</div>
-            <div>- uses: <span class="t-hi">AgentsKit-io/doc-bridge@v1.4.0</span></div>
+            <div>- uses: <span class="t-hi">AgentsKit-io/doc-bridge@ee756a13c006c597445c31e2643c1e8cece715d7</span> <span class="t-dim"># v1.7.45</span></div>
             <div>&nbsp;&nbsp;with:</div>
             <div>&nbsp;&nbsp;&nbsp;&nbsp;config-path: doc-bridge.config.json</div>
           </div>