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

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.0",
   "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,6 +44,8 @@
     "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",
@@ -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/"
 }

package/src/cli/demo.ts

@@ -0,0 +1,143 @@
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import type { DocBridgeConfigV1 } from '../config/schema.js'
+import { buildDocBridgeIndex } from '../index-builder/build-index.js'
+import { runGates } from '../gates/run-gates.js'
+import { mcpSnippet } from '../mcp/install.js'
+import { loadDocBridgeIndex } from '../query/load-index.js'
+import { runQuery } from '../query/query.js'
+import type { AgentHandoffV1 } from '../schemas/agent-handoff.js'
+
+export type DemoFixture = 'example' | 'monorepo'
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..')
+
+const fixturePath = (fixture: DemoFixture): string => {
+  if (fixture === 'monorepo') {
+    return join(packageRoot, 'examples', 'demo-monorepo')
+  }
+  return join(packageRoot, 'examples', 'demo-example')
+}
+
+const formatHandoffText = (handoff: AgentHandoffV1): string[] => {
+  const bridge =
+    handoff.bridge?.humanDoc === 'missing'
+      ? `human guide: missing → ${handoff.bridge.action ?? 'ak-docs bootstrap agent-docs'}`
+      : handoff.humanDoc
+        ? `human guide: ${handoff.humanDoc}`
+        : 'human guide: (none)'
+
+  return [
+    `target:  ${handoff.target.id} (${handoff.target.path ?? 'n/a'})`,
+    `start:   ${handoff.startHere}`,
+    `edit:    ${handoff.editRoots.join(', ')}`,
+    `checks:  ${handoff.checks.length ? handoff.checks.join(' · ') : '(none)'}`,
+    bridge,
+    ...(handoff.notes.length ? [`notes:   ${handoff.notes[0]}`] : []),
+  ]
+}
+
+export type DemoResult = {
+  readonly ok: boolean
+  readonly fixture: DemoFixture
+  readonly handoff: AgentHandoffV1
+  readonly gateBefore: { readonly ok: boolean; readonly message: string }
+  readonly gateAfter: { readonly ok: boolean; readonly message: string }
+  readonly mcpSnippet: string
+  readonly nextCommands: readonly string[]
+}
+
+export const runDemo = (
+  root: string,
+  config: DocBridgeConfigV1,
+  fixture: DemoFixture = 'example',
+  options: { readonly copyFixture?: boolean } = {},
+): DemoResult => {
+  const targetPackage = fixture === 'monorepo' ? 'auth' : 'example'
+  const fixtureDir = fixturePath(fixture)
+
+  if (options.copyFixture && existsSync(fixtureDir)) {
+    for (const rel of ['doc-bridge.config.json', 'docs', 'packages', 'pnpm-workspace.yaml', 'package.json']) {
+      const src = join(fixtureDir, rel)
+      if (!existsSync(src)) continue
+      const dest = join(root, rel)
+      cpSync(src, dest, { recursive: true })
+    }
+  }
+
+  const gateBeforeStale = runGates(root, config, ['index-freshness'])
+  const beforeGate = gateBeforeStale.results[0] ?? { ok: false, message: 'index-freshness unavailable' }
+
+  buildDocBridgeIndex({ root, config })
+  const index = loadDocBridgeIndex(root, config)
+  const handoff = runQuery(index, config, {
+    kind: 'package',
+    id: targetPackage,
+    agent: true,
+  }) as AgentHandoffV1
+
+  const gateAfter = runGates(root, config, ['index-freshness'])
+  const afterGate = gateAfter.results[0] ?? { ok: true, message: 'Index is fresh' }
+
+  return {
+    ok: afterGate.ok,
+    fixture,
+    handoff,
+    gateBefore: { ok: beforeGate.ok, message: beforeGate.message },
+    gateAfter: { ok: afterGate.ok, message: afterGate.message },
+    mcpSnippet: mcpSnippet(root),
+    nextCommands: [
+      `ak-docs query package ${targetPackage} --agent`,
+      'ak-docs doctor --text',
+      'ak-docs mcp install --cursor',
+      'ak-docs ask "where do I change auth?"',
+    ],
+  }
+}
+
+export const formatDemoText = (result: DemoResult): string[] => {
+  const lines = [
+    'ak-docs demo — AgentHandoff in 60s',
+    '═'.repeat(44),
+    '',
+    'Before (agent guesses package)',
+    '  ✗ edits packages/billing when task mentions "auth"',
+    '  ✗ runs repo-wide test instead of package checks',
+    '',
+    'After (handoff.resolve / query --agent)',
+    ...formatHandoffText(result.handoff).map((line) => `  ✓ ${line}`),
+    '',
+    `Gate: ${result.gateBefore.ok ? 'green' : 'red'} → ${result.gateAfter.ok ? 'green' : 'red'}`,
+    `  before: ${result.gateBefore.message}`,
+    `  after:  ${result.gateAfter.message}`,
+    '',
+    'MCP snippet (.cursor/mcp.json)',
+    ...result.mcpSnippet.split('\n').map((line) => `  ${line}`),
+    '',
+    'Next',
+    ...result.nextCommands.map((cmd) => `  → ${cmd}`),
+  ]
+  return lines
+}
+
+/** Ephemeral demo workspace for `ak-docs demo` without polluting cwd. */
+export const withDemoWorkspace = (
+  fixture: DemoFixture,
+  fn: (root: string, config: DocBridgeConfigV1) => DemoResult,
+): DemoResult => {
+  const dir = mkdtempSync(join(tmpdir(), 'ak-docs-demo-'))
+  try {
+    const fixtureDir = fixturePath(fixture)
+    if (!existsSync(fixtureDir)) {
+      throw new Error(`Demo fixture "${fixture}" not found at ${fixtureDir}`)
+    }
+    cpSync(fixtureDir, dir, { recursive: true })
+    const config = JSON.parse(readFileSync(join(dir, 'doc-bridge.config.json'), 'utf8')) as DocBridgeConfigV1
+    return fn(dir, config)
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+}