@agentskit/doc-bridge

doc-bridge

npm: @agentskit/doc-bridge · CLI: ak-docs · Landing: agentskit-io.github.io/doc-bridge

AgentHandoff for your monorepo — deterministic routing so coding agents edit the right package, run the right checks, and stay linked to human docs.

Not a wiki. Not a hosted RAG chat. Layer 0 works without any LLM or API key.

60-second wow path

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

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

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

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

- uses: AgentsKit-io/doc-bridge@v1.0.0
  with:
    config-path: doc-bridge.config.json

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.

Surfaces

Layer 0 — 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 / memory / bootstrap
MCP	handoff.resolve, doc.search, doc.get, gate.status, …
Gates	Freshness, human-link validation, optional OKF style
Plugins	pnpm-monorepo, fumadocs, docusaurus, plain-markdown

Layer 1 — 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.

Who uses it (public)

Designed for and dogfooded on open AgentsKit surfaces:

Surface	Link
for-agents	agentskit.io/docs/for-agents
Registry	registry.agentskit.io
Playbook	playbook.agentskit.io
This repo	CI green · ak-docs gate run on every PR

Playbook pattern: docs/playbook/doc-bridge-pattern.md — export with ak-docs playbook pattern --text

Configuration examples

Profile	Example
Solo markdown	examples/minimal-plain-markdown.config.ts
pnpm monorepo	examples/pnpm-monorepo.config.ts
Demo monorepo	examples/demo-monorepo/
Fumadocs + chat	examples/fumadocs-with-chat.config.ts

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.0.0 stable — doctor + CI + skill boring-reliable. Landing, Playbook pattern, full Tier A/B/C shipped.

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

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

Contributing

• CONTRIBUTING.md · SECURITY.md · CODE_OF_CONDUCT.md · CHANGELOG.md
• Positioning: docs/POSITIONING.md

License

MIT