@agentskit/doc-bridge 0.1.0-alpha.3 → 1.0.0

package/docs/DOGFOOD-ROUND3.md

@@ -0,0 +1,74 @@
+# Dogfood round 3 — `@agentskit/doc-bridge@0.1.0-alpha.3`
+
+**Date:** 2026-07-09  
+**npm:** `alpha` → `0.1.0-alpha.3` · `latest` still `0.1.0-alpha.1`
+
+## Scoreboard
+
+| Repo | Install | Ver | K | Handoffs | Gate | Ranking | Ask | Retrieve |
+|------|---------|-----|---|----------|------|---------|-----|----------|
+| **agentskit** | `pnpm add -Dw` ✅ | 0.1.0-alpha.3 | 25 | 24 | ✅ 24 humanDoc | `core` #1 (683) ✅ | ownership core ✅ | ✅ soft, 8 chunks |
+| **agentskit-os** | `npx` (store issue) ✅ | 0.1.0-alpha.3 | 170 | 92 | ✅ | `os-core` #1 (689) ✅ | ownership os-core ✅ | ✅ 8 chunks |
+| **playbook** | `pnpm add -D` ✅ | 0.1.0-alpha.3 | 127 | 81 | ✅ okf | OKF pattern #1 ✅ | pattern ownership ✅ | ✅ |
+| **registry** | `--legacy-peer-deps` ⚠️ | 0.1.0-alpha.3 | 36 | 36 | ✅ | `docs-chat` #1 (593) ✅ | docs-chat ✅ | ✅ |
+
+## Round-2 issues — validation
+
+| Item (R2) | Status | Evidence |
+|-----------|--------|----------|
+| Exact id ranking | **Fixed** | agentskit `search core` → best=`core` not angular |
+| ask wrong package | **Fixed** | “change the core package?” → ownership core |
+| Notes truncated | **Fixed** | full purpose sentences on core / os-core |
+| Full-text search | **Improved** | `search documentation` → 20 matches (was 0) |
+| Federation 404 hard-fail | **Fixed** | retrieve exit 0, no error, local chunks only |
+| Peer install friction | **Improved** | no peer warning on agentskit; registry still needs legacy-peer-deps |
+| Text UX | **Fixed** | multi-line `[ownership] id score=` format |
+| Path dedupe | **OK** | top lists are unique ownership rows |
+| AKOS humanDoc sparse | **Still open** | os-core handoff has no `humanDoc` (product docs thin) |
+| pnpm store AKOS | **Still open** | environment; npx works |
+| `latest` on old alpha | **Still open** | publish hygiene |
+
+## Sample outputs (alpha.3)
+
+### agentskit — ranking
+
+```json
+{ "term": "core", "best": "core", "top": ["core:683", "angular:27", "ink:27"] }
+```
+
+### agentskit — handoff
+
+```json
+{
+  "startHere": "apps/docs-next/content/docs/for-agents/core.mdx",
+  "editRoots": ["packages/core"],
+  "checks": ["pnpm --filter @agentskit/core test", "pnpm --filter @agentskit/core lint"],
+  "humanDoc": "/docs/reference/packages/core",
+  "notes": ["Stable TypeScript contracts (Adapter, Tool, Memory, Retriever, Skill, Runtime) + `createChatController` + primitives. Target: <10 KB gzipped, zero runtime deps."]
+}
+```
+
+### agentskit-os — ranking
+
+```json
+{ "best": "os-core", "top": ["os-core:689", "command-palette:36", "os-blob:36"] }
+```
+
+### registry — ranking
+
+```json
+{ "best": "docs-chat", "top": ["docs-chat:593", "agency-brief-generator:15"] }
+```
+
+## Remaining improvements (lower urgency)
+
+1. **AKOS humanDoc coverage** — enrich for-agents frontmatter `humanDoc` or map product Fumadocs more densely (content work more than code).
+2. **npm install without legacy-peer-deps** on registry — may still need peerOptional tuning vs npm ERESOLVE; document install flags.
+3. **HTML entities in notes** — `&lt;10 KB` from source MD; optional decode on index.
+4. **AKOS lockfile install path** — fix local pnpm store / commit published dep version.
+5. **CI wire-up** — `docs:bridge:gate` on each consumer after merge of dogfood branches.
+6. **Publish tags** — keep `latest` free of prereleases or retag intentionally.
+
+## Verdict
+
+**alpha.3 is a successful dogfood pass.** P0/P1 product issues from round 2 are validated fixed on published package across monorepo + playbook + registry. Remaining items are polish, content, or consumer-side install/CI.

package/docs/POSITIONING.md

@@ -49,6 +49,8 @@ Engineering teams with real ownership (monorepos first). Secondary: solo libs, i
 - [AgentsKit for-agents](https://www.agentskit.io/docs/for-agents) — agent-first package corpus
 - [Registry](https://registry.agentskit.io/) — agent discovery / onboarding companion
 - [Playbook llms.txt](https://playbook.agentskit.io/llms.txt) — patterns + federation source
+- [doc-bridge landing](https://agentskit-io.github.io/doc-bridge/) — conversion page + used-by
+- [Doc Bridge Playbook pattern](../playbook/doc-bridge-pattern.md) — `ak-docs playbook pattern`
 
 ## Comparison
 

package/docs/RELEASE.md

@@ -21,7 +21,7 @@ pnpm changeset          # if new entry needed
 pnpm version-packages   # bumps package.json + CHANGELOG from .changeset/*
 ```
 
-Current track: `0.1.0-alpha.x`.
+Current track: **`1.0.0` stable** (alpha series ended at `0.1.0-alpha.5`).
 
 ## Publish (npm)
 
@@ -49,11 +49,13 @@ npx ak-docs@0.1.0-alpha.x --version
 ## GitHub
 
 ```bash
-git tag v0.1.0-alpha.x
+git tag v1.0.0
 git push origin master --tags
-gh release create v0.1.0-alpha.x --title "v0.1.0-alpha.x" --notes-file CHANGELOG.md
+gh release create v1.0.0 --title "v1.0.0 — AgentHandoff stable" --notes-file CHANGELOG.md
 ```
 
+Enable GitHub Pages (Settings → Pages → GitHub Actions) for landing deploy from `.github/workflows/pages.yml`.
+
 ## Post-publish smoke (fresh machine)
 
 ```bash

package/docs/chat-and-rag.md

@@ -29,6 +29,8 @@ ak-docs ask "<question>" --chat
 
 Missing peers produce an install hint instead of a silent no-op.
 
+**Ollama walkthrough:** [ollama-demo.md](./ollama-demo.md) · `pnpm smoke:ollama`
+
 ## Providers
 
 | provider | Notes |

package/docs/getting-started.md

@@ -10,15 +10,28 @@ 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.
+
 ## Two-minute path (no API key)
 
 ```bash
 ak-docs init          # config + demo ownership + AGENTS.md snippet
 ak-docs index
 ak-docs query package example --agent
+ak-docs doctor --text
+ak-docs doctor --badge
+ak-docs mcp install --cursor
+ak-docs index --watch          # optional — dev loop
 ```
 
-You should see an **AgentHandoff** with `startHere`, `editRoots`, and `checks`.
+You should see an **AgentHandoff** with `startHere`, `editRoots`, `checks`, and optional `bridge`.
 
 Useful follow-ups:
 

package/docs/landing/index.html

@@ -0,0 +1,299 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>doc-bridge — AgentHandoff for your monorepo</title>
+  <meta name="description" content="Deterministic routing for coding agents: edit the right package, run the right checks, bridge to human docs. No API key required." />
+  <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" />
+  <style>
+    :root {
+      --bg: #0b0f14;
+      --surface: #121820;
+      --border: #1e2a38;
+      --text: #e8eef6;
+      --muted: #8fa3b8;
+      --accent: #3d9cf5;
+      --accent-dim: #2563a8;
+      --green: #3ecf8e;
+      --red: #f07178;
+      --amber: #e6c07b;
+      --mono: "IBM Plex Mono", ui-monospace, monospace;
+      --sans: "IBM Plex Sans", system-ui, sans-serif;
+      --radius: 12px;
+      --max: 1080px;
+    }
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body {
+      font-family: var(--sans);
+      background: var(--bg);
+      color: var(--text);
+      line-height: 1.55;
+      -webkit-font-smoothing: antialiased;
+    }
+    a { color: var(--accent); text-decoration: none; }
+    a:hover { text-decoration: underline; }
+    .wrap { max-width: var(--max); margin: 0 auto; padding: 0 1.25rem; }
+    header {
+      padding: 1.25rem 0;
+      border-bottom: 1px solid var(--border);
+      position: sticky; top: 0; z-index: 10;
+      background: rgba(11, 15, 20, 0.92);
+      backdrop-filter: blur(8px);
+    }
+    .nav { display: flex; align-items: center; justify-content: space-between; gap: 1rem; }
+    .logo { font-weight: 700; font-size: 1.05rem; letter-spacing: -0.02em; }
+    .logo span { color: var(--muted); font-weight: 500; }
+    .nav-links { display: flex; gap: 1.25rem; font-size: 0.9rem; }
+    .nav-links a { color: var(--muted); }
+    .nav-links a:hover { color: var(--text); text-decoration: none; }
+    .hero { padding: 4.5rem 0 3rem; }
+    .eyebrow {
+      display: inline-block;
+      font-size: 0.75rem;
+      font-weight: 600;
+      letter-spacing: 0.08em;
+      text-transform: uppercase;
+      color: var(--accent);
+      margin-bottom: 1rem;
+    }
+    h1 {
+      font-size: clamp(2rem, 5vw, 3.25rem);
+      line-height: 1.1;
+      letter-spacing: -0.03em;
+      max-width: 16ch;
+      margin-bottom: 1.25rem;
+    }
+    .lead {
+      font-size: 1.15rem;
+      color: var(--muted);
+      max-width: 52ch;
+      margin-bottom: 2rem;
+    }
+    .cta-row { display: flex; flex-wrap: wrap; gap: 0.75rem; margin-bottom: 3rem; }
+    .btn {
+      display: inline-flex; align-items: center; gap: 0.4rem;
+      padding: 0.7rem 1.15rem;
+      border-radius: 8px;
+      font-weight: 600; font-size: 0.95rem;
+      border: 1px solid transparent;
+      cursor: pointer;
+      text-decoration: none !important;
+    }
+    .btn-primary { background: var(--accent); color: #041018; }
+    .btn-primary:hover { background: #5aadf7; }
+    .btn-ghost { border-color: var(--border); color: var(--text); background: var(--surface); }
+    .btn-ghost:hover { border-color: var(--muted); }
+    .terminal {
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: var(--radius);
+      overflow: hidden;
+      font-family: var(--mono);
+      font-size: 0.82rem;
+      line-height: 1.65;
+    }
+    .terminal-bar {
+      display: flex; gap: 6px; padding: 0.65rem 1rem;
+      border-bottom: 1px solid var(--border);
+      background: #0d1219;
+    }
+    .dot { width: 10px; height: 10px; border-radius: 50%; }
+    .dot-r { background: var(--red); }
+    .dot-y { background: var(--amber); }
+    .dot-g { background: var(--green); }
+    .terminal-body { padding: 1.25rem 1.5rem; overflow-x: auto; }
+    .t-dim { color: var(--muted); }
+    .t-ok { color: var(--green); }
+    .t-bad { color: var(--red); }
+    .t-hi { color: var(--accent); }
+    section { padding: 3.5rem 0; border-top: 1px solid var(--border); }
+    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; } }
+    .card {
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: var(--radius);
+      padding: 1.25rem 1.35rem;
+    }
+    .card h3 { font-size: 1rem; margin-bottom: 0.35rem; }
+    .card p { color: var(--muted); font-size: 0.92rem; }
+    .card code { font-family: var(--mono); font-size: 0.8rem; color: var(--accent); }
+    .loops { display: grid; grid-template-columns: repeat(4, 1fr); gap: 1rem; }
+    @media (max-width: 900px) { .loops { grid-template-columns: repeat(2, 1fr); } }
+    @media (max-width: 480px) { .loops { grid-template-columns: 1fr; } }
+    .loop-tag {
+      font-size: 0.7rem; font-weight: 700; letter-spacing: 0.06em;
+      text-transform: uppercase; color: var(--accent); margin-bottom: 0.4rem;
+    }
+    .used-by {
+      display: flex; flex-wrap: wrap; gap: 1rem; align-items: center;
+    }
+    .used-by a {
+      display: flex; align-items: center; gap: 0.5rem;
+      padding: 0.65rem 1rem;
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      color: var(--text);
+      font-weight: 500;
+      font-size: 0.9rem;
+      text-decoration: none;
+    }
+    .used-by a:hover { border-color: var(--accent-dim); }
+    .badge-row { display: flex; flex-wrap: wrap; gap: 0.5rem; margin-top: 1.5rem; }
+    .badge-row img { height: 22px; }
+    footer {
+      padding: 2.5rem 0 3rem;
+      border-top: 1px solid var(--border);
+      color: var(--muted);
+      font-size: 0.85rem;
+    }
+    footer .wrap { display: flex; flex-wrap: wrap; justify-content: space-between; gap: 1rem; }
+  </style>
+</head>
+<body>
+  <header>
+    <div class="wrap nav">
+      <div class="logo">doc-bridge <span>/ ak-docs</span></div>
+      <nav class="nav-links">
+        <a href="#demo">Demo</a>
+        <a href="#loops">Loops</a>
+        <a href="#used-by">Used by</a>
+        <a href="https://github.com/AgentsKit-io/doc-bridge">GitHub</a>
+      </nav>
+      <a class="btn btn-primary" href="https://www.npmjs.com/package/@agentskit/doc-bridge">npm install</a>
+    </div>
+  </header>
+
+  <main>
+    <section class="hero">
+      <div class="wrap">
+        <div class="eyebrow">AgentHandoff for your monorepo</div>
+        <h1>Your agent never edits the wrong package again.</h1>
+        <p class="lead">
+          Deterministic handoffs: <strong>startHere</strong>, <strong>editRoots</strong>, <strong>checks</strong>, and a bridge to human docs.
+          Layer 0 works without any LLM or API key.
+        </p>
+        <div class="cta-row">
+          <a class="btn btn-primary" href="#demo">See 60s demo</a>
+          <a class="btn btn-ghost" href="https://github.com/AgentsKit-io/doc-bridge#readme">Read README</a>
+        </div>
+        <div class="grid-2" id="demo">
+          <div class="terminal">
+            <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"># Before — agent guesses</div>
+              <div class="t-bad">✗ edits packages/billing when task says "auth"</div>
+              <div class="t-bad">✗ runs repo-wide test instead of package checks</div>
+              <br />
+              <div class="t-dim">$ npx ak-docs demo --text</div>
+              <br />
+              <div class="t-dim"># After — handoff.resolve</div>
+              <div class="t-ok">✓ target: auth (packages/auth)</div>
+              <div class="t-ok">✓ edit: packages/auth</div>
+              <div class="t-ok">✓ checks: pnpm --filter @demo/auth test</div>
+              <div class="t-ok">✓ human guide: /docs/guides/auth</div>
+              <div class="t-hi">Gate: red → green</div>
+            </div>
+          </div>
+          <div class="terminal">
+            <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">$ npm i -D @agentskit/doc-bridge</div>
+              <div class="t-dim">$ npx ak-docs init && npx ak-docs index</div>
+              <div class="t-dim">$ ak-docs mcp install --cursor</div>
+              <div class="t-dim">$ ak-docs doctor --text</div>
+              <br />
+              <div>Score: <span class="t-ok">82/100 (B)</span></div>
+              <div>Agent docs: 8/10 <span class="t-dim">(80% handoff-ready)</span></div>
+              <div>Human guides: 6/10 <span class="t-dim">(60% bridged)</span></div>
+              <div>Gates: <span class="t-ok">3/3 passing</span></div>
+              <br />
+              <div class="t-dim">→ ak-docs query package auth --agent</div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </section>
+
+    <section id="loops">
+      <div class="wrap">
+        <h2>Four loops, one bridge</h2>
+        <p class="section-lead">Act, bridge, learn, explain — each loop has a CLI command and real output, not a concept table.</p>
+        <div class="loops">
+          <div class="card">
+            <div class="loop-tag">Act</div>
+            <h3>Handoff routing</h3>
+            <p><code>query --agent</code> · MCP <code>handoff.resolve</code></p>
+          </div>
+          <div class="card">
+            <div class="loop-tag">Bridge</div>
+            <h3>Human ↔ agent</h3>
+            <p><code>bootstrap agent-docs</code> · <code>bridge.humanDoc</code></p>
+          </div>
+          <div class="card">
+            <div class="loop-tag">Learn</div>
+            <h3>Memory → docs</h3>
+            <p><code>memory promote --pr</code> · HITL draft PR</p>
+          </div>
+          <div class="card">
+            <div class="loop-tag">Explain</div>
+            <h3>Local consult</h3>
+            <p><code>ask</code> · optional Ollama chat</p>
+          </div>
+        </div>
+      </div>
+    </section>
+
+    <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>
+        <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>
+          <a href="https://playbook.agentskit.io/llms.txt">Agents Playbook</a>
+          <a href="https://github.com/AgentsKit-io/doc-bridge">doc-bridge (this repo)</a>
+        </div>
+        <div class="badge-row">
+          <img src="https://img.shields.io/npm/v/@agentskit/doc-bridge?style=flat-square&color=3d9cf5" alt="npm version" />
+          <img src="https://img.shields.io/badge/Layer%200-no%20API%20key-3ecf8e?style=flat-square" alt="no api key" />
+          <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>
+    </section>
+
+    <section>
+      <div class="wrap">
+        <h2>CI on every PR</h2>
+        <p class="section-lead">Stale handoffs fail the build — same gate locally and in GitHub Actions.</p>
+        <div class="terminal">
+          <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.0.0</span></div>
+            <div>&nbsp;&nbsp;with:</div>
+            <div>&nbsp;&nbsp;&nbsp;&nbsp;config-path: doc-bridge.config.json</div>
+          </div>
+        </div>
+      </div>
+    </section>
+  </main>
+
+  <footer>
+    <div class="wrap">
+      <div>MIT · <a href="https://github.com/AgentsKit-io/doc-bridge">AgentsKit-io/doc-bridge</a></div>
+      <div>
+        <a href="https://github.com/AgentsKit-io/doc-bridge/blob/master/docs/playbook/doc-bridge-pattern.md">Playbook pattern</a>
+        · <a href="https://github.com/AgentsKit-io/doc-bridge/blob/master/docs/skills/doc-bridge.md">Agent skill</a>
+      </div>
+    </div>
+  </footer>
+</body>
+</html>

package/docs/mcp.md

@@ -1,6 +1,15 @@
 # MCP setup
 
-## Cursor / Claude Desktop / Codex-style
+## One command (recommended)
+
+```bash
+ak-docs mcp install --cursor    # writes .cursor/mcp.json in repo root
+ak-docs mcp install --claude    # merges into Claude Desktop config (macOS)
+```
+
+Then add the agent skill: [skills/doc-bridge.md](./skills/doc-bridge.md)
+
+## Manual — Cursor / Claude Desktop / Codex-style
 
 ```json
 {

package/docs/ollama-demo.md

@@ -0,0 +1,64 @@
+# Ollama chat demo (Layer 1)
+
+Zero-cloud path for grounded `ak-docs chat` and `ak-docs ask --chat`.
+
+## Prerequisites
+
+```bash
+# Terminal 1 — model server
+ollama serve
+
+# Terminal 2 — models
+ollama pull llama3.2
+ollama pull nomic-embed-text
+
+# Layer 1 peers (once per repo)
+npm i -D @agentskit/doc-bridge \
+  @agentskit/rag @agentskit/ink @agentskit/adapters @agentskit/memory react
+```
+
+## Config
+
+Copy [`examples/ollama-chat.config.ts`](../examples/ollama-chat.config.ts) or merge into your `doc-bridge.config.ts`:
+
+```ts
+intelligence: {
+  enabled: true,
+  adapter: {
+    provider: 'ollama',
+    model: 'llama3.2',
+    baseUrl: 'http://127.0.0.1:11434',
+    options: { embedModel: 'nomic-embed-text' },
+  },
+  chat: { enabled: true, handoffFirst: true },
+  retriever: { enabled: true, mode: 'agentskit-rag' },
+}
+```
+
+## Run
+
+```bash
+ak-docs index
+ak-docs rag ingest
+ak-docs ask "who owns auth?" --chat    # one-shot; handoffFirst when package id matches
+ak-docs chat                            # Ink terminal UI
+```
+
+`handoffFirst` (default) prepends deterministic AgentHandoff JSON when the question mentions a known package id — visible in the chat transcript before the model answer.
+
+## Smoke test
+
+```bash
+pnpm smoke:ollama
+```
+
+Skips gracefully if Ollama is down or peers are missing (safe for CI as optional job).
+
+## Troubleshooting
+
+| Error | Fix |
+|-------|-----|
+| `Intelligence provider request failed` | `ollama serve` not running |
+| `Optional peer "@agentskit/rag" is not installed` | Install Layer 1 peers (see above) |
+| Empty chat response | Pull models: `ollama pull llama3.2` |
+| Slow first `rag ingest` | Normal — embeds entire corpus locally |

package/docs/playbook/doc-bridge-pattern.md

@@ -0,0 +1,114 @@
+---
+type: pattern
+id: doc-bridge-pattern
+purpose: Route coding agents to the correct package, checks, and human docs in any monorepo.
+owner: AgentsKit
+license: CC-BY-4.0
+visibility: public
+tags: [agents, documentation, monorepo, handoff, mcp]
+---
+
+# Doc Bridge Pattern
+
+**AgentHandoff for your monorepo** — deterministic routing so agents edit the right roots, run the right checks, and stay linked to human documentation.
+
+Published pattern for [Agents Playbook](https://playbook.agentskit.io/). Export with:
+
+```bash
+ak-docs playbook pattern --text
+ak-docs playbook pattern --json
+```
+
+## Problem
+
+Coding agents guess package ownership. They edit sibling modules, run repo-wide tests, and ship changes without a bridge to human-facing guides. Wikis and RAG explain concepts but weakly answer *where to act*.
+
+## Solution (three artifacts)
+
+| Artifact | Role |
+|----------|------|
+| **AgentHandoff** | JSON handoff: `startHere`, `editRoots`, `checks`, `humanDoc`, `bridge` |
+| **DocBridgeIndex** | Deterministic index + `contentHash` for CI freshness gates |
+| **Self-describe** | `llms.txt`, `capabilities.json` for discovery |
+
+## Four loops
+
+| Loop | Command | Outcome |
+|------|---------|---------|
+| **Act** | `ak-docs query package <id> --agent` | Agent edits only `editRoots` |
+| **Bridge** | `ak-docs bootstrap agent-docs` | Link agent corpus ↔ human site |
+| **Learn** | `ak-docs memory promote --pr` | HITL draft PR from agent memory |
+| **Explain** | `ak-docs ask "<question>"` | Local consult + handoff preview |
+
+## 60-second proof
+
+```bash
+npm i -D @agentskit/doc-bridge
+npx ak-docs demo --text
+ak-docs mcp install --cursor
+```
+
+## AgentHandoff example
+
+```json
+{
+  "type": "agent-handoff",
+  "startHere": "docs/for-agents/packages/auth.md",
+  "editRoots": ["packages/auth"],
+  "checks": ["pnpm --filter @demo/auth test"],
+  "humanDoc": "/docs/guides/auth",
+  "bridge": { "humanDoc": "linked" }
+}
+```
+
+When `humanDoc` is missing, handoffs surface `bridge.action: "ak-docs bootstrap agent-docs"` — a feature, not a silent gap.
+
+## MCP contract
+
+Agents call `handoff.resolve` before editing `packages/*`:
+
+1. Read `startHere`
+2. Stay inside `editRoots`
+3. Run every `checks` command
+4. Link `humanDoc` or escalate missing bridge
+
+## CI gate
+
+```yaml
+- uses: AgentsKit-io/doc-bridge@v1.0.0
+```
+
+Or: `ak-docs index && ak-docs gate run` — stale index fails the PR.
+
+## Coverage metric
+
+```bash
+ak-docs doctor --text
+ak-docs doctor --badge
+```
+
+Teams track handoff % and human-bridge % daily.
+
+## When to use
+
+- pnpm/npm monorepos with real package ownership
+- Fumadocs / Docusaurus human sites + dense agent corpus
+- Cursor / Claude / Codex agents that should not guess edit roots
+
+## When not to use
+
+- Single-file repos with no ownership boundaries (AGENTS.md may suffice)
+- Hosted doc chat as primary product (doc-bridge is routing + bridge, not SaaS chat)
+
+## Promotion to Playbook
+
+1. Review this file for secrets and private paths
+2. Open PR to [agents-playbook](https://github.com/AgentsKit-io/agents-playbook) under `content/docs/pillars/ai-collaboration/`
+3. Or run `ak-docs memory promote --pr` for memory-sourced findings
+
+## References
+
+- npm: https://www.npmjs.com/package/@agentskit/doc-bridge
+- repo: https://github.com/AgentsKit-io/doc-bridge
+- skill: [doc-bridge skill](../skills/doc-bridge.md)
+- landing: https://agentskit-io.github.io/doc-bridge/