Doc Bridge

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

Deterministic proof of documentation drift, with evidence-linked handoffs for coding agents.

Turn your docs into executable handoffs: 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

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. The separate Layer-1 benchmark results measure deterministic documentation findings with native and fixture scores reported separately.

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

Verify documentation divergence

Compare revision snapshots deterministically: inspect symbol, CLI, configuration and signature changes, historical references and remaining head citations. Broken references require removal evidence; ambiguity and unsupported extraction stay explicit. Changed references require review. Default policy routes findings separately from their evidence status; use --no-policy to inspect raw diagnostics.

From a built checkout, this runnable comparison snapshots a temporary copy of the signature fixture before and after removing a cited export. Use an installed ak-docs, or replace it with node /path/to/checkout/bin/ak-docs.js from a built checkout. The Node step extracts the raw snapshot from the discovery response:

set -e

work=$(mktemp -d) cp -R tests/fixtures/signature-api "$work/repo" (cd "$work/repo" && ak-docs discover --json) > "$work/discovery.json" node -e 'const fs = require("node:fs"); const result = JSON.parse(fs.readFileSync(process.argv[1], "utf8")); fs.writeFileSync(process.argv[2], JSON.stringify(result.snapshot))' "$work/discovery.json" "$work/base.json" sed '/^export const describeThing/d' "$work/repo/api.ts" > "$work/api.ts" mv "$work/api.ts" "$work/repo/api.ts" ak-docs diff --base "$work/base.json" --root "$work/repo" ak-docs diff --base "$work/base.json" --root "$work/repo" --no-policy rm -rf "$work"

Capture each revision independently for a real delta. See diff and findings and Action advisory mode for bounded PR reports. Reports never approve documentation corrections.

2.0 workflows

• Vault: opt-in Obsidian discovery reads wikilinks, aliases and tags; ak-docs vault export generates ignored navigation notes and vault diff turns edited generated notes into pending proposals. Vault guide.
• Rationale: enable index.knowledgeEntities.enabled, index decisions/concepts/changes, then run ak-docs why . MCP exposes knowledge.decision, knowledge.concept and knowledge.whyChanged. Evidence is observed rationale, not inferred causality. Knowledge query contract.
• Remediation: optional ak-docs fix --llm uses scripted fake-provider responses in the key-free guide; real providers use explicit intelligence configuration. Proposals require deterministic rechecking and human review.
• Advisory: CHANGED_REFERENCE concerns a claim about the changed aspect; bare mentions do not trigger it. Unknown syntax remains review-required uncertainty. Action advisory.
• Upgrade: follow the 1.x → 2.0 migration guide. This package ships no Studio UI; use the deterministic StudioGraphV1 export to visualize the graph with other tools.

The latest Layer-1 benchmark and method report native findings at 100% precision (15 TP, 0 FP, 0 FN), historical changed-reference findings at 83.3% precision (10 TP, 2 FP, 0 FN), and 6.25% false-positive rate on historical negative cases (2/32). These purposive controls measure different denominators; they do not establish general semantic accuracy or release readiness.

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.

| **Documentation