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

package/docs/DOGFOOD-ROUND2.md

@@ -0,0 +1,142 @@
+# Dogfood round 2 — published `@agentskit/doc-bridge@0.1.0-alpha.2`
+
+**Date:** 2026-07-09  
+**Install:** npm registry tag `alpha` → `0.1.0-alpha.2`  
+**Consumers:** agentskit · agentskit-os · agents-playbook · agentskit-registry  
+
+## Scoreboard
+
+| Repo | Install | Version | Knowledge | Handoffs | Gate | Sample handoff quality |
+|------|---------|---------|-----------|----------|------|------------------------|
+| **agentskit** | `pnpm add -Dw @0.1.0-alpha.2` ✅ | 0.1.0-alpha.2 | 25 | 24 | ✅ freshness + 23 humanDoc | Excellent: pnpm filter checks + humanDoc `/docs/reference/packages/core` |
+| **agentskit-os** | pnpm store conflict; used **`npx`** ✅ | 0.1.0-alpha.2 | 170 | 92 | ✅ freshness + 9 humanDoc | Good act path; weak human bridge (9/92) |
+| **agents-playbook** | `pnpm add -D` ✅ | 0.1.0-alpha.2 | 127 | 81 | ✅ freshness + okf-type | Pattern ownership + `check:okf-type` ✅ |
+| **agentskit-registry** | needs `--legacy-peer-deps` ⚠️ | 0.1.0-alpha.2 | 36 | 36 | ✅ freshness | Full agent ownership + humanDoc ✅ |
+
+### npm dist-tags (observed)
+
+| Tag | Version |
+|-----|---------|
+| `latest` | `0.1.0-alpha.1` |
+| `alpha` | `0.1.0-alpha.2` |
+
+**Recommendation:** keep prereleases only on `alpha` until stable; document `npm i -D @agentskit/doc-bridge@alpha`.
+
+---
+
+## What works well (validated)
+
+1. **Published binary works** — `ak-docs 0.1.0-alpha.2` from registry / npx.
+2. **Monorepo handoffs** — `editRoots` + `pnpm --filter @agentskit/<pkg> test|lint` on agentskit and AKOS.
+3. **Playbook preset** — gates green without crushing large OKF corpus.
+4. **Registry ownership** — all 36 agents resolve; checks use `npm run validate`.
+5. **Fumadocs humanDoc** on agentskit points at **reference** docs, not nested for-agents.
+6. **Pattern checks** — playbook patterns emit `pnpm run check:okf-type`.
+
+---
+
+## Issues found (prioritized)
+
+### P0 — correctness / ranking (agents will take wrong action)
+
+| ID | Issue | Evidence | Suggested fix |
+|----|--------|----------|----------------|
+| **R2-1** | **Search/ask ranking ignores exact package id** | `search core --agent` bestMatch = **angular** (score 8) tied with **core** (score 8) because summary contains `@agentskit/core` | Boost exact `id` / path segment matches; prefer ownership id === term before body mentions |
+| **R2-2** | **`ask` suggests wrong handoff** | “where do I change the **core** package?” → best match **angular**, next `query ownership angular` | Same ranking fix; optional: prefer ownership over knowledge for “package/module” language |
+| **R2-3** | **Purpose/notes truncated mid-sentence** | core notes: `"Stable TypeScript contracts (Adapter, Tool, Memory, Retriever, Skill,"` | Raise firstParagraph budget; strip trailing incomplete commas; prefer frontmatter `purpose` full line |
+
+### P1 — install / peer DX
+
+| ID | Issue | Evidence | Suggested fix |
+|----|--------|----------|----------------|
+| **R2-4** | **Optional peers still break npm install** | registry: `ERESOLVE` with optional peers vs `@agentskit/adapters@0.12.x` | Peer ranges more permissive (`>=0.12` / `>=1.0`); document `--legacy-peer-deps`; ensure optional peers never hard-fail Layer 0 |
+| **R2-5** | **Peer `@agentskit/core@^1.10.0` vs monorepo 1.9.0** | pnpm warning on agentskit install | Align peer to `^1.9.0 \|\| ^1.10.0` or `>=1.9.0 <2` for dogfood until monorepo bumps |
+| **R2-6** | **`latest` still points at alpha.1** | `npm view` latest=alpha.1, alpha=alpha.2 | Publish hygiene: don’t put prereleases on `latest`, or retag after publish |
+| **R2-7** | **AKOS cannot `pnpm add` (store v10 vs v11)** | `ERR_PNPM_UNEXPECTED_STORE` | Docs: use npx / align store; not a doc-bridge bug but dogfood friction |
+
+### P2 — search / retrieval quality
+
+| ID | Issue | Evidence | Suggested fix |
+|----|--------|----------|----------------|
+| **R2-8** | **Search miss on common English** | agentskit `search documentation` → **0 matches** | Index more body text / titles; lower threshold; BM25 over full file not only description |
+| **R2-9** | **Playbook `search handoff` → 0** | term may only appear deep in body | Same as R2-8; chunk full markdown into search corpus |
+| **R2-10** | **Federation hard-fail noise** | `retrieve` → `Failed to fetch https://registry.agentskit.io/llms.txt: 404` | Soft-fail federation sources; warn once; don’t fail command |
+| **R2-11** | **Text search UX** | tab-separated dense lines | Columnar/TTY formatting (`type  id  path  summary`) |
+
+### P3 — bridge coverage & product polish
+
+| ID | Issue | Evidence | Suggested fix |
+|----|--------|----------|----------------|
+| **R2-12** | **AKOS humanDoc still sparse** | 9/92 handoffs with humanDoc | Map for-agents frontmatter `humanDoc`; product Fumadocs catalog; optional plain-markdown `docs/errors` etc. |
+| **R2-13** | **Duplicate knowledge+ownership rows in search** | same path appears as ownership + knowledge | Deduplicate by path; show ownership preferred |
+| **R2-14** | **Default checks for patterns without okf script** | N/A playbook ok | Fine; document convention |
+| **R2-15** | **MCP not re-smoked this round** | — | Keep in CI smoke; optional round 3 |
+
+---
+
+## Sample outputs (good)
+
+### agentskit — `query package core --agent`
+
+```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"
+}
+```
+
+### playbook — pattern handoff
+
+```json
+{
+  "startHere": "content/docs/pillars/ai-collaboration/open-knowledge-format-pattern.md",
+  "checks": ["pnpm run check:okf-type"],
+  "humanDoc": "/docs/pillars/ai-collaboration/open-knowledge-format-pattern"
+}
+```
+
+### registry — `docs-chat`
+
+```json
+{
+  "startHere": "registry/docs-chat/README.md",
+  "editRoots": ["registry/docs-chat"],
+  "checks": ["npm run validate", "npm test"],
+  "humanDoc": "/agents/docs-chat"
+}
+```
+
+---
+
+## Recommended next alpha (0.1.0-alpha.3) scope
+
+1. **Ranking:** exact id / basename boost; package-intent heuristics for `ask`
+2. **Search corpus:** full-text over body (not only description); dedupe paths
+3. **Descriptions:** full purpose from frontmatter or first complete paragraph
+4. **Peers:** widen optional peer ranges; Layer 0 install never requires AgentsKit packages
+5. **Federation:** soft-fail missing `llms.txt` sources
+6. **Publish:** keep `latest` free of broken prereleases; doc install as `@alpha`
+
+---
+
+## Consumer follow-ups (not doc-bridge code)
+
+| Repo | Action |
+|------|--------|
+| agentskit | Bump `@agentskit/core` to 1.10+ or live with peer warning |
+| agentskit-os | Align pnpm store / commit lock with published dep; add CI `docs:bridge:gate` |
+| agents-playbook | Optional CI workflow for gate |
+| agentskit-registry | Publish `public/llms.txt` at site root (404 today); use `--legacy-peer-deps` until peer ranges loosen |
+| all | After alpha.3: switch dep to `@agentskit/doc-bridge@alpha` only |
+
+---
+
+## Conclusion
+
+**Round 2 proves Layer 0 is useful on real monorepos and OKF/registry corpora with the published package.**  
+The biggest remaining gap for “agents do the right thing” is **discovery ranking (R2-1/R2-2)** and **search body coverage (R2-8/R2-9)** — not indexing or handoff structure.

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 |