@agentskit/doc-bridge 0.1.0-alpha.3 → 1.0.1

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

@@ -0,0 +1,114 @@
+---
+type: pattern
+id: doc-bridge-pattern
+purpose: Route coding agents to the correct package, checks, and human docs in any monorepo.
+owner: AgentsKit
+license: CC-BY-4.0
+visibility: public
+tags: [agents, documentation, monorepo, handoff, mcp]
+---
+
+# Doc Bridge Pattern
+
+**AgentHandoff for your monorepo** — deterministic routing so agents edit the right roots, run the right checks, and stay linked to human documentation.
+
+Published pattern for [Agents Playbook](https://playbook.agentskit.io/). Export with:
+
+```bash
+ak-docs playbook pattern --text
+ak-docs playbook pattern --json
+```
+
+## Problem
+
+Coding agents guess package ownership. They edit sibling modules, run repo-wide tests, and ship changes without a bridge to human-facing guides. Wikis and RAG explain concepts but weakly answer *where to act*.
+
+## Solution (three artifacts)
+
+| Artifact | Role |
+|----------|------|
+| **AgentHandoff** | JSON handoff: `startHere`, `editRoots`, `checks`, `humanDoc`, `bridge` |
+| **DocBridgeIndex** | Deterministic index + `contentHash` for CI freshness gates |
+| **Self-describe** | `llms.txt`, `capabilities.json` for discovery |
+
+## Four loops
+
+| Loop | Command | Outcome |
+|------|---------|---------|
+| **Act** | `ak-docs query package <id> --agent` | Agent edits only `editRoots` |
+| **Bridge** | `ak-docs bootstrap agent-docs` | Link agent corpus ↔ human site |
+| **Learn** | `ak-docs memory promote --pr` | HITL draft PR from agent memory |
+| **Explain** | `ak-docs ask "<question>"` | Local consult + handoff preview |
+
+## 60-second proof
+
+```bash
+npm i -D @agentskit/doc-bridge
+npx ak-docs demo --text
+ak-docs mcp install --cursor
+```
+
+## AgentHandoff example
+
+```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 `humanDoc` is missing, handoffs surface `bridge.action: "ak-docs bootstrap agent-docs"` — a feature, not a silent gap.
+
+## MCP contract
+
+Agents call `handoff.resolve` before editing `packages/*`:
+
+1. Read `startHere`
+2. Stay inside `editRoots`
+3. Run every `checks` command
+4. Link `humanDoc` or escalate missing bridge
+
+## CI gate
+
+```yaml
+- uses: AgentsKit-io/doc-bridge@v1.0.0
+```
+
+Or: `ak-docs index && ak-docs gate run` — stale index fails the PR.
+
+## Coverage metric
+
+```bash
+ak-docs doctor --text
+ak-docs doctor --badge
+```
+
+Teams track handoff % and human-bridge % daily.
+
+## When to use
+
+- pnpm/npm monorepos with real package ownership
+- Fumadocs / Docusaurus human sites + dense agent corpus
+- Cursor / Claude / Codex agents that should not guess edit roots
+
+## When not to use
+
+- Single-file repos with no ownership boundaries (AGENTS.md may suffice)
+- Hosted doc chat as primary product (doc-bridge is routing + bridge, not SaaS chat)
+
+## Promotion to Playbook
+
+1. Review this file for secrets and private paths
+2. Open PR to [agents-playbook](https://github.com/AgentsKit-io/agents-playbook) under `content/docs/pillars/ai-collaboration/`
+3. Or run `ak-docs memory promote --pr` for memory-sourced findings
+
+## References
+
+- npm: https://www.npmjs.com/package/@agentskit/doc-bridge
+- repo: https://github.com/AgentsKit-io/doc-bridge
+- skill: [doc-bridge skill](../skills/doc-bridge.md)
+- landing: https://agentskit-io.github.io/doc-bridge/

package/docs/recipes/index-pipeline.md

@@ -0,0 +1,89 @@
+# Index pipeline recipes
+
+Keep `.doc-bridge/index.json` fresh during development and in CI.
+
+## Watch mode (local dev)
+
+```bash
+ak-docs index --watch
+```
+
+Watches `docs/for-agents/` (and human corpus dirs when configured). Rebuilds on `.md`, `.mdx`, `.json`, `.yaml` changes.
+
+Pair with MCP in Cursor — agents always resolve against a live index.
+
+## Pre-commit hook
+
+`.husky/pre-commit` or `.git/hooks/pre-commit`:
+
+```bash
+#!/bin/sh
+ak-docs index
+ak-docs gate run index-freshness || {
+  echo "doc-bridge index is stale — run: ak-docs index"
+  exit 1
+}
+```
+
+Or only index agent docs when they change:
+
+```bash
+#!/bin/sh
+if git diff --cached --name-only | grep -Eq 'docs/for-agents/|doc-bridge\.config'; then
+  ak-docs index
+fi
+```
+
+## Turborepo task
+
+`turbo.json`:
+
+```json
+{
+  "tasks": {
+    "ak-docs:index": {
+      "inputs": ["docs/for-agents/**", "doc-bridge.config.*"],
+      "outputs": [".doc-bridge/index.json", "llms.txt", ".doc-bridge/capabilities.json"]
+    },
+    "build": {
+      "dependsOn": ["ak-docs:index"]
+    }
+  }
+}
+```
+
+Root `package.json`:
+
+```json
+{
+  "scripts": {
+    "ak-docs:index": "ak-docs index",
+    "ak-docs:gate": "ak-docs gate run"
+  }
+}
+```
+
+## CI (GitHub Action)
+
+```yaml
+- uses: AgentsKit-io/doc-bridge@v1.0.0
+```
+
+Or manual:
+
+```yaml
+- run: npm i -g @agentskit/doc-bridge && ak-docs index && ak-docs gate run
+```
+
+## Coverage badge in README
+
+```bash
+ak-docs doctor --badge
+# paste markdown into README
+
+# or persist for CI:
+ak-docs doctor --write-badge
+pnpm coverage:badge
+```
+
+Paste the shields.io line from `.doc-bridge/coverage-badge.json` → `markdown` field.

package/docs/skills/doc-bridge.md

@@ -0,0 +1,64 @@
+# Doc Bridge — agent routing skill
+
+Use this skill in Cursor, Claude Code, or Codex so agents resolve ownership **before** editing packages.
+
+## When to trigger
+
+- User asks to change code under `packages/*`, `apps/*`, or any monorepo module
+- Task mentions auth, billing, API, schema, or a package name
+- Before creating or moving files in an unfamiliar area of the repo
+
+## Required workflow
+
+1. **Resolve handoff first** — call MCP tool `handoff.resolve` with the package id, or run:
+   ```bash
+   ak-docs query ownership <id> --agent
+   ```
+2. **Read `startHere`** — open the agent doc path from the handoff
+3. **Edit only `editRoots`** — do not touch sibling packages
+4. **Run `checks`** from the handoff before claiming done
+5. **Bridge to humans** — if `bridge.humanDoc` is `missing`, tell the user and suggest `ak-docs bootstrap agent-docs`; if `humanDoc` is set, link it in your summary
+
+## MCP setup (one-time)
+
+```bash
+ak-docs mcp install --cursor
+```
+
+Or paste into `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ak-docs": {
+      "command": "npx",
+      "args": ["ak-docs", "mcp"],
+      "cwd": "/absolute/path/to/repo"
+    }
+  }
+}
+```
+
+## Cursor rule (paste into `.cursor/rules/doc-bridge.mdc`)
+
+```markdown
+---
+description: Resolve doc-bridge handoff before editing packages
+globs: packages/**/*
+---
+
+Before editing any file under packages/ or apps/:
+
+1. Call MCP `handoff.resolve` for the owning package id
+2. Read `startHere` from the handoff
+3. Only modify paths under `editRoots`
+4. Run every command in `checks` before finishing
+5. If humanDoc is missing, surface `ak-docs bootstrap agent-docs` to the user
+```
+
+## Quick consult (no LLM)
+
+```bash
+ak-docs ask "auth is broken in staging"
+ak-docs doctor --text
+```

package/docs/spec/cli.md

@@ -49,7 +49,10 @@ pnpm add -D @agentskit/doc-bridge
 | `ak-docs init --scaffold-workspaces` | Also create draft `docs/for-agents/packages/*.md` from discovered pnpm workspaces; never overwrites existing docs |
 | `ak-docs bootstrap agent-docs` | Create draft `docs/for-agents/human/*.md` from configured human-doc adapters; never overwrites existing docs |
 | `ak-docs validate-config` | Zod-validate config file |
+| `ak-docs demo [--fixture example\|monorepo] [--text]` | Bundled 60s wow path: handoff, gate red→green, MCP snippet |
+| `ak-docs doctor [--text] [--badge] [--write-badge]` | Coverage score, gaps, gates, shields.io badge |
 | `ak-docs index` | Build `DocBridgeIndex` + optional `llms.txt` |
+| `ak-docs index --watch` | Debounced rebuild on agent/human doc changes |
 | `ak-docs query <target> [--agent] [--text]` | Resolve package/module/intent/change → handoff JSON or text |
 | `ak-docs search <term> [--agent] [--text]` | Full-text search over index |
 | `ak-docs ask <question>` | Human-readable local consult mode: search + best match + next handoff commands; no LLM |
@@ -60,11 +63,14 @@ pnpm add -D @agentskit/doc-bridge
 | `ak-docs memory ingest` | Normalize local memory files (`.agent-memory/**/*.md`, `.cursor/rules/*.mdc`) into `MemoryCandidate[]` |
 | `ak-docs memory classify` | Deterministically route candidates to agent/human/playbook/discard |
 | `ak-docs memory promote` | Build draft-only promotion body with safety scan; never auto-merges |
+| `ak-docs memory promote --pr [--dry-run] [--force]` | Write draft + open GitHub draft PR via `gh` |
 | `ak-docs registry topology` | Print the `doc-curator` topology for AgentsKit/Registry composition |
 | `ak-docs playbook draft` | Build a draft Playbook feedback payload from local memory candidates |
+| `ak-docs playbook pattern [--text]` | Export published Doc Bridge Playbook pattern (OKF markdown / JSON) |
 | `ak-docs list <kind> [--text]` | List packages, apps, intents, … |
 | `ak-docs gate run [index-freshness]` | Check generated index freshness |
 | `ak-docs mcp` | Start MCP server (stdio default) |
+| `ak-docs mcp install --cursor \| --claude` | Write MCP server config for Cursor or Claude Desktop |
 
 ### Layer 1 — optional AgentsKit peers (`intelligence.enabled`)
 

package/docs/spec/playbook-feedback.md

@@ -66,12 +66,20 @@ mergePolicy:
   autoMerge: false
 ```
 
-## Doc Bridge Pattern Stub
+## Doc Bridge Pattern (published)
 
-The public pattern should describe the trilogy:
+Full pattern: [`docs/playbook/doc-bridge-pattern.md`](../playbook/doc-bridge-pattern.md)
+
+Export for Playbook PR:
+
+```bash
+ak-docs playbook pattern --text > doc-bridge-pattern.md
+```
+
+The pattern describes the trilogy:
 
 - `AgentHandoff`: precise editing route for coding agents.
 - OKF docs: knowledge files that can be linted and indexed.
-- Self-Describe artifacts: `llms.txt`, `capabilities.json`, and content hashes for discovery.
+- Self-describe artifacts: `llms.txt`, `capabilities.json`, and content hashes for discovery.
 
-The first automated implementation should only open a draft PR. Human review owns merge, licensing, and final wording.
+Memory-sourced findings still use `ak-docs memory promote --pr` — human review owns merge, licensing, and final wording.

package/examples/demo-example/doc-bridge.config.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 1,
+  "corpus": {
+    "agent": {
+      "root": "docs/for-agents"
+    }
+  },
+  "routing": {
+    "options": {
+      "ownership": {
+        "example": {
+          "path": "src",
+          "purpose": "Starter ownership target — replace with your real modules",
+          "checks": ["npm test"],
+          "agentDoc": "docs/for-agents/packages/example.md"
+        }
+      }
+    }
+  },
+  "gates": {
+    "preset": "minimal"
+  }
+}

package/examples/demo-example/docs/for-agents/INDEX.md

@@ -0,0 +1,3 @@
+# Agent docs index
+
+- [example](./packages/example.md) — starter ownership target

package/examples/demo-example/docs/for-agents/packages/example.md

@@ -0,0 +1,14 @@
+---
+type: package
+package: example
+editRoot: src
+checks: [npm test]
+---
+
+# example
+
+Starter agent doc for the ak-docs demo.
+
+## Checks
+
+- `npm test`

package/examples/demo-example/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "ak-docs-demo-example",
+  "private": true,
+  "scripts": {
+    "test": "node -e \"process.exit(0)\""
+  }
+}

package/examples/demo-monorepo/doc-bridge.config.json

@@ -0,0 +1,37 @@
+{
+  "schemaVersion": 1,
+  "corpus": {
+    "agent": {
+      "root": "docs/for-agents",
+      "index": "docs/for-agents/INDEX.md"
+    },
+    "human": {
+      "plugin": "plain-markdown",
+      "options": {
+        "contentDir": "docs/human",
+        "urlPrefix": "/docs"
+      }
+    }
+  },
+  "routing": {
+    "plugin": "pnpm-monorepo",
+    "options": {
+      "ownership": {
+        "auth": {
+          "path": "packages/auth",
+          "purpose": "Authentication, sessions, and token validation",
+          "checks": ["pnpm --filter @demo/auth test", "pnpm --filter @demo/auth lint"],
+          "humanDoc": "/docs/guides/auth"
+        },
+        "billing": {
+          "path": "packages/billing",
+          "purpose": "Subscriptions, invoices, and payment webhooks",
+          "checks": ["pnpm --filter @demo/billing test"]
+        }
+      }
+    }
+  },
+  "gates": {
+    "preset": "minimal"
+  }
+}

package/examples/demo-monorepo/docs/for-agents/INDEX.md

@@ -0,0 +1,4 @@
+# Agent docs index
+
+- [auth](./packages/auth.md) — authentication package
+- [billing](./packages/billing.md) — billing package

package/examples/demo-monorepo/docs/for-agents/packages/auth.md

@@ -0,0 +1,22 @@
+---
+type: package
+package: auth
+editRoot: packages/auth
+checks:
+  - pnpm --filter @demo/auth test
+  - pnpm --filter @demo/auth lint
+humanDoc: /docs/guides/auth
+---
+
+# auth
+
+Owns authentication, sessions, and token validation.
+
+## Edit roots
+
+- `packages/auth`
+
+## Checks
+
+- `pnpm --filter @demo/auth test`
+- `pnpm --filter @demo/auth lint`

package/examples/demo-monorepo/docs/for-agents/packages/billing.md

@@ -0,0 +1,19 @@
+---
+type: package
+package: billing
+editRoot: packages/billing
+checks:
+  - pnpm --filter @demo/billing test
+---
+
+# billing
+
+Owns subscriptions, invoices, and payment webhooks.
+
+## Edit roots
+
+- `packages/billing`
+
+## Checks
+
+- `pnpm --filter @demo/billing test`

package/examples/demo-monorepo/docs/human/guides/auth.md

@@ -0,0 +1,7 @@
+---
+id: guides/auth
+---
+
+# Auth guide
+
+Human-facing guide for authentication flows and session management.

package/examples/demo-monorepo/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "ak-docs-demo-monorepo",
+  "private": true,
+  "scripts": {
+    "test": "pnpm -r test"
+  }
+}

package/examples/demo-monorepo/packages/auth/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@demo/auth",
+  "private": true,
+  "scripts": {
+    "test": "node -e \"process.exit(0)\"",
+    "lint": "node -e \"process.exit(0)\""
+  }
+}

package/examples/demo-monorepo/packages/billing/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "@demo/billing",
+  "private": true,
+  "scripts": {
+    "test": "node -e \"process.exit(0)\""
+  }
+}

package/examples/demo-monorepo/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+packages:
+  - 'packages/*'

package/examples/ollama-chat.config.ts

@@ -0,0 +1,42 @@
+import { defineConfig } from '@agentskit/doc-bridge/config'
+
+/**
+ * Local Ollama chat demo — zero cloud API key.
+ *
+ * Prerequisites:
+ *   ollama serve
+ *   ollama pull llama3.2
+ *   ollama pull nomic-embed-text
+ *   npm i -D @agentskit/rag @agentskit/ink @agentskit/adapters @agentskit/memory react
+ *
+ * Then:
+ *   ak-docs index
+ *   ak-docs rag ingest
+ *   ak-docs ask "who owns auth?" --chat
+ *   ak-docs chat
+ */
+export default defineConfig({
+  schemaVersion: 1,
+  corpus: {
+    agent: { root: 'docs/for-agents' },
+  },
+  intelligence: {
+    enabled: true,
+    adapter: {
+      provider: 'ollama',
+      model: 'llama3.2',
+      baseUrl: 'http://127.0.0.1:11434',
+      options: { embedModel: 'nomic-embed-text' },
+    },
+    chat: {
+      enabled: true,
+      sources: ['agent'],
+      handoffFirst: true,
+    },
+    retriever: {
+      enabled: true,
+      mode: 'agentskit-rag',
+    },
+    runtime: 'agentskit',
+  },
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentskit/doc-bridge",
-  "version": "0.1.0-alpha.3",
+  "version": "1.0.1",
   "description": "Human↔agent documentation bridge — deterministic handoffs, doc-site links, memory→docs, optional AgentsKit RAG/chat.",
   "type": "module",
   "bin": {
@@ -21,6 +21,7 @@
   "files": [
     "dist",
     "bin",
+    "action.yml",
     "scripts/prepare.mjs",
     "docs",
     "examples",
@@ -43,12 +44,14 @@
     "smoke:packaged": "node scripts/smoke-packaged.mjs",
     "smoke:docsites": "node scripts/smoke-docsites.mjs",
     "smoke:real-docsites": "node scripts/smoke-real-docsites.mjs",
+    "smoke:ollama": "node scripts/smoke-ollama.mjs",
+    "coverage:badge": "node scripts/update-coverage-badge.mjs",
     "changeset": "changeset",
     "version-packages": "changeset version",
     "release": "pnpm build && pnpm test && changeset publish",
-    "prepublishOnly": "pnpm build && pnpm test",
+    "prepublishOnly": "npm run build && npm test",
     "prepare": "node scripts/prepare.mjs",
-    "prepack": "pnpm build"
+    "prepack": "npm run build"
   },
   "keywords": [
     "agentskit",
@@ -119,5 +122,5 @@
   "bugs": {
     "url": "https://github.com/AgentsKit-io/doc-bridge/issues"
   },
-  "homepage": "https://github.com/AgentsKit-io/doc-bridge#readme"
+  "homepage": "https://agentskit-io.github.io/doc-bridge/"
 }