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:

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.

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