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 every agent the same answer:

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

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

That contract works from the terminal, MCP, CI, and optional RAG/chat.

60-second proof

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

Monorepo fixture with auth + billing:

npx ak-docs demo --fixture monorepo --text

Verify the real handoff path

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

import { execFileSync } from 'node:child_process'

execFileSync(process.execPath, ['bin/ak-docs.js', 'demo', '--text'], {
  stdio: 'inherit',
})

node examples/verify-handoff.mjs

Full setup in your repo:

npx ak-docs init
npx ak-docs index
npx ak-docs query package example --agent
ak-docs mcp install --cursor   # wires MCP into .cursor/mcp.json

What ships

See docs/getting-started.md, docs/mcp.md, and docs/examples.md.

Why this exists

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)

ak-docs ask "who owns schemas"
# Best match: ownership os-core
# Handoff preview
#   start:  docs/for-agents/packages/os-core.md
#   edit:   packages/os-core
#   checks: pnpm --filter os-core lint · pnpm --filter os-core test

Coverage your team checks daily

ak-docs doctor --text
ak-docs doctor --badge          # shields.io markdown for README
ak-docs index --watch           # keep index fresh while editing docs

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

1. MCP auto-wire: ak-docs mcp install --cursor

2. Skill/rule: paste docs/skills/doc-bridge.md into Cursor rules — agents call handoff.resolve before editing packages/*

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

permissions:
  contents: read

steps:
  - uses: actions/checkout@v4
  - uses: AgentsKit-io/doc-bridge@v1.2.1
    with:
      config-path: doc-bridge.config.json

The Action checks the committed index before changing anything, pins the matching npm package, and rejects non-exact package versions. See the Marketplace guide.

Run ak-docs doctor --badge locally to refresh — or pnpm coverage:badge in CI.

Or locally:

ak-docs index && ak-docs gate run

Gate fails with Index is stale. Run: ak-docs index — same check in CI annotations.

Product surface

Core — always (no LLM)

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   # preview gh commands
ak-docs memory promote --pr              # opens draft PR via gh

Status

v1.2.1 stable — deterministic Documentation Standard v1 conformance, verified release provenance, Fumadocs portal, Marketplace Action, doctor + CI + skill, and full Tier A/B/C.

pnpm install && pnpm build && pnpm test
pnpm smoke:ollama    # optional — skips if Ollama/peers unavailable

Landing: https://doc-bridge.agentskit.io/

Contributing

Issues and PRs are welcome. Start here:

License

MIT