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

package/dist/index.js

@@ -372,6 +372,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),
@@ -382,6 +387,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();
@@ -1111,6 +1117,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,
@@ -1129,7 +1140,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 = {};
@@ -1157,7 +1172,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) => {
@@ -1256,10 +1271,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 = [];
@@ -1290,9 +1305,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;
@@ -2062,6 +2077,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",
@@ -2077,7 +2097,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) => {
@@ -2378,9 +2402,531 @@ var startMcpStdioServer = (ctx) => {
   process.stdin.resume();
 };
 
+// src/mcp/install.ts
+import { existsSync as existsSync9, mkdirSync as mkdirSync2, readFileSync as readFileSync13, writeFileSync as writeFileSync2 } from "fs";
+import { homedir } from "os";
+import { dirname as dirname4, join as join13, resolve as resolve5 } from "path";
+var SERVER_NAME = "ak-docs";
+var mcpServerEntry = (root) => ({
+  command: "npx",
+  args: ["ak-docs", "mcp"],
+  cwd: root
+});
+var readJson = (path) => {
+  if (!existsSync9(path)) return {};
+  try {
+    const parsed = JSON.parse(readFileSync13(path, "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+};
+var writeJson = (path, value) => {
+  mkdirSync2(dirname4(path), { recursive: true });
+  writeFileSync2(path, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+};
+var resolveTargetPath = (target, root) => {
+  if (target === "cursor") return resolve5(root, ".cursor", "mcp.json");
+  return join13(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+};
+var installMcpConfig = (root, target) => {
+  const configPath = resolveTargetPath(target, root);
+  const created = !existsSync9(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/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/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/index-builder/watch-index.ts
+import { existsSync as existsSync10, watch } from "fs";
+import { dirname as dirname5, resolve as resolve6 } from "path";
+var WATCH_PATTERN = /\.(md|mdx|json|ya?ml|mdc)$/i;
+var collectWatchRoots = (root, config, configPath) => {
+  const roots = /* @__PURE__ */ new Set();
+  roots.add(resolve6(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(resolve6(root, value));
+    }
+  }
+  if (configPath) roots.add(dirname5(resolve6(configPath)));
+  return [...roots].filter((dir) => existsSync10(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 = resolve6(opts.root);
+  if (existsSync10(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/memory/github-pr.ts
+import { execFileSync, spawnSync } from "child_process";
+import { existsSync as existsSync11, mkdirSync as mkdirSync3, writeFileSync as writeFileSync3 } 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);
+  mkdirSync3(join15(root, ".doc-bridge", "drafts"), { recursive: true });
+  writeFileSync3(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 (!existsSync11(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/federation/llms.ts
-import { existsSync as existsSync9, readFileSync as readFileSync13 } from "fs";
-import { resolve as resolve5 } from "path";
+import { existsSync as existsSync12, readFileSync as readFileSync14 } from "fs";
+import { resolve as resolve7 } from "path";
 var tokenize2 = (value) => value.toLowerCase().split(/[^a-z0-9]+/).filter((token) => token.length >= 2);
 var scoreText = (query, text) => {
   const hay = text.toLowerCase();
@@ -2395,9 +2941,9 @@ var defaultFetchText = async (url) => {
 var sourceText = async (root, source, fetchText) => {
   try {
     if (/^https?:\/\//.test(source)) return await fetchText(source);
-    const path = resolve5(root, source);
-    if (!existsSync9(path)) return null;
-    return readFileSync13(path, "utf8");
+    const path = resolve7(root, source);
+    if (!existsSync12(path)) return null;
+    return readFileSync14(path, "utf8");
   } catch {
     return null;
   }
@@ -2482,11 +3028,11 @@ var retrieveHybridChunks = async (root, config, index, query, options = {}) => {
 };
 
 // src/intelligence/rag.ts
-import { readFileSync as readFileSync14 } from "fs";
-import { join as join14 } from "path";
+import { readFileSync as readFileSync15 } from "fs";
+import { join as join17 } from "path";
 
 // src/intelligence/adapter.ts
-import { join as join13 } from "path";
+import { join as join16 } from "path";
 
 // src/intelligence/peers.ts
 var PeerMissingError = class extends Error {
@@ -2540,6 +3086,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.");
@@ -2551,7 +3109,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;
@@ -2601,7 +3159,7 @@ var resolveIntelligenceRuntime = async (config) => {
   }
   return { adapter, embed, provider, ...model ? { model } : {} };
 };
-var defaultVectorStorePath = (root) => join13(root, ".doc-bridge", "vectors");
+var defaultVectorStorePath = (root) => join16(root, ".doc-bridge", "vectors");
 
 // src/intelligence/rag.ts
 var loadDocuments = (root, index, sources) => {
@@ -2609,10 +3167,10 @@ var loadDocuments = (root, index, sources) => {
   const docs = [];
   if (includeAgent) {
     for (const entry of index.knowledge) {
-      const abs = join14(root, entry.path);
+      const abs = join17(root, entry.path);
       let content = "";
       try {
-        content = readFileSync14(abs, "utf8");
+        content = readFileSync15(abs, "utf8");
       } catch {
         content = [entry.title, entry.description].filter(Boolean).join("\n\n");
       }
@@ -2630,7 +3188,7 @@ var createDocBridgeRag = async (root, config, index) => {
   const { embed } = await resolveIntelligenceRuntime(config);
   const ragMod = await importPeer("@agentskit/rag");
   const memoryMod = await importPeer("@agentskit/memory");
-  const storePath = typeof config.intelligence?.retriever?.options?.storePath === "string" ? join14(root, config.intelligence.retriever.options.storePath) : defaultVectorStorePath(root);
+  const storePath = typeof config.intelligence?.retriever?.options?.storePath === "string" ? join17(root, config.intelligence.retriever.options.storePath) : defaultVectorStorePath(root);
   const store = memoryMod.fileVectorMemory({ path: storePath });
   const rag = ragMod.createRAG({
     embed,
@@ -2763,17 +3321,140 @@ var startInkChat = async (root, config, index) => {
     throw wrapIntelligenceError(error);
   }
 };
+
+// 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()
+});
 export {
   AgentHandoffLegacySchema,
   AgentHandoffV1JsonSchema,
   AgentHandoffV1Schema,
   AgentSearchV1Schema,
   ConfigNotFoundError,
+  DOC_BRIDGE_PATTERN_ID,
+  DOC_BRIDGE_PATTERN_META,
   DocBridgeConfigV1Schema,
   DocBridgeIndexV1JsonSchema,
   DocBridgeIndexV1Schema,
   DocBridgeJsonSchemas,
   HANDOFF_SCHEMA_VERSION,
+  HandoffBridgeSchema,
   HandoffTargetTypeSchema,
   INDEX_SCHEMA_VERSION,
   IndexNotFoundError,
@@ -2792,17 +3473,26 @@ export {
   collectPackages,
   createDocBridgeRag,
   createDocBridgeRetriever,
+  defaultPromotionDraftPath,
   defineConfig,
+  docBridgePatternMarkdown,
+  docBridgePatternPayload,
+  doctorBadgeMetrics,
   draftMemoryPromotion,
+  formatDoctorBadgeJson,
+  formatDoctorBadgeMarkdown,
+  formatDoctorText,
   handleMcpRequest,
   indexFilePath,
   ingestAgentMemory,
   ingestCursorRules,
   ingestMemoryCandidates,
+  installMcpConfig,
   layer1InstallHint,
   loadConfig,
   loadDocBridgeIndex,
   loadFederatedChunks,
+  mcpSnippet,
   normalizeAgentHandoff,
   parseAgentHandoff,
   parseAgentSearch,
@@ -2811,12 +3501,14 @@ export {
   parseLlmsTxtLinks,
   parseMemoryCandidate,
   projectRootFromConfigPath,
+  promoteMemoryToGithubPr,
   resolveGateIds,
   resolveProjectRoot,
   resolveRoot,
   retrieveDocBridgeChunks,
   retrieveHybridChunks,
   runChatOnce,
+  runDoctor,
   runGate,
   runGates,
   runQuery,
@@ -2827,6 +3519,8 @@ export {
   searchIndex,
   sha256NormalizedV1,
   startInkChat,
-  startMcpStdioServer
+  startMcpStdioServer,
+  watchDocBridgeIndex,
+  writePromotionDraft
 };
 //# sourceMappingURL=index.js.map