@agentskit/doc-bridge 1.1.1 → 1.2.3

package/docs/guides/index-and-query.md

@@ -0,0 +1,75 @@
+---
+title: Index and query
+description: Build a deterministic index and resolve ownership handoffs without calling a model.
+---
+
+# Index and query
+
+Layer 0 is **offline and deterministic**. Indexing scans your corpus; querying never re-scans and never calls a model.
+
+## Index
+
+```bash
+ak-docs index
+ak-docs index --watch   # rebuild on doc changes
+```
+
+Outputs (defaults):
+
+| Path | Role |
+| --- | --- |
+| `.doc-bridge/index.json` | Machine index (DocBridgeIndex v1) |
+| `llms.txt` | Concise agent discovery surface |
+| `.doc-bridge/capabilities.json` | Capability map for MCP / tools |
+
+After ownership or corpus changes, **always re-index** (or gate in CI will fail).
+
+## Query ownership
+
+```bash
+ak-docs query package <id> --agent
+ak-docs query ownership <id> --agent
+ak-docs query package <id> --text      # human-readable
+```
+
+`--agent` returns validated **AgentHandoff** JSON:
+
+```json
+{
+  "startHere": "docs/for-agents/packages/auth.md",
+  "editRoots": ["packages/auth"],
+  "checks": ["pnpm test --filter auth"],
+  "humanDoc": "docs/guides/auth.md"
+}
+```
+
+Use this **before** an agent edits code. The model should not invent ownership from the full monorepo dump.
+
+## Search and ask (local)
+
+```bash
+ak-docs list packages --text
+ak-docs ask "where is authentication?"
+```
+
+`ask` stays on the deterministic plane when a known match exists. Only unresolved questions should escalate to optional backend/RAG (see [Chat and RAG](../chat-and-rag.md)).
+
+## Agent workflow
+
+```text
+resolve ownership  →  read startHere  →  edit only editRoots  →  run checks
+```
+
+1. `ak-docs query ownership <module> --agent`  
+2. Open `startHere` / `readBeforeEditing`  
+3. Edit paths under `editRoots` only  
+4. Run every command in `checks`  
+5. Promote durable learnings via memory pipeline when ready  
+
+## Related
+
+- [Install and run](./install-and-run.md)  
+- [For agents](../for-agents.md)  
+- [MCP](./mcp-agents.md)  
+- [AgentHandoff schema](../schemas/agent-handoff-v1.md)  
+- [CLI reference](../spec/cli.md)  

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

@@ -0,0 +1,84 @@
+---
+title: Install and run
+description: Install Doc Bridge, run the demo, and index your repository in minutes.
+---
+
+# Install and run
+
+Get a deterministic AgentHandoff from your own docs — no API key required for Layer 0.
+
+## Install
+
+```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
+
+```bash
+ak-docs index --watch
+ak-docs list packages --text
+ak-docs ask "where do I change auth?"
+```
+
+## Related
+
+- [Index and query](./index-and-query.md) — resolve ownership deterministically  
+- [Gate and CI](./gate-ci.md) — fail stale context in PRs  
+- [MCP for agents](./mcp-agents.md) — wire Cursor / Claude / Codex  
+- [Config reference](../spec/config-v1.md)  
+- [Examples](../examples.md)  

package/docs/guides/mcp-agents.md

@@ -0,0 +1,63 @@
+---
+title: MCP for agents
+description: Expose Doc Bridge handoffs to Cursor, Claude Desktop, and other MCP clients.
+---
+
+# MCP for agents
+
+Doc Bridge MCP tools return the **same deterministic handoffs** as the CLI — ownership, start files, edit roots, and checks.
+
+## One-command install
+
+```bash
+ak-docs mcp install --cursor    # writes .cursor/mcp.json
+ak-docs mcp install --claude    # merges Claude Desktop config (macOS)
+```
+
+Then index your repo:
+
+```bash
+ak-docs index
+```
+
+Optional skill text: [skills/doc-bridge.md](../skills/doc-bridge.md)
+
+## Manual config
+
+```json
+{
+  "mcpServers": {
+    "ak-docs": {
+      "command": "npx",
+      "args": ["ak-docs", "mcp"],
+      "cwd": "/absolute/path/to/your/repo"
+    }
+  }
+}
+```
+
+Run MCP from the **repository root** (or ensure config discovery resolves there).
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `handoff.resolve` | Package / ownership → AgentHandoff |
+| Search / list tools | Discover modules and docs without dumping the tree |
+
+Prefer `handoff.resolve` **before** any multi-file edit.
+
+## Agent loop
+
+1. Resolve ownership via MCP or `ak-docs query … --agent`  
+2. Read `startHere`  
+3. Edit only `editRoots`  
+4. Run `checks`  
+5. Re-index when docs change  
+
+## Related
+
+- [For agents](../for-agents.md)  
+- [Index and query](./index-and-query.md)  
+- [MCP deep dive](../mcp.md)  
+- [Chat and RAG](../chat-and-rag.md) — optional intelligence plane  

package/docs/guides/memory-pipeline.md

@@ -0,0 +1,105 @@
+---
+title: Memory pipeline
+description: Digest agent notes, classify them, and promote reviewable documentation drafts — never silent auto-merge.
+---
+
+# Memory pipeline
+
+Agent sessions leave durable learnings in local files. Doc Bridge **ingests**, **classifies**, and **promotes** them into draft documentation that humans review. Nothing lands in the corpus without a PR.
+
+## Sources (Layer 0)
+
+| Source | Path pattern |
+| --- | --- |
+| Agent memory notes | `.agent-memory/**/*.md` |
+| Cursor rules | `.cursor/rules/*.mdc` |
+
+No API key. Classification is deterministic.
+
+## End-to-end commands
+
+```bash
+# 1) Normalize raw notes → MemoryCandidate[]
+ak-docs memory ingest
+
+# 2) Route each candidate: agent | human | playbook | discard
+ak-docs memory classify
+
+# 3) Build a safe draft body (safety scan; never auto-merges)
+ak-docs memory promote
+
+# 4) Optional: open a GitHub draft PR via `gh`
+ak-docs memory promote --pr --dry-run
+ak-docs memory promote --pr
+```
+
+## What a candidate looks like
+
+```json
+{
+  "schemaVersion": 1,
+  "id": "auth-abort-signal",
+  "source": "agent-memory",
+  "rawPath": ".agent-memory/auth.md",
+  "fact": "Auth handlers must forward AbortSignal.",
+  "why": "Run cancellation must stop network work.",
+  "howToApply": "Use AbortSignal.any([caller, AbortSignal.timeout(ms)]).",
+  "suggestedType": "project",
+  "confidence": 0.8,
+  "references": ["docs/for-agents/auth.md"]
+}
+```
+
+Schema: [MemoryCandidate v1](../schemas/memory-candidate-v1.md)
+
+## Digest mental model
+
+```text
+.agent-memory / .cursor/rules
+        │
+        ▼
+  memory ingest     →  normalized candidates
+        │
+        ▼
+  memory classify   →  agent | human | playbook | discard
+        │
+        ▼
+  memory promote    →  draft markdown (+ optional draft PR)
+        │
+        ▼
+  Human review / merge   (never silent)
+```
+
+## Safety guarantees
+
+| Guarantee | Behavior |
+| --- | --- |
+| Draft-only | Promotion never writes the canonical corpus directly |
+| Safety scan | Risky content is flagged before draft output |
+| HITL | `--pr` opens a **draft** GitHub PR via `gh` |
+| Deterministic | Same inputs → same classify/promote routing |
+
+## MCP tools
+
+When MCP is running (`ak-docs mcp`):
+
+| Tool | Role |
+| --- | --- |
+| `memory.classify` | Classify candidates |
+| `memory.promoteDraft` | Produce a draft promotion body |
+
+See [MCP for agents](./mcp-agents.md).
+
+## Playbook feedback
+
+```bash
+ak-docs playbook draft      # payload from classified memory
+ak-docs playbook pattern    # published Doc Bridge pattern (OKF)
+```
+
+## Related
+
+- [CLI map](./cli-map.md) — every command  
+- [MemoryCandidate schema](../schemas/memory-candidate-v1.md)  
+- [Chat and RAG](../chat-and-rag.md) — optional Layer 1 after handoffs  
+- [Getting started](../getting-started.md)  

package/docs/guides/meta.json

@@ -0,0 +1,11 @@
+{
+  "title": "Guides",
+  "pages": [
+    "install-and-run",
+    "index-and-query",
+    "gate-ci",
+    "mcp-agents",
+    "memory-pipeline",
+    "cli-map"
+  ]
+}

package/docs/index.md

@@ -0,0 +1,58 @@
+---
+title: Documentation
+description: Practical Doc Bridge paths for humans, agents, PR gates, and MCP — one repository, two audiences.
+---
+
+# Documentation
+
+Doc Bridge keeps **one repository** useful to people and coding agents. Pick the shortest path:
+
+## Start
+
+| Goal | Page |
+| --- | --- |
+| Install + 60s proof | [Getting started](./getting-started.md) |
+| Guided install | [Install and run](./guides/install-and-run.md) |
+| Machine-first entry | [For agents](./for-agents.md) · site route `/for-agents` |
+| PR freshness gate | [Gate and CI](./guides/gate-ci.md) · [Marketplace](./MARKETPLACE.md) |
+
+## Build workflows
+
+| Goal | Page |
+| --- | --- |
+| Index + resolve ownership | [Index and query](./guides/index-and-query.md) · [Query](./query.md) |
+| MCP for Cursor / Claude | [MCP for agents](./guides/mcp-agents.md) · [MCP](./mcp.md) |
+| Memory digest → draft docs | [Memory pipeline](./guides/memory-pipeline.md) |
+| 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) |
+
+## How it works
+
+```text
+Repository docs
+      │
+      ▼
+ak-docs index  ──►  .doc-bridge/index.json + llms.txt
+      │
+      ├─► Human guides (Fumadocs / Docusaurus / md)
+      ├─► Agent handoff (CLI / MCP)
+      └─► PR gate (Marketplace Action)
+```
+
+1. **Index** — map ownership from corpus + config  
+2. **Resolve** — deterministic handoffs (`startHere`, `editRoots`, `checks`)  
+3. **Gate** — fail stale context before agents run  
+4. **Promote** — optional memory → draft docs loop  
+
+## Product vs reference
+
+- **Start / Guides** — get value in minutes  
+- **Product** — [Positioning](./POSITIONING.md), [Playbook pattern](./playbook/doc-bridge-pattern.md), [Recipes](./recipes/index-pipeline.md)  
+- **Reference** — [CLI](./spec/cli.md), [Config](./spec/config-v1.md), [Schemas](./schemas/agent-handoff-v1.md)  
+
+Machine surfaces: [llms.txt](/llms.txt) · [llms-full.txt](/llms-full.txt) · [raw Markdown](/raw/getting-started.md)
+
+## 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).

package/docs/landing/index.html

@@ -337,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.1.1</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>

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)
@@ -57,3 +62,12 @@ Before editing a package:
 2. Open `startHere`  
 3. Stay inside `editRoots`  
 4. Run `checks` before claiming done  
+
+## Related
+
+- [MCP for agents guide](./guides/mcp-agents.md)  
+- [CLI map](./guides/cli-map.md)  
+- [Memory pipeline](./guides/memory-pipeline.md)  
+- [For agents](./for-agents.md)  
+- [Index and query](./guides/index-and-query.md)  
+- [Skill](./skills/doc-bridge.md) 

package/docs/meta.json

@@ -0,0 +1,26 @@
+{
+  "title": "Doc Bridge",
+  "pages": [
+    "index",
+    "---Start---",
+    "getting-started",
+    "guides",
+    "for-agents",
+    "MARKETPLACE",
+    "---Build---",
+    "mcp",
+    "query",
+    "examples",
+    "chat-and-rag",
+    "ollama-demo",
+    "---Product---",
+    "POSITIONING",
+    "playbook",
+    "recipes",
+    "---Reference---",
+    "schemas",
+    "skills",
+    "spec",
+    "RELEASE"
+  ]
+}

package/docs/ollama-demo.md

@@ -1,3 +1,8 @@
+---
+title: Ollama chat demo
+description: Run the optional local chat layer with Ollama after deterministic routing.
+---
+
 # Ollama chat demo (Layer 1)
 
 Zero-cloud path for grounded `ak-docs chat` and `ak-docs ask --chat`.
@@ -61,4 +66,4 @@ Skips gracefully if Ollama is down or peers are missing (safe for CI as optional
 | `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 |
+| Slow first `rag ingest` | Normal — embeds entire corpus locally |

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

@@ -1,6 +1,8 @@
 ---
 type: pattern
 id: doc-bridge-pattern
+title: Doc Bridge pattern
+description: A reusable pattern for making documentation useful to humans and agents.
 purpose: Route coding agents to the correct package, checks, and human docs in any monorepo.
 owner: AgentsKit
 license: CC-BY-4.0
@@ -75,7 +77,7 @@ Agents call `handoff.resolve` before editing `packages/*`:
 ## CI gate
 
 ```yaml
-- uses: AgentsKit-io/doc-bridge@v1.1.1
+- uses: AgentsKit-io/doc-bridge@v1.2.1
 ```
 
 Or: `ak-docs index && ak-docs gate run` — stale index fails the PR.
@@ -111,4 +113,4 @@ Teams track handoff % and human-bridge % daily.
 - 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/
+- landing: https://doc-bridge.agentskit.io/

package/docs/query.md

@@ -0,0 +1,58 @@
+---
+title: Query
+description: Deterministic ownership and documentation lookup — no model, no re-scan of the repo.
+---
+
+# Query
+
+The query layer reads `.doc-bridge/index.json` only. It does **not** re-scan the repository and does **not** call a model.
+
+## Commands
+
+```bash
+# Machine-readable handoff (for agents / MCP)
+ak-docs query package auth --agent
+ak-docs query ownership auth --agent
+
+# Human-readable
+ak-docs query package auth --text
+
+# Discovery
+ak-docs list packages --text
+ak-docs ask "where do I change billing?"
+```
+
+## What you get
+
+An **AgentHandoff** (v1) with stable fields:
+
+| Field | Use |
+| --- | --- |
+| `startHere` | First file the agent should open |
+| `editRoots` | Allowed write paths |
+| `checks` | Verification commands |
+| `humanDoc` | Parallel human documentation |
+
+Schema: [AgentHandoff v1](./schemas/agent-handoff-v1.md) · Index: [DocBridgeIndex v1](./schemas/doc-bridge-index-v1.md)
+
+## When to use which surface
+
+| Need | Surface |
+| --- | --- |
+| Agent about to edit a module | `query … --agent` or MCP `handoff.resolve` |
+| Human browsing ownership | `query … --text` / `list packages` |
+| Free-form question with known docs | `ask "…"` (local first) |
+| Unresolved semantic question | Optional [Chat and RAG](./chat-and-rag.md) backend |
+
+## Guarantees
+
+- Same inputs → same handoff JSON (deterministic)  
+- Breaking field meaning requires a **new schema version**, not silent reinterpretation of v1  
+- Gate/CI can require a fresh index so agents never see stale ownership  
+
+## Related
+
+- [Guide: Index and query](./guides/index-and-query.md)  
+- [For agents](./for-agents.md)  
+- [CLI reference](./spec/cli.md)  
+- [MCP](./mcp.md)  

package/docs/recipes/index-pipeline.md

@@ -1,3 +1,8 @@
+---
+title: Index pipeline recipes
+description: Compose indexing, querying, gating, and CI into repeatable documentation workflows.
+---
+
 # Index pipeline recipes
 
 Keep `.doc-bridge/index.json` fresh during development and in CI.
@@ -66,7 +71,7 @@ Root `package.json`:
 ## CI (GitHub Action)
 
 ```yaml
-- uses: AgentsKit-io/doc-bridge@v1.1.1
+- uses: AgentsKit-io/doc-bridge@v1.2.1
 ```
 
 Or manual:

package/docs/schemas/agent-handoff-v1.md

@@ -1,3 +1,8 @@
+---
+title: AgentHandoff v1
+description: Machine-readable contract for a compact, actionable coding-agent handoff.
+---
+
 # AgentHandoff v1
 
 Zod schema: `AgentHandoffV1Schema` in `@agentskit/doc-bridge`.

package/docs/schemas/doc-bridge-index-v1.md

@@ -1,3 +1,8 @@
+---
+title: DocBridgeIndex v1
+description: Schema reference for the deterministic Doc Bridge repository index.
+---
+
 # DocBridgeIndex v1
 
 Zod schema: `DocBridgeIndexV1Schema` in `@agentskit/doc-bridge`.

package/docs/schemas/memory-candidate-v1.md

@@ -1,3 +1,8 @@
+---
+title: MemoryCandidate v1
+description: Contract for reviewing and promoting durable agent memory into canonical documentation.
+---
+
 # MemoryCandidate v1
 
 Zod schema: `MemoryCandidateV1Schema` in `@agentskit/doc-bridge`.

package/docs/skills/doc-bridge.md

@@ -1,3 +1,8 @@
+---
+title: Agent routing skill
+description: Give coding agents a deterministic recipe for finding ownership and checks.
+---
+
 # Doc Bridge — agent routing skill
 
 Use this skill in Cursor, Claude Code, or Codex so agents resolve ownership **before** editing packages.
@@ -61,4 +66,4 @@ Before editing any file under packages/ or apps/:
 ```bash
 ak-docs ask "auth is broken in staging"
 ak-docs doctor --text
-```
+```

package/docs/spec/cli.md

@@ -1,3 +1,8 @@
+---
+title: ak-docs CLI
+description: Complete command reference for indexing, querying, gates, doctor, memory, and MCP.
+---
+
 # ak-docs CLI
 
 Command-line interface for **`@agentskit/doc-bridge`**. The npm package is scoped; the **only published binary** is `ak-docs`.

package/docs/spec/config-v1.md

@@ -1,3 +1,8 @@
+---
+title: Configuration contract v1
+description: Configure documentation corpora, ownership routing, conformance, and gates.
+---
+
 # doc-bridge config contract v1
 
 `doc-bridge.config.ts` (or `.js`, `.mjs`, `.json`, or `package.json` → `docBridge`) is the alpha integration point for any project. Layer 0 fields are sufficient to run `index`, `query`, and MCP without an LLM.

package/docs/spec/documentation-standard-v1.md

@@ -1,3 +1,8 @@
+---
+title: Documentation Standard v1
+description: Shared quality contract for AgentsKit documentation, metadata, examples, links, and visuals.
+---
+
 # Documentation Standard v1
 
 Status: **stable — HITL-approved on 2026-07-13**

package/docs/spec/playbook-feedback.md

@@ -1,3 +1,8 @@
+---
+title: Playbook feedback promotion
+description: Promote durable implementation lessons into reviewed AgentsKit Playbook contributions.
+---
+
 # Playbook Feedback Promotion
 
 doc-bridge can feed durable documentation learnings back into public patterns, but promotion must be explicit and reviewable.

package/docs/spec/registry-agents.md

@@ -1,3 +1,8 @@
+---
+title: Registry agent topology
+description: Connect registry agent definitions to Doc Bridge ownership and documentation handoffs.
+---
+
 # Registry Agent Topology
 
 doc-bridge exposes deterministic tools; Registry agents can compose them into maintenance flows.

package/ecosystem-claims.json

@@ -12,9 +12,9 @@
       "claims": [
         {
           "id": "packages",
-          "value": 25,
+          "value": 22,
           "noun": "packages",
-          "conservativeFloor": 25,
+          "conservativeFloor": 22,
           "evidence": {
             "type": "repository-derivation",
             "repo": "AgentsKit-io/agentskit",