@agentskit/doc-bridge 1.0.2 → 1.2.1

package/docs/DOGFOOD-ROUND2.md

@@ -1,3 +1,8 @@
+---
+title: Dogfood round 2
+description: Validation evidence from the second published Doc Bridge alpha.
+---
+
 # Dogfood round 2 — published `@agentskit/doc-bridge@0.1.0-alpha.2`
 
 **Date:** 2026-07-09  

package/docs/DOGFOOD-ROUND3.md

@@ -1,3 +1,8 @@
+---
+title: Dogfood round 3
+description: Validation evidence from the third published Doc Bridge alpha.
+---
+
 # Dogfood round 3 — `@agentskit/doc-bridge@0.1.0-alpha.3`
 
 **Date:** 2026-07-09  

package/docs/DOGFOOD-V1.md

@@ -1,3 +1,8 @@
+---
+title: Dogfood validation v1
+description: Release validation evidence for the first stable Doc Bridge package.
+---
+
 # Dogfood validation — `@agentskit/doc-bridge@1.0.0`
 
 **Date:** 2026-07-09  

package/docs/DOGFOOD.md

@@ -1,3 +1,8 @@
+---
+title: Ecosystem dogfood
+description: How AgentsKit repositories validate Doc Bridge against real documentation surfaces.
+---
+
 # Ecosystem dogfood — `@agentskit/doc-bridge`
 
 Validated **2026-07-09** against four consumers.

package/docs/MARKETPLACE-ECOSYSTEM-PLAN.md

@@ -0,0 +1,16 @@
+---
+title: Ecosystem and Marketplace acceptance plan
+description: Internal acceptance criteria for the Doc Bridge ecosystem and Marketplace slice.
+---
+
+# Doc Bridge ecosystem and Marketplace acceptance plan
+
+This slice is complete only when all conditions below are evidenced locally. Publication remains an owner-only follow-up.
+
+- Composite Action validates committed freshness, accepts shell inputs only through quoted environment variables, pins its runtime package, and pins third-party Actions by SHA.
+- Marketplace metadata, consumer example, release-owner checklist, and automated contract checks agree on the same version.
+- The public portal exposes seven ecosystem products, six Doc Bridge peers, and contextual routes for Chat, Code Review, and AKOS.
+- `/for-agents`, `llms.txt`, `llms-full.txt`, raw Markdown, and deterministic knowledge are public and cross-linked.
+- Human docs remain concise and navigable; source-heavy detail stays in raw/full machine surfaces.
+- Landing and documentation pages have no horizontal overflow at 375, 768, 1280, or 1440 pixels.
+- `ak-docs gate run`, documentation conformance, and `ak-docs doctor` finish at 100/A.

package/docs/MARKETPLACE.md

@@ -0,0 +1,39 @@
+---
+title: GitHub Marketplace
+description: Add the Doc Bridge freshness gate to pull requests with a reproducible composite Action.
+---
+
+# GitHub Marketplace
+
+Doc Bridge ships one root composite Action: `doc-bridge-gate`. It verifies the committed index and configured documentation gates without rebuilding artifacts first.
+
+## Use it in a repository
+
+```yaml
+name: Documentation gate
+on: [pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: AgentsKit-io/doc-bridge@v1.2.1
+        with:
+          config-path: doc-bridge.config.json
+```
+
+If the index is stale, run `ak-docs index`, review the generated diff, and commit it. The Action's default package version matches its immutable release tag.
+
+## Release-owner checklist
+
+1. Run `pnpm check:marketplace`, `pnpm test:marketplace`, and the repository release matrix.
+2. Confirm the public repository contains exactly one root `action.yml` and its name is available.
+3. Push the immutable semver tag. The release workflow publishes npm, uploads the artifact, and leaves a GitHub Release draft ready for review.
+4. Open that draft, select **Publish this Action to the GitHub Marketplace**, choose categories, and accept the GitHub Marketplace Developer Agreement if prompted.
+5. Publish the release, then verify the listing and execute the exact consumer workflow above in a clean fixture repository.
+
+Marketplace publication is a deliberate owner action; the workflow never moves tags and does not publish the GitHub Release before the Marketplace fields are complete.

package/docs/POSITIONING.md

@@ -1,3 +1,8 @@
+---
+title: Doc Bridge positioning
+description: Product purpose, boundaries, maturity, and role inside the AgentsKit ecosystem.
+---
+
 # doc-bridge positioning
 
 Source of truth for README, issues, RFCs, and external posts.

package/docs/RELEASE.md

@@ -1,16 +1,27 @@
+---
+title: Release checklist
+description: Reproducible package, documentation, and registry checks for a Doc Bridge release.
+---
+
 # Release checklist — `@agentskit/doc-bridge`
 
 ## Pre-flight (local)
 
 ```bash
 pnpm install
+pnpm audit --audit-level low
 pnpm typecheck
+pnpm check:ecosystem-upstream
 pnpm test
+pnpm coverage
 pnpm build
 pnpm smoke:packaged
+node bin/ak-docs.js index
+node bin/ak-docs.js gate run
+node bin/ak-docs.js conformance run documentation-standard-v1 --text
 ```
 
-Expect: packaged smoke prints `packaged smoke passed` and includes demo `query package example --agent`.
+Expect: zero known vulnerabilities, coverage above the repository threshold, packaged smoke prints `packaged smoke passed`, and every required and recommended documentation rule passes without exceptions.
 
 ## Version
 
@@ -21,45 +32,41 @@ pnpm changeset          # if new entry needed
 pnpm version-packages   # bumps package.json + CHANGELOG from .changeset/*
 ```
 
-Current track: **`1.0.0` stable** (alpha series ended at `0.1.0-alpha.5`).
+Current track: **`1.2.1` stable** (alpha series ended at `0.1.0-alpha.5`).
 
-## Publish (npm)
+## Publish (npm + GitHub)
 
-Requires npm auth for the `@agentskit` org (`npm whoami` / `NPM_TOKEN`).
+Stable packages are published only by `.github/workflows/release.yml` from an immutable semver tag. The workflow re-runs the complete security, test, coverage, packaged-smoke, dogfood, Marketplace-contract, and conformance matrix, publishes npm with provenance, verifies the registry result, uploads the tarball to a GitHub Release draft, and leaves final publication to the owner so the Marketplace fields can be completed first.
 
 ```bash
-pnpm release
-# equivalent:
-# pnpm build && pnpm test && changeset publish
+git tag v1.2.1
+git push origin v1.2.1
 ```
 
-Or one-shot after version bump:
+For recovery of an existing immutable tag, use the guarded manual dispatch. Never move or recreate a release tag.
 
 ```bash
-npm publish --access public
+gh workflow run release.yml --ref master -f tag=v1.2.1
 ```
 
 Confirm:
 
 ```bash
-npm view @agentskit/doc-bridge version
-npx ak-docs@0.1.0-alpha.x --version
+npm view @agentskit/doc-bridge@1.2.1 version dist.integrity
+npx ak-docs@1.2.1 --version
+gh release view v1.2.1 --json isDraft
 ```
 
-## GitHub
+GitHub Pages must remain configured for GitHub Actions; `.github/workflows/pages.yml` builds and deploys the Fumadocs portal from `apps/docs`.
 
-```bash
-git tag v1.0.0
-git push origin master --tags
-gh release create v1.0.0 --title "v1.0.0 — AgentHandoff stable" --notes-file CHANGELOG.md
-```
+## Publish the GitHub Action to Marketplace
 
-Enable GitHub Pages (Settings → Pages → GitHub Actions) for landing deploy from `.github/workflows/pages.yml`.
+Run `pnpm check:marketplace && pnpm test:marketplace`, then follow [the Marketplace guide](./MARKETPLACE.md). In the generated release draft, select the Marketplace option and categories before publishing the GitHub Release. npm success alone does not publish the listing.
 
 ## Post-publish smoke (fresh machine)
 
 ```bash
-npm i -D @agentskit/doc-bridge@0.1.0-alpha.x
+npm i -D @agentskit/doc-bridge@1.2.1
 npx ak-docs init
 npx ak-docs index
 npx ak-docs query package example --agent

package/docs/agent-corpus/INDEX.md

@@ -0,0 +1,10 @@
+---
+type: package
+package: doc-bridge-index
+editRoot: src/index-builder
+humanDoc: /docs/recipes/index-pipeline
+---
+
+# Index builder
+
+Owns corpus scanning, handoffs, hashes, `llms.txt`, and watch mode. Generated output must remain deterministic.

package/docs/agent-corpus/OVERVIEW.md

@@ -0,0 +1,9 @@
+---
+type: index
+purpose: Route coding agents to Doc Bridge ownership sidecars.
+owner: maintainers
+---
+
+# Doc Bridge agent corpus
+
+Resolve the requested ownership ID with `ak-docs query ownership <id> --agent`. Read the returned sidecar and its linked human guide before editing.

package/docs/agent-corpus/chat.md

@@ -0,0 +1,10 @@
+---
+type: package
+package: doc-bridge-chat
+editRoot: src/intelligence
+humanDoc: /docs/chat-and-rag
+---
+
+# Chat and RAG
+
+Owns optional AgentsKit retrieval and chat after deterministic lookup. Conversational UI belongs to AgentsKit Chat; enterprise orchestration belongs to AKOS.

package/docs/agent-corpus/cli.md

@@ -0,0 +1,10 @@
+---
+type: package
+package: doc-bridge-cli
+editRoot: src/cli
+humanDoc: /docs/spec/cli
+---
+
+# CLI
+
+Owns public `ak-docs` commands and output modes. Keep JSON output versioned and text output readable.

package/docs/agent-corpus/conformance.md

@@ -0,0 +1,10 @@
+---
+type: package
+package: doc-bridge-conformance
+editRoot: src/conformance
+humanDoc: /docs/spec/documentation-standard-v1
+---
+
+# Conformance
+
+Owns versioned documentation-standard rules and evidence. Do not turn missing evidence into a passing score.

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

@@ -0,0 +1,10 @@
+---
+type: package
+package: doc-bridge
+editRoot: src
+humanDoc: /docs/POSITIONING
+---
+
+# Doc Bridge core
+
+Owns the public CLI, index, MCP, gates, and doctor contracts. Preserve deterministic behavior and run `pnpm test && pnpm typecheck`.

package/docs/agent-corpus/doctor.md

@@ -0,0 +1,10 @@
+---
+type: package
+package: doc-bridge-doctor
+editRoot: src/doctor
+humanDoc: /docs/spec/documentation-standard-v1
+---
+
+# Doctor
+
+Owns health scoring and remediation guidance. Every point must trace to meaningful repository evidence.

package/docs/agent-corpus/gates.md

@@ -0,0 +1,10 @@
+---
+type: package
+package: doc-bridge-gates
+editRoot: src/gates
+humanDoc: /docs/spec/documentation-standard-v1
+---
+
+# Gates
+
+Owns freshness, coverage, and human-link checks. A gate must observe committed state before rewriting artifacts.

package/docs/agent-corpus/mcp.md

@@ -0,0 +1,10 @@
+---
+type: package
+package: doc-bridge-mcp
+editRoot: src/mcp
+humanDoc: /docs/mcp
+---
+
+# MCP
+
+Owns the stdio server and public tool contracts. Preserve runtime validation and stable response shapes.

package/docs/agent-corpus/memory.md

@@ -0,0 +1,10 @@
+---
+type: package
+package: doc-bridge-memory
+editRoot: src/memory
+humanDoc: /docs/schemas/memory-candidate-v1
+---
+
+# Memory
+
+Owns reviewable learning ingestion, classification, and promotion. Durable knowledge becomes a documented change, never silent state.

package/docs/agent-corpus/query.md

@@ -0,0 +1,10 @@
+---
+type: package
+package: doc-bridge-query
+editRoot: src/query
+humanDoc: /docs/query
+---
+
+# Query
+
+Owns deterministic package and document resolution. Prefer an explicit miss over an invented answer.

package/docs/chat-and-rag.md

@@ -1,3 +1,8 @@
+---
+title: Chat and RAG
+description: Add optional AgentsKit retrieval and chat after deterministic documentation resolution.
+---
+
 # Chat and RAG (Layer 1)
 
 Layer 0 (index, handoff, MCP, gates, memory pipeline) never requires an LLM.
@@ -12,6 +17,35 @@ Layer 1 is **opt-in** and dogfoods public AgentsKit packages:
 | `@agentskit/ink` | Terminal chat UI (`ak-docs chat`) |
 | `react` | Required by Ink |
 
+## Public docs chat: deterministic before backend
+
+The documentation portal uses `@agentskit/chat` (root), `@agentskit/chat/react`,
+and `@agentskit/chat/protocol` directly — the consolidated AgentsKit Chat 0.3.x
+surface. It does not recreate chat lifecycle or session state.
+
+At build time, `scripts/build-docs-artifacts.mjs` reads the fresh
+`.doc-bridge/index.json` and canonical `docs/**` corpus, then writes:
+
+- `deterministic/knowledge.json` — exact commands, documents, and real ownership handoffs;
+- `deterministic/site-config.json` — trusted artifact hash plus fallback policy;
+- `llms.txt`, `llms-full.txt`, and `raw/**` — model-friendly public sources.
+
+The browser verifies the SHA-256 content hash before using the artifact. A
+known exact question answers locally with provenance. Multiple exact matches
+return local choices. Only a genuine miss reaches the configured backend, and
+the UI reports a backend answer only after a successful completed stream.
+
+```mermaid
+flowchart LR
+  Q[Question] --> A{Verified exact match?}
+  A -->|one| L[Local answer + citation]
+  A -->|many| C[Local choices]
+  A -->|none| B[AgentsKit backend]
+  B --> S{Completed stream?}
+  S -->|yes| R[Backend answer + provenance]
+  S -->|no| E[Retryable error]
+```
+
 ## Trust model
 
 1. **`handoffFirst`** (default): if the question mentions a known package id, attach deterministic AgentHandoff context before the model answers.

package/docs/examples.md

@@ -1,3 +1,8 @@
+---
+title: Examples
+description: Ready-to-run Doc Bridge configurations and integration examples.
+---
+
 # Examples
 
 Config sketches under [`examples/`](../examples/):

package/docs/for-agents.md

@@ -0,0 +1,31 @@
+---
+title: For agents
+description: Resolve ownership, read compact context, and run the repository's own checks before editing.
+---
+
+# For agents
+
+Use Doc Bridge before changing a module. It returns versioned, runtime-validated data instead of asking a model to infer ownership from the entire repository.
+
+```bash
+ak-docs query ownership <id> --agent
+```
+
+The response supplies four things: `startHere`, `readBeforeEditing`, `editRoots`, and `checks`.
+
+```mermaid
+flowchart LR
+  Q["Resolve ownership"] --> R["Read startHere"]
+  R --> E["Edit only editRoots"]
+  E --> T["Run checks"]
+  T --> P["Promote durable learning"]
+```
+
+## Machine entry points
+
+- [`llms.txt`](https://agentskit-io.github.io/doc-bridge/llms.txt) — concise discovery and canonical routes
+- [`llms-full.txt`](https://agentskit-io.github.io/doc-bridge/llms-full.txt) — complete source corpus
+- [`deterministic/knowledge.json`](https://agentskit-io.github.io/doc-bridge/deterministic/knowledge.json) — local chat/discovery artifact
+- [`raw/for-agents.md`](https://agentskit-io.github.io/doc-bridge/raw/for-agents.md) — this guide as raw Markdown
+
+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).

package/docs/getting-started.md

@@ -1,5 +1,21 @@
+---
+title: Getting started
+description: Install, index, query, and gate repository documentation in about 60 seconds.
+---
+
 # Getting started
 
+doc-bridge turns your existing docs into an **AgentHandoff** index:
+
+- `startHere` — what the agent reads first
+- `editRoots` — where the agent is allowed to work
+- `checks` — what proves the edit
+- `humanDoc` — the human-facing guide for the same area
+
+It also runs the inverse loop: local agent memory becomes a classified,
+reviewable documentation draft. Start with CLI. Add MCP when agents should call
+it automatically. Add CI when the bridge becomes part of review.
+
 ## Install
 
 ```bash
@@ -60,6 +76,17 @@ Project root for `--config path/to/doc-bridge.config.json` is the **directory of
 
 See [config-v1](./spec/config-v1.md) and [examples](./examples.md).
 
+## Use surfaces
+
+| Surface | When to use | Command |
+|---------|-------------|---------|
+| 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` |
+| 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` |
+
 ## MCP (Cursor / Claude)
 
 ```json
@@ -90,10 +117,13 @@ ak-docs bootstrap agent-docs         # draft agent docs from human site
 ```bash
 ak-docs memory ingest
 ak-docs memory classify
-ak-docs memory promote   # draft only — never auto-merges
+ak-docs memory promote              # prints a safe draft body
+ak-docs memory promote --pr --dry-run
+ak-docs memory promote --pr         # opens a GitHub draft PR via gh
 ```
 
-Sources include `.agent-memory/**` and `.cursor/rules/*.mdc`.
+Sources include `.agent-memory/**` and `.cursor/rules/*.mdc`. Promotion is
+draft-only and never auto-merges.
 
 ## Optional chat + RAG (AgentsKit)
 

package/docs/index.md

@@ -0,0 +1,23 @@
+---
+title: Documentation
+description: Choose the shortest Doc Bridge path for humans, agents, or pull-request enforcement.
+---
+
+# Documentation
+
+Doc Bridge keeps one repository useful to both people and coding agents. Start with the outcome you need:
+
+- **Try it locally:** [Getting started](./getting-started.md)
+- **Route an agent:** [For agents](./for-agents.md)
+- **Block stale context in PRs:** [GitHub Marketplace](./MARKETPLACE.md)
+- **Connect an MCP client:** [MCP](./mcp.md)
+
+```mermaid
+flowchart LR
+  D["Repository docs"] --> I["Deterministic index"]
+  I --> H["Human guide"]
+  I --> A["Agent handoff"]
+  I --> G["Pull-request gate"]
+```
+
+Long-form contracts remain available under **Specification** and as raw Markdown, without making the primary path read like a reference manual.

package/docs/landing/index.html

@@ -3,8 +3,8 @@
 <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." />
+  <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="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" />
@@ -105,6 +105,22 @@
     .dot-y { background: var(--amber); }
     .dot-g { background: var(--green); }
     .terminal-body { padding: 1.25rem 1.5rem; overflow-x: auto; }
+    .hero-image {
+      display: block;
+      width: 100%;
+      margin: 0 0 2rem;
+      border: 1px solid var(--border);
+      border-radius: var(--radius);
+      box-shadow: 0 24px 70px rgba(0, 0, 0, 0.35);
+    }
+    .section-image {
+      display: block;
+      width: 100%;
+      margin: 0 0 1.5rem;
+      border: 1px solid var(--border);
+      border-radius: var(--radius);
+      box-shadow: 0 18px 50px rgba(0, 0, 0, 0.28);
+    }
     .t-dim { color: var(--muted); }
     .t-ok { color: var(--green); }
     .t-bad { color: var(--red); }
@@ -145,6 +161,25 @@
       text-decoration: none;
     }
     .used-by a:hover { border-color: var(--accent-dim); }
+    .surface-table {
+      width: 100%;
+      border-collapse: collapse;
+      overflow: hidden;
+      border: 1px solid var(--border);
+      border-radius: var(--radius);
+      background: var(--surface);
+    }
+    .surface-table th,
+    .surface-table td {
+      padding: 0.9rem 1rem;
+      border-bottom: 1px solid var(--border);
+      text-align: left;
+      vertical-align: top;
+      font-size: 0.92rem;
+    }
+    .surface-table th { color: var(--text); font-weight: 600; }
+    .surface-table td { color: var(--muted); }
+    .surface-table tr:last-child td { border-bottom: 0; }
     .badge-row { display: flex; flex-wrap: wrap; gap: 0.5rem; margin-top: 1.5rem; }
     .badge-row img { height: 22px; }
     footer {
@@ -173,16 +208,19 @@
   <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>
+        <div class="eyebrow">Docs your agents can act on</div>
+        <h1>Turn repo docs into executable handoffs.</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.
+          doc-bridge gives every coding agent the same contract: <strong>startHere</strong>,
+          <strong>editRoots</strong>, <strong>checks</strong>, and <strong>humanDoc</strong>.
+          Then it turns agent memory back into reviewable documentation drafts.
+          Use it from CLI, MCP, and CI. No LLM or API key required.
         </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>
+        <img class="hero-image" src="assets/doc-bridge-hero.webp" alt="doc-bridge maps human docs into structured agent handoffs for CLI, MCP, and CI" />
         <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>
@@ -221,10 +259,32 @@
       </div>
     </section>
 
+    <section>
+      <div class="wrap">
+        <h2>Use it where agents already work</h2>
+        <p class="section-lead">One index, multiple surfaces. Start with the CLI; wire MCP and CI when the first handoff is useful.</p>
+        <img class="section-image" src="assets/doc-bridge-surfaces.webp" alt="doc-bridge index used through CLI, MCP, CI, and documentation adapters" />
+        <table class="surface-table">
+          <thead>
+            <tr><th>Surface</th><th>What it does</th><th>How you use it</th></tr>
+          </thead>
+          <tbody>
+            <tr><td>CLI</td><td>Query ownership, inspect handoffs, run doctor, search docs.</td><td><code>ak-docs query package auth --agent</code></td></tr>
+            <tr><td>MCP</td><td>Lets Cursor, Claude Code, and Codex-style agents resolve before editing.</td><td><code>ak-docs mcp install --cursor</code></td></tr>
+            <tr><td>CI</td><td>Blocks stale indexes and broken human-doc bridges.</td><td><code>ak-docs index && ak-docs gate run</code></td></tr>
+            <tr><td>Adapters</td><td>Connect Fumadocs, Docusaurus, plain markdown, and pnpm workspaces.</td><td><code>fumadocs</code> · <code>docusaurus</code> · <code>plain-markdown</code></td></tr>
+            <tr><td>Memory pipeline</td><td>Classifies local agent memory and drafts documentation updates.</td><td><code>ak-docs memory promote --pr</code></td></tr>
+            <tr><td>Optional RAG/chat</td><td>Adds handoff-first chat when you install AgentsKit peers.</td><td><code>ak-docs rag ingest && ak-docs chat</code></td></tr>
+          </tbody>
+        </table>
+      </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>
+        <img class="section-image" src="assets/doc-bridge-two-way.webp" alt="doc-bridge connects human docs to coding agents and agent memory back to draft docs" />
         <div class="loops">
           <div class="card">
             <div class="loop-tag">Act</div>
@@ -238,8 +298,8 @@
           </div>
           <div class="card">
             <div class="loop-tag">Learn</div>
-            <h3>Memory → docs</h3>
-            <p><code>memory promote --pr</code> · HITL draft PR</p>
+            <h3>Agent memory → docs</h3>
+            <p><code>memory classify</code> · <code>promote --pr</code></p>
           </div>
           <div class="card">
             <div class="loop-tag">Explain</div>
@@ -277,7 +337,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.0.0</span></div>
+            <div>- uses: <span class="t-hi">AgentsKit-io/doc-bridge@v1.2.1</span></div>
             <div>&nbsp;&nbsp;with:</div>
             <div>&nbsp;&nbsp;&nbsp;&nbsp;config-path: doc-bridge.config.json</div>
           </div>
@@ -296,4 +356,4 @@
     </div>
   </footer>
 </body>
-</html>
+</html>

package/docs/mcp.md

@@ -1,3 +1,8 @@
+---
+title: MCP setup
+description: Connect Doc Bridge deterministic handoffs to MCP-compatible coding agents.
+---
+
 # MCP setup
 
 ## One command (recommended)