@agentskit/doc-bridge 1.3.0 → 1.4.1

package/docs/MARKETPLACE.md

@@ -21,7 +21,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: AgentsKit-io/doc-bridge@v1.2.1
+      - uses: AgentsKit-io/doc-bridge@v1.4.0
         with:
           config-path: doc-bridge.config.json
 ```

package/docs/guides/choose-context-layer.md

@@ -0,0 +1,129 @@
+---
+title: Choose the right context layer
+description: Decide when an agent needs repository rules, deterministic routing, code search, RAG, or human review.
+---
+
+# Choose the right context layer
+
+Coding agents rarely fail because a repository has no context. They fail because the right context arrives too late, or because several different kinds of context are treated as interchangeable.
+
+`AGENTS.md`, Doc Bridge, code search, RAG, and human review solve different problems. The most reliable workflow composes them in that order instead of asking one layer to do every job.
+
+## The short version
+
+| Layer | Best question | Use it for | Do not rely on it for |
+| --- | --- | --- | --- |
+| `AGENTS.md` | What rules apply here? | Repository-wide invariants, conventions, safety rules, and workflow expectations | Selecting the owner of every task in a large monorepo |
+| Doc Bridge | Where does this task belong? | Deterministic ownership, starting docs, declared edit roots, package checks, and matching human docs | Explaining every implementation detail or enforcing filesystem permissions |
+| Code search | Where is this exact thing used? | Symbols, imports, references, call sites, and concrete strings | Deciding ownership from similarity alone |
+| RAG | What broader context may be relevant? | Design history, migrations, scattered documentation, and open-ended questions | Overriding an explicit ownership contract |
+| Human review | Is this boundary still correct? | Ambiguous, cross-cutting, security-sensitive, or high-impact decisions | Routine routing that the repository can declare and test |
+
+## Start with repository rules
+
+An `AGENTS.md` file is the right place for rules that should survive individual tasks:
+
+- required coding conventions;
+- security and privacy constraints;
+- commands that must run before a change is accepted;
+- architectural invariants;
+- contribution and release expectations.
+
+Doc Bridge does not replace those rules. A handoff can include `AGENTS.md` in `readBeforeEditing`, then narrow the task to the package-specific material that matters.
+
+## Use Doc Bridge for deterministic routing
+
+When the repository already knows which package owns authentication, the agent should not infer ownership from filenames or semantic similarity. Resolve a handoff first:
+
+```bash
+ak-docs query package auth --agent
+```
+
+A useful handoff answers four operational questions:
+
+```json
+{
+  "startHere": "docs/for-agents/packages/auth.md",
+  "editRoots": ["packages/auth"],
+  "checks": [
+    "pnpm --filter @example/auth test",
+    "pnpm --filter @example/auth lint"
+  ],
+  "humanDoc": "docs/guides/auth.md"
+}
+```
+
+This is intentionally smaller than a repository dump. It gives the agent an explicit starting point, declared scope, evidence to run, and a human-facing description of the same feature.
+
+`editRoots` is a routing and audit contract. It does not create an operating-system sandbox by itself. If a workflow must technically prevent writes outside those roots, enforce that boundary with the agent runner, sandbox, permissions, or CI policy.
+
+## Search after scope is known
+
+Code search is strongest after the owner is resolved. Inside the intended scope, use it to find:
+
+- the implementation of a symbol;
+- all imports of an adapter;
+- tests for an error code;
+- callers affected by a signature change.
+
+Search can reveal that a task is genuinely cross-cutting. When it does, expand the declared handoff or ask for human review. Do not quietly turn a package-scoped change into a repository-wide edit.
+
+## Add RAG for open-ended context
+
+RAG is useful when the question does not have one exact answer:
+
+- Why did the authentication design change?
+- Which migration notes mention token rotation?
+- What guidance exists for moving from one provider to another?
+
+That context can improve the implementation, but it should expand a deterministic handoff rather than replace one. Similar documents are evidence, not ownership.
+
+Doc Bridge keeps this distinction explicit: Layer 0 indexing and handoffs work offline without a model or API key; RAG and chat are optional intelligence layers.
+
+## Escalate ambiguity to a human
+
+Some changes should not be forced into a convenient directory. Ask for human review when:
+
+- multiple packages legitimately own part of the change;
+- a public contract or security boundary may change;
+- the handoff conflicts with the current repository shape;
+- checks are missing or no longer prove the behavior;
+- the cost of a wrong boundary is high.
+
+A useful routing system should make uncertainty visible. It should not produce false confidence when the repository has not declared an answer.
+
+## Recommended order
+
+```text
+resolve handoff
+  → read AGENTS.md and startHere
+  → search exact code inside the declared scope
+  → retrieve broader context when needed
+  → edit the intended roots
+  → run the declared checks
+  → request human review for unresolved boundaries
+```
+
+For an existing repository, the smallest adoption path is:
+
+```bash
+npm install --save-dev @agentskit/doc-bridge@1.2.6
+npx ak-docs init
+npx ak-docs index
+npx ak-docs query package example --agent
+npx ak-docs gate run
+```
+
+The gate makes drift visible when ownership inputs or linked documentation change without a refreshed index. That keeps the routing contract reviewable instead of silently rebuilding it during validation.
+
+## A practical decision rule
+
+If the question begins with **must**, put the invariant in repository instructions. If it begins with **where**, resolve a Doc Bridge handoff. If it begins with **which exact reference**, search the code. If it begins with **why** or **what else**, retrieve broader context. If the answers disagree, stop and ask a human.
+
+## Related
+
+- [Index and query](./index-and-query.md)
+- [For agents](../for-agents.md)
+- [Chat and RAG](../chat-and-rag.md)
+- [Gate in CI](./gate-ci.md)
+- [AgentHandoff schema](../schemas/agent-handoff-v1.md)

package/docs/guides/gate-ci.md

@@ -38,7 +38,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: AgentsKit-io/doc-bridge@v1.2.1
+      - uses: AgentsKit-io/doc-bridge@v1.4.0
         with:
           config-path: doc-bridge.config.json
 ```

package/docs/guides/meta.json

@@ -3,6 +3,7 @@
   "pages": [
     "install-and-run",
     "index-and-query",
+    "choose-context-layer",
     "gate-ci",
     "mcp-agents",
     "memory-pipeline",

package/docs/landing/index.html

@@ -337,7 +337,7 @@
           <div class="terminal-bar"><span class="dot dot-r"></span><span class="dot dot-y"></span><span class="dot dot-g"></span></div>
           <div class="terminal-body">
             <div class="t-dim"># .github/workflows/pr.yml</div>
-            <div>- uses: <span class="t-hi">AgentsKit-io/doc-bridge@v1.2.1</span></div>
+            <div>- uses: <span class="t-hi">AgentsKit-io/doc-bridge@v1.4.0</span></div>
             <div>&nbsp;&nbsp;with:</div>
             <div>&nbsp;&nbsp;&nbsp;&nbsp;config-path: doc-bridge.config.json</div>
           </div>

package/docs/playbook/doc-bridge-pattern.md

@@ -77,7 +77,7 @@ Agents call `handoff.resolve` before editing `packages/*`:
 ## CI gate
 
 ```yaml
-- uses: AgentsKit-io/doc-bridge@v1.2.1
+- uses: AgentsKit-io/doc-bridge@v1.4.0
 ```
 
 Or: `ak-docs index && ak-docs gate run` — stale index fails the PR.

package/docs/recipes/index-pipeline.md

@@ -71,7 +71,7 @@ Root `package.json`:
 ## CI (GitHub Action)
 
 ```yaml
-- uses: AgentsKit-io/doc-bridge@v1.2.1
+- uses: AgentsKit-io/doc-bridge@v1.4.0
 ```
 
 Or manual:

package/mcpb/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.3",
   "name": "doc-bridge",
   "display_name": "Doc Bridge",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "Deterministic repository handoffs for coding agents, running locally without an LLM or API key.",
   "long_description": "Doc Bridge turns a repository's own documentation and ownership metadata into deterministic handoffs: where an agent should start, which paths it may edit, which checks it must run, and when a human must take over. The local connector exposes the same read-only contract available through Doc Bridge CLI and CI.",
   "author": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentskit/doc-bridge",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "mcpName": "io.github.AgentsKit-io/doc-bridge",
   "description": "Human↔agent documentation bridge — deterministic handoffs, doc-site links, memory→docs, optional AgentsKit RAG/chat.",
   "type": "module",
@@ -40,12 +40,13 @@
     "mcpb",
     "tsup.config.ts",
     "tsconfig.json",
-    "src"
+    "src",
+    "skills"
   ],
   "scripts": {
     "prebuild": "node scripts/sync-version.mjs",
     "build": "tsup",
-    "test": "vitest run",
+    "test": "vitest run && pnpm test:cursor-plugin && pnpm test:claude-plugin && pnpm test:copilot-plugin && pnpm test:portable-skill",
     "test:watch": "vitest",
     "coverage": "vitest run --coverage",
     "check:ecosystem-upstream": "node scripts/check-ecosystem-upstream.mjs",
@@ -60,6 +61,10 @@
     "mcpb:smoke": "node scripts/smoke-mcpb.mjs",
     "mcpb:pack": "npm run mcpb:stage && npm run mcpb:smoke && node scripts/build-mcpb.mjs pack",
     "test:mcpb": "node --test scripts/mcpb-contract.test.mjs",
+    "test:cursor-plugin": "node --test scripts/cursor-plugin-contract.test.mjs",
+    "test:claude-plugin": "node --test scripts/claude-plugin-contract.test.mjs",
+    "test:copilot-plugin": "node --test scripts/copilot-plugin-contract.test.mjs",
+    "test:portable-skill": "node --test scripts/portable-skill-contract.test.mjs",
     "coverage:badge": "node scripts/update-coverage-badge.mjs",
     "changeset": "changeset",
     "version-packages": "changeset version && node scripts/sync-version.mjs",
@@ -85,12 +90,18 @@
     "agentskit",
     "documentation",
     "mcp",
+    "pi-package",
     "for-agents",
     "llms-txt",
     "agent-handoff",
     "rag",
     "human-agent-bridge"
   ],
+  "pi": {
+    "skills": [
+      "./skills"
+    ]
+  },
   "license": "MIT",
   "repository": {
     "type": "git",

package/skills/doc-bridge-handoff/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: doc-bridge-handoff
+description: Resolve Doc Bridge boundaries before changing code.
+version: 1.0.0
+author: AgentsKit
+license: MIT
+platforms:
+  - darwin
+  - linux
+  - windows
+---
+
+# Doc Bridge handoff
+
+Use this skill before editing a repository that contains `doc-bridge.config.json`.
+
+1. Resolve the package or ownership id that best matches the requested change:
+   - Prefer the read-only MCP tool `handoff.resolve` when it is available.
+   - Otherwise run `node <skill-directory>/scripts/resolve-handoff.mjs <id>` from the repository.
+2. Read every file in `readBeforeEditing`, beginning with `startHere`.
+3. Keep changes inside `editRoots`. If the requested path is not covered, stop and report the missing route instead of guessing.
+4. Make the smallest change that satisfies the request.
+5. Run every command in `checks` before claiming completion.
+6. If documentation changed, refresh the Doc Bridge index and run its gate.
+
+If resolution fails, returns incomplete fields, or names an unknown target, stop. Do not infer edit permission from repository layout.
+
+The resolver and MCP tools are read-only. They resolve project guidance but never authorize edits, publish changes, execute returned checks, or replace repository instructions. The skill uses no credentials and has no provider, hosted service, or AKOS dependency.
+
+## Portable runtimes
+
+This directory follows the open Agent Skills layout: one `SKILL.md` plus optional scripts and fixtures. It can be loaded as a local skill by OpenClaw-compatible clients, Hermes Agent, Pi, Cursor, or another runtime that supports Agent Skills and shell execution. Runtime-specific publication metadata is intentionally kept outside the skill.

package/skills/doc-bridge-handoff/fixtures/synthetic-repo/doc-bridge.config.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 1,
+  "corpus": {
+    "agent": {
+      "root": "docs/for-agents"
+    }
+  },
+  "routing": {
+    "options": {
+      "ownership": {
+        "payments": {
+          "path": "packages/payments",
+          "purpose": "Synthetic package used only to verify portable handoff routing",
+          "checks": ["npm test -- payments"],
+          "agentDoc": "docs/for-agents/packages/payments.md"
+        }
+      }
+    }
+  },
+  "gates": {
+    "preset": "minimal"
+  }
+}

package/skills/doc-bridge-handoff/fixtures/synthetic-repo/docs/for-agents/packages/payments.md

@@ -0,0 +1,5 @@
+# Payments package
+
+This is public synthetic guidance for the portable skill compatibility test.
+
+Only edit `packages/payments` and run the checks returned by Doc Bridge.

package/skills/doc-bridge-handoff/fixtures/synthetic-repo/packages/payments/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "synthetic-payments",
+  "private": true
+}

package/skills/doc-bridge-handoff/scripts/resolve-handoff.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process'
+import { isAbsolute } from 'node:path'
+
+const VERSION = '1.4.1'
+const kinds = new Set(['package', 'ownership'])
+const args = process.argv.slice(2)
+const id = args[0]
+const kindFlag = args.indexOf('--kind')
+const configFlag = args.indexOf('--config')
+const kind = kindFlag === -1 ? 'package' : args[kindFlag + 1]
+const config = configFlag === -1 ? undefined : args[configFlag + 1]
+
+const fail = (message) => {
+  process.stderr.write(`Doc Bridge handoff blocked: ${message}\n`)
+  process.exit(1)
+}
+
+if (!id || id.startsWith('--') || /[\u0000-\u001f\u007f]/u.test(id)) {
+  fail('provide a package or ownership id')
+}
+if (!kind || !kinds.has(kind)) fail('--kind must be package or ownership')
+if (configFlag !== -1 && (!config || config.startsWith('--'))) fail('--config requires a path')
+
+const queryArgs = ['query', kind, id, '--agent']
+if (config) queryArgs.push('--config', config)
+
+const localBin = process.env.DOC_BRIDGE_BIN
+const command = localBin ? process.execPath : 'npx'
+const commandArgs = localBin
+  ? [localBin, ...queryArgs]
+  : ['-y', `@agentskit/doc-bridge@${VERSION}`, ...queryArgs]
+const result = spawnSync(command, commandArgs, {
+  cwd: process.cwd(),
+  encoding: 'utf8',
+  timeout: 60_000,
+  maxBuffer: 1024 * 1024,
+})
+
+if (result.error) fail(result.error.message)
+if (result.status !== 0) fail(result.stderr.trim() || `resolver exited with status ${result.status}`)
+
+let handoff
+try {
+  handoff = JSON.parse(result.stdout)
+} catch {
+  fail('resolver returned invalid JSON')
+}
+
+const nonEmptyStrings = (value) =>
+  Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === 'string' && item.trim())
+const safeRelativePath = (value) => {
+  if (typeof value !== 'string' || !value.trim() || isAbsolute(value)) return false
+  if (/^(?:[a-z]:[\\/]|\\\\)/iu.test(value)) return false
+  return !value.split(/[\\/]+/u).includes('..')
+}
+
+if (handoff?.target?.id !== id) fail('resolver returned a different target')
+if (!safeRelativePath(handoff.startHere)) fail('startHere is missing or unsafe')
+if (!nonEmptyStrings(handoff.readBeforeEditing) || !handoff.readBeforeEditing.every(safeRelativePath)) {
+  fail('readBeforeEditing is missing or unsafe')
+}
+if (!handoff.readBeforeEditing.includes(handoff.startHere)) fail('readBeforeEditing omits startHere')
+if (!nonEmptyStrings(handoff.editRoots) || !handoff.editRoots.every(safeRelativePath)) {
+  fail('editRoots is missing or unsafe')
+}
+if (!nonEmptyStrings(handoff.checks)) fail('checks are missing')
+
+process.stdout.write(`${JSON.stringify(handoff, null, 2)}\n`)

package/src/version.ts

@@ -1 +1 @@
-export const PACKAGE_VERSION = '1.3.0'
+export const PACKAGE_VERSION = '1.4.1'