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

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();
@@ -423,7 +429,9 @@ var KnowledgeEntrySchema = z3.object({
   type: z3.string().min(1).max(128),
   title: z3.string().min(1).max(256),
   path: z3.string().min(1).max(512),
-  description: z3.string().max(1024).optional(),
+  description: z3.string().max(2048).optional(),
+  /** Flattened body excerpt for full-text search (not for display). */
+  body: z3.string().max(8e3).optional(),
   links: z3.array(z3.string().min(1).max(512)).max(64).optional(),
   tags: z3.array(z3.string().min(1).max(64)).max(32).optional()
 }).strict();
@@ -628,7 +636,8 @@ var DocBridgeIndexV1JsonSchema = {
           type: { type: "string", minLength: 1, maxLength: 128 },
           title: { type: "string", minLength: 1, maxLength: 256 },
           path: { type: "string", minLength: 1, maxLength: 512 },
-          description: { type: "string", maxLength: 1024 },
+          description: { type: "string", maxLength: 2048 },
+          body: { type: "string", maxLength: 8e3 },
           links: stringArray(64),
           tags: stringArray(32)
         }
@@ -821,7 +830,7 @@ var firstHeading = (markdown) => {
   }
   return void 0;
 };
-var firstParagraph = (markdown) => {
+var firstParagraph = (markdown, maxLen = 400) => {
   const { body } = parseFrontmatter(markdown);
   const lines = body.split("\n");
   const buf = [];
@@ -833,11 +842,27 @@ var firstParagraph = (markdown) => {
     }
     if (t.startsWith("#")) continue;
     if (t.startsWith("---")) continue;
+    if (t.startsWith("```")) break;
+    if (t.startsWith("|") || t.startsWith("- [") || t.startsWith("* [")) {
+      if (buf.length) break;
+      continue;
+    }
     buf.push(t);
-    if (buf.join(" ").length > 40) break;
-  }
-  const text = buf.join(" ").trim();
-  return text || void 0;
+    if (buf.join(" ").length >= maxLen) break;
+  }
+  let text = buf.join(" ").replace(/\s+/g, " ").trim();
+  if (!text) return void 0;
+  if (text.length <= maxLen) return text;
+  const sliced = text.slice(0, maxLen);
+  const sentenceEnd = Math.max(sliced.lastIndexOf(". "), sliced.lastIndexOf("! "), sliced.lastIndexOf("? "));
+  if (sentenceEnd > maxLen * 0.4) return sliced.slice(0, sentenceEnd + 1).trim();
+  const wordEnd = sliced.lastIndexOf(" ");
+  return (wordEnd > 0 ? sliced.slice(0, wordEnd) : sliced).trim();
+};
+var extractSearchBody = (markdown, maxLen = 6e3) => {
+  const { body } = parseFrontmatter(markdown);
+  const text = body.replace(/```[\s\S]*?```/g, " ").replace(/!\[[^\]]*\]\([^)]+\)/g, " ").replace(/\[[^\]]*\]\([^)]+\)/g, " ").replace(/^#+\s+/gm, "").replace(/[|>*_`#]/g, " ").replace(/\s+/g, " ").trim();
+  return text.length > maxLen ? text.slice(0, maxLen) : text;
 };
 var slugFromPath = (relPath) => {
   const base = relPath.replace(/\.mdx?$/, "");
@@ -895,7 +920,9 @@ var scanAgentCorpus = (root, config) => {
     const { data: frontmatter } = parseFrontmatter(raw);
     const id = frontmatterString(frontmatter, "id") ?? frontmatterString(frontmatter, "package") ?? slugFromPath(relToCorpus);
     const title = firstHeading(raw) ?? id;
-    const description = firstParagraph(raw);
+    const purpose = frontmatterString(frontmatter, "purpose");
+    const description = purpose ?? firstParagraph(raw, 400);
+    const body = extractSearchBody(raw);
     return {
       id,
       type: "agent-doc",
@@ -904,7 +931,8 @@ var scanAgentCorpus = (root, config) => {
       absPath: abs,
       relPath,
       frontmatter,
-      ...description ? { description } : {}
+      ...description ? { description } : {},
+      ...body ? { body } : {}
     };
   });
 };
@@ -1037,11 +1065,19 @@ var resolveHumanDoc = (packageId, override, fmHuman, humanDocs = {}) => {
     packageId,
     packageId.replace(/^@[^/]+\//, ""),
     packageId.replace(/^os-/, ""),
-    packageId.replace(/-pattern$/, "")
+    packageId.replace(/-pattern$/, ""),
+    `packages/${packageId}`,
+    `reference/packages/${packageId}`,
+    `packages/${packageId}/index`
   ];
   for (const alias of aliases) {
     if (humanDocs[alias]) return humanDocs[alias];
   }
+  for (const [key, url] of Object.entries(humanDocs)) {
+    if (key === packageId || key.endsWith(`/${packageId}`) || key.endsWith(`/${packageId}/index`) || key.endsWith(`-${packageId}`)) {
+      return url;
+    }
+  }
   return void 0;
 };
 var buildLookup = (config, packages, corpus, indexOutFile, humanDocs = {}, root = process.cwd()) => {
@@ -1081,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,
@@ -1099,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 = {};
@@ -1127,7 +1172,7 @@ var buildLookup = (config, packages, corpus, indexOutFile, humanDocs = {}, root
 };
 
 // src/version.ts
-var PACKAGE_VERSION = "0.1.0-alpha.2";
+var PACKAGE_VERSION = "1.0.0";
 
 // src/index-builder/capabilities.ts
 var renderCapabilitiesJson = (config, index, paths) => {
@@ -1226,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 = [];
@@ -1260,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;
@@ -1800,19 +1845,58 @@ import { relative, resolve as resolve4 } from "path";
 import { z as z5, ZodError } from "zod";
 
 // src/query/search.ts
-var tokenize = (value) => value.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length >= 2);
+var tokenize = (value) => value.toLowerCase().split(/[^a-z0-9@/_-]+/).filter((t) => t.length >= 2);
+var PACKAGE_INTENT = /\b(package|module|pkg|edit|change|where|owns?|ownership|handoff|start)\b/i;
+var scoreHay = (tokens, hay, weight = 1) => {
+  let score = 0;
+  for (const token of tokens) {
+    if (!hay.includes(token)) continue;
+    score += token.length * weight;
+    if (new RegExp(`(?:^|[^a-z0-9])${token}(?:[^a-z0-9]|$)`).test(hay)) {
+      score += token.length;
+    }
+  }
+  return score;
+};
+var identityBoost = (id, path, tokens, term) => {
+  const idLower = id.toLowerCase();
+  const termLower = term.toLowerCase().trim();
+  const base = path.split("/").pop()?.replace(/\.mdx?$/i, "").toLowerCase() ?? "";
+  let boost = 0;
+  if (idLower === termLower || base === termLower) boost += 200;
+  if (tokens.length === 1 && (idLower === tokens[0] || base === tokens[0])) boost += 200;
+  for (const token of tokens) {
+    if (idLower === token) boost += 120;
+    else if (idLower.startsWith(`${token}-`) || idLower.endsWith(`-${token}`)) boost += 40;
+    else if (idLower.includes(token) && idLower.length <= token.length + 4) boost += 30;
+    if (base === token) boost += 100;
+  }
+  if (tokens.includes(idLower)) boost += Math.max(0, 40 - idLower.length);
+  return boost;
+};
+var preferOwnership = (term) => PACKAGE_INTENT.test(term) || /^(where|how).*(edit|change|package|module)/i.test(term);
 var searchIndex = (index, term, limit = 20) => {
   const tokens = tokenize(term);
   if (!tokens.length) return [];
-  const matches = [];
-  for (const entry of index.knowledge) {
-    const hay = `${entry.id} ${entry.title} ${entry.description ?? ""} ${entry.path}`.toLowerCase();
-    let score = 0;
-    for (const token of tokens) {
-      if (hay.includes(token)) score += token.length;
+  const wantOwnership = preferOwnership(term);
+  const byPath = /* @__PURE__ */ new Map();
+  const consider = (match) => {
+    const key = match.path;
+    const existing = byPath.get(key);
+    if (!existing) {
+      byPath.set(key, match);
+      return;
     }
+    const prefer = match.score > existing.score || match.score === existing.score && match.type === "ownership" && existing.type !== "ownership" || wantOwnership && match.type === "ownership" && existing.type !== "ownership" && match.score >= existing.score - 20;
+    if (prefer) byPath.set(key, match);
+  };
+  for (const entry of index.knowledge) {
+    const body = entry.body ?? "";
+    const hay = `${entry.id} ${entry.title} ${entry.description ?? ""} ${entry.path} ${body}`.toLowerCase();
+    let score = scoreHay(tokens, hay, 1);
+    score += identityBoost(entry.id, entry.path, tokens, term);
     if (score > 0) {
-      matches.push({
+      consider({
         type: "knowledge",
         id: entry.id,
         path: entry.path,
@@ -1822,22 +1906,31 @@ var searchIndex = (index, term, limit = 20) => {
     }
   }
   for (const [id, owner] of Object.entries(index.lookup?.ownership ?? {})) {
-    const hay = `${id} ${owner.path} ${owner.purpose ?? ""} ${owner.group ?? ""}`.toLowerCase();
-    let score = 0;
-    for (const token of tokens) {
-      if (hay.includes(token)) score += token.length * 2;
-    }
+    const path = owner.agentDoc ?? owner.path;
+    const hay = `${id} ${owner.path} ${owner.purpose ?? ""} ${owner.group ?? ""} ${owner.agentDoc ?? ""} ${owner.humanDoc ?? ""}`.toLowerCase();
+    let score = scoreHay(tokens, hay, 2);
+    score += identityBoost(id, path, tokens, term);
+    if (wantOwnership) score += 25;
+    score += 15;
     if (score > 0) {
-      matches.push({
+      consider({
         type: "ownership",
         id,
-        path: owner.agentDoc ?? owner.path,
+        path,
         ...owner.purpose ? { summary: owner.purpose } : {},
         score
       });
     }
   }
-  return matches.sort((a, b) => b.score - a.score).slice(0, limit);
+  return [...byPath.values()].sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    const aExact = tokens.includes(a.id.toLowerCase()) ? 1 : 0;
+    const bExact = tokens.includes(b.id.toLowerCase()) ? 1 : 0;
+    if (bExact !== aExact) return bExact - aExact;
+    if (a.type === "ownership" && b.type !== "ownership") return -1;
+    if (b.type === "ownership" && a.type !== "ownership") return 1;
+    return a.id.localeCompare(b.id);
+  }).slice(0, limit);
 };
 
 // src/retriever/doc-bridge-retriever.ts
@@ -1984,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",
@@ -1999,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) => {
@@ -2300,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();
@@ -2315,10 +2939,14 @@ var defaultFetchText = async (url) => {
   return res.text();
 };
 var sourceText = async (root, source, fetchText) => {
-  if (/^https?:\/\//.test(source)) return fetchText(source);
-  const path = resolve5(root, source);
-  if (!existsSync9(path)) throw new Error(`Federation source not found: ${source}`);
-  return readFileSync13(path, "utf8");
+  try {
+    if (/^https?:\/\//.test(source)) return await fetchText(source);
+    const path = resolve7(root, source);
+    if (!existsSync12(path)) return null;
+    return readFileSync14(path, "utf8");
+  } catch {
+    return null;
+  }
 };
 var sameOrigin = (base, target) => {
   if (!/^https?:\/\//.test(base) || !/^https?:\/\//.test(target)) return true;
@@ -2357,22 +2985,28 @@ var chunksFromMarkdown = (property, raw, sourceUrl) => {
 var loadFederatedChunks = async (root, config, options = {}) => {
   const fetchText = options.fetchText ?? defaultFetchText;
   const chunks = [];
+  const warnings = [];
   for (const source of config.federation?.sources ?? []) {
     if (source.includeInRetriever === false || !source.llmsTxt) continue;
     const llms = await sourceText(root, source.llmsTxt, fetchText);
+    if (!llms) {
+      warnings.push(`federation source skipped (unavailable): ${source.id} \u2192 ${source.llmsTxt}`);
+      continue;
+    }
     chunks.push(...chunksFromMarkdown(source.id, llms, source.llmsTxt));
     const links = parseLlmsTxtLinks(llms);
     for (const link of links) {
       const url = !/^https?:\/\//.test(link.url) && source.rawBaseUrl ? `${source.rawBaseUrl.replace(/\/$/, "")}/${link.url.replace(/^\//, "")}` : link.url;
       if (!/\.(md|txt)(?:$|\?)/.test(url)) continue;
       if (!sameOrigin(source.llmsTxt, url)) continue;
-      try {
-        const raw = await sourceText(root, url, fetchText);
-        chunks.push(...chunksFromMarkdown(source.id, raw, url));
-      } catch {
-      }
+      const raw = await sourceText(root, url, fetchText);
+      if (raw) chunks.push(...chunksFromMarkdown(source.id, raw, url));
     }
   }
+  if (warnings.length && process.stderr.isTTY) {
+    for (const w of warnings) process.stderr.write(`${w}
+`);
+  }
   return chunks;
 };
 var retrieveHybridChunks = async (root, config, index, query, options = {}) => {
@@ -2394,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 {
@@ -2513,7 +3147,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) => {
@@ -2521,10 +3155,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");
       }
@@ -2542,7 +3176,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,
@@ -2675,17 +3309,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,
@@ -2704,17 +3461,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,
@@ -2723,12 +3489,14 @@ export {
   parseLlmsTxtLinks,
   parseMemoryCandidate,
   projectRootFromConfigPath,
+  promoteMemoryToGithubPr,
   resolveGateIds,
   resolveProjectRoot,
   resolveRoot,
   retrieveDocBridgeChunks,
   retrieveHybridChunks,
   runChatOnce,
+  runDoctor,
   runGate,
   runGates,
   runQuery,
@@ -2739,6 +3507,8 @@ export {
   searchIndex,
   sha256NormalizedV1,
   startInkChat,
-  startMcpStdioServer
+  startMcpStdioServer,
+  watchDocBridgeIndex,
+  writePromotionDraft
 };
 //# sourceMappingURL=index.js.map