doc-bridge
npm: @agentskit/doc-bridge · CLI: ak-docs · Landing: agentskit-io.github.io/doc-bridge
Topics: ai-agents · documentation · developer-experience · mcp · llms-txt · typescript
Compatibility: node >=22 · TypeScript 5.8+ · pnpm, npm, or yarn consumers
Turn your docs into executable handoffs for coding agents.
doc-bridge reads your repo docs, ownership map, and human documentation site, then gives humans and agents the same evidence-linked starting point:
- where to start reading
- which files/packages it may edit
- which checks prove the change
- which human docs explain the feature
It 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.
Built for agent-scale repositories
Doc 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.
Historical context-payload estimate
An earlier anonymized dogfooding cycle estimated up to 99% less serialized context payload. This is a historical payload estimate—not a guarantee of provider-token savings, answer quality, or semantic correctness. It is not the same measure as provider-token usage.
Historical controlled A/B signal
The published controlled study with 96 anonymized executions reported a directional operational signal of:
- 18.46% fewer paired provider token-equivalent units across 46 token-complete pairs;
- 39.75 seconds lower P95 latency;
- 87.5% operationally completed executions vs. 75.0% with repository-only context.
These are historical, separately defined measures: the 99% figure is an estimated context-payload reduction, while the 18.46% figure uses provider-token-equivalent data from 46 paired observations. The bounded adjudicator recorded zero adjudicator-success outcomes in both arms; because that adjudicator is mechanical and does not independently judge semantic correctness, this result is directional and inconclusive. A newer local pilot is intentionally not promoted here while its semantic evaluation and publication review remain incomplete. See the full methodology and anonymized data.
Why teams use it
Agents 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.
doc-bridge works in both directions:
| Direction | What it does | Command |
|---|
| Human docs → agents | Turns Fumadocs, Docusaurus, markdown, and ownership docs into AgentHandoff | ak-docs index · ak-docs query --agent |
| 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 |
The handoff is a routing contract:
{
"startHere": "docs/for-agents/packages/auth.md",
"editRoots": ["packages/auth"],
"checks": ["pnpm --filter @demo/auth test"],
"humanDoc": "/docs/guides/auth"
}
Workflow runs may carry the same optional correlation envelope used by the
AgentsKit runtime and Chat protocol. operationId is the cross-repository
identity; runId, sessionId, turnId, actionId, and traceId retain local
meaning. It is bounded metadata only and must not contain prompts, secrets, or
document content.
That contract works from the terminal, MCP, CI, and optional RAG/chat.
Documentation quality and reconciliation
Discovery 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.
Natural-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.
Example finding (anonymized)
CONTRADICTION · high confidence
Documentation declaration differs from the observed project relation
Evidence: 4 source files + 1 documentation declaration
Action: review ownership and update the canonical document
60-second proof
This README owns the one-command proof; the Getting started guide
owns the complete repository setup and first-index workflow.
npm i -D @agentskit/doc-bridge
npx ak-docs demo --text
No config, no docs to read first. Output shows before/after, a real handoff, gate red→green, and the MCP snippet:
After (handoff.resolve / query --agent)
✓ target: auth (packages/auth)
✓ start: docs/for-agents/packages/auth.md
✓ edit: packages/auth
✓ checks: pnpm --filter @demo/auth test · pnpm --filter @demo/auth lint
✓ human guide: /docs/guides/auth
Gate: red → green
Verify the real handoff path
This checked example runs the bundled demo through the public CLI. The
repository's scripts/check-readme-standard.mjs gate compares this block byte-for-byte
with the executable fixture; .github/workflows/ci.yml runs that gate and its
executable tests on every pull request.
The study figures below are not recomputed by the README gate; their protocol,
privacy checks, and limitations are documented in the linked study artifacts.
import { execFileSync } from 'node:child_process'
execFileSync(process.execPath, ['bin/ak-docs.js', 'demo', '--text'], {
stdio: 'inherit',
})
node examples/verify-handoff.mjs
For the complete repository setup, follow the Getting started guide.
Using Cline? Follow the deterministic llms-install.md setup. It runs the pinned MCP server through pnpm dlx without adding Doc Bridge to your repository dependencies.
What ships
See the surface map for a visual overview of the CLI, MCP, CI, and adapter surfaces.
| Surface | Use it for | Command / artifact |
|---|
| CLI | Inspect ownership, search docs, run gates, ask local questions | ak-docs query, search, ask, doctor, gate |
| MCP server | Let Cursor, Claude Code, Codex-style agents resolve handoffs before editing | ak-docs mcp, handoff.resolve |
| GitHub Action / CI | Fail stale indexes and configured documentation gates on PRs | AgentsKit-io/doc-bridge@ee756a13c006c597445c31e2643c1e8cece715d7 |
| Documentation conformance | Check the stable ecosystem standard with auditable evidence | ak-docs conformance run documentation-standard-v1 --text |
| Documentation audit | Measure documentation quality and compare docs with the observed project graph | ak-docs audit documentation --json |
| Doc adapters | Link human docs to agent docs | fumadocs, docusaurus, vitepress, starlight, nextra, plain-markdown |
| Monorepo routing | Discover workspaces and checks | pnpm-monorepo, nx |
| Memory pipeline | Turn agent notes into reviewable documentation drafts | memory ingest, classify, promote --pr |
| Optional RAG/chat | Ground chat in the same handoff-first index | @agentskit/rag, @agentskit/ink, ak-docs chat |
See docs/getting-started.md, docs/mcp.md, and docs/examples.md.
Cursor plugin
This repository also contains a Cursor plugin that pairs the Doc Bridge MCP server (read-only except for the explicit proposal tool) 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.
GitHub Copilot plugin
The root Agent Plugins manifest exposes the same portable handoff skill and 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.
copilot plugin install AgentsKit-io/doc-bridge
Portable Agent Skill
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.
Install the published skill from ClawHub:
clawhub install doc-bridge-handoff
Pi users can install the same source-owned skill through the npm package:
pi install npm:@agentskit/doc-bridge
Claude Desktop MCP Bundle
Doc Bridge can be packaged as a local MCP Bundle for Claude Desktop. The bundle advertises 14 MCP tools, exercises 8 of them in its smoke test, and marks every tool except docbridge.proposals read-only. It asks the user to select the repository's doc-bridge.config.json; that file defines the project boundary Doc Bridge may read.
From a clean checkout:
pnpm install --frozen-lockfile
pnpm mcpb:pack
The 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.
The current packaged compatibility declaration is macOS-only; this project does not claim bundle support for other operating systems until the exact artifact passes an independent installation test there.
Why this exists
| Pattern | Gap |
|---|
| Wiki + RAG | Explains; weak on where to act and proof docs match code |
| AGENTS.md alone | Great static rules; no ownership index, gates, or human bridge |
| Context7-class tools | Library docs for the model; not your monorepo routing |
doc-bridge ships AgentHandoff 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 a human guide is missing, handoffs surface it as a feature:
{
"bridge": {
"humanDoc": "missing",
"action": "ak-docs bootstrap agent-docs"
},
"notes": ["Human guide missing for billing. Run: ak-docs bootstrap agent-docs"]
}
Four loops (with real commands)
| Loop | Command | What you see |
|---|
| Act | ak-docs query package auth --agent | editRoots, checks, startHere |
| Bridge | ak-docs bootstrap agent-docs | Draft agent docs from human site; bridge.humanDoc in handoff |
| Learn | ak-docs memory classify → promote | HITL draft for agent corpus |
| Explain | ak-docs ask "auth is broken in staging" | Ownership match + handoff preview + next commands |
ak-docs ask "who owns schemas"
Coverage your team checks daily
The following is illustrative output from the command, not a measurement of
this repository. Run the command locally or in CI for current values.
ak-docs doctor --text
ak-docs doctor --badge
ak-docs index --watch
Score: 82/100 (B)
Agent docs: 8/10 (80% handoff-ready)
Human guides: 6/10 (60% bridged)
Gates: 3/3 passing
Next actions
→ ak-docs bootstrap agent-docs
→ ak-docs query package billing --agent
Agent uses it alone
- MCP auto-wire:
ak-docs mcp install --cursor
- Skill/rule: paste docs/skills/doc-bridge.md into Cursor rules — agents call
handoff.resolve before editing packages/*
- Handoff is the next step:
startHere, checks, and bridge are in the JSON/MCP response
CI as first-class citizen
Reuse the bundled GitHub Action on every PR:
Follow the canonical Gate and CI guide, which includes
the complete workflow and pins the published Action release.
The Action installs the exact configured package (or the workspace package when
dogfooding this repository), then verifies the committed index and configured
gates without silently rebuilding them. It rejects non-exact package versions.
See the Marketplace guide.
The guide is pinned to the published stable Action release v1.7.45; the
checked-in package version is 1.11.2.
Coverage is repository-specific. Run ak-docs doctor --badge locally to emit
current handoff and human-bridge badges, or pnpm coverage:badge in CI; this
README intentionally avoids publishing a stale static percentage.
Or locally, as two steps rather than one, because they answer different questions:
ak-docs index
ak-docs gate run
Chaining them (index && gate run) cannot report a stale index: it gates an artifact written a
second earlier against a rebuild of the same tree. The gate's value is that the committed index
and the repository agree, so run it the way CI does, against what is committed. It fails with
Index is stale. Run: ak-docs index — the same check, and the same annotation, as in CI.
Product surface
Core — always (no LLM)
| Surface | Purpose |
|---|
| Demo | ak-docs demo — bundled fixture, no setup |
| Doctor | Coverage score, missing humanDoc/agent doc, next actions |
| Index | DocBridgeIndex + contentHash + llms.txt + capabilities |
| CLI | query / search / list / ask / gate / bench / memory / bootstrap |
| MCP | handoff.resolve, doc.search, doc.get, gate.status, … |
| Gates | Freshness, human-link validation, optional OKF style |
| Adapters | pnpm-monorepo, nx, fumadocs, docusaurus, vitepress, starlight, nextra, plain-markdown |
Optional AgentsKit peers
npm i -D @agentskit/rag @agentskit/ink @agentskit/adapters @agentskit/memory react
ak-docs rag ingest && ak-docs chat
See docs/chat-and-rag.md.
AgentsKit ecosystem
Who uses it (public)
Designed for and dogfooded on open AgentsKit surfaces:
Playbook pattern: docs/playbook/doc-bridge-pattern.md — export with ak-docs playbook pattern --text
Configuration examples
Contract: docs/spec/config-v1.md · CLI: docs/spec/cli.md · MCP: docs/mcp.md · Skill: docs/skills/doc-bridge.md · Pattern: docs/playbook/doc-bridge-pattern.md · Recipes: docs/recipes/index-pipeline.md
Learn loop — memory → draft PR
ak-docs memory ingest
ak-docs memory classify
ak-docs memory promote --pr --dry-run
ak-docs memory promote --pr
Status
Published npm package: v1.7.45 stable. The working-tree package version is
1.8.0 and is not published yet. The Action example below intentionally pins
the latest published stable release; the release workflow updates the package
and Action version together when a new release is published.
The published package provides portable, fail-closed handoffs through the CLI,
MCP server, CI action, and packaged skill; deterministic Documentation Standard
v1 conformance; verified release provenance; and documentation-quality audit
tooling.
pnpm install && pnpm build && pnpm test
pnpm smoke:ollama
Landing: https://doc-bridge.agentskit.io/
Privacy Policy
The 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 MCP tools. See the complete Privacy Policy for accessed paths, use, storage, sharing, retention, optional integrations, and contact information.
Contributing
Issues and PRs are welcome. Start here:
To improve the evidence base, reproduce the anonymized study, add a language or framework analyzer, contribute a documentation-quality rule, or add a fixture for a real contradiction or stale relation.
License
MIT