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

package/dist/cli/program.js

@@ -1,6 +1,6 @@
 // src/cli/program.ts
-import { existsSync as existsSync10, mkdirSync as mkdirSync2, readFileSync as readFileSync15, writeFileSync as writeFileSync2 } from "fs";
-import { dirname as dirname4, resolve as resolve6 } from "path";
+import { existsSync as existsSync14, mkdirSync as mkdirSync5, readFileSync as readFileSync17, writeFileSync as writeFileSync4 } from "fs";
+import { dirname as dirname7, resolve as resolve9 } from "path";
 import { createInterface } from "readline/promises";
 
 // src/config/load-config.ts
@@ -756,6 +756,11 @@ var buildLookup = (config, packages, corpus, indexOutFile, humanDocs = {}, root
       ...agentDoc ? { agentDoc } : {}
     };
     ownership[pkg.id] = record;
+    const bridge = record.humanDoc ? /^https?:\/\//.test(record.humanDoc) ? { humanDoc: "external" } : { humanDoc: "linked" } : config.corpus.human ? {
+      humanDoc: "missing",
+      action: "ak-docs bootstrap agent-docs",
+      bootstrap: `docs/for-agents/human/${pkg.id}.md`
+    } : void 0;
     handoffs[pkg.id] = {
       type: "agent-handoff",
       schemaVersion: 1,
@@ -774,7 +779,11 @@ var buildLookup = (config, packages, corpus, indexOutFile, humanDocs = {}, root
       editRoots: [record.path],
       checks: [...record.checks],
       ...record.humanDoc ? { humanDoc: record.humanDoc } : {},
-      notes: record.purpose ? [record.purpose] : []
+      ...bridge ? { bridge } : {},
+      notes: [
+        ...record.purpose ? [record.purpose] : [],
+        ...!record.humanDoc && config.corpus.human ? [`Human guide missing for ${pkg.id}. Run: ak-docs bootstrap agent-docs`] : []
+      ]
     };
   }
   const intents = {};
@@ -802,7 +811,7 @@ var buildLookup = (config, packages, corpus, indexOutFile, humanDocs = {}, root
 };
 
 // src/version.ts
-var PACKAGE_VERSION = "0.1.0-alpha.3";
+var PACKAGE_VERSION = "1.0.0";
 
 // src/index-builder/capabilities.ts
 var renderCapabilitiesJson = (config, index, paths) => {
@@ -901,10 +910,10 @@ var docId = (relToHumanRoot, raw) => {
   return meta.package ?? meta.module ?? meta.id ?? slugFromPath(relToHumanRoot);
 };
 var routeSlug = (relToHumanRoot, opts) => relToHumanRoot.split("/").filter((part) => !opts?.stripGroups || !/^\(.+\)$/.test(part)).join("/").replace(/(?:^|\/)index\.mdx?$/, "").replace(/\.mdx?$/, "");
-var humanUrl = (slug, urlPrefix) => {
-  if (typeof urlPrefix !== "string" || !urlPrefix) return slug;
+var humanUrl = (slug2, urlPrefix) => {
+  if (typeof urlPrefix !== "string" || !urlPrefix) return slug2;
   const prefix = urlPrefix.replace(/\/$/, "");
-  return slug ? `${prefix}/${slug.replace(/^\//, "")}` : prefix;
+  return slug2 ? `${prefix}/${slug2.replace(/^\//, "")}` : prefix;
 };
 var scanMarkdownDocs = (root, humanRoot, options) => {
   const out = [];
@@ -935,9 +944,9 @@ var docusaurusFileSlug = (relPath) => {
   return routeSlug(relPath);
 };
 var docusaurusSlug = (relPath, raw) => {
-  const slug = parseFrontmatter2(raw).slug;
-  if (!slug) return docusaurusFileSlug(relPath);
-  return slug.replace(/^\.\//, "").replace(/^\//, "").replace(/\/$/, "");
+  const slug2 = parseFrontmatter2(raw).slug;
+  if (!slug2) return docusaurusFileSlug(relPath);
+  return slug2.replace(/^\.\//, "").replace(/^\//, "").replace(/\/$/, "");
 };
 var docusaurusSidebarId = (relPath, raw) => {
   const id = parseFrontmatter2(raw).id;
@@ -1519,6 +1528,11 @@ var HandoffTargetSchema = z2.object({
   group: z2.string().min(1).max(128).optional(),
   layer: z2.string().min(1).max(32).optional()
 }).strict();
+var HandoffBridgeSchema = z2.object({
+  humanDoc: z2.enum(["linked", "missing", "external"]),
+  action: z2.string().min(1).max(256).optional(),
+  bootstrap: z2.string().min(1).max(256).optional()
+}).strict();
 var AgentHandoffV1Schema = z2.object({
   type: z2.literal("agent-handoff"),
   schemaVersion: z2.literal(HANDOFF_SCHEMA_VERSION).default(HANDOFF_SCHEMA_VERSION),
@@ -1529,6 +1543,7 @@ var AgentHandoffV1Schema = z2.object({
   editRoots: z2.array(z2.string().min(1).max(512)).max(32),
   checks: z2.array(z2.string().min(1).max(256)).max(32),
   humanDoc: z2.string().min(1).max(512).nullable().optional(),
+  bridge: HandoffBridgeSchema.optional(),
   playbookPatterns: z2.array(z2.string().url()).max(16).optional(),
   notes: z2.array(z2.string().min(1).max(1024)).max(16)
 }).strict();
@@ -1889,6 +1904,11 @@ var handoffForPackage = (index, id, config) => {
   if (fromIndex) return normalizeAgentHandoff(fromIndex);
   const owner = index.lookup?.ownership?.[id];
   if (!owner) throw new Error(`Unknown package/ownership id "${id}". Try: ak-docs list packages`);
+  const bridge = owner.humanDoc ? /^https?:\/\//.test(owner.humanDoc) ? { humanDoc: "external" } : { humanDoc: "linked" } : config.corpus.human ? {
+    humanDoc: "missing",
+    action: "ak-docs bootstrap agent-docs",
+    bootstrap: `docs/for-agents/human/${id}.md`
+  } : void 0;
   return normalizeAgentHandoff({
     type: "agent-handoff",
     source: config.index?.outFile ?? ".doc-bridge/index.json",
@@ -1904,7 +1924,11 @@ var handoffForPackage = (index, id, config) => {
     editRoots: [owner.path],
     checks: [...owner.checks],
     ...owner.humanDoc ? { humanDoc: owner.humanDoc } : {},
-    notes: owner.purpose ? [owner.purpose] : []
+    ...bridge ? { bridge } : {},
+    notes: [
+      ...owner.purpose ? [owner.purpose] : [],
+      ...!owner.humanDoc && config.corpus.human ? [`Human guide missing for ${id}. Run: ak-docs bootstrap agent-docs`] : []
+    ]
   });
 };
 var runQuery = (index, config, req) => {
@@ -2039,6 +2063,18 @@ var readEnv = (name) => {
   const value = process.env[name];
   return value && value.length > 0 ? value : void 0;
 };
+var providerDefaultApiKeyEnv = (provider) => {
+  switch (provider) {
+    case "openai":
+      return "OPENAI_API_KEY";
+    case "anthropic":
+      return "ANTHROPIC_API_KEY";
+    case "openrouter":
+      return "OPENROUTER_API_KEY";
+    default:
+      return void 0;
+  }
+};
 var resolveIntelligenceRuntime = async (config) => {
   if (!config.intelligence?.enabled) {
     throw new Error("Intelligence is disabled. Set intelligence.enabled: true in doc-bridge config.");
@@ -2050,7 +2086,7 @@ var resolveIntelligenceRuntime = async (config) => {
   const adapters = await importPeer("@agentskit/adapters");
   const provider = adapterCfg.provider;
   const model = adapterCfg.model;
-  const apiKey = readEnv(adapterCfg.apiKeyEnv) ?? readEnv("OPENAI_API_KEY") ?? readEnv("ANTHROPIC_API_KEY");
+  const apiKey = readEnv(adapterCfg.apiKeyEnv) ?? readEnv(providerDefaultApiKeyEnv(provider));
   const baseUrl = adapterCfg.baseUrl;
   let adapter;
   let embed;
@@ -2377,9 +2413,752 @@ var draftMemoryPromotion = (classifications) => {
   };
 };
 
+// src/memory/github-pr.ts
+import { execFileSync, spawnSync } from "child_process";
+import { existsSync as existsSync10, mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "fs";
+import { join as join15 } from "path";
+var run = (cmd, args, cwd) => {
+  const result = spawnSync(cmd, [...args], { cwd, encoding: "utf8" });
+  const out = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
+  return { ok: result.status === 0, out };
+};
+var hasGh = () => run("gh", ["--version"], process.cwd()).ok;
+var slug = () => (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19);
+var defaultPromotionDraftPath = (root) => join15(root, ".doc-bridge", "drafts", `memory-promotion-${slug()}.md`);
+var writePromotionDraft = (root, draft, path) => {
+  const draftPath = path ?? defaultPromotionDraftPath(root);
+  mkdirSync2(join15(root, ".doc-bridge", "drafts"), { recursive: true });
+  writeFileSync2(draftPath, `${draft.body}
+`, "utf8");
+  return draftPath;
+};
+var promoteMemoryToGithubPr = (root, draft, options = {}) => {
+  if (!draft.ok && !options.force) {
+    return {
+      ok: false,
+      dryRun: Boolean(options.dryRun),
+      draftPath: "",
+      branch: "",
+      commands: [],
+      message: "Safety scan blocked promotion. Fix findings or pass --force to draft anyway."
+    };
+  }
+  const branch = options.branch ?? `doc-bridge/memory-promotion-${slug()}`;
+  const draftPath = writePromotionDraft(root, draft);
+  const relDraft = draftPath.startsWith(`${root}/`) ? draftPath.slice(root.length + 1) : draftPath;
+  const commands = [
+    `git checkout -b ${branch}`,
+    `git add ${relDraft}`,
+    `git commit -m "draft: doc-bridge memory promotion"`,
+    `git push -u origin ${branch}`,
+    `gh pr create --draft --title "${draft.title}" --body-file ${relDraft}${options.base ? ` --base ${options.base}` : ""}`
+  ];
+  if (options.dryRun) {
+    return {
+      ok: true,
+      dryRun: true,
+      draftPath,
+      branch,
+      commands,
+      message: `Wrote draft to ${relDraft}. Run the printed git/gh commands to open a draft PR.`
+    };
+  }
+  if (!existsSync10(join15(root, ".git"))) {
+    return {
+      ok: false,
+      dryRun: false,
+      draftPath,
+      branch,
+      commands,
+      message: "Not a git repository. Commit the draft manually or run with --dry-run."
+    };
+  }
+  if (!hasGh()) {
+    return {
+      ok: false,
+      dryRun: false,
+      draftPath,
+      branch,
+      commands,
+      message: "GitHub CLI (gh) not found. Install gh or use --dry-run for local draft + commands."
+    };
+  }
+  const auth = run("gh", ["auth", "status"], root);
+  if (!auth.ok) {
+    return {
+      ok: false,
+      dryRun: false,
+      draftPath,
+      branch,
+      commands,
+      message: `gh is not authenticated. Run: gh auth login
+${auth.out}`
+    };
+  }
+  const checkout = run("git", ["checkout", "-b", branch], root);
+  if (!checkout.ok) {
+    return {
+      ok: false,
+      dryRun: false,
+      draftPath,
+      branch,
+      commands,
+      message: `git checkout failed: ${checkout.out}`
+    };
+  }
+  run("git", ["add", relDraft], root);
+  const commit = run("git", ["commit", "-m", "draft: doc-bridge memory promotion"], root);
+  if (!commit.ok) {
+    return {
+      ok: false,
+      dryRun: false,
+      draftPath,
+      branch,
+      commands,
+      message: `git commit failed: ${commit.out}`
+    };
+  }
+  const push = run("git", ["push", "-u", "origin", branch], root);
+  if (!push.ok) {
+    return {
+      ok: false,
+      dryRun: false,
+      draftPath,
+      branch,
+      commands,
+      message: `git push failed: ${push.out}`
+    };
+  }
+  const prArgs = [
+    "pr",
+    "create",
+    "--draft",
+    "--title",
+    draft.title,
+    "--body-file",
+    relDraft,
+    ...options.base ? ["--base", options.base] : []
+  ];
+  let prUrl = "";
+  try {
+    prUrl = execFileSync("gh", prArgs, { cwd: root, encoding: "utf8" }).trim();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      ok: false,
+      dryRun: false,
+      draftPath,
+      branch,
+      commands,
+      message: `gh pr create failed: ${message}`
+    };
+  }
+  return {
+    ok: true,
+    dryRun: false,
+    draftPath,
+    branch,
+    prUrl,
+    ...prUrl ? { previewUrl: prUrl } : {},
+    commands,
+    message: prUrl ? `Draft PR opened: ${prUrl}` : "Draft PR created."
+  };
+};
+
+// src/index-builder/watch-index.ts
+import { existsSync as existsSync11, watch } from "fs";
+import { dirname as dirname4, resolve as resolve5 } from "path";
+var WATCH_PATTERN = /\.(md|mdx|json|ya?ml|mdc)$/i;
+var collectWatchRoots = (root, config, configPath) => {
+  const roots = /* @__PURE__ */ new Set();
+  roots.add(resolve5(root, config.corpus.agent.root));
+  const humanSources = config.corpus.human ? Array.isArray(config.corpus.human) ? config.corpus.human : [config.corpus.human] : [];
+  for (const source of humanSources) {
+    const humanOpts = source.options ?? {};
+    for (const key of ["contentDir", "docsDir", "root"]) {
+      const value = humanOpts[key];
+      if (typeof value === "string" && value.length) roots.add(resolve5(root, value));
+    }
+  }
+  if (configPath) roots.add(dirname4(resolve5(configPath)));
+  return [...roots].filter((dir) => existsSync11(dir));
+};
+var watchDocBridgeIndex = (opts) => {
+  const debounceMs = opts.debounceMs ?? 350;
+  let timer;
+  let running = false;
+  const rebuild = () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      if (running) return;
+      running = true;
+      try {
+        const result = buildDocBridgeIndex({ root: opts.root, config: opts.config });
+        const handoffCount = Object.keys(result.index.handoffs ?? {}).length;
+        const summary = {
+          knowledgeCount: result.index.knowledge.length,
+          handoffCount,
+          hash: result.index.contentHash.slice(0, 8)
+        };
+        opts.onRebuild?.(summary);
+        process.stdout.write(
+          `[ak-docs] indexed ${summary.knowledgeCount} docs, ${summary.handoffCount} handoffs (${summary.hash}\u2026)
+`
+        );
+      } catch (error) {
+        process.stderr.write(
+          `[ak-docs] index failed: ${error instanceof Error ? error.message : String(error)}
+`
+        );
+      } finally {
+        running = false;
+      }
+    }, debounceMs);
+  };
+  rebuild();
+  for (const dir of collectWatchRoots(opts.root, opts.config, opts.configPath)) {
+    watch(dir, { recursive: true }, (_event, filename) => {
+      if (!filename || !WATCH_PATTERN.test(filename)) return;
+      rebuild();
+    });
+  }
+  const configDir = resolve5(opts.root);
+  if (existsSync11(configDir)) {
+    watch(configDir, (_event, filename) => {
+      if (!filename || !/doc-bridge\.config/.test(filename)) return;
+      rebuild();
+    });
+  }
+  process.stdout.write(
+    `[ak-docs] watching ${collectWatchRoots(opts.root, opts.config, opts.configPath).join(", ") || opts.root} (Ctrl+C to stop)
+`
+  );
+  return new Promise((resolvePromise) => {
+    const onSignal = () => resolvePromise(0);
+    process.once("SIGINT", onSignal);
+    process.once("SIGTERM", onSignal);
+  });
+};
+
+// src/doctor/badge.ts
+var doctorBadgeMetrics = (report) => {
+  const { packages } = report.coverage;
+  const handoffPct = packages.total > 0 ? Math.round(packages.withAgentDoc / packages.total * 100) : 0;
+  const bridgePct = packages.total > 0 ? Math.round(packages.withHumanDoc / packages.total * 100) : 0;
+  return {
+    handoffPct,
+    bridgePct,
+    score: report.score,
+    grade: report.grade,
+    packages: packages.total
+  };
+};
+var badgeColor = (pct) => {
+  if (pct >= 80) return "2ea44f";
+  if (pct >= 50) return "dbab09";
+  return "cb2431";
+};
+var formatDoctorBadgeMarkdown = (metrics) => {
+  const handoff = `handoff_coverage-${metrics.handoffPct}%25-${badgeColor(metrics.handoffPct)}`;
+  const bridge = `human_bridge-${metrics.bridgePct}%25-${badgeColor(metrics.bridgePct)}`;
+  return [
+    `![handoff coverage](https://img.shields.io/badge/${handoff}?style=flat-square)`,
+    `![human bridge](https://img.shields.io/badge/${bridge}?style=flat-square)`,
+    `![doc-bridge score](https://img.shields.io/badge/doc--bridge_score-${metrics.score}%2F100-${badgeColor(metrics.score)}?style=flat-square)`
+  ].join(" ");
+};
+var formatDoctorBadgeJson = (metrics) => JSON.stringify(
+  {
+    schemaVersion: 1,
+    ...metrics,
+    markdown: formatDoctorBadgeMarkdown(metrics),
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  },
+  null,
+  2
+);
+
+// src/playbook/doc-bridge-pattern.ts
+var DOC_BRIDGE_PATTERN_ID = "doc-bridge-pattern";
+var DOC_BRIDGE_PATTERN_META = {
+  id: DOC_BRIDGE_PATTERN_ID,
+  title: "Doc Bridge Pattern",
+  slug: "pillars/ai-collaboration/doc-bridge-pattern",
+  license: "CC-BY-4.0",
+  visibility: "public",
+  playbookUrl: "https://playbook.agentskit.io/patterns/doc-bridge-pattern",
+  npmPackage: "@agentskit/doc-bridge",
+  cli: "ak-docs"
+};
+var docBridgePatternMarkdown = () => `---
+type: pattern
+id: ${DOC_BRIDGE_PATTERN_ID}
+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** \u2014 deterministic routing so agents edit the right roots, run the right checks, and stay linked to human documentation.
+
+## 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 \u2194 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"\` \u2014 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\` \u2014 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
+- Fumadocus / 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)
+
+## References
+
+- npm: https://www.npmjs.com/package/@agentskit/doc-bridge
+- repo: https://github.com/AgentsKit-io/doc-bridge
+- skill: https://github.com/AgentsKit-io/doc-bridge/blob/master/docs/skills/doc-bridge.md
+- landing: https://agentskit-io.github.io/doc-bridge/
+`;
+var docBridgePatternPayload = () => ({
+  ...DOC_BRIDGE_PATTERN_META,
+  format: "okf-pattern-v1",
+  body: docBridgePatternMarkdown()
+});
+
+// src/cli/demo.ts
+import { cpSync, existsSync as existsSync13, mkdtempSync, readFileSync as readFileSync15, rmSync } from "fs";
+import { tmpdir } from "os";
+import { dirname as dirname6, join as join18, resolve as resolve7 } from "path";
+import { fileURLToPath } from "url";
+
+// src/mcp/install.ts
+import { existsSync as existsSync12, mkdirSync as mkdirSync3, readFileSync as readFileSync14, writeFileSync as writeFileSync3 } from "fs";
+import { homedir } from "os";
+import { dirname as dirname5, join as join17, resolve as resolve6 } from "path";
+var SERVER_NAME = "ak-docs";
+var mcpServerEntry = (root) => ({
+  command: "npx",
+  args: ["ak-docs", "mcp"],
+  cwd: root
+});
+var readJson = (path) => {
+  if (!existsSync12(path)) return {};
+  try {
+    const parsed = JSON.parse(readFileSync14(path, "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+};
+var writeJson = (path, value) => {
+  mkdirSync3(dirname5(path), { recursive: true });
+  writeFileSync3(path, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+};
+var resolveTargetPath = (target, root) => {
+  if (target === "cursor") return resolve6(root, ".cursor", "mcp.json");
+  return join17(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+};
+var installMcpConfig = (root, target) => {
+  const configPath = resolveTargetPath(target, root);
+  const created = !existsSync12(configPath);
+  const existing = readJson(configPath);
+  const servers = existing.mcpServers && typeof existing.mcpServers === "object" && !Array.isArray(existing.mcpServers) ? { ...existing.mcpServers } : {};
+  servers[SERVER_NAME] = mcpServerEntry(root);
+  writeJson(configPath, { ...existing, mcpServers: servers });
+  const nextSteps = target === "cursor" ? [
+    "Restart Cursor or reload MCP servers",
+    "Paste the doc-bridge skill into Cursor rules (see docs/skills/doc-bridge.md)",
+    "Before editing packages/* call handoff.resolve"
+  ] : [
+    "Restart Claude Desktop",
+    "Run ak-docs index after doc changes"
+  ];
+  return {
+    ok: true,
+    target,
+    configPath,
+    created,
+    serverName: SERVER_NAME,
+    nextSteps
+  };
+};
+var mcpSnippet = (root) => JSON.stringify({ mcpServers: { [SERVER_NAME]: mcpServerEntry(root) } }, null, 2);
+
+// src/cli/demo.ts
+var packageRoot = resolve7(dirname6(fileURLToPath(import.meta.url)), "..", "..");
+var fixturePath = (fixture) => {
+  if (fixture === "monorepo") {
+    return join18(packageRoot, "examples", "demo-monorepo");
+  }
+  return join18(packageRoot, "examples", "demo-example");
+};
+var formatHandoffText = (handoff) => {
+  const bridge = handoff.bridge?.humanDoc === "missing" ? `human guide: missing \u2192 ${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(" \xB7 ") : "(none)"}`,
+    bridge,
+    ...handoff.notes.length ? [`notes:   ${handoff.notes[0]}`] : []
+  ];
+};
+var runDemo = (root, config, fixture = "example", options = {}) => {
+  const targetPackage = fixture === "monorepo" ? "auth" : "example";
+  const fixtureDir = fixturePath(fixture);
+  if (options.copyFixture && existsSync13(fixtureDir)) {
+    for (const rel of ["doc-bridge.config.json", "docs", "packages", "pnpm-workspace.yaml", "package.json"]) {
+      const src = join18(fixtureDir, rel);
+      if (!existsSync13(src)) continue;
+      const dest = join18(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
+  });
+  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?"'
+    ]
+  };
+};
+var formatDemoText = (result) => {
+  const lines = [
+    "ak-docs demo \u2014 AgentHandoff in 60s",
+    "\u2550".repeat(44),
+    "",
+    "Before (agent guesses package)",
+    '  \u2717 edits packages/billing when task mentions "auth"',
+    "  \u2717 runs repo-wide test instead of package checks",
+    "",
+    "After (handoff.resolve / query --agent)",
+    ...formatHandoffText(result.handoff).map((line) => `  \u2713 ${line}`),
+    "",
+    `Gate: ${result.gateBefore.ok ? "green" : "red"} \u2192 ${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) => `  \u2192 ${cmd}`)
+  ];
+  return lines;
+};
+var withDemoWorkspace = (fixture, fn) => {
+  const dir = mkdtempSync(join18(tmpdir(), "ak-docs-demo-"));
+  try {
+    const fixtureDir = fixturePath(fixture);
+    if (!existsSync13(fixtureDir)) {
+      throw new Error(`Demo fixture "${fixture}" not found at ${fixtureDir}`);
+    }
+    cpSync(fixtureDir, dir, { recursive: true });
+    const config = JSON.parse(readFileSync15(join18(dir, "doc-bridge.config.json"), "utf8"));
+    return fn(dir, config);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+};
+
+// src/doctor/run-doctor.ts
+var gradeForScore = (score) => {
+  if (score >= 90) return "A";
+  if (score >= 75) return "B";
+  if (score >= 60) return "C";
+  if (score >= 40) return "D";
+  return "F";
+};
+var agentDocPaths = (index) => {
+  const paths = /* @__PURE__ */ new Set();
+  for (const owner of Object.values(index.lookup?.ownership ?? {})) {
+    if (owner.agentDoc) paths.add(owner.agentDoc);
+  }
+  for (const handoff of Object.values(index.handoffs ?? {})) {
+    if (handoff.startHere) paths.add(handoff.startHere);
+  }
+  return paths;
+};
+var computeScore = (coverage) => {
+  let score = 0;
+  if (coverage.freshness.hasIndex) score += 15;
+  if (coverage.freshness.ok) score += 15;
+  const { total, withAgentDoc, withHumanDoc } = coverage.packages;
+  if (total > 0) {
+    score += Math.round(withAgentDoc / total * 35);
+    score += Math.round(withHumanDoc / total * 20);
+  } else if (coverage.agentDocs.indexed > 0) {
+    score += 35;
+  }
+  if (coverage.gates.ok) score += 15;
+  else {
+    const passed = coverage.gates.results.filter((gate) => gate.ok).length;
+    const totalGates = coverage.gates.results.length || 1;
+    score += Math.round(passed / totalGates * 10);
+  }
+  return Math.min(100, Math.max(0, score));
+};
+var buildIssues = (coverage) => {
+  const issues = [];
+  if (!coverage.freshness.hasIndex) {
+    issues.push({
+      severity: "error",
+      code: "index-missing",
+      message: "No doc-bridge index found.",
+      action: "ak-docs index"
+    });
+  } else if (!coverage.freshness.ok) {
+    issues.push({
+      severity: "error",
+      code: "index-stale",
+      message: coverage.freshness.message,
+      action: "ak-docs index"
+    });
+  }
+  for (const id of coverage.packages.missingAgentDoc) {
+    issues.push({
+      severity: "warn",
+      code: "missing-agent-doc",
+      message: `Package "${id}" has no dedicated agent doc.`,
+      action: `ak-docs init --scaffold-workspaces  # or edit docs/for-agents/packages/${id}.md`
+    });
+  }
+  for (const id of coverage.packages.missingHumanDoc) {
+    issues.push({
+      severity: "info",
+      code: "missing-human-doc",
+      message: `Package "${id}" has no linked human guide.`,
+      action: "ak-docs bootstrap agent-docs"
+    });
+  }
+  for (const gate of coverage.gates.results.filter((result) => !result.ok)) {
+    issues.push({
+      severity: gate.id === "index-freshness" ? "error" : "warn",
+      code: `gate-${gate.id}`,
+      message: gate.message,
+      action: gate.id === "index-freshness" ? "ak-docs index" : "ak-docs gate run"
+    });
+  }
+  return issues;
+};
+var buildNextActions = (issues, coverage) => {
+  const actions = /* @__PURE__ */ new Set();
+  for (const issue of issues) {
+    if (issue.action) actions.add(issue.action);
+  }
+  if (!coverage.freshness.hasIndex || !coverage.freshness.ok) {
+    actions.add("ak-docs index");
+  }
+  if (coverage.packages.missingHumanDoc.length) {
+    actions.add("ak-docs bootstrap agent-docs");
+  }
+  if (coverage.packages.total > 0) {
+    const sample = coverage.packages.missingAgentDoc[0] ?? coverage.packages.missingHumanDoc[0];
+    if (sample) actions.add(`ak-docs query package ${sample} --agent`);
+  }
+  if (!actions.size) {
+    actions.add("ak-docs mcp install --cursor");
+    actions.add("ak-docs gate run");
+  }
+  return [...actions].slice(0, 6);
+};
+var runDoctor = (root, config) => {
+  let index;
+  let hasIndex = true;
+  let freshnessOk = false;
+  let freshnessMessage = "Index is fresh";
+  try {
+    index = loadDocBridgeIndex(root, config);
+    const next = buildDocBridgeIndex({ root, config, write: false }).index.contentHash;
+    freshnessOk = index.contentHash === next;
+    freshnessMessage = freshnessOk ? "Index is fresh" : "Index is stale. Run: ak-docs index";
+  } catch (error) {
+    if (error instanceof IndexNotFoundError) {
+      hasIndex = false;
+      freshnessOk = false;
+      freshnessMessage = error.message;
+      index = buildDocBridgeIndex({ root, config, write: false }).index;
+    } else {
+      throw error;
+    }
+  }
+  const ownership = Object.entries(index.lookup?.ownership ?? {});
+  const missingAgentDoc = ownership.filter(([, owner]) => !owner.agentDoc || owner.agentDoc === config.corpus.agent.index).map(([id]) => id);
+  const missingHumanDoc = ownership.filter(([, owner]) => !owner.humanDoc).map(([id]) => id);
+  const indexedPaths = new Set(index.knowledge.map((entry) => entry.path));
+  const expectedAgentDocs = agentDocPaths(index);
+  const unindexed = [...expectedAgentDocs].filter((path) => !indexedPaths.has(path));
+  const corpusDocs = scanAgentCorpus(root, config).filter(
+    (doc) => doc.path !== config.corpus.agent.index
+  );
+  const gates = runGates(root, config);
+  const coverage = {
+    packages: {
+      total: ownership.length,
+      withAgentDoc: ownership.length - missingAgentDoc.length,
+      withHumanDoc: ownership.length - missingHumanDoc.length,
+      missingAgentDoc,
+      missingHumanDoc
+    },
+    agentDocs: {
+      total: corpusDocs.length,
+      indexed: corpusDocs.filter((doc) => indexedPaths.has(doc.path)).length,
+      unindexed: corpusDocs.filter((doc) => !indexedPaths.has(doc.path)).map((doc) => doc.path)
+    },
+    freshness: {
+      ok: freshnessOk,
+      message: freshnessMessage,
+      hasIndex
+    },
+    gates
+  };
+  const issues = buildIssues(coverage);
+  const score = computeScore(coverage);
+  const nextActions = buildNextActions(issues, coverage);
+  const report = {
+    ok: issues.every((issue) => issue.severity !== "error") && gates.ok,
+    score,
+    grade: gradeForScore(score),
+    coverage,
+    badge: { handoffPct: 0, bridgePct: 0, score, grade: gradeForScore(score), packages: 0 },
+    issues,
+    nextActions
+  };
+  return { ...report, badge: doctorBadgeMetrics(report) };
+};
+var formatDoctorText = (report) => {
+  const { coverage } = report;
+  const handoffPct = coverage.packages.total > 0 ? Math.round(coverage.packages.withAgentDoc / coverage.packages.total * 100) : 0;
+  const humanPct = coverage.packages.total > 0 ? Math.round(coverage.packages.withHumanDoc / coverage.packages.total * 100) : 0;
+  const lines = [
+    "doc-bridge doctor",
+    "\u2500".repeat(40),
+    `Score: ${report.score}/100 (${report.grade})`,
+    "",
+    "Coverage",
+    `  Packages:        ${coverage.packages.total}`,
+    `  Agent docs:      ${coverage.packages.withAgentDoc}/${coverage.packages.total} (${handoffPct}% handoff-ready)`,
+    `  Human guides:    ${coverage.packages.withHumanDoc}/${coverage.packages.total} (${humanPct}% bridged)`,
+    `  Corpus indexed:  ${coverage.agentDocs.indexed}/${coverage.agentDocs.total} agent docs`,
+    `  Index freshness: ${coverage.freshness.ok ? "fresh" : "stale or missing"}`,
+    `  Gates:           ${coverage.gates.results.filter((g) => g.ok).length}/${coverage.gates.results.length} passing`,
+    `  Badge:           handoff ${report.badge.handoffPct}% \xB7 bridge ${report.badge.bridgePct}%`
+  ];
+  if (coverage.packages.missingHumanDoc.length) {
+    lines.push("", "Missing humanDoc (bridge gap)", ...coverage.packages.missingHumanDoc.map((id) => `  \u2022 ${id}`));
+  }
+  if (coverage.packages.missingAgentDoc.length) {
+    lines.push("", "Missing agent doc", ...coverage.packages.missingAgentDoc.map((id) => `  \u2022 ${id}`));
+  }
+  if (report.issues.length) {
+    lines.push("", "Issues");
+    for (const issue of report.issues.slice(0, 8)) {
+      const icon = issue.severity === "error" ? "\u2717" : issue.severity === "warn" ? "!" : "\xB7";
+      lines.push(`  ${icon} [${issue.code}] ${issue.message}`);
+    }
+    if (report.issues.length > 8) {
+      lines.push(`  \u2026 +${report.issues.length - 8} more`);
+    }
+  }
+  lines.push("", "Next actions", ...report.nextActions.map((action) => `  \u2192 ${action}`));
+  return lines;
+};
+
 // src/mcp/server.ts
-import { readFileSync as readFileSync14, realpathSync } from "fs";
-import { relative, resolve as resolve5 } from "path";
+import { readFileSync as readFileSync16, realpathSync } from "fs";
+import { relative, resolve as resolve8 } from "path";
 import { z as z5, ZodError } from "zod";
 var MCP_TOOLS = [
   {
@@ -2486,7 +3265,7 @@ var findDocPath = (index, args) => {
 };
 var resolveDocPath = (root, relPath) => {
   const rootAbs = realpathSync.native(root);
-  const unresolved = resolve5(rootAbs, relPath);
+  const unresolved = resolve8(rootAbs, relPath);
   const unresolvedRel = relative(rootAbs, unresolved);
   if (unresolvedRel.startsWith("..")) throw new Error("doc.get path escapes project root");
   const abs = realpathSync.native(unresolved);
@@ -2524,7 +3303,7 @@ var handleMcpRequest = (ctx, request) => {
     }
     if (name === "doc.get") {
       const relPath = findDocPath(index(), parseToolArgs("doc.get", DocGetArgsSchema, args));
-      return textResult(readFileSync14(resolveDocPath(ctx.root, relPath), "utf8"));
+      return textResult(readFileSync16(resolveDocPath(ctx.root, relPath), "utf8"));
     }
     if (name === "gate.status") return textResult(runGates(ctx.root, ctx.config));
     if (name === "retriever.query") {
@@ -2606,14 +3385,17 @@ var usage = `ak-docs \u2014 human\u2194agent documentation bridge (@agentskit/do
 
 Core (no API key):
   ak-docs init [--demo] [--scaffold-workspaces]
-  ak-docs index
+  ak-docs demo [--fixture example|monorepo] [--text] [--in-project]
+  ak-docs doctor [--text] [--badge] [--write-badge]
+  ak-docs index [--watch]
   ak-docs query <package|ownership|intent|change> <id> [--agent] [--text]
   ak-docs search <term> [--agent] [--text]
   ak-docs list <packages|intents|changes|knowledge> [--text]
   ak-docs ask [question]          local consult (no LLM)
   ak-docs gate run [gate-id]
   ak-docs mcp
-  ak-docs memory ingest|classify|promote
+  ak-docs mcp install --cursor | --claude
+  ak-docs memory ingest|classify|promote [--pr] [--dry-run]
   ak-docs bootstrap agent-docs
   ak-docs validate-config | validate-handoff <file>
 
@@ -2625,7 +3407,7 @@ Intelligence (optional AgentsKit peers):
 Advanced / ecosystem:
   ak-docs retrieve <query>
   ak-docs registry topology
-  ak-docs playbook draft
+  ak-docs playbook draft | pattern [--text]
 
 Global flags:
   -h, --help   --version
@@ -2666,6 +3448,8 @@ var parseArgs = (argv) => {
   else if (positional[0] === "index") command = "index";
   else if (positional[0] === "gate") command = "gate";
   else if (positional[0] === "mcp") command = "mcp";
+  else if (positional[0] === "doctor") command = "doctor";
+  else if (positional[0] === "demo") command = "demo";
   else if (positional[0] === "query") command = "query";
   else if (positional[0] === "search") command = "search";
   else if (positional[0] === "retrieve") command = "retrieve";
@@ -2675,7 +3459,7 @@ var parseArgs = (argv) => {
   else if (positional[0] === "list") command = "list";
   return { command, flags, configPath, positional };
 };
-var writeJson = (payload) => {
+var writeJson2 = (payload) => {
   process.stdout.write(`${JSON.stringify(payload, null, 2)}
 `);
 };
@@ -2723,13 +3507,33 @@ var writeTextSearch = (term, matches) => {
     ...matches.length ? matches.map(formatSearchMatch) : ["  (none)"]
   ]);
 };
-var writeAsk = (question, matches, index) => {
+var handoffSummaryLines = (index, config, ownerId) => {
+  try {
+    const handoff = runQuery(index, config, { kind: "ownership", id: ownerId, agent: true });
+    if (!handoff || typeof handoff !== "object" || !("editRoots" in handoff)) return [];
+    const payload = handoff;
+    const bridgeLine = payload.bridge?.humanDoc === "missing" ? `Bridge: human guide missing \u2192 ${payload.bridge.action ?? "ak-docs bootstrap agent-docs"}` : payload.humanDoc ? `Bridge: ${payload.humanDoc}` : "Bridge: (no human plugin configured)";
+    return [
+      "",
+      "Handoff preview",
+      `  start:  ${payload.startHere ?? "(unknown)"}`,
+      `  edit:   ${(payload.editRoots ?? []).join(", ") || "(none)"}`,
+      `  checks: ${(payload.checks ?? []).join(" \xB7 ") || "(none)"}`,
+      `  ${bridgeLine}`
+    ];
+  } catch {
+    return [];
+  }
+};
+var writeAsk = (question, matches, index, config) => {
   const owner = matches.find((match) => match.type === "ownership") ?? matches.find((match) => Boolean(index.lookup?.ownership?.[match.id]));
   const best = owner ?? matches[0];
-  const bestQuery = best && (best.type === "ownership" || index.lookup?.ownership?.[best.id]) ? `ak-docs query ownership ${best.id} --agent` : "ak-docs list knowledge --text";
+  const ownerId = best && (best.type === "ownership" || index.lookup?.ownership?.[best.id]) ? best.id : void 0;
+  const bestQuery = ownerId ? `ak-docs query ownership ${ownerId} --agent` : "ak-docs list knowledge --text";
   writeLines([
     `Question: ${question}`,
     best ? `Best match: ${best.type} ${best.id} (${best.path})` : "Best match: none",
+    ...ownerId ? handoffSummaryLines(index, config, ownerId) : [],
     "",
     "Matches:",
     ...matches.length ? matches.slice(0, 5).map(formatSearchMatch) : ["  No local matches. Try: ak-docs search <term>"],
@@ -2737,20 +3541,21 @@ var writeAsk = (question, matches, index) => {
     "Next commands:",
     ...best ? [
       `ak-docs search "${question}" --agent`,
-      bestQuery
-    ] : ["ak-docs list knowledge --text"]
+      bestQuery,
+      ...ownerId ? [`ak-docs doctor --text`] : []
+    ] : ["ak-docs list knowledge --text", "ak-docs doctor --text"]
   ]);
 };
 var readIndexedDoc = (root, config, idOrPath) => {
   const index = loadDocBridgeIndex(root, config);
   const entry = index.knowledge.find((doc) => doc.id === idOrPath || doc.path === idOrPath);
   if (!entry) throw new Error(`Unknown indexed doc "${idOrPath}". Try: search ${idOrPath}`);
-  const abs = resolve6(root, entry.path);
-  const rootAbs = resolve6(root);
+  const abs = resolve9(root, entry.path);
+  const rootAbs = resolve9(root);
   if (abs !== rootAbs && !abs.startsWith(`${rootAbs}/`)) {
     throw new Error(`Indexed doc escapes project root: ${entry.path}`);
   }
-  return readFileSync15(abs, "utf8");
+  return readFileSync17(abs, "utf8");
 };
 var runAskRepl = async (root, config) => {
   const index = loadDocBridgeIndex(root, config);
@@ -2769,12 +3574,12 @@ var runAskRepl = async (root, config) => {
           process.stdout.write(`${readIndexedDoc(root, config, value).slice(0, 8e3)}
 `);
         } else if (command === "resolve") {
-          writeJson(runQuery(index, config, { kind: "ownership", id: value, agent: true }));
+          writeJson2(runQuery(index, config, { kind: "ownership", id: value, agent: true }));
         } else if (command === "gate") {
           const gateId = value || void 0;
-          writeJson(runGates(root, config, gateId ? [gateId] : void 0));
+          writeJson2(runGates(root, config, gateId ? [gateId] : void 0));
         } else {
-          writeAsk(line, searchIndex(index, line, 8), index);
+          writeAsk(line, searchIndex(index, line, 8), index, config);
         }
       } catch (error) {
         process.stderr.write(`${error instanceof Error ? error.message : String(error)}
@@ -2826,9 +3631,9 @@ var diagnosticNextCommands = (config, result) => {
   ];
 };
 var writeIfMissing = (path, contents) => {
-  if (existsSync10(path)) return false;
-  mkdirSync2(dirname4(path), { recursive: true });
-  writeFileSync2(path, contents, "utf8");
+  if (existsSync14(path)) return false;
+  mkdirSync5(dirname7(path), { recursive: true });
+  writeFileSync4(path, contents, "utf8");
   return true;
 };
 var demoOwnership = {
@@ -2931,7 +3736,7 @@ var scaffoldWorkspaceDocs = (root, config) => {
   const created = [];
   const skipped = [];
   for (const pkg of discoverPnpmPackages(root, config)) {
-    const path = resolve6(root, config.corpus.agent.root, "packages", `${pkg.id}.md`);
+    const path = resolve9(root, config.corpus.agent.root, "packages", `${pkg.id}.md`);
     if (writeIfMissing(path, workspaceDocDraft(pkg.id, pkg.path))) created.push(path);
     else skipped.push(path);
   }
@@ -2941,11 +3746,11 @@ var bootstrapAgentDocs = (root, config) => {
   const created = [];
   const skipped = [];
   for (const doc of scanHumanDocRecords(root, config)) {
-    const raw = readFileSync15(doc.path, "utf8");
+    const raw = readFileSync17(doc.path, "utf8");
     const body = raw.replace(/^---\n[\s\S]*?\n---\n?/, "");
     const title = firstHeading(body) ?? doc.id;
     const description = firstParagraph(body);
-    const draftPath = resolve6(root, config.corpus.agent.root, "human", `${doc.id}.md`);
+    const draftPath = resolve9(root, config.corpus.agent.root, "human", `${doc.id}.md`);
     const draft = [
       "---",
       "type: knowledge",
@@ -2994,7 +3799,7 @@ var runCli = (argv) => {
         configPath ? { explicitPath: configPath } : {}
       );
       parseDocBridgeConfig(config);
-      writeJson({ ok: true, path, schemaVersion: config.schemaVersion });
+      writeJson2({ ok: true, path, schemaVersion: config.schemaVersion });
       return 0;
     } catch (error) {
       process.stderr.write(`${error instanceof Error ? error.message : String(error)}
@@ -3009,10 +3814,10 @@ var runCli = (argv) => {
       return 1;
     }
     try {
-      const abs = resolve6(file);
-      const raw = readFileSync15(abs, "utf8");
+      const abs = resolve9(file);
+      const raw = readFileSync17(abs, "utf8");
       const handoff = parseAgentHandoff(JSON.parse(raw));
-      writeJson({ ok: true, handoff });
+      writeJson2({ ok: true, handoff });
       return 0;
     } catch (error) {
       process.stderr.write(`${error instanceof Error ? error.message : String(error)}
@@ -3023,10 +3828,10 @@ var runCli = (argv) => {
   if (command === "init") {
     const root = process.cwd();
     const withDemo = flags.has("--demo") || !flags.has("--no-demo");
-    const configFile = resolve6(root, configPath ?? "doc-bridge.config.json");
-    const docsIndex = resolve6(root, "docs/for-agents/INDEX.md");
-    const exampleDoc = resolve6(root, "docs/for-agents/packages/example.md");
-    const agentsMd = resolve6(root, "AGENTS.md");
+    const configFile = resolve9(root, configPath ?? "doc-bridge.config.json");
+    const docsIndex = resolve9(root, "docs/for-agents/INDEX.md");
+    const exampleDoc = resolve9(root, "docs/for-agents/packages/example.md");
+    const agentsMd = resolve9(root, "AGENTS.md");
     const configWritten = writeIfMissing(configFile, initConfigContents(configFile, withDemo));
     const indexWritten = writeIfMissing(
       docsIndex,
@@ -3034,9 +3839,9 @@ var runCli = (argv) => {
     );
     const exampleWritten = withDemo ? writeIfMissing(exampleDoc, exampleAgentDoc) : false;
     const agentsWritten = writeIfMissing(agentsMd, agentsMdSnippet);
-    if (withDemo) writeIfMissing(resolve6(root, "src/.gitkeep"), "");
+    if (withDemo) writeIfMissing(resolve9(root, "src/.gitkeep"), "");
     const scaffold = flags.has("--scaffold-workspaces") ? scaffoldWorkspaceDocs(root, loadProject(configFile).config) : void 0;
-    writeJson({
+    writeJson2({
       ok: true,
       configPath: configFile,
       demo: withDemo,
@@ -3060,7 +3865,7 @@ var runCli = (argv) => {
     try {
       const { config, root } = loadProject(configPath);
       const result = bootstrapAgentDocs(root, config);
-      writeJson({ ok: true, ...result });
+      writeJson2({ ok: true, ...result });
       return 0;
     } catch (error) {
       process.stderr.write(`${error instanceof Error ? error.message : String(error)}
@@ -3070,24 +3875,43 @@ var runCli = (argv) => {
   }
   if (command === "memory") {
     if (!["ingest", "classify", "promote"].includes(positional[1] ?? "")) {
-      process.stderr.write("Usage: ak-docs memory <ingest|classify|promote> [--config <path>]\n");
+      process.stderr.write(
+        "Usage: ak-docs memory <ingest|classify|promote> [--pr] [--dry-run] [--force] [--config <path>]\n"
+      );
       return 1;
     }
     try {
       const { config, root } = loadProject(configPath);
       const candidates = ingestMemoryCandidates(root);
       if (positional[1] === "ingest") {
-        writeJson({ ok: true, count: candidates.length, candidates });
+        writeJson2({ ok: true, count: candidates.length, candidates });
         return 0;
       }
       const index = loadDocBridgeIndex(root, config);
       const classifications = classifyMemoryCandidates(candidates, index);
       if (positional[1] === "classify") {
-        writeJson({ ok: true, count: classifications.length, classifications });
+        writeJson2({ ok: true, count: classifications.length, classifications });
         return 0;
       }
       const draft = draftMemoryPromotion(classifications);
-      writeJson(draft);
+      if (flags.has("--pr") || flags.has("--github")) {
+        const pr = promoteMemoryToGithubPr(root, draft, {
+          dryRun: flags.has("--dry-run"),
+          force: flags.has("--force")
+        });
+        if (flags.has("--text")) {
+          writeLines([
+            pr.message,
+            ...pr.draftPath ? [`Draft: ${pr.draftPath}`] : [],
+            ...pr.prUrl ? [`PR: ${pr.prUrl}`] : [],
+            ...pr.commands.length ? ["", "Commands:", ...pr.commands.map((cmd) => `  ${cmd}`)] : []
+          ]);
+        } else {
+          writeJson2({ ...draft, pr });
+        }
+        return pr.ok ? 0 : 1;
+      }
+      writeJson2(draft);
       return draft.ok ? 0 : 1;
     } catch (error) {
       process.stderr.write(`${error instanceof Error ? error.message : String(error)}
@@ -3100,22 +3924,35 @@ var runCli = (argv) => {
       process.stderr.write("Usage: ak-docs registry topology\n");
       return 1;
     }
-    writeJson(registryTopology());
+    writeJson2(registryTopology());
     return 0;
   }
   if (command === "playbook") {
-    if (positional[1] !== "draft") {
-      process.stderr.write("Usage: ak-docs playbook draft [--config <path>]\n");
+    const action = positional[1];
+    if (action === "pattern") {
+      const payload = docBridgePatternPayload();
+      if (flags.has("--text") || wantsTextOutput(flags, { schemaVersion: 1, corpus: { agent: { root: "docs" } } })) {
+        process.stdout.write(`${docBridgePatternMarkdown()}
+`);
+      } else {
+        writeJson2(payload);
+      }
+      return 0;
+    }
+    if (action !== "draft") {
+      process.stderr.write("Usage: ak-docs playbook draft | pattern [--text] [--config <path>]\n");
       return 1;
     }
     try {
       const { config, root } = loadProject(configPath);
       const index = loadDocBridgeIndex(root, config);
       const draft = draftMemoryPromotion(classifyMemoryCandidates(ingestMemoryCandidates(root), index));
-      writeJson({
+      writeJson2({
         ...draft,
         title: "Draft Playbook feedback promotion",
-        pattern: "Doc Bridge Pattern"
+        pattern: "Doc Bridge Pattern",
+        patternDoc: "docs/playbook/doc-bridge-pattern.md",
+        exportCommand: "ak-docs playbook pattern --text"
       });
       return 0;
     } catch (error) {
@@ -3126,11 +3963,18 @@ var runCli = (argv) => {
   }
   if (command === "index") {
     try {
-      const { config, root } = loadProject(configPath);
+      const { config, root, configPath: loadedConfigPath } = loadProject(configPath);
+      if (flags.has("--watch")) {
+        return watchDocBridgeIndex({
+          root,
+          config,
+          configPath: loadedConfigPath
+        });
+      }
       const result = buildDocBridgeIndex({ root, config });
       const diagnostics = indexDiagnostics(config, result);
       const handoffCount = Object.keys(result.index.handoffs ?? {}).length;
-      writeJson({
+      writeJson2({
         ok: true,
         indexPath: result.indexPath,
         ...result.llmsTxtPath ? { llmsTxtPath: result.llmsTxtPath } : {},
@@ -3166,7 +4010,7 @@ var runCli = (argv) => {
     try {
       const { config, root } = loadProject(configPath);
       const result = runGates(root, config, gateId ? [gateId] : void 0);
-      writeJson(result);
+      writeJson2(result);
       return result.ok ? 0 : 1;
     } catch (error) {
       process.stderr.write(`${error instanceof Error ? error.message : String(error)}
@@ -3175,12 +4019,98 @@ var runCli = (argv) => {
     }
   }
   if (command === "mcp") {
+    if (positional[1] === "install") {
+      const target = flags.has("--claude") ? "claude" : flags.has("--cursor") ? "cursor" : void 0;
+      if (!target) {
+        process.stderr.write("Usage: ak-docs mcp install --cursor | --claude\n");
+        return 1;
+      }
+      try {
+        const { config, root } = loadProject(configPath);
+        const result = installMcpConfig(root, target);
+        if (wantsTextOutput(flags, config)) {
+          writeLines([
+            `Installed MCP server "${result.serverName}" for ${result.target}`,
+            `Config: ${result.configPath}`,
+            ...result.created ? ["Created new config file"] : ["Merged into existing config"],
+            "",
+            "Next steps:",
+            ...result.nextSteps.map((step) => `  \u2192 ${step}`)
+          ]);
+        } else {
+          writeJson2({ ...result, snippet: mcpSnippet(root) });
+        }
+        return 0;
+      } catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+        return 1;
+      }
+    }
     try {
       const { config, root } = loadProject(configPath);
       startMcpStdioServer({ root, config });
       return void 0;
     } catch (error) {
       process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+      return 1;
+    }
+  }
+  if (command === "doctor") {
+    try {
+      const { config, root } = loadProject(configPath);
+      const report = runDoctor(root, config);
+      if (flags.has("--write-badge")) {
+        const badgePath = resolve9(root, ".doc-bridge", "coverage-badge.json");
+        mkdirSync5(dirname7(badgePath), { recursive: true });
+        writeFileSync4(badgePath, `${formatDoctorBadgeJson(report.badge)}
+`, "utf8");
+      }
+      if (flags.has("--badge")) {
+        writeLines([formatDoctorBadgeMarkdown(report.badge)]);
+        return 0;
+      }
+      if (wantsTextOutput(flags, config)) writeLines(formatDoctorText(report));
+      else writeJson2(report);
+      return report.ok ? 0 : 1;
+    } catch (error) {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+      return 1;
+    }
+  }
+  if (command === "demo") {
+    const resolveDemoFixture = () => {
+      const fixtureFlagIndex = positional.indexOf("--fixture");
+      if (fixtureFlagIndex >= 0) {
+        const value = positional[fixtureFlagIndex + 1];
+        if (value === "monorepo" || value === "example") return value;
+      }
+      if (flags.has("--monorepo") || positional.includes("monorepo")) return "monorepo";
+      if (positional[1] === "monorepo") return "monorepo";
+      return "example";
+    };
+    const resolvedFixture = resolveDemoFixture();
+    try {
+      const useProject = flags.has("--in-project") || flags.has("--copy-fixture");
+      if (!useProject) {
+        const result2 = withDemoWorkspace(
+          resolvedFixture,
+          (root2, config2) => runDemo(root2, config2, resolvedFixture)
+        );
+        const textMode = flags.has("--text") || !flags.has("--json") && !flags.has("--agent");
+        if (textMode) writeLines(formatDemoText(result2));
+        else writeJson2(result2);
+        return result2.ok ? 0 : 1;
+      }
+      const { config, root } = loadProject(configPath);
+      const result = runDemo(root, config, resolvedFixture, { copyFixture: flags.has("--copy-fixture") });
+      if (wantsTextOutput(flags, config)) writeLines(formatDemoText(result));
+      else writeJson2(result);
+      return result.ok ? 0 : 1;
+    } catch (error) {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}
 `);
       return 1;
     }
@@ -3202,7 +4132,7 @@ var runCli = (argv) => {
       const index = loadDocBridgeIndex(root, config);
       const result = runQuery(index, config, { kind, id, agent: flags.has("--agent") });
       if (wantsTextOutput(flags, config)) writeTextQuery(result);
-      else writeJson(result);
+      else writeJson2(result);
       return 0;
     } catch (error) {
       process.stderr.write(`${error instanceof Error ? error.message : String(error)}
@@ -3221,11 +4151,11 @@ var runCli = (argv) => {
       const index = loadDocBridgeIndex(root, config);
       if (flags.has("--agent")) {
         const result = runQuery(index, config, { kind: "search", term, agent: true });
-        writeJson(result);
+        writeJson2(result);
       } else {
         const matches = searchIndex(index, term);
         if (wantsTextOutput(flags, config)) writeTextSearch(term, matches);
-        else writeJson({ term, count: matches.length, matches });
+        else writeJson2({ term, count: matches.length, matches });
       }
       return 0;
     } catch (error) {
@@ -3249,7 +4179,7 @@ var runCli = (argv) => {
       try {
         const { config, root } = loadProject(configPath);
         const index = loadDocBridgeIndex(root, config);
-        writeJson({ query, chunks: await retrieveHybridChunks(root, config, index, query) });
+        writeJson2({ query, chunks: await retrieveHybridChunks(root, config, index, query) });
         return 0;
       } catch (error) {
         process.stderr.write(`${error instanceof Error ? error.message : String(error)}
@@ -3271,7 +4201,7 @@ var runCli = (argv) => {
         const rag = await createDocBridgeRag(root, config, index);
         if (action === "ingest") {
           const result = await rag.ingest();
-          writeJson({ ok: true, ...result });
+          writeJson2({ ok: true, ...result });
           return 0;
         }
         const query = positional.slice(2).join(" ").trim();
@@ -3280,7 +4210,7 @@ var runCli = (argv) => {
           return 1;
         }
         const hits = await rag.search(query);
-        writeJson({ query, count: hits.length, hits });
+        writeJson2({ query, count: hits.length, hits });
         return 0;
       } catch (error) {
         if (error instanceof PeerMissingError) {
@@ -3362,7 +4292,7 @@ Install peers: ${layer1InstallHint()}
         return 1;
       }
       const index = loadDocBridgeIndex(root, config);
-      writeAsk(question, searchIndex(index, question, 8), index);
+      writeAsk(question, searchIndex(index, question, 8), index, config);
       return 0;
     } catch (error) {
       process.stderr.write(`${error instanceof Error ? error.message : String(error)}
@@ -3382,19 +4312,19 @@ Install peers: ${layer1InstallHint()}
       if (kind === "packages") {
         const items2 = index.lookup?.packages ?? [];
         if (wantsTextOutput(flags, config)) writeLines(items2);
-        else writeJson({ kind, items: items2 });
+        else writeJson2({ kind, items: items2 });
         return 0;
       }
       if (kind === "intents") {
         const items2 = Object.keys(index.lookup?.intents ?? {});
         if (wantsTextOutput(flags, config)) writeLines(items2);
-        else writeJson({ kind, items: items2 });
+        else writeJson2({ kind, items: items2 });
         return 0;
       }
       if (kind === "changes") {
         const items2 = Object.keys(index.lookup?.changes ?? {});
         if (wantsTextOutput(flags, config)) writeLines(items2);
-        else writeJson({ kind, items: items2 });
+        else writeJson2({ kind, items: items2 });
         return 0;
       }
       const items = index.knowledge.map((entry) => ({
@@ -3405,7 +4335,7 @@ Install peers: ${layer1InstallHint()}
       if (wantsTextOutput(flags, config)) {
         writeLines(items.map((item) => [item.id, item.path, item.title].join("	")));
       } else {
-        writeJson({ kind, items });
+        writeJson2({ kind, items });
       }
       return 0;
     } catch (error) {