{
  "markdown": "# doc-bridge\n\n[![npm](https://img.shields.io/npm/v/@agentskit/doc-bridge?style=flat-square)](https://www.npmjs.com/package/@agentskit/doc-bridge)\n[![CI](https://img.shields.io/github/actions/workflow/status/AgentsKit-io/doc-bridge/ci.yml?branch=master&style=flat-square)](https://github.com/AgentsKit-io/doc-bridge/actions/workflows/ci.yml)\n[![Pages](https://img.shields.io/github/actions/workflow/status/AgentsKit-io/doc-bridge/pages.yml?branch=master&label=pages&style=flat-square)](https://doc-bridge.agentskit.io/)\n[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13872/baseline)](https://www.bestpractices.dev/projects/13872)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)\n[![Node](https://img.shields.io/badge/node-%3E%3D22-339933?style=flat-square)](package.json)\n[![TypeScript](https://img.shields.io/badge/types-TypeScript-3178c6?style=flat-square)](dist/index.d.ts)\n\n**npm:** [`@agentskit/doc-bridge`](https://www.npmjs.com/package/@agentskit/doc-bridge) · **CLI:** `ak-docs` · **Landing:** [agentskit-io.github.io/doc-bridge](https://doc-bridge.agentskit.io/)\n\n**Topics:** `ai-agents` · `documentation` · `developer-experience` · `mcp` · `llms-txt` · `typescript`\n\n**Compatibility:** node >=22 · TypeScript 5.8+ · pnpm, npm, or yarn consumers\n\n**Turn your docs into executable handoffs for coding agents.**\n\ndoc-bridge reads your repo docs, ownership map, and human documentation site, then gives humans and agents the same evidence-linked starting point:\n\n- where to start reading\n- which files/packages it may edit\n- which checks prove the change\n- which human docs explain the feature\n\nIt is not a wiki or hosted RAG. The core works **without any LLM or API key**; the documentation portal dogfoods AgentsKit Chat as an optional surface over that deterministic layer.\n\n![doc-bridge maps human docs into structured agent handoffs](docs/landing/assets/doc-bridge-hero.webp)\n\n## Built for agent-scale repositories\n\nDoc Bridge turns large repository structure and documentation into compact, evidence-linked context that humans and coding agents can query instead of repeatedly traversing the full repository.\n\n### Up to 99% less context payload\n\nThis is an estimated reduction in serialized context payload for one historical benchmark—not a guarantee of token savings or answer quality. It is not the same measure as provider-token usage below.\n\n![Estimated context payload reduction](docs/landing/assets/context-payload-reduction.svg)\n\n### Controlled A/B signal\n\nIn a controlled study with 96 anonymized executions, the deterministic Doc Bridge workflow showed a directional operational signal of:\n\n- **2.29% fewer paired provider tokens**;\n- **3.15 seconds lower P95 latency**;\n- **83.3% operationally completed executions vs. 79.2%** with repository-only context.\n\nThese are different measures: the 99% figure is an estimated context-payload reduction from anonymized dogfooding, while the 2.29% figure uses provider-token data from 47 paired observations in the controlled run. Neither result establishes semantic correctness or enterprise readiness. See the [full methodology and anonymized data](docs/study/README.md).\n\n## Why teams use it\n\nAgents are powerful, but most repo docs are written for humans. The result is familiar: the agent guesses ownership, edits the sibling package, runs the wrong test, or ignores the human guide that already explained the rule.\n\ndoc-bridge works in both directions:\n\n![doc-bridge connects human docs to coding agents and agent memory back to draft docs](docs/landing/assets/doc-bridge-two-way.webp)\n\n| Direction | What it does | Command |\n|-----------|--------------|---------|\n| **Human docs → agents** | Turns Fumadocs, Docusaurus, markdown, and ownership docs into `AgentHandoff` | `ak-docs index` · `ak-docs query --agent` |\n| **Agent memory → docs** | Reads `.agent-memory/**` and `.cursor/rules/*.mdc`, classifies what should become project docs, and drafts a human-reviewed promotion | `ak-docs memory ingest` · `classify` · `promote --pr` |\n\nThe handoff is a routing contract:\n\n```json\n{\n  \"startHere\": \"docs/for-agents/packages/auth.md\",\n  \"editRoots\": [\"packages/auth\"],\n  \"checks\": [\"pnpm --filter @demo/auth test\"],\n  \"humanDoc\": \"/docs/guides/auth\"\n}\n```\n\nWorkflow runs may carry the same optional `correlation` envelope used by the\nAgentsKit runtime and Chat protocol. `operationId` is the cross-repository\nidentity; `runId`, `sessionId`, `turnId`, `actionId`, and `traceId` retain local\nmeaning. It is bounded metadata only and must not contain prompts, secrets, or\ndocument content.\n\nThat contract works from the terminal, MCP, CI, and optional RAG/chat.\n\n## Documentation quality and reconciliation\n\nDiscovery is only the first step. `ak-docs audit documentation` compares declared documentation and ownership with the observed project graph and reports evidence-backed findings for missing coverage, stale relations, structured contradictions, exact duplicates, missing examples, and incomplete maintenance metadata.\n\nNatural-language correctness, unnecessary prose, and semantic redundancy remain explicitly `not-analyzed` until a configured agent or human review evaluates them. Proposed changes stay reviewable and human-approved.\n\n```text\nExample finding (anonymized)\n  CONTRADICTION · high confidence\n  Documentation declaration differs from the observed project relation\n  Evidence: 4 source files + 1 documentation declaration\n  Action: review ownership and update the canonical document\n```\n\n## 60-second proof\n\n```bash\nnpm i -D @agentskit/doc-bridge\nnpx ak-docs demo --text\n```\n\nNo config, no docs to read first. Output shows before/after, a real handoff, gate red→green, and the MCP snippet:\n\n```\nAfter (handoff.resolve / query --agent)\n  ✓ target:  auth (packages/auth)\n  ✓ start:   docs/for-agents/packages/auth.md\n  ✓ edit:    packages/auth\n  ✓ checks:  pnpm --filter @demo/auth test · pnpm --filter @demo/auth lint\n  ✓ human guide: /docs/guides/auth\n\nGate: red → green\n```\n\nMonorepo fixture with auth + billing:\n\n```bash\nnpx ak-docs demo --fixture monorepo --text\n```\n\n### Verify the real handoff path\n\nThis checked example runs the bundled demo through the public CLI. The README gate compares this block byte-for-byte with the executable fixture and runs it on every PR.\n\n<!-- readme-command:verify-handoff -->\n<!-- readme-example:verify-handoff -->\n```js\nimport { execFileSync } from 'node:child_process'\n\nexecFileSync(process.execPath, ['bin/ak-docs.js', 'demo', '--text'], {\n  stdio: 'inherit',\n})\n```\n\n```bash\nnode examples/verify-handoff.mjs\n```\n\nFull setup in your repo:\n\n```bash\nnpx ak-docs init\nnpx ak-docs index\nnpx ak-docs query package example --agent\nak-docs mcp install --cursor   # wires MCP into .cursor/mcp.json\n```\n\nUsing Cline? Follow the deterministic [`llms-install.md`](llms-install.md) setup. It runs the pinned MCP server through `pnpm dlx` without adding Doc Bridge to your repository dependencies.\n\n## What ships\n\nSee the [surface map](docs/landing/assets/doc-bridge-surfaces.webp) for a visual overview of the CLI, MCP, CI, and adapter surfaces.\n\n| Surface | Use it for | Command / artifact |\n|---------|------------|--------------------|\n| **CLI** | Inspect ownership, search docs, run gates, ask local questions | `ak-docs query`, `search`, `ask`, `doctor`, `gate` |\n| **MCP server** | Let Cursor, Claude Code, Codex-style agents resolve handoffs before editing | `ak-docs mcp`, `handoff.resolve` |\n| **GitHub Action / CI** | Fail stale indexes and broken human-doc links on PRs | `AgentsKit-io/doc-bridge@ee756a13c006c597445c31e2643c1e8cece715d7` |\n| **Documentation conformance** | Check the stable ecosystem standard with auditable evidence | `ak-docs conformance run documentation-standard-v1 --text` |\n| **Documentation audit** | Measure documentation quality and compare docs with the observed project graph | `ak-docs audit documentation --json` |\n| **Doc adapters** | Link human docs to agent docs | `fumadocs`, `docusaurus`, `vitepress`, `starlight`, `nextra`, `plain-markdown` |\n| **Monorepo routing** | Discover workspaces and checks | `pnpm-monorepo`, `nx` |\n| **Memory pipeline** | Turn agent notes into reviewable documentation drafts | `memory ingest`, `classify`, `promote --pr` |\n| **Optional RAG/chat** | Ground chat in the same handoff-first index | `@agentskit/rag`, `@agentskit/ink`, `ak-docs chat` |\n\nSee [docs/getting-started.md](docs/getting-started.md), [docs/mcp.md](docs/mcp.md), and [docs/examples.md](docs/examples.md).\n\n### Cursor plugin\n\nThis repository also contains a Cursor plugin that pairs the read-only Doc Bridge MCP server with a handoff skill. It resolves `startHere`, `readBeforeEditing`, `editRoots`, and `checks` before Cursor edits a routed repository. The plugin does not request credentials or write project files through MCP.\n\n### GitHub Copilot plugin\n\nThe root Agent Plugins manifest exposes the same portable handoff skill and read-only MCP server to GitHub Copilot CLI. Copilot discovers `skills/` and `.mcp.json` from the standard plugin layout, so the integration stays source-owned instead of copying prompts into another repository.\n\n```bash\ncopilot plugin install AgentsKit-io/doc-bridge\n```\n\n### Portable Agent Skill\n\n[`skills/doc-bridge-handoff`](skills/doc-bridge-handoff) packages the same fail-closed routing contract in the open Agent Skills layout for OpenClaw-compatible clients, Hermes Agent, Pi, Cursor, and other runtimes that can execute a local skill script. The skill prefers the read-only MCP tool and falls back to a pinned, zero-credential CLI resolver. It never edits files, runs returned checks, or grants authority outside `editRoots`.\n\nInstall the published skill from [ClawHub](https://clawhub.ai/emersonbraun/skills/doc-bridge-handoff):\n\n```bash\nclawhub install doc-bridge-handoff\n```\n\nPi users can install the same source-owned skill through the npm package:\n\n```bash\npi install npm:@agentskit/doc-bridge\n```\n\n## Claude Desktop MCP Bundle\n\nDoc Bridge can be packaged as a local MCP Bundle for Claude Desktop. The bundle keeps the eight MCP tools read-only and asks the user to select the repository's `doc-bridge.config.json`; that file defines the project boundary Doc Bridge may read.\n\nFrom a clean checkout:\n\n```bash\npnpm install --frozen-lockfile\npnpm mcpb:pack\n```\n\nThe command builds Doc Bridge, creates a production-only staging directory, validates the MCPB manifest, packs the extension, checks its file inventory, and writes the local artifact under `.mcpb-output/`. Generated bundles and staging directories are intentionally excluded from Git.\n\nCurrent packaged compatibility is macOS. Other operating systems will be declared only after the exact bundle passes an independent installation test there.\n\n## Why this exists\n\n| Pattern | Gap |\n|---------|-----|\n| Wiki + RAG | Explains; weak on *where to act* and proof docs match code |\n| AGENTS.md alone | Great static rules; no ownership index, gates, or human bridge |\n| Context7-class tools | Library docs for the model; not *your* monorepo routing |\n\ndoc-bridge ships **AgentHandoff** JSON:\n\n```json\n{\n  \"type\": \"agent-handoff\",\n  \"startHere\": \"docs/for-agents/packages/auth.md\",\n  \"editRoots\": [\"packages/auth\"],\n  \"checks\": [\"pnpm --filter @demo/auth test\"],\n  \"humanDoc\": \"/docs/guides/auth\",\n  \"bridge\": { \"humanDoc\": \"linked\" }\n}\n```\n\nWhen a human guide is missing, handoffs surface it as a feature:\n\n```json\n{\n  \"bridge\": {\n    \"humanDoc\": \"missing\",\n    \"action\": \"ak-docs bootstrap agent-docs\"\n  },\n  \"notes\": [\"Human guide missing for billing. Run: ak-docs bootstrap agent-docs\"]\n}\n```\n\n## Four loops (with real commands)\n\n| Loop | Command | What you see |\n|------|---------|--------------|\n| **Act** | `ak-docs query package auth --agent` | `editRoots`, `checks`, `startHere` |\n| **Bridge** | `ak-docs bootstrap agent-docs` | Draft agent docs from human site; `bridge.humanDoc` in handoff |\n| **Learn** | `ak-docs memory classify` → `promote` | HITL draft for agent corpus |\n| **Explain** | `ak-docs ask \"auth is broken in staging\"` | Ownership match + handoff preview + next commands |\n\n```bash\nak-docs ask \"who owns schemas\"\n# Best match: ownership os-core\n# Handoff preview\n#   start:  docs/for-agents/packages/os-core.md\n#   edit:   packages/os-core\n#   checks: pnpm --filter os-core lint · pnpm --filter os-core test\n```\n\n## Coverage your team checks daily\n\n```bash\nak-docs doctor --text\nak-docs doctor --badge          # shields.io markdown for README\nak-docs index --watch           # keep index fresh while editing docs\n```\n\n```\nScore: 82/100 (B)\n  Agent docs:      8/10 (80% handoff-ready)\n  Human guides:    6/10 (60% bridged)\n  Gates:           3/3 passing\n\nNext actions\n  → ak-docs bootstrap agent-docs\n  → ak-docs query package billing --agent\n```\n\n## Agent uses it alone\n\n1. **MCP auto-wire:** `ak-docs mcp install --cursor`\n2. **Skill/rule:** paste [docs/skills/doc-bridge.md](docs/skills/doc-bridge.md) into Cursor rules — agents call `handoff.resolve` before editing `packages/*`\n3. **Handoff is the next step:** `startHere`, `checks`, and `bridge` are in the JSON/MCP response\n\n## CI as first-class citizen\n\nReuse the bundled GitHub Action on every PR:\n\n```yaml\npermissions:\n  contents: read\n\nsteps:\n  - uses: actions/checkout@v4\n  - uses: AgentsKit-io/doc-bridge@ee756a13c006c597445c31e2643c1e8cece715d7 # v1.7.45\n    with:\n      config-path: doc-bridge.config.json\n```\n\nThe Action checks the committed index before changing anything, pins the matching npm package, and rejects non-exact package versions. See the [Marketplace guide](docs/MARKETPLACE.md).\n\n![handoff coverage](https://img.shields.io/badge/handoff_coverage-100%25-2ea44f?style=flat-square) ![human bridge](https://img.shields.io/badge/human_bridge-0%25-cb2431?style=flat-square)\n\nRun `ak-docs doctor --badge` locally to refresh — or `pnpm coverage:badge` in CI.\n\nOr locally:\n\n```bash\nak-docs index && ak-docs gate run\n```\n\nGate fails with `Index is stale. Run: ak-docs index` — same check in CI annotations.\n\n## Product surface\n\n### Core — always (no LLM)\n\n| Surface | Purpose |\n|---------|---------|\n| **Demo** | `ak-docs demo` — bundled fixture, no setup |\n| **Doctor** | Coverage score, missing humanDoc/agent doc, next actions |\n| **Index** | `DocBridgeIndex` + `contentHash` + `llms.txt` + capabilities |\n| **CLI** | `query` / `search` / `list` / `ask` / `gate` / `memory` / `bootstrap` |\n| **MCP** | `handoff.resolve`, `doc.search`, `doc.get`, `gate.status`, … |\n| **Gates** | Freshness, human-link validation, optional OKF style |\n| **Adapters** | `pnpm-monorepo`, `nx`, `fumadocs`, `docusaurus`, `vitepress`, `starlight`, `nextra`, `plain-markdown` |\n\n### Optional AgentsKit peers\n\n```bash\nnpm i -D @agentskit/rag @agentskit/ink @agentskit/adapters @agentskit/memory react\nak-docs rag ingest && ak-docs chat\n```\n\nSee **[docs/chat-and-rag.md](docs/chat-and-rag.md)**.\n\n## AgentsKit ecosystem\n\n### Who uses it (public)\n\nDesigned for and dogfooded on open AgentsKit surfaces:\n\n| Surface | Link |\n|---------|------|\n| **for-agents** | [agentskit.io/docs/for-agents](https://www.agentskit.io/docs/for-agents) |\n| **Registry** | [registry.agentskit.io](https://registry.agentskit.io/) |\n| **Playbook** | [playbook.agentskit.io](https://playbook.agentskit.io/llms.txt) |\n| **AgentsKit Chat** | [documentation](https://chat.agentskit.io) · [source](https://github.com/AgentsKit-io/agentskit-chat) |\n| **Code Review** | [repository-native CLI](https://github.com/AgentsKit-io/code-review-cli) |\n| **This repo** | CI green · `ak-docs gate run` on every PR |\n\n**Playbook pattern:** [`docs/playbook/doc-bridge-pattern.md`](docs/playbook/doc-bridge-pattern.md) — export with `ak-docs playbook pattern --text`\n\n## Configuration examples\n\n| Profile | Example |\n|---------|---------|\n| Solo markdown | [`examples/minimal-plain-markdown.config.ts`](examples/minimal-plain-markdown.config.ts) |\n| pnpm monorepo | [`examples/pnpm-monorepo.config.ts`](examples/pnpm-monorepo.config.ts) |\n| Nx monorepo | [`examples/nx-monorepo.config.ts`](examples/nx-monorepo.config.ts) |\n| Demo monorepo | [`examples/demo-monorepo/`](examples/demo-monorepo/) |\n| Fumadocs + chat | [`examples/fumadocs-with-chat.config.ts`](examples/fumadocs-with-chat.config.ts) |\n| VitePress | [`examples/vitepress-only.config.ts`](examples/vitepress-only.config.ts) |\n| Astro Starlight | [`examples/starlight-only.config.ts`](examples/starlight-only.config.ts) |\n| Nextra | [`examples/nextra-only.config.ts`](examples/nextra-only.config.ts) |\n\nContract: [`docs/spec/config-v1.md`](docs/spec/config-v1.md) · CLI: [`docs/spec/cli.md`](docs/spec/cli.md) · MCP: [`docs/mcp.md`](docs/mcp.md) · Skill: [`docs/skills/doc-bridge.md`](docs/skills/doc-bridge.md) · Pattern: [`docs/playbook/doc-bridge-pattern.md`](docs/playbook/doc-bridge-pattern.md) · Recipes: [`docs/recipes/index-pipeline.md`](docs/recipes/index-pipeline.md)\n\n## Learn loop — memory → draft PR\n\n```bash\nak-docs memory ingest\nak-docs memory classify\nak-docs memory promote --pr --dry-run   # preview gh commands\nak-docs memory promote --pr              # opens draft PR via gh\n```\n\n## Status\n\n**Current npm package: v1.7.45 stable** — portable, fail-closed handoffs for Cursor, Pi, Hermes, and ClawHub-compatible clients; deterministic Documentation Standard v1 conformance; verified release provenance; Marketplace Action; doctor + CI + skill; and documentation-quality audit tooling.\n\n```bash\npnpm install && pnpm build && pnpm test\npnpm smoke:ollama    # optional — skips if Ollama/peers unavailable\n```\n\n**Landing:** https://doc-bridge.agentskit.io/\n\n## Privacy Policy\n\nThe local MCP server reads only the project selected through `doc-bridge.config.json`. It does not require an API key, send project data to AgentsKit, collect telemetry, or write project files through its eight MCP tools. See the complete [Privacy Policy](PRIVACY.md) for accessed paths, use, storage, sharing, retention, optional integrations, and contact information.\n\n## Contributing\n\nIssues and PRs are welcome. Start here:\n\nTo improve the evidence base, reproduce the [anonymized study](docs/study/README.md), add a language or framework analyzer, contribute a documentation-quality rule, or add a fixture for a real contradiction or stale relation.\n\n| Need | Doc |\n|------|-----|\n| Local setup, tests, release flow | [CONTRIBUTING.md](CONTRIBUTING.md) |\n| Governance and maintainer responsibilities | [GOVERNANCE.md](GOVERNANCE.md) |\n| Vulnerability reports | [SECURITY.md](SECURITY.md) |\n| Community standards | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) |\n| Release history | [CHANGELOG.md](CHANGELOG.md) |\n| Product positioning | [docs/POSITIONING.md](docs/POSITIONING.md) |\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 18725,
  "sha": "7c83b72357e44ea5f42695dbd5c76de33ba90feed21070098ba8658d6cbeae51",
  "repo_slug": "agentskit-io/doc-bridge",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_agentskit_io_doc_bridge_b46be3f8/readme"
}