# AgentsKit Doc Bridge

> Deterministic human↔agent documentation handoffs, generated from the repository itself.

## Start here

- [Getting started](https://doc-bridge.agentskit.io/docs/getting-started/): Install, index, query, and gate in 60 seconds.
- [For agents](https://doc-bridge.agentskit.io/for-agents/): Resolve ownership, edit boundaries, and repository checks.
- [GitHub Marketplace](https://doc-bridge.agentskit.io/docs/MARKETPLACE/): Enforce committed documentation freshness on pull requests.
- [Positioning](https://doc-bridge.agentskit.io/docs/POSITIONING/): Product purpose, maturity, and ecosystem role.
- [MCP](https://doc-bridge.agentskit.io/docs/mcp/): Expose repository knowledge to compatible agents.
- [CLI reference](https://doc-bridge.agentskit.io/docs/spec/cli/): Complete deterministic command surface.

## Canonical documentation

- [GitHub Marketplace](https://doc-bridge.agentskit.io/raw/MARKETPLACE.md): Add the Doc Bridge freshness gate to pull requests with a reproducible composite Action.
- [doc-bridge positioning](https://doc-bridge.agentskit.io/raw/POSITIONING.md): Product purpose, boundaries, maturity, and role inside the AgentsKit ecosystem.
- [Release checklist — `@agentskit/doc-bridge`](https://doc-bridge.agentskit.io/raw/RELEASE.md): Reproducible package, documentation, and registry checks for a Doc Bridge release.
- [Chat and RAG (Layer 1)](https://doc-bridge.agentskit.io/raw/chat-and-rag.md): Add optional AgentsKit retrieval and chat after deterministic documentation resolution.
- [Examples](https://doc-bridge.agentskit.io/raw/examples.md): Ready-to-run Doc Bridge configurations and integration examples.
- [For agents](https://doc-bridge.agentskit.io/raw/for-agents.md): Resolve ownership, read compact context, and run the repository's own checks before editing.
- [Getting started](https://doc-bridge.agentskit.io/raw/getting-started.md): Install, index, query, and gate repository documentation in about 60 seconds.
- [CLI map](https://doc-bridge.agentskit.io/raw/guides/cli-map.md): Every ak-docs command with copy-paste examples — Layer 0 core and optional Layer 1 intelligence.
- [Gate and CI](https://doc-bridge.agentskit.io/raw/guides/gate-ci.md): Fail stale documentation context in pull requests with Doc Bridge gates and the Marketplace Action.
- [Index and query](https://doc-bridge.agentskit.io/raw/guides/index-and-query.md): Build a deterministic index and resolve ownership handoffs without calling a model.
- [Install and run](https://doc-bridge.agentskit.io/raw/guides/install-and-run.md): Install Doc Bridge, run the demo, and index your repository in minutes.
- [MCP for agents](https://doc-bridge.agentskit.io/raw/guides/mcp-agents.md): Expose Doc Bridge handoffs to Cursor, Claude Desktop, and other MCP clients.
- [Memory pipeline](https://doc-bridge.agentskit.io/raw/guides/memory-pipeline.md): Digest agent notes, classify them, and promote reviewable documentation drafts — never silent auto-merge.
- [Documentation](https://doc-bridge.agentskit.io/raw/index.md): Practical Doc Bridge paths for humans, agents, PR gates, and MCP — one repository, two audiences.
- [MCP setup](https://doc-bridge.agentskit.io/raw/mcp.md): Connect Doc Bridge deterministic handoffs to MCP-compatible coding agents.
- [Ollama chat demo (Layer 1)](https://doc-bridge.agentskit.io/raw/ollama-demo.md): Run the optional local chat layer with Ollama after deterministic routing.
- [Doc Bridge Pattern](https://doc-bridge.agentskit.io/raw/playbook/doc-bridge-pattern.md): A reusable pattern for making documentation useful to humans and agents.
- [Query](https://doc-bridge.agentskit.io/raw/query.md): Deterministic ownership and documentation lookup — no model, no re-scan of the repo.
- [Index pipeline recipes](https://doc-bridge.agentskit.io/raw/recipes/index-pipeline.md): Compose indexing, querying, gating, and CI into repeatable documentation workflows.
- [AgentHandoff v1](https://doc-bridge.agentskit.io/raw/schemas/agent-handoff-v1.md): Machine-readable contract for a compact, actionable coding-agent handoff.
- [DocBridgeIndex v1](https://doc-bridge.agentskit.io/raw/schemas/doc-bridge-index-v1.md): Schema reference for the deterministic Doc Bridge repository index.
- [MemoryCandidate v1](https://doc-bridge.agentskit.io/raw/schemas/memory-candidate-v1.md): Contract for reviewing and promoting durable agent memory into canonical documentation.
- [Doc Bridge — agent routing skill](https://doc-bridge.agentskit.io/raw/skills/doc-bridge.md): Give coding agents a deterministic recipe for finding ownership and checks.
- [ak-docs CLI](https://doc-bridge.agentskit.io/raw/spec/cli.md): Complete command reference for indexing, querying, gates, doctor, memory, and MCP.
- [doc-bridge config contract v1](https://doc-bridge.agentskit.io/raw/spec/config-v1.md): Configure documentation corpora, ownership routing, conformance, and gates.
- [Documentation Standard v1](https://doc-bridge.agentskit.io/raw/spec/documentation-standard-v1.md): Shared quality contract for AgentsKit documentation, metadata, examples, links, and visuals.
- [Playbook Feedback Promotion](https://doc-bridge.agentskit.io/raw/spec/playbook-feedback.md): Promote durable implementation lessons into reviewed AgentsKit Playbook contributions.
- [Registry Agent Topology](https://doc-bridge.agentskit.io/raw/spec/registry-agents.md): Connect registry agent definitions to Doc Bridge ownership and documentation handoffs.

## AgentsKit ecosystem

- [AgentsKit](https://www.agentskit.io/docs) — Build agents without gluing many libraries together. Role: `foundation`. Maturity: beta. Machine index: https://www.agentskit.io/llms.txt
- [AgentsKit Registry](https://registry.agentskit.io/docs) — Copy ready-made agents and own the source. Role: `starting-point`. Maturity: beta. Machine index: https://registry.agentskit.io/llms.txt
- [AgentsKit Chat](https://chat.agentskit.io/docs) — Define one agent experience and deliver it across interfaces. Role: `experience`. Maturity: alpha. Machine index: https://chat.agentskit.io/llms.txt
- [Agents Playbook](https://playbook.agentskit.io/docs) — Train coding agents to ship code your team would merge. Role: `discipline`. Maturity: stable. Machine index: https://playbook.agentskit.io/llms.txt
- [Doc Bridge](https://doc-bridge.agentskit.io/) **(current)** — Turn repository documentation into executable agent handoffs. Role: `understanding`. Maturity: stable. Machine index: https://doc-bridge.agentskit.io/llms.txt
- [AgentsKit Code Review](https://github.com/AgentsKit-io/code-review-cli#readme) — Run deep, low-noise review with the model already in use. Role: `verification`. Maturity: alpha. Machine index: https://raw.githubusercontent.com/AgentsKit-io/code-review-cli/main/llms.txt
- [AgentsKit OS](https://akos.agentskit.io/docs) — Run and govern agents in production. Role: `operation`. Maturity: stable. Machine index: https://akos.agentskit.io/llms.txt

## Machine surfaces

- [Full corpus](https://doc-bridge.agentskit.io/llms-full.txt)
- [Deterministic knowledge artifact](https://doc-bridge.agentskit.io/deterministic/knowledge.json)
- [Doc Bridge index schema](https://doc-bridge.agentskit.io/raw/schemas/doc-bridge-index-v1.md)


---

# Source: agent-corpus/chat.md

---
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.


---

# Source: agent-corpus/cli.md

---
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.


---

# Source: agent-corpus/conformance.md

---
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.


---

# Source: agent-corpus/doc-bridge.md

---
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`.


---

# Source: agent-corpus/doctor.md

---
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.


---

# Source: agent-corpus/gates.md

---
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.


---

# Source: agent-corpus/INDEX.md

---
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.


---

# Source: agent-corpus/mcp.md

---
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.


---

# Source: agent-corpus/memory.md

---
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.


---

# Source: agent-corpus/OVERVIEW.md

---
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.


---

# Source: agent-corpus/query.md

---
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.


---

# Source: chat-and-rag.md

---
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.

Layer 1 is **opt-in** and dogfoods public AgentsKit packages:

| Peer | Role |
|------|------|
| `@agentskit/rag` | Chunk, embed, ingest, search |
| `@agentskit/memory` | `fileVectorMemory` under `.doc-bridge/vectors` |
| `@agentskit/adapters` | Chat model + embedder (ollama, openai, …) |
| `@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.4.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.
2. RAG retrieves from the indexed agent corpus (and configured sources).
3. CI gates still decide merge truth — chat never auto-writes docs.

## Commands

```bash
ak-docs rag ingest
ak-docs rag search "<query>"
ak-docs chat
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 |
|----------|--------|
| `ollama` | Best zero-cloud path; uses `ollamaEmbedder` (e.g. `nomic-embed-text`) |
| `openai` | Chat + `text-embedding-3-small` |
| `openrouter` | Chat via OpenRouter |
| `anthropic` | Chat; embeddings currently need `OPENAI_API_KEY` or use ollama |

## Config sketch

See `examples/fumadocs-with-chat.config.ts`.

## When not to use Layer 1

- You only need routing for coding agents → Layer 0 is enough.
- You already have another RAG stack → keep Layer 0 handoffs; skip peers.


---

# Source: examples.md

---
title: Examples
description: Ready-to-run Doc Bridge configurations and integration examples.
---

# Examples

Config sketches under [`examples/`](../examples/):

| File | Profile |
|------|---------|
| `minimal-plain-markdown.config.ts` | Solo markdown, Layer 0 only |
| `pnpm-monorepo.config.ts` | Workspace discovery + ownership |
| `fumadocs-only.config.ts` | Human bridge via Fumadocs |
| `docusaurus-only.config.ts` | Human bridge via Docusaurus |
| `fumadocs-with-chat.config.ts` | Standard + intelligence (AgentsKit peers) |
| `docusaurus-with-memory.config.ts` | Assisted memory promotion path |

## Ownership without monorepo

```json
{
  "schemaVersion": 1,
  "corpus": { "agent": { "root": "docs/for-agents" } },
  "routing": {
    "options": {
      "ownership": {
        "auth": {
          "path": "src/auth",
          "purpose": "Authentication",
          "checks": ["npm test -- auth"]
        }
      }
    }
  }
}
```

Or frontmatter on an agent doc:

```md
---
package: auth
editRoot: src/auth
checks: [npm test -- auth]
---
```

## Public ecosystem surfaces

Doc Bridge is designed to be consumed by:

- https://www.agentskit.io/docs/for-agents
- https://registry.agentskit.io/
- https://playbook.agentskit.io/llms.txt
- https://chat.agentskit.io/docs
- https://doc-bridge.agentskit.io/

## Related

- [Install and run](./guides/install-and-run.md)
- [Config reference](./spec/config-v1.md)
- [Getting started](./getting-started.md)


---

# Source: for-agents.md

---
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://doc-bridge.agentskit.io/llms.txt) — concise discovery and canonical routes
- [`llms-full.txt`](https://doc-bridge.agentskit.io/llms-full.txt) — complete source corpus
- [`deterministic/knowledge.json`](https://doc-bridge.agentskit.io/deterministic/knowledge.json) — local chat/discovery artifact
- [`raw/for-agents.md`](https://doc-bridge.agentskit.io/raw/for-agents.md) — this guide as raw Markdown
- Site route: [`/for-agents`](https://doc-bridge.agentskit.io/for-agents/) — human-readable agent entry

## Related

- [MCP for agents](./guides/mcp-agents.md)
- [Index and query](./guides/index-and-query.md)
- [AgentHandoff schema](./schemas/agent-handoff-v1.md)
- [Skill text](./skills/doc-bridge.md)

If the task is conversational UI, continue with [AgentsKit Chat](https://chat.agentskit.io). For verification before merge, use [AgentsKit Code Review](https://github.com/AgentsKit-io/code-review-cli). For enterprise orchestration, governance, and audit, continue with [AKOS](https://akos.agentskit.io).


---

# Source: getting-started.md

---
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
npm i -D @agentskit/doc-bridge
# or
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`, `checks`, and optional `bridge`.

Useful follow-ups:

```bash
ak-docs list packages --text
ak-docs ask "where do I change example?"
ak-docs gate run
ak-docs mcp
```

`init --no-demo` skips the starter module if you want an empty corpus.

## Configuration

Default: `doc-bridge.config.json` (also `.ts` / `.js` / `package.json#docBridge`).

**Required:** `schemaVersion: 1` + `corpus.agent.root`.

Ownership (any one of these):

1. `routing.options.ownership`
2. Frontmatter on agent docs: `package` + `editRoot`
3. Monorepo plugin (`pnpm-monorepo` + workspace discovery)

Project root for `--config path/to/doc-bridge.config.json` is the **directory of that file**.

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
{
  "mcpServers": {
    "ak-docs": {
      "command": "ak-docs",
      "args": ["mcp"]
    }
  }
}
```

Tools: `handoff.resolve`, `doc.search`, `doc.get`, `gate.status`, …

## Human ↔ agent bridge

```bash
# After configuring corpus.human (fumadocs | docusaurus | plain-markdown)
ak-docs index
ak-docs query package <id> --agent   # includes humanDoc when linked
ak-docs gate run human-guide-links
ak-docs bootstrap agent-docs         # draft agent docs from human site
```

## Memory → project docs

```bash
ak-docs memory ingest
ak-docs memory classify
ak-docs memory promote              # prints a safe draft body
ak-docs memory promote --pr --dry-run
ak-docs memory promote --pr         # opens a GitHub draft PR via gh
```

Sources include `.agent-memory/**` and `.cursor/rules/*.mdc`. Promotion is
draft-only and never auto-merges.

## Optional chat + RAG (AgentsKit)

```bash
npm i -D @agentskit/rag @agentskit/ink @agentskit/adapters @agentskit/memory react
```

Enable in config:

```json
{
  "intelligence": {
    "enabled": true,
    "adapter": { "provider": "ollama", "model": "llama3.2" },
    "chat": { "enabled": true, "handoffFirst": true, "sources": ["agent", "human"] }
  }
}
```

```bash
ak-docs index
ak-docs rag ingest
ak-docs rag search "authentication boundaries"
ak-docs chat
ak-docs ask "how does auth work?" --chat
```

Details: [chat-and-rag.md](./chat-and-rag.md).

## Related

- [Install and run](./guides/install-and-run.md) — guided path with tables  
- [CLI map](./guides/cli-map.md) — every command with copy-paste examples  
- [Memory pipeline](./guides/memory-pipeline.md) — digest · classify · promote  
- [Index and query](./guides/index-and-query.md) · [MCP for agents](./guides/mcp-agents.md)  
- [Gate and CI](./guides/gate-ci.md) · [Marketplace](./MARKETPLACE.md)  
- [CLI reference](./spec/cli.md) · [Config](./spec/config-v1.md)  
- [Positioning](./POSITIONING.md)


---

# Source: guides/cli-map.md

---
title: CLI map
description: Every ak-docs command with copy-paste examples — Layer 0 core and optional Layer 1 intelligence.
---

# CLI map

Binary: **`ak-docs`** · Package: **`@agentskit/doc-bridge`**

Full flags: [CLI reference](../spec/cli.md)

## Global flags

```bash
ak-docs --help
ak-docs --version
ak-docs --config path/to/doc-bridge.config.json <command>
ak-docs <command> --agent    # machine JSON (handoffs)
ak-docs <command> --text     # human text
ak-docs <command> --json     # JSON where supported
```

---

## Layer 0 — no API key

### Bootstrap

```bash
ak-docs init
ak-docs init --demo
ak-docs init --no-demo
ak-docs init --scaffold-workspaces
ak-docs bootstrap agent-docs
ak-docs validate-config
ak-docs validate-handoff path/to/handoff.json
ak-docs demo --text
ak-docs demo --fixture monorepo --text
```

### Index & doctor

```bash
ak-docs index
ak-docs index --watch
ak-docs doctor --text
ak-docs doctor --badge
ak-docs doctor --write-badge
ak-docs gate run
ak-docs gate run index-freshness
ak-docs conformance run documentation-standard-v1 --text
```

### Query & search

```bash
ak-docs query package auth --agent
ak-docs query ownership auth --text
ak-docs query intent onboard --agent
ak-docs search "abort signal" --agent
ak-docs list packages --text
ak-docs list intents --text
ak-docs ask "where do I change billing?"
ak-docs retrieve "authentication boundaries"
```

### MCP

```bash
ak-docs mcp
ak-docs mcp install --cursor
ak-docs mcp install --claude
```

### Memory pipeline

```bash
ak-docs memory ingest
ak-docs memory classify
ak-docs memory promote
ak-docs memory promote --pr --dry-run
ak-docs memory promote --pr
```

Deep dive: [Memory pipeline](./memory-pipeline.md)

### Ecosystem / playbook

```bash
ak-docs registry topology
ak-docs playbook draft
ak-docs playbook pattern --text
```

---

## Layer 1 — optional AgentsKit peers

Requires `intelligence.enabled` + peers (`@agentskit/rag`, `@agentskit/ink`, …).

```bash
ak-docs rag ingest
ak-docs rag search "how does auth work?"
ak-docs chat
ak-docs ask "how does auth work?" --chat
```

Walkthrough: [Chat and RAG](../chat-and-rag.md) · [Ollama demo](../ollama-demo.md)

---

## Suggested sequences

### New repo in 2 minutes

```bash
pnpm add -D @agentskit/doc-bridge
ak-docs init
ak-docs index
ak-docs query package example --agent
ak-docs doctor --text
```

### Agent about to edit

```bash
ak-docs query ownership <id> --agent
# read startHere → edit editRoots → run checks
```

### Turn session notes into docs

```bash
ak-docs memory ingest
ak-docs memory classify
ak-docs memory promote --pr --dry-run
```

### PR gate

```bash
ak-docs index
ak-docs gate run
# commit generated index if your repo treats it as source-of-truth
```

## Related

- [Install and run](./install-and-run.md)  
- [Index and query](./index-and-query.md)  
- [MCP for agents](./mcp-agents.md)  
- [Memory pipeline](./memory-pipeline.md)  
- [CLI reference](../spec/cli.md)  


---

# Source: guides/gate-ci.md

---
title: Gate and CI
description: Fail stale documentation context in pull requests with Doc Bridge gates and the Marketplace Action.
---

# Gate and CI

Gates keep incomplete or stale documentation context from reaching coding agents.

## Local gate

```bash
ak-docs index
ak-docs gate run
ak-docs doctor --text
ak-docs doctor --badge
```

Typical failures:

| Symptom | Fix |
| --- | --- |
| Stale index | `ak-docs index`, review + commit generated files |
| Missing ownership | Add config ownership, frontmatter, or monorepo plugin |
| Documentation Standard gaps | Follow doctor remediations / evidence paths |

## Pull request workflow

```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
```

The composite Action verifies the **committed** index and configured gates — it does **not** silently rebuild and hide drift.

If the Action fails:

1. Run `ak-docs index` locally  
2. Review the diff under `.doc-bridge/` / `llms.txt`  
3. Commit intentional updates  
4. Re-run the PR check  

## What to commit

Commit generated index artifacts your repo treats as source-of-truth (common: `.doc-bridge/index.json`, root `llms.txt`). Keep CI fail-closed when those drift from the docs corpus.

## Related

- [Marketplace details](../MARKETPLACE.md)  
- [Install and run](./install-and-run.md)  
- [Documentation Standard](../spec/documentation-standard-v1.md)  
- [Doctor / CLI](../spec/cli.md)  


---

# Source: guides/index-and-query.md

---
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)  


---

# Source: guides/install-and-run.md

---
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)  


---

# Source: guides/mcp-agents.md

---
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  


---

# Source: guides/memory-pipeline.md

---
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)  


---

# Source: index.md

---
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).


---

# Source: MARKETPLACE.md

---
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.

## Related

- [Gate and CI guide](./guides/gate-ci.md)  
- [Getting started](./getting-started.md)  
- [CLI](./spec/cli.md)


---

# Source: mcp.md

---
title: MCP setup
description: Connect Doc Bridge deterministic handoffs to MCP-compatible coding agents.
---

# MCP setup

## 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
{
  "mcpServers": {
    "ak-docs": {
      "command": "npx",
      "args": ["ak-docs", "mcp"],
      "cwd": "/absolute/path/to/your/repo"
    }
  }
}
```

Or with a global/local bin:

```json
{
  "mcpServers": {
    "ak-docs": {
      "command": "ak-docs",
      "args": ["mcp"]
    }
  }
}
```

Run from the repo root (or pass config discovery that resolves to it). Always `ak-docs index` after doc changes (or gate in CI).

## Tools

| Tool | Purpose |
|------|---------|
| `handoff.resolve` | Package/ownership → AgentHandoff |
| `doc.search` | Deterministic index search |
| `doc.get` | Read an indexed agent doc |
| `gate.status` | Freshness / configured gates |
| `retriever.query` | Local retriever chunks |
| `memory.classify` / `memory.promoteDraft` | Memory pipeline |

## Agent guidance (paste into AGENTS.md)

Before editing a package:

1. Call `handoff.resolve` with the package id  
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) 


---

# Source: ollama-demo.md

---
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`.

## 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 |


---

# Source: playbook/doc-bridge-pattern.md

---
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
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.2.1
```

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://doc-bridge.agentskit.io/


---

# Source: POSITIONING.md

---
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.

## One-liner

**Human↔agent documentation bridge for any repo** — deterministic handoffs, doc-site links, memory→docs promotion, optional AgentsKit RAG/chat.

## What we are

- A **bridge** between agent corpus (dense markdown) and human corpus (Fumadocs, Docusaurus, plain md, …)
- A **task router** for coding agents (`startHere`, `editRoots`, `checks`, `humanDoc`)
- A **memory pipeline** that turns local agent memory into draft project docs (HITL)
- A **modular toolkit**: CLI, MCP, plugins, optional intelligence — install only what you need
- **Offline-capable at the core** (Layer 0 needs no API key)

## Four loops

| Loop | Job |
|------|-----|
| **Act** | Handoff JSON / MCP so agents edit the right place and run the right checks |
| **Bridge** | Keep agent docs ↔ human docs linked and gate-validated |
| **Learn** | Ingest Cursor/Claude-style memory → classify → promote drafts |
| **Explain** | Optional RAG + terminal chat (`@agentskit/rag` + `@agentskit/ink`) with `handoffFirst` |

## What we are not

- Not a replacement for your human documentation site
- Not a hosted doc chat SaaS
- Not an AgentsKit brochure in the hero
- Not “just AGENTS.md” (we *compose* with it)

## Primary persona

Engineering teams with real ownership (monorepos first). Secondary: solo libs, internal platforms, any stack with markdown.

## AgentsKit relationship (dogfood, not force)

| Public message | Reality |
|----------------|---------|
| Layer 0 works alone | Pure `@agentskit/doc-bridge` + zod |
| Optional chat/RAG | Peers: `@agentskit/rag`, `@agentskit/ink`, `@agentskit/adapters`, `@agentskit/memory` |
| Ecosystem proof | Public consumers — not private monorepos as marketing |

**Rule:** User-facing docs lead with **your repo**. AgentsKit appears as opt-in intelligence and ecosystem consumers.

### Public consumers

- [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://doc-bridge.agentskit.io/) — conversion page + used-by
- [Doc Bridge Playbook pattern](../playbook/doc-bridge-pattern.md) — `ak-docs playbook pattern`

## Comparison

| Dimension | Wiki + RAG | AGENTS.md | Context7 | doc-bridge |
|-----------|------------|-----------|----------|------------|
| Primary job | Explain | Static instructions | Library docs | **Act + bridge + memory** |
| Correctness | Best-effort | Manual | Versioned remote | Index + CI gates |
| Your monorepo ownership | Weak | Weak | N/A | **First-class** |
| LLM required | Usually | No | No for setup | **No for Layer 0** |

## Feature modularity

```
required:  index, CLI, MCP handoff tools, gate presets
optional:  fumadocs | docusaurus | plain-markdown plugins
optional:  memory ingest → promote
optional:  @agentskit/rag + ink chat (intelligence.*)
optional:  Playbook / Registry federation
```

## Success metrics

- Zero-key: `init` → `index` → `query --agent` in &lt; 2 minutes
- Handoff from ownership-only config (no monorepo plugin required)
- Human guide links gate green on fixture adapters
- Chat/RAG path documented with optional peers
- Public consumers cited (for-agents, Registry, Playbook)

## Canonical ecosystem role

| Field | Value |
|-------|--------|
| **Product id** | `doc-bridge` |
| **Role** | `understanding` |
| **Kind** | developer-tool |
| **Promise** | Human↔agent documentation bridge — deterministic handoffs for any repo |

AgentsKit is the **foundation library** (not a “JavaScript framework” in marketing cards). Chat is the **experience** layer. Doc Bridge stays the **understanding** product.


---

# Source: query.md

---
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)  


---

# Source: recipes/index-pipeline.md

---
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.

## Watch mode (local dev)

```bash
ak-docs index --watch
```

Watches `docs/for-agents/` (and human corpus dirs when configured). Rebuilds on `.md`, `.mdx`, `.json`, `.yaml` changes.

Pair with MCP in Cursor — agents always resolve against a live index.

## Pre-commit hook

`.husky/pre-commit` or `.git/hooks/pre-commit`:

```bash
#!/bin/sh
ak-docs index
ak-docs gate run index-freshness || {
  echo "doc-bridge index is stale — run: ak-docs index"
  exit 1
}
```

Or only index agent docs when they change:

```bash
#!/bin/sh
if git diff --cached --name-only | grep -Eq 'docs/for-agents/|doc-bridge\.config'; then
  ak-docs index
fi
```

## Turborepo task

`turbo.json`:

```json
{
  "tasks": {
    "ak-docs:index": {
      "inputs": ["docs/for-agents/**", "doc-bridge.config.*"],
      "outputs": [".doc-bridge/index.json", "llms.txt", ".doc-bridge/capabilities.json"]
    },
    "build": {
      "dependsOn": ["ak-docs:index"]
    }
  }
}
```

Root `package.json`:

```json
{
  "scripts": {
    "ak-docs:index": "ak-docs index",
    "ak-docs:gate": "ak-docs gate run"
  }
}
```

## CI (GitHub Action)

```yaml
- uses: AgentsKit-io/doc-bridge@v1.2.1
```

Or manual:

```yaml
- run: npm i -g @agentskit/doc-bridge && ak-docs index && ak-docs gate run
```

## Coverage badge in README

```bash
ak-docs doctor --badge
# paste markdown into README

# or persist for CI:
ak-docs doctor --write-badge
pnpm coverage:badge
```

Paste the shields.io line from `.doc-bridge/coverage-badge.json` → `markdown` field.


---

# Source: RELEASE.md

---
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: 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

Alpha versions use Changesets:

```bash
pnpm changeset          # if new entry needed
pnpm version-packages   # bumps package.json + CHANGELOG from .changeset/*
```

Current track: **`1.2.1` stable** (alpha series ended at `0.1.0-alpha.5`).

## Publish (npm + GitHub)

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
git tag v1.2.1
git push origin v1.2.1
```

For recovery of an existing immutable tag, use the guarded manual dispatch. Never move or recreate a release tag.

```bash
gh workflow run release.yml --ref master -f tag=v1.2.1
```

Confirm:

```bash
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 Pages must remain configured for GitHub Actions; `.github/workflows/pages.yml` builds and deploys the Fumadocs portal from `apps/docs`.

## Publish the GitHub Action to Marketplace

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@1.2.1
npx ak-docs init
npx ak-docs index
npx ak-docs query package example --agent
```

## Ecosystem dogfood (after npm is live)

1. **for-agents** — https://www.agentskit.io/docs/for-agents — add `doc-bridge.config` + CI gate in AgentsKit docs monorepo  
2. **Playbook** — https://playbook.agentskit.io/llms.txt — federation source already used in smoke  
3. **Registry** — https://registry.agentskit.io/ — ship `llms.txt` + link doc-bridge as onboarding companion  

## Do not claim

- Chat/RAG works without installing Layer 1 peers  
- Private monorepos as the public proof of scale  


---

# Source: schemas/agent-handoff-v1.md

---
title: AgentHandoff v1
description: Machine-readable contract for a compact, actionable coding-agent handoff.
---

# AgentHandoff v1

Zod schema: `AgentHandoffV1Schema` in `@agentskit/doc-bridge`.

Portable JSON Schema export: `AgentHandoffV1JsonSchema`.

## Shape

```json
{
  "type": "agent-handoff",
  "schemaVersion": 1,
  "source": ".doc-bridge/index.json",
  "target": { "type": "package", "id": "auth" },
  "startHere": "docs/for-agents/modules/auth.md",
  "readBeforeEditing": ["docs/for-agents/modules/auth.md", "AGENTS.md"],
  "editRoots": ["src/auth/"],
  "checks": ["npm test -- auth"],
  "humanDoc": "/docs/guides/authentication",
  "notes": ["Authentication module"]
}
```

## Legacy compatibility

Legacy `--agent` payloads may omit `schemaVersion`. Use `normalizeAgentHandoff()` or `safeParseAgentHandoff()` to upgrade.

## CLI validation

```bash
ak-docs validate-handoff ./handoff.json
```


---

# Source: schemas/doc-bridge-index-v1.md

---
title: DocBridgeIndex v1
description: Schema reference for the deterministic Doc Bridge repository index.
---

# DocBridgeIndex v1

Zod schema: `DocBridgeIndexV1Schema` in `@agentskit/doc-bridge`.

Portable JSON Schema export: `DocBridgeIndexV1JsonSchema`.

## Shape

```json
{
  "schemaVersion": 1,
  "contentHash": "df701207f5f3663d3e0a5d0e257c7ce1b8f2898ef8e1ea1fe91d5289ec74bb3c",
  "contentHashAlgo": "sha256-normalized-v1",
  "generatedAt": "2026-07-09T00:00:00.000Z",
  "project": { "name": "my-project", "root": "." },
  "knowledge": [
    {
      "id": "auth",
      "type": "agent-doc",
      "title": "Authentication",
      "path": "docs/for-agents/auth.md",
      "description": "Auth ownership and edit workflow."
    }
  ],
  "handoffs": {
    "auth": {
      "type": "agent-handoff",
      "schemaVersion": 1,
      "source": ".doc-bridge/index.json",
      "target": { "type": "package", "id": "auth", "path": "packages/auth" },
      "startHere": "docs/for-agents/auth.md",
      "readBeforeEditing": ["docs/for-agents/auth.md", "AGENTS.md"],
      "editRoots": ["packages/auth"],
      "checks": ["npm test -- auth"],
      "notes": ["Authentication package"]
    }
  },
  "lookup": {
    "packages": ["auth"],
    "ownership": {
      "auth": {
        "id": "auth",
        "path": "packages/auth",
        "checks": ["npm test -- auth"],
        "agentDoc": "docs/for-agents/auth.md"
      }
    }
  }
}
```

## Content Hash

`contentHashAlgo` is `sha256-normalized-v1`.

The hash input is deterministic JSON containing only:

- `schemaVersion`
- `knowledge`
- `handoffs`
- `lookup`

`generatedAt` is not part of the hash input. When the hash is unchanged, `ak-docs index` preserves the existing `generatedAt` so regenerated `index.json` bytes stay stable.

## Validation

```ts
import { parseDocBridgeIndex } from '@agentskit/doc-bridge'

const index = parseDocBridgeIndex(JSON.parse(raw))
```


---

# Source: schemas/memory-candidate-v1.md

---
title: MemoryCandidate v1
description: Contract for reviewing and promoting durable agent memory into canonical documentation.
---

# MemoryCandidate v1

Zod schema: `MemoryCandidateV1Schema` in `@agentskit/doc-bridge`.

Portable JSON Schema export: `MemoryCandidateV1JsonSchema`.

This is the normalized shape for memory ingestion. The core ships deterministic
local ingest for Cursor rules and `.agent-memory/**/*.md`, classification into
`agent | human | playbook | discard`, safety scanning, draft generation, and an
optional GitHub draft PR flow.

```bash
ak-docs memory ingest
ak-docs memory classify
ak-docs memory promote --pr --dry-run
```

## Shape

```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"]
}
```

## Validation

```ts
import { parseMemoryCandidate } from '@agentskit/doc-bridge'

const candidate = parseMemoryCandidate(JSON.parse(raw))
```


---

# Source: skills/doc-bridge.md

---
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.

## When to trigger

- User asks to change code under `packages/*`, `apps/*`, or any monorepo module
- Task mentions auth, billing, API, schema, or a package name
- Before creating or moving files in an unfamiliar area of the repo

## Required workflow

1. **Resolve handoff first** — call MCP tool `handoff.resolve` with the package id, or run:
   ```bash
   ak-docs query ownership <id> --agent
   ```
2. **Read `startHere`** — open the agent doc path from the handoff
3. **Edit only `editRoots`** — do not touch sibling packages
4. **Run `checks`** from the handoff before claiming done
5. **Bridge to humans** — if `bridge.humanDoc` is `missing`, tell the user and suggest `ak-docs bootstrap agent-docs`; if `humanDoc` is set, link it in your summary

## MCP setup (one-time)

```bash
ak-docs mcp install --cursor
```

Or paste into `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "ak-docs": {
      "command": "npx",
      "args": ["ak-docs", "mcp"],
      "cwd": "/absolute/path/to/repo"
    }
  }
}
```

## Cursor rule (paste into `.cursor/rules/doc-bridge.mdc`)

```markdown
---
description: Resolve doc-bridge handoff before editing packages
globs: packages/**/*
---

Before editing any file under packages/ or apps/:

1. Call MCP `handoff.resolve` for the owning package id
2. Read `startHere` from the handoff
3. Only modify paths under `editRoots`
4. Run every command in `checks` before finishing
5. If humanDoc is missing, surface `ak-docs bootstrap agent-docs` to the user
```

## Quick consult (no LLM)

```bash
ak-docs ask "auth is broken in staging"
ak-docs doctor --text
```


---

# Source: spec/cli.md

---
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`.

## Naming

| What | Name |
|------|------|
| npm package | `@agentskit/doc-bridge` |
| CLI binary | `ak-docs` |
| Config file | `doc-bridge.config.ts` |
| GitHub repo | `AgentsKit-io/doc-bridge` |

Install the package, run `ak-docs` — not `doc-bridge` on the shell.

## Why a separate binary

| Choice | Rationale |
|--------|-----------|
| **`ak-docs`**, not `agentskit docs` | Dedicated tool; no need for full `@agentskit/cli` |
| **`ak-docs`**, not an OS subcommand | OS CLIs imply sidecar / runs / pipelines |
| **`@agentskit/doc-bridge` package** | Part of AgentsKit npm scope; engine + first consumer alignment |
| **`ak-docs` bin name** | Short, memorable CLI; avoids colliding with package import path |

## Install

```bash
npm install @agentskit/doc-bridge
# or
pnpm add -D @agentskit/doc-bridge
```

```json
{
  "name": "@agentskit/doc-bridge",
  "bin": {
    "ak-docs": "./bin/ak-docs.js"
  }
}
```

## Commands (v1)

### Layer 0 — no API key

| Command | Description |
|---------|-------------|
| `ak-docs init` | Scaffold `doc-bridge.config.json` + agent INDEX stub |
| `ak-docs init --scaffold-workspaces` | Also create draft `docs/for-agents/packages/*.md` from discovered pnpm workspaces; never overwrites existing docs |
| `ak-docs bootstrap agent-docs` | Create draft `docs/for-agents/human/*.md` from configured human-doc adapters; never overwrites existing docs |
| `ak-docs validate-config` | Zod-validate config file |
| `ak-docs demo [--fixture example\|monorepo] [--text]` | Bundled 60s wow path: handoff, gate red→green, MCP snippet |
| `ak-docs doctor [--text] [--badge] [--write-badge]` | Coverage score, gaps, gates, shields.io badge |
| `ak-docs index` | Build `DocBridgeIndex` + optional `llms.txt` |
| `ak-docs index --watch` | Debounced rebuild on agent/human doc changes |
| `ak-docs query <target> [--agent] [--text]` | Resolve package/module/intent/change → handoff JSON or text |
| `ak-docs search <term> [--agent] [--text]` | Full-text search over index |
| `ak-docs ask <question>` | Human-readable local consult mode: search + best match + next handoff commands; no LLM |
| `ak-docs ask` | Interactive local REPL in a TTY; commands: `search <term>`, `read <id-or-path>`, `open <id-or-path>`, `resolve <id>`, `gate [id]`, `exit` |
| `ak-docs retrieve <query>` | Hybrid local/federated retriever chunks; deterministic local first |
| `ak-docs init --demo` / default | Scaffold demo ownership (`example`) + `AGENTS.md` snippet so `query --agent` works immediately |
| `ak-docs init --no-demo` | Config + empty INDEX only |
| `ak-docs memory ingest` | Normalize local memory files (`.agent-memory/**/*.md`, `.cursor/rules/*.mdc`) into `MemoryCandidate[]` |
| `ak-docs memory classify` | Deterministically route candidates to agent/human/playbook/discard |
| `ak-docs memory promote` | Build draft-only promotion body with safety scan; never auto-merges |
| `ak-docs memory promote --pr [--dry-run] [--force]` | Write draft + open GitHub draft PR via `gh` |
| `ak-docs registry topology` | Print the `doc-curator` topology for AgentsKit/Registry composition |
| `ak-docs playbook draft` | Build a draft Playbook feedback payload from local memory candidates |
| `ak-docs playbook pattern [--text]` | Export published Doc Bridge Playbook pattern (OKF markdown / JSON) |
| `ak-docs list <kind> [--text]` | List packages, apps, intents, … |
| `ak-docs gate run [index-freshness]` | Check generated index freshness |
| `ak-docs conformance run documentation-standard-v1 [--text\|--json]` | Run the stable ecosystem documentation profile with evidence and remediation |
| `ak-docs mcp` | Start MCP server (stdio default) |
| `ak-docs mcp install --cursor \| --claude` | Write MCP server config for Cursor or Claude Desktop |

### Layer 1 — optional AgentsKit peers (`intelligence.enabled`)

| Command | Description |
|---------|-------------|
| `ak-docs rag ingest` | Ingest agent corpus into `@agentskit/rag` + file vector store |
| `ak-docs rag search <query>` | Semantic search over ingested vectors |
| `ak-docs chat` | Interactive terminal chat (`@agentskit/ink` + retriever + adapter) |
| `ak-docs ask <question> --chat` | One-shot grounded answer (`handoffFirst` when possible) |

Peers: `@agentskit/rag`, `@agentskit/ink`, `@agentskit/adapters`, `@agentskit/memory`, `react`.

## Global flags

| Flag | Description |
|------|-------------|
| `--config <path>` | Config file (default: auto-discover) |
| `--json` / `--text` | Output format for non-agent commands (default: json); `--agent` always emits agent JSON |
| `--chat` | Request planned intelligence-backed ask mode; errors clearly until `intelligence.adapter` and RAG/chat support are configured |
| `--help` | Command help |

## Examples

```bash
ak-docs index
ak-docs query ownership auth --agent
ak-docs query ownership auth --text
ak-docs search "sidecar transport" --agent
ak-docs list packages --text
ak-docs gate run
ak-docs mcp
```

## MCP server config (Cursor)

```json
{
  "mcpServers": {
    "ak-docs": {
      "command": "ak-docs",
      "args": ["mcp"]
    }
  }
}
```

## Programmatic API

```ts
import { buildIndex, query, defineConfig } from '@agentskit/doc-bridge'

export default defineConfig({ schemaVersion: 1, corpus: { agent: { root: 'docs' } } })
```

CLI is a thin wrapper over the same exports.

`MCP_TOOLS` exports the static tool descriptors used by `tools/list`.

## Private Dogfood Alias

```bash
pnpm docs:internal:query …   # private dogfood wrapper → ak-docs query …
```

Private repo wrappers stay private. `ak-docs` is the only public binary.

## See also

- [config-v1.md](./config-v1.md)
- [POSITIONING.md](../POSITIONING.md)


---

# Source: spec/config-v1.md

---
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.

| npm package | `@agentskit/doc-bridge` |
| CLI binary | `ak-docs` |
| Config file | `doc-bridge.config.ts` |

Standalone CLI — not merged into a framework or OS CLI.

## Design rules

1. **Progressive** — only `schemaVersion` + `corpus.agent` required; everything else defaults sensibly.
2. **Plugin-shaped** — doc sites and monorepo layout are plugins, not hardcoded paths.
3. **No provider in core** — adapter config lives under `intelligence`, never required.
4. **Deterministic output** — paths in config are resolved at build time; no timestamps in index hash input.
5. **One config per repo** — monorepo root config; packages inherit via `routing` / plugin discovery.

## Discovery order

```
doc-bridge.config.ts
doc-bridge.config.mts
doc-bridge.config.js
doc-bridge.config.mjs
doc-bridge.config.json
package.json → "docBridge" field (subset, JSON only)
```

TypeScript/JavaScript configs are static in v0.1 alpha: `defineConfig` imports are supported, but arbitrary imports are not. YAML config files are planned.

## TypeScript shape (authoritative)

```ts
import type { DocBridgeConfigV1 } from '@agentskit/doc-bridge/config'

export default {
  schemaVersion: 1,

  /** Optional display name; defaults to package.json name or directory basename */
  project?: { name?: string; root?: string }

  /** Agent-readable knowledge (required) */
  corpus: {
    agent: AgentCorpusConfig
    human?: HumanCorpusConfig | HumanCorpusConfig[]
  }

  /** Where deterministic artifacts are written */
  index?: IndexConfig

  /** Ownership, intents, change routes — monorepo plugin fills this */
  routing?: RoutingConfig

  /** CI gate presets */
  gates?: GatesConfig

  /** CLI + MCP surfaces */
  surfaces?: SurfacesConfig

  /** Optional: chat, memory, retriever — any provider */
  intelligence?: IntelligenceConfig

  /** Optional: Playbook / Registry / remote OKF bundles */
  federation?: FederationConfig

  /** Optional deterministic documentation conformance profiles */
  conformance?: ConformanceConfig
} satisfies DocBridgeConfigV1
```

---

## `corpus.agent` (required)

Agent corpus = dense markdown for coding agents (OKF or for-agents layout).

```ts
type AgentCorpusConfig = {
  /** Root directory, relative to project root */
  root: string                    // e.g. 'docs/for-agents' | '.agent-docs' | 'docs'

  /** Jump table entrypoint (recommended) */
  index?: string                  // default: '{root}/INDEX.md'

  /**
   * Glob patterns under root, relative to root.
   * Default: ['**/*.md'] excluding INDEX conventions
   */
  include?: string[]
  exclude?: string[]              // default: ['**/node_modules/**', '**/.git/**']

  /** OKF frontmatter: require `type` field (soft warn vs hard gate) */
  okf?: {
    requireType?: boolean         // default: false (warn); true in strict preset
    allowedTypes?: string[]       // optional vocabulary enforcement
  }
}
```

### Minimal solo project

```ts
corpus: {
  agent: { root: 'docs' }
}
```

---

## `corpus.human` (optional)

Human wiki / doc site. **Always via plugin** — doc-bridge does not ship a site generator.

```ts
type HumanCorpusConfig = {
  plugin: HumanCorpusPluginId
  /** Plugin-specific options (see plugin docs) */
  options?: Record<string, unknown>
}

type HumanCorpusPluginId =
  | 'plain-markdown'    // docs/**/*.md, frontmatter `package`/`module`/`id`
  | 'fumadocs'          // markdown scan with index routes, (group) slugs, pages allowlists
  | 'docusaurus'        // markdown scan with id/slug frontmatter + static sidebars.js
  | 'mkdocs'            // planned
  | 'vitepress'         // planned
  | 'custom'            // path to user plugin module
```

### Bridge to agent docs

When `corpus.human` is set, plugins MUST:

1. Emit resolvable `humanDoc` URLs/paths into `AgentHandoff`
2. Support `## Human guide` link validation (gate `human-guide-links`)
3. Map by stable id (`packageId`, `moduleId`, `slug`) — config defines the join key

```ts
corpus: {
  agent: { root: 'docs/for-agents' },
  human: {
    plugin: 'fumadocs',
    options: {
      contentDir: 'apps/web/content/docs',
      urlPrefix: '/docs',           // public path prefix
      metaFile: 'meta.json',
    },
  },
}
```

Multiple human corpora (e.g. marketing + internal):

```ts
human: [
  { plugin: 'fumadocs', options: { contentDir: 'apps/web/content/docs', urlPrefix: '/docs' } },
  { plugin: 'plain-markdown', options: { root: 'docs/internal', urlPrefix: null } },
]
```

---

## `index` (optional)

```ts
type IndexConfig = {
  /** Output path for DocBridgeIndex JSON */
  outFile?: string                // default: '.doc-bridge/index.json'

  /** Optional llms.txt alongside index */
  llmsTxt?: {
    enabled?: boolean             // default: true
    outFile?: string              // default: 'llms.txt' at project root
    preamble?: string             // project-specific intro paragraph
  }

  /** Optional Self-Describe companion artifact */
  capabilities?: {
    enabled?: boolean             // default: true
    outFile?: string              // default: '.doc-bridge/capabilities.json'
  }

  /** Hash algorithm for contentHash field */
  contentHash?: 'sha256-normalized-v1'  // only algo in v1
}
```

---

## `routing` (optional — monorepo-first)

Without `routing`, handoffs are inferred from agent corpus links only. Monorepo plugin populates ownership graph.

```ts
type RoutingConfig = {
  plugin?: 'pnpm-monorepo' | 'npm-workspaces' | 'yarn-workspaces' | 'custom'

  options?: {
    /** Workspace globs; default from package manager */
    packages?: string[]           // e.g. ['packages/*', 'apps/*']

    /** Map package id → metadata (auto-discovered if omitted) */
    ownership?: Record<string, OwnershipEntry>

    /** Curated reading paths for tasks */
    intents?: IntentEntry[]

    /** "I want to change X" → start here */
    changes?: ChangeRouteEntry[]
  }
}

type OwnershipEntry = {
  path: string                    // 'packages/auth'
  group?: string                  // logical layer / team
  layer?: string                  // L0–L4 or custom
  purpose?: string                // one line
  checks?: string[]               // default gates for this owner
  agentDoc?: string               // override path; default inferred
  humanDoc?: string               // filled by human plugin join
}

type IntentEntry = {
  id: string                      // kebab-case
  title: string
  paths: string[]                 // read-before-editing list
}

type ChangeRouteEntry = {
  id: string                      // e.g. 'add-api-endpoint'
  title: string
  startHere: string
  relatedPackages?: string[]
}
```

### Join keys (agent ↔ human ↔ ownership)

| Entity | Primary key | Human plugin maps via |
|--------|-------------|------------------------|
| Package / module | `id` (folder name or `package.json` name) | frontmatter `package` or path convention |
| Screen / feature | `id` in `screens/` or `features/` | MDX slug |
| Flow / recipe | `id` in `flows/` | docs slug |

Plugins document their join convention; gates fail on orphan links.

---

## `gates` (optional)

```ts
type GatesConfig = {
  preset?: 'minimal' | 'standard' | 'strict' | 'playbook'
  /** Enabled gate ids; merged with preset */
  include?: GateId[]
  exclude?: GateId[]
  /** Gate-specific options */
  options?: {
    'human-guide-links'?: { strict?: boolean }
    'index-freshness'?: { failOnDrift?: boolean }
    'okf-type'?: { requireType?: boolean }
    'docs-style'?: {
      profile?: 'google-dev-docs' | 'playbook-okf' | 'custom'
      required?: Array<
        | 'title'
        | 'purpose'
        | 'audience'
        | 'task-orientation'
        | 'examples'
        | 'owner-source'
        | 'no-stale-wording'
      >
    }
  }
}

type GateId =
  | 'index-freshness'
  | 'human-guide-links'
  | 'link-rot'                    // reserved; emits a diagnostic and is not executed
  | 'okf-type'
  | 'docs-style'
  | 'routing-currency'            // reserved; emits a diagnostic and is not executed
  | 'bootstrap-size'              // reserved; emits a diagnostic and is not executed
  | 'documentation-standard-v1'    // opt-in ecosystem documentation profile
```

| Preset | Gates |
|--------|-------|
| `minimal` | `index-freshness` |
| `standard` | + `human-guide-links` in v0.1 alpha |
| `strict` | + `okf-type` in v0.1 alpha |

Implemented gates include `index-freshness`, `human-guide-links`, `okf-type`, `docs-style`, and the opt-in `documentation-standard-v1`. For v1 compatibility, `link-rot`, `routing-currency`, and `bootstrap-size` remain accepted as reserved IDs; including one emits `AK_DOCS_RESERVED_GATE` and does not claim that the gate ran. Unknown IDs are rejected.

### Structural vs style validation

Alpha gates are deterministic lint checks, not editorial grading:

| Gate | Kind | What it proves |
|------|------|----------------|
| `index-freshness` | structural | Generated index matches current docs/config |
| `human-guide-links` | structural | Local `humanDoc` links resolve through configured human-doc adapters |
| `okf-type` | OKF lint | Agent docs have required `type:` frontmatter when strict/required |
| `docs-style` | style lint | Opt-in deterministic profile checks for title, purpose, audience, examples, owner/source, task orientation, and stale wording |

`docs-style` supports `google-dev-docs`, `playbook-okf`, and `custom` profiles. It is not part of the default alpha path and does not grade prose quality; it checks for explicit structural signals. LLM critique remains planned optional behavior.

---

## `conformance` (optional)

Documentation Standard v1 is an opt-in, deterministic ecosystem profile. It validates
repository evidence without executing configured commands or making network/model calls.

```ts
type ConformanceConfig = {
  documentationStandardV1?: {
    rawSources?: string[]
    contributionPaths?: string[]
    metadata?: Array<{ path: string; contains: string[] }>
    links?: Array<{ url: string; paths: string[] }>
    quickstarts?: Array<{
      id: string
      doc: string
      test: string
      command: string
      testContains: string[]
    }>
    visuals?: string[]
    diagrams?: Array<{ path: string; contains: string[] }>
    ecosystemContract?: {
      manifest: string
      claims: string
      productId: string
    }
    exceptions?: Array<{
      ruleId: DocumentationStandardRuleId
      reason: string
      approvedBy: string
      trackingUrl: string
    }>
  }
}
```

See [Documentation Standard v1](documentation-standard-v1.md) for rule semantics,
report status, commands, and the recorded stable-publication HITL decision.

---

## `surfaces` (optional)

```ts
type SurfacesConfig = {
  cli?: {
    /** Published binary name (package.json bin) */
    bin?: string                    // default: 'ak-docs'
    /** Default output: json | text */
    defaultFormat?: 'json' | 'text'
  }

  mcp?: {
    enabled?: boolean               // default: true
    /** Tool ids to expose; default: core set */
    tools?: McpToolId[]
    transport?: 'stdio' | 'http'
    http?: { port?: number; path?: string }
  }
}

type McpToolId =
  | 'handoff.resolve'
  | 'doc.search'                   // deterministic index search
  | 'doc.get'
  | 'gate.status'
  | 'playbook.pattern.get'         // requires federation
```

---

## `intelligence` (optional — any provider)

Absent `intelligence` = Layer 0 only. AgentsKit is the **reference implementation** of this block.

```ts
type IntelligenceConfig = {
  /** When false, ignore all other intelligence fields */
  enabled?: boolean                 // default: false

  adapter?: {
    /** Provider id or path to custom adapter module */
    provider: 'openai' | 'anthropic' | 'ollama' | 'openrouter' | 'custom'
    model?: string
    /** Env var name for API key; never inline secrets in config */
    apiKeyEnv?: string
    baseUrl?: string
    options?: Record<string, unknown>
  }

  chat?: {
    enabled?: boolean
    /** Corpus scopes for retrieval */
    sources?: ('agent' | 'human' | 'federation')[]
    /** Prefer deterministic handoff before RAG when confidence high */
    handoffFirst?: boolean          // default: true
  }

  retriever?: {
    enabled?: boolean
    /** local | remote | bm25-only */
    mode?: 'local' | 'remote' | 'bm25'
    embedModel?: string
    chunkSize?: number
  }

  memory?: {
    enabled?: boolean
    adapters?: MemoryAdapterId[]
    ingestDir?: string              // default: '.agent-memory'
    classify?: boolean              // default: false — opt-in
    promote?: {
      enabled?: boolean
      targets?: ('agent' | 'human' | 'agents-md')[]
      requireApproval?: boolean     // default: true
    }
  }

  /** Reference runtime; custom path for non-AgentsKit engines later */
  runtime?: 'agentskit' | 'custom'
  runtimeModule?: string
}

type MemoryAdapterId =
  | 'playbook-memory'              // .agent-memory/MEMORY.md layout
  | 'cursor-rules'                 // .cursor/rules/*.mdc
  | 'session-export'               // manual JSON/md drop folder
  | 'bootstrap-delta'              // git diff on AGENTS.md
```

---

## `federation` (optional — ecosystem)

Not required for any project. Private dogfood enables this profile to validate scale; public consumers do not depend on private repos.

```ts
type FederationConfig = {
  enabled?: boolean
  sources?: FederationSource[]
}

type FederationSource = {
  id: string                        // 'playbook' | 'agentskit' | custom
  llmsTxt?: string                  // URL or local path
  rawBaseUrl?: string               // e.g. 'https://playbook.agentskit.io/raw'
  includeInRetriever?: boolean
  includeInChat?: boolean
}
```

Layer 0 exports a local retriever helper over `DocBridgeIndex`:

```ts
import { createDocBridgeRetriever } from '@agentskit/doc-bridge'

const retriever = createDocBridgeRetriever(index, { property: 'my-project' })
const chunks = retriever.retrieve('auth ownership')
```

Chunk keys are stable: `{property}:{type}:{id}`. Deterministic CLI search and exact handoff resolution stay first; semantic/RAG runtimes can inject this retriever and add federated sources later.

---

## `AgentHandoff` emission rules

When `ak-docs query <target> --agent` runs:

```ts
type AgentHandoffV1 = {
  type: 'agent-handoff'
  schemaVersion: 1
  source: string                    // index.outFile path
  target: { type: TargetType; id: string }
  startHere: string
  readBeforeEditing: string[]
  editRoots: string[]
  checks: string[]
  humanDoc?: string | null
  playbookPatterns?: string[]       // only if federation enabled
  notes: string[]
}

type TargetType =
  | 'package' | 'module' | 'app'
  | 'screen' | 'flow' | 'component'
  | 'intent' | 'change'
  | 'search'                       // --agent on search picks best match
```

**Merge precedence** (later wins):

1. Agent corpus frontmatter (`checks`, `humanDoc`)
2. `routing.ownership[id]`
3. `gates.preset` default checks
4. Global `handoff.defaults` (if set in future minor version)

---

## Example configs

### 1. Solo library (minimal)

```ts
// doc-bridge.config.ts
import { defineConfig } from '@agentskit/doc-bridge'

export default defineConfig({
  schemaVersion: 1,
  corpus: {
    agent: {
      root: 'docs',
      index: 'docs/INDEX.md',
    },
  },
})
```

### 2. pnpm monorepo + ownership

```ts
import { defineConfig } from '@agentskit/doc-bridge'

export default defineConfig({
  schemaVersion: 1,
  corpus: {
    agent: { root: 'docs/for-agents' },
  },
  routing: {
    plugin: 'pnpm-monorepo',
    options: {
      packages: ['packages/*', 'apps/*'],
    },
  },
  gates: { preset: 'standard' },
})
```

### 3. Monorepo + Fumadocs (standard profile)

```ts
import { defineConfig } from '@agentskit/doc-bridge'

export default defineConfig({
  schemaVersion: 1,
  corpus: {
    agent: { root: 'docs/for-agents' },
    human: {
      plugin: 'fumadocs',
      options: {
        contentDir: 'apps/web/content/docs',
        urlPrefix: '/docs',
      },
    },
  },
  routing: { plugin: 'pnpm-monorepo' },
  gates: { preset: 'standard' },
  intelligence: {
    enabled: true,
    adapter: { provider: 'ollama', model: 'llama3', apiKeyEnv: '' },
    chat: { enabled: true, handoffFirst: true },
  },
})
```

### 4. Docusaurus + optional memory

```ts
import { defineConfig } from '@agentskit/doc-bridge'

export default defineConfig({
  schemaVersion: 1,
  corpus: {
    agent: { root: '.agent-docs' },
    human: {
      plugin: 'docusaurus',
      options: {
        docsDir: 'website/docs',
        sidebarsFile: 'website/sidebars.js',
        urlPrefix: '/docs',
      },
    },
  },
  intelligence: {
    enabled: true,
    adapter: { provider: 'openrouter', model: 'openai/gpt-4o-mini', apiKeyEnv: 'OPENROUTER_API_KEY' },
    chat: { enabled: true, sources: ['agent', 'human'] },
    memory: {
      enabled: true,
      adapters: ['cursor-rules', 'playbook-memory'],
      classify: true,
      promote: { enabled: true, requireApproval: true },
    },
  },
})
```

### 5. JSON config (no TypeScript)

```json
{
  "schemaVersion": 1,
  "corpus": {
    "agent": { "root": "docs/for-agents" }
  },
  "routing": {
    "plugin": "npm-workspaces"
  },
  "gates": { "preset": "minimal" }
}
```

---

## CLI mapping

| Command | Config sections used |
|---------|---------------------|
| `ak-docs init` | scaffolds minimal `corpus.agent` + optional plugin prompt |
| `ak-docs index` | `corpus`, `routing`, `index`, plugins |
| `ak-docs query <t> --agent` | `index` + `routing` + handoff merge |
| `ak-docs search <q>` | `index` |
| `ak-docs retrieve <q>` | `index` + `federation` |
| `ak-docs gate run` | `gates` |
| `ak-docs conformance run documentation-standard-v1` | `corpus`, `routing`, `index`, `conformance` |
| `ak-docs mcp` | `surfaces.mcp` |
| `ak-docs chat` | planned; `intelligence.*` |
| `ak-docs memory ingest` | deterministic local ingest; `MemoryCandidate[]` |
| `ak-docs memory classify` | deterministic route classifier |
| `ak-docs memory promote` | draft promotion + safety scan |
| `ak-docs registry topology` | doc-curator topology |
| `ak-docs playbook draft` | draft Playbook feedback payload |

---

## Validation

- Config validated with **Zod** at CLI startup (`ak-docs validate-config`).
- Unknown `schemaVersion` → hard error with migration link.
- Unknown plugin id → hard error listing built-in + `custom` path.
- `intelligence.enabled: true` without `adapter` → warn + chat/memory subcommands disabled.

---

## Versioning

| Version | Scope |
|---------|-------|
| **v1** | This document. Additive fields only in v1.x. |
| **v2** | Breaking changes require `schemaVersion: 2` + codemod. |

---

## See also

- [POSITIONING.md](../POSITIONING.md)
- [AgentHandoff v1](../schemas/agent-handoff-v1.md)
- [DocBridgeIndex v1](../schemas/doc-bridge-index-v1.md)
- [MemoryCandidate v1](../schemas/memory-candidate-v1.md)


---

# Source: spec/documentation-standard-v1.md

---
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**

Profile ID: `documentation-standard-v1`

Schema version: `1`

Documentation Standard v1 is a deterministic Doc Bridge conformance profile for
documentation properties in the AgentsKit ecosystem. It turns the shared quality
expectations into local evidence that humans, CI, and agents can inspect without a model,
API key, or network request.

```mermaid
flowchart LR
  A[Human docs] --> P[Documentation Standard v1]
  L[llms.txt and raw sources] --> P
  H[AgentHandoff index] --> P
  C[Contribution and metadata] --> P
  Q[Quickstart test evidence] --> P
  P --> R[Versioned conformance report]
  R --> CI[CI exit code]
  R --> HITL[Human approval]
```

## Rule set

| Rule | Level | Passing evidence |
|---|---|---|
| `human-docs` | Required | A configured human adapter discovers at least one non-agent document |
| `llms-and-raw-source` | Required | `llms.txt` exactly matches the current deterministic Doc Bridge output and every declared raw source is non-empty |
| `agent-handoffs` | Required | Every emitted handoff has `startHere`, edit roots, checks, and a linked/external human bridge |
| `contribution` | Required | At least one declared contribution guide exists and is non-empty |
| `metadata` | Required | Declared metadata files exist and contain every configured marker |
| `cross-links` | Required | Vendored canonical manifest/claims snapshots agree, include this product, and every declared URL is canonical and occurs in source |
| `tested-quickstarts` | Required | Each quickstart maps a doc to a test file, identifying test markers, and a CI command |
| `visual-explanations` | Recommended | Every declared image or animation asset exists |
| `structured-diagrams` | Recommended | Declared diagram source exists and contains its configured marker |

Recommended failures remain visible but do not fail the command. Required failures return
exit code 1 unless an approved exception applies.

## Approved exceptions

Exceptions are explicit audit records, not hidden exclusions. A valid exception requires
the rule ID, a substantive reason, the approver, and a tracking URL:

```json
{
  "ruleId": "structured-diagrams",
  "reason": "The interactive visual already expresses this relationship more clearly.",
  "approvedBy": "Documentation Working Group",
  "trackingUrl": "https://github.com/AgentsKit-io/example/issues/123"
}
```

The report uses status `excepted`; it never rewrites an exception as an ordinary pass.

## Configuration

```json
{
  "conformance": {
    "documentationStandardV1": {
      "rawSources": ["README.md", "docs/getting-started.md"],
      "contributionPaths": ["CONTRIBUTING.md"],
      "metadata": [
        { "path": "docs/index.html", "contains": ["<title>", "name=\"description\""] }
      ],
      "links": [
        { "url": "https://www.agentskit.io", "paths": ["README.md"] }
      ],
      "ecosystemContract": {
        "manifest": "ecosystem.json",
        "claims": "ecosystem-claims.json",
        "productId": "example"
      },
      "quickstarts": [
        {
          "id": "demo",
          "doc": "README.md",
          "test": "tests/demo.test.ts",
          "command": "pnpm vitest run tests/demo.test.ts",
          "testContains": ["runs the demo"]
        }
      ],
      "visuals": ["docs/assets/overview.webp"],
      "diagrams": [
        { "path": "docs/architecture.md", "contains": ["```mermaid"] }
      ],
      "exceptions": []
    }
  }
}
```

The profile does not execute the declared quickstart command. The test-evidence file and
identifying markers prove that the quickstart has a repository test; the normal CI suite
executes that test. This avoids turning documentation configuration into an arbitrary
command-execution surface.

The ecosystem contract files are committed, network-free consumer snapshots of the canonical
AgentsKit `ecosystem.json` v2 manifest and `ecosystem-claims.json` ledger. The gate verifies
their schema relationship, product identity parity, the adopting product ID, and that declared
cross-links occur both in the manifest's public surfaces and in repository documentation.
Doc Bridge also records the upstream ref and SHA-256 digests in `ecosystem-upstream.json`;
`pnpm check:ecosystem-upstream` compares the local snapshots with AgentsKit `main` in CI.
This network parity check is deliberately separate from the runtime conformance profile, which
remains deterministic and offline.

## Run the profile

```bash
ak-docs conformance run documentation-standard-v1 --text
ak-docs conformance run documentation-standard-v1 --json
ak-docs gate run documentation-standard-v1
```

JSON output is the stable automation surface. Text output sends the same evidence in a
human-scannable form. Both return 0 when required rules pass or are explicitly excepted,
and 1 when a required rule fails.

## Adoption and stability

The Doc Bridge repository is the first real fixture and dogfoods the profile in its normal
`ak-docs gate run`. Other ecosystem repositories adopt it in their documentation slices.
The required/recommended rule split received product-owner HITL approval in
[issue #27](https://github.com/AgentsKit-io/doc-bridge/issues/27), and the canonical ecosystem
contract was delivered by
[AgentsKit #1208](https://github.com/AgentsKit-io/agentskit/pull/1208). The profile is stable;
future breaking rule changes require a new version.


---

# Source: spec/playbook-feedback.md

---
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.

## Finding Template

```md
---
type: Playbook Finding
source: doc-bridge
visibility: public-candidate
license: CC-BY-4.0
---

# Finding title

## Context

What happened, where it was observed, and why it matters.

## Evidence

Links to public docs, issue numbers, or redacted local references.

## Proposed Playbook Change

The smallest pattern, checklist, or raw doc update that should be drafted.

## Safety Review

- [ ] No secrets
- [ ] No private customer names
- [ ] No private repository paths
- [ ] Attribution preserved
```

## Promotion Pipeline

```yaml
id: playbook-feedback-promotion
version: 1
trigger:
  manual: true
  schedule: weekly
  onContentHashDrift: optional
steps:
  - id: collect
    reads:
      - ".agent-memory/**/*.md"
      - "docs/for-agents/**/*.md"
  - id: scan
    checks:
      - secrets
      - pii
      - private-paths
  - id: draft
    delegate: knowledge-promoter
    output: draft-pr
  - id: verify
    checks:
      - attribution-cc-by-4
      - doc-bridge-gates
  - id: review
    requiresHuman: true
mergePolicy:
  autoMerge: false
```

## Doc Bridge Pattern (published)

Full pattern: [`docs/playbook/doc-bridge-pattern.md`](../playbook/doc-bridge-pattern.md)

Export for Playbook PR:

```bash
ak-docs playbook pattern --text > doc-bridge-pattern.md
```

The pattern describes the trilogy:

- `AgentHandoff`: precise editing route for coding agents.
- OKF docs: knowledge files that can be linted and indexed.
- Self-describe artifacts: `llms.txt`, `capabilities.json`, and content hashes for discovery.

Memory-sourced findings still use `ak-docs memory promote --pr` — human review owns merge, licensing, and final wording.


---

# Source: spec/registry-agents.md

---
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.

## `doc-curator`

Supervisor flow:

```yaml
id: doc-curator
version: 1
description: Classify documentation changes, draft updates, and verify gates.
inputs:
  diff:
    type: string
  projectRoot:
    type: string
tools:
  - doc-bridge.mcp.handoff.resolve
  - doc-bridge.mcp.doc.search
  - doc-bridge.mcp.doc.get
  - doc-bridge.mcp.gate.status
delegates:
  docsChat:
    agent: docs-chat
    purpose: Answer grounded questions using deterministic search first.
  knowledgePromoter:
    agent: knowledge-promoter
    purpose: Convert accepted findings into draft documentation changes.
  codeReview:
    agent: code-review
    purpose: Review doc-only diffs before human merge.
steps:
  - id: classify
    delegate: docsChat
    input:
      question: "Which docs and owners are affected by this diff?"
  - id: draft
    delegate: knowledgePromoter
    input:
      finding: "${classify.output}"
      mode: draft-pr
  - id: verify
    tool: doc-bridge.mcp.gate.status
    input:
      gates:
        - index-freshness
        - human-guide-links
        - okf-type
  - id: review
    delegate: codeReview
    input:
      diff: "${draft.diff}"
mergePolicy:
  autoMerge: false
  requiresHuman: true
```

## Runtime Notes

- The MCP server is local: `ak-docs mcp`.
- The flow must not require a private repository shape.
- `knowledge-promoter` may draft PR content, but must never merge.
- `code-review` runs after gates so reviewers see deterministic failures first.
- Future RAG mode should inject `createDocBridgeRetriever(index)` and keep exact handoff resolution ahead of semantic results.