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

package/dist/index.js

@@ -10,7 +10,7 @@ var applyConfigDefaults = (config) => {
       agent: {
         ...config.corpus.agent,
         index: agentIndex,
-        include: config.corpus.agent.include ?? ["**/*.md"],
+        include: config.corpus.agent.include ?? ["**/*.{md,mdx}"],
         exclude: config.corpus.agent.exclude ?? [...DEFAULT_AGENT_EXCLUDE]
       }
     },
@@ -103,9 +103,11 @@ var OwnershipEntrySchema = z.object({
   humanDoc: z.string().min(1).max(512).optional()
 }).strict();
 var RoutingConfigSchema = z.object({
-  plugin: z.enum(["pnpm-monorepo", "npm-workspaces", "yarn-workspaces", "custom"]).optional(),
+  plugin: z.enum(["pnpm-monorepo", "npm-workspaces", "yarn-workspaces", "pattern-files", "custom"]).optional(),
   options: z.object({
     packages: z.array(z.string().min(1).max(256)).max(128).optional(),
+    /** Infer ownership from corpus paths/frontmatter (default true). */
+    ownershipFromCorpus: z.boolean().optional(),
     ownership: z.record(z.string().min(1).max(256), OwnershipEntrySchema).optional(),
     intents: z.array(
       z.object({
@@ -125,7 +127,8 @@ var RoutingConfigSchema = z.object({
   }).strict().optional()
 }).strict();
 var GatesConfigSchema = z.object({
-  preset: z.enum(["minimal", "standard", "strict"]).optional(),
+  /** minimal: freshness · standard: + human links · strict: + okf-type · playbook: freshness + okf soft style */
+  preset: z.enum(["minimal", "standard", "strict", "playbook"]).optional(),
   include: z.array(
     z.enum([
       "index-freshness",
@@ -420,7 +423,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();
@@ -625,7 +630,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)
         }
@@ -695,16 +701,80 @@ ${zodIssues(result.error).map((i) => `  - ${i.path}: ${i.message}`).join("\n")}`
 };
 
 // src/index-builder/build-index.ts
-import { mkdirSync, readFileSync as readFileSync7, writeFileSync } from "fs";
-import { dirname as dirname3, join as join9 } from "path";
+import { mkdirSync, readFileSync as readFileSync8, writeFileSync } from "fs";
+import { dirname as dirname3, join as join10 } from "path";
 
 // src/lib/paths.ts
 import { resolve as resolve2 } from "path";
 var toPosix = (value) => value.split("\\").join("/");
 
+// src/lib/package-manager.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { join as join2 } from "path";
+var detectPackageManager = (root) => {
+  if (existsSync2(join2(root, "pnpm-lock.yaml")) || existsSync2(join2(root, "pnpm-workspace.yaml"))) {
+    return "pnpm";
+  }
+  if (existsSync2(join2(root, "yarn.lock"))) return "yarn";
+  if (existsSync2(join2(root, "bun.lockb")) || existsSync2(join2(root, "bun.lock"))) return "bun";
+  if (existsSync2(join2(root, "package-lock.json"))) return "npm";
+  try {
+    const pkg = JSON.parse(readFileSync2(join2(root, "package.json"), "utf8"));
+    const pm = pkg.packageManager?.split("@")[0];
+    if (pm === "pnpm" || pm === "npm" || pm === "yarn" || pm === "bun") return pm;
+  } catch {
+  }
+  return "npm";
+};
+var defaultChecksForTarget = (root, opts) => {
+  const pm = detectPackageManager(root);
+  if (/\.mdx?$/.test(opts.packagePath) || opts.packagePath.includes("/pillars/")) {
+    try {
+      const pkg = JSON.parse(readFileSync2(join2(root, "package.json"), "utf8"));
+      const scripts = pkg.scripts ?? {};
+      if (scripts["check:okf-type"]) return ["pnpm run check:okf-type"];
+      if (scripts["docs:bridge:gate"]) return ["pnpm run docs:bridge:gate"];
+      if (scripts.test) return [pm === "pnpm" ? "pnpm test" : "npm test"];
+    } catch {
+    }
+  }
+  const isWorkspace = existsSync2(join2(root, "pnpm-workspace.yaml")) || existsSync2(join2(root, "lerna.json")) || Boolean(
+    (() => {
+      try {
+        const pkg = JSON.parse(readFileSync2(join2(root, "package.json"), "utf8"));
+        return Boolean(pkg.workspaces);
+      } catch {
+        return false;
+      }
+    })()
+  );
+  const filter = opts.packageName ?? (opts.packagePath.startsWith("packages/") || opts.packagePath.startsWith("apps/") ? opts.packageId : void 0);
+  if (pm === "pnpm") {
+    if (isWorkspace && filter) {
+      const base = [`pnpm --filter ${filter} test`];
+      if (opts.strict) base.push(`pnpm --filter ${filter} lint`);
+      return base;
+    }
+    return opts.strict ? ["pnpm test", "pnpm run lint"] : ["pnpm test"];
+  }
+  if (pm === "yarn") {
+    if (isWorkspace && filter) {
+      return opts.strict ? [`yarn workspace ${filter} test`, `yarn workspace ${filter} lint`] : [`yarn workspace ${filter} test`];
+    }
+    return opts.strict ? ["yarn test", "yarn lint"] : ["yarn test"];
+  }
+  if (pm === "bun") {
+    return opts.strict ? ["bun test", "bun run lint"] : ["bun test"];
+  }
+  if (isWorkspace && filter) {
+    return opts.strict ? [`npm test -w ${filter}`, `npm run lint -w ${filter}`] : [`npm test -w ${filter}`];
+  }
+  return opts.strict ? ["npm test", "npm run lint"] : ["npm test"];
+};
+
 // src/index-builder/scan-corpus.ts
-import { readFileSync as readFileSync2 } from "fs";
-import { join as join3 } from "path";
+import { readFileSync as readFileSync3 } from "fs";
+import { join as join4 } from "path";
 
 // src/lib/markdown.ts
 var parseFrontmatter = (markdown) => {
@@ -754,7 +824,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 = [];
@@ -766,11 +836,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?$/, "");
@@ -780,7 +866,7 @@ var slugFromPath = (relPath) => {
 
 // src/lib/walk.ts
 import { readdirSync, statSync } from "fs";
-import { join as join2 } from "path";
+import { join as join3 } from "path";
 var DEFAULT_SKIP = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", "coverage", ".doc-bridge"]);
 var walkFiles = (root, opts) => {
   const extensions = opts?.extensions ?? [".md"];
@@ -794,7 +880,7 @@ var walkFiles = (root, opts) => {
       return;
     }
     for (const name of entries) {
-      const abs = join2(dir, name);
+      const abs = join3(dir, name);
       let st;
       try {
         st = statSync(abs);
@@ -818,17 +904,19 @@ var walkFiles = (root, opts) => {
 
 // src/index-builder/scan-corpus.ts
 var scanAgentCorpus = (root, config) => {
-  const agentRoot = join3(root, config.corpus.agent.root);
+  const agentRoot = join4(root, config.corpus.agent.root);
   const files = walkFiles(agentRoot, { extensions: [".md", ".mdx"] });
   const corpusRelRoot = toPosix(config.corpus.agent.root);
   return files.map((abs) => {
     const relToCorpus = toPosix(abs.replace(`${toPosix(agentRoot)}/`, ""));
     const relPath = `${corpusRelRoot}/${relToCorpus}`;
-    const raw = readFileSync2(abs, "utf8");
+    const raw = readFileSync3(abs, "utf8");
     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",
@@ -837,21 +925,35 @@ var scanAgentCorpus = (root, config) => {
       absPath: abs,
       relPath,
       frontmatter,
-      ...description ? { description } : {}
+      ...description ? { description } : {},
+      ...body ? { body } : {}
     };
   });
 };
 var guessAgentDocForPackage = (corpus, packageId) => {
-  const exact = corpus.find(
-    (doc) => frontmatterString(doc.frontmatter, "package") === packageId || doc.relPath.endsWith(`/packages/${packageId}.md`) || doc.relPath.endsWith(`/${packageId}.md`) || doc.id === packageId
-  );
-  return exact?.path;
+  const candidates = [
+    (doc) => frontmatterString(doc.frontmatter, "package") === packageId,
+    (doc) => doc.id === packageId,
+    (doc) => doc.relPath.endsWith(`/packages/${packageId}.md`),
+    (doc) => doc.relPath.endsWith(`/packages/${packageId}.mdx`),
+    (doc) => doc.relPath.endsWith(`/packages/${packageId}/index.md`),
+    (doc) => doc.relPath.endsWith(`/packages/${packageId}/index.mdx`),
+    (doc) => doc.relPath.endsWith(`/${packageId}.md`),
+    (doc) => doc.relPath.endsWith(`/${packageId}.mdx`),
+    (doc) => doc.relPath.includes(`/packages/${packageId}/`)
+  ];
+  for (const match of candidates) {
+    const hit = corpus.find(match);
+    if (hit) return hit.path;
+  }
+  return void 0;
 };
 var ownershipFromFrontmatter = (corpus) => {
   const out = [];
   for (const doc of corpus) {
-    const id = frontmatterString(doc.frontmatter, "package") ?? (frontmatterString(doc.frontmatter, "type") === "package" ? frontmatterString(doc.frontmatter, "id") ?? doc.id : void 0);
-    const path = frontmatterString(doc.frontmatter, "editRoot") ?? frontmatterString(doc.frontmatter, "path");
+    const type = frontmatterString(doc.frontmatter, "type");
+    const id = frontmatterString(doc.frontmatter, "package") ?? (type === "package" || type === "module" || type === "pattern" ? frontmatterString(doc.frontmatter, "id") ?? doc.id : void 0);
+    const path = frontmatterString(doc.frontmatter, "editRoot") ?? frontmatterString(doc.frontmatter, "path") ?? (type === "package" || type === "module" ? `packages/${id}` : void 0);
     if (!id || !path) continue;
     const purpose = frontmatterString(doc.frontmatter, "purpose") ?? doc.description;
     const checks = frontmatterStringList(doc.frontmatter, "checks");
@@ -867,13 +969,55 @@ var ownershipFromFrontmatter = (corpus) => {
   }
   return out;
 };
+var ownershipFromCorpus = (corpus) => {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const doc of corpus) {
+    if (frontmatterString(doc.frontmatter, "package") && frontmatterString(doc.frontmatter, "editRoot")) {
+      continue;
+    }
+    let id;
+    let path;
+    let purpose = frontmatterString(doc.frontmatter, "purpose") ?? doc.description;
+    const packagesFile = /(?:^|\/)packages\/([^/]+)\.(?:md|mdx)$/.exec(doc.relPath);
+    const packagesIndex = /(?:^|\/)packages\/([^/]+)\/index\.(?:md|mdx)$/.exec(doc.relPath);
+    const registryReadme = /(?:^|\/)registry\/([^/]+)\/README\.(?:md|mdx)$/i.exec(doc.relPath);
+    const patternFile = /(?:^|\/)pillars\/[^/]+\/([^/]+(?:-pattern)?)\.(?:md|mdx)$/.exec(doc.relPath);
+    const topLevelPkg = /(?:^|\/)for-agents\/([^/]+)\.(?:md|mdx)$/.exec(doc.relPath);
+    if (packagesFile?.[1] && packagesFile[1] !== "index") {
+      id = packagesFile[1];
+      path = `packages/${id}`;
+    } else if (packagesIndex?.[1]) {
+      id = packagesIndex[1];
+      path = `packages/${id}`;
+    } else if (registryReadme?.[1]) {
+      id = registryReadme[1];
+      path = `registry/${id}`;
+    } else if (patternFile?.[1] && patternFile[1] !== "index" && patternFile[1] !== "universal") {
+      id = patternFile[1];
+      path = doc.path;
+      purpose = purpose ?? `Playbook pattern: ${id}`;
+    } else if (topLevelPkg?.[1] && topLevelPkg[1] !== "index" && topLevelPkg[1] !== "INDEX") {
+      id = topLevelPkg[1];
+      path = `packages/${id}`;
+    }
+    if (!id || !path || seen.has(id)) continue;
+    seen.add(id);
+    const humanDoc = frontmatterString(doc.frontmatter, "humanDoc");
+    const checks = frontmatterStringList(doc.frontmatter, "checks");
+    out.push({
+      id,
+      path,
+      agentDoc: doc.path,
+      ...purpose ? { purpose } : {},
+      ...checks ? { checks } : {},
+      ...humanDoc ? { humanDoc } : {}
+    });
+  }
+  return out;
+};
 
 // src/index-builder/build-handoffs.ts
-var defaultChecks = (config) => {
-  const preset = config.gates?.preset ?? "minimal";
-  if (preset === "strict" || preset === "standard") return ["npm test", "npm run lint"];
-  return ["npm test"];
-};
 var collectPackages = (config, discovered, corpus) => {
   const byId = /* @__PURE__ */ new Map();
   for (const [id, entry] of Object.entries(config.routing?.options?.ownership ?? {})) {
@@ -891,7 +1035,11 @@ var collectPackages = (config, discovered, corpus) => {
       ...pkg.name ? { name: pkg.name } : existing.name ? { name: existing.name } : {}
     });
   }
-  for (const seed of ownershipFromFrontmatter(corpus)) {
+  const seeds = [
+    ...ownershipFromFrontmatter(corpus),
+    ...config.routing?.options?.ownershipFromCorpus === false ? [] : ownershipFromCorpus(corpus)
+  ];
+  for (const seed of seeds) {
     const existing = byId.get(seed.id);
     if (!existing) {
       byId.set(seed.id, { id: seed.id, path: seed.path });
@@ -903,22 +1051,59 @@ var collectPackages = (config, discovered, corpus) => {
   }
   return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
 };
-var buildLookup = (config, packages, corpus, indexOutFile, humanDocs = {}) => {
+var resolveHumanDoc = (packageId, override, fmHuman, humanDocs = {}) => {
+  if (override) return override;
+  if (fmHuman) return fmHuman;
+  if (humanDocs[packageId]) return humanDocs[packageId];
+  const aliases = [
+    packageId,
+    packageId.replace(/^@[^/]+\//, ""),
+    packageId.replace(/^os-/, ""),
+    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()) => {
   const ownership = {};
   const handoffs = {};
-  const checks = defaultChecks(config);
-  const fmSeeds = new Map(ownershipFromFrontmatter(corpus).map((seed) => [seed.id, seed]));
+  const strict = (config.gates?.preset ?? "minimal") !== "minimal";
+  const fmSeeds = new Map(
+    [...ownershipFromFrontmatter(corpus), ...ownershipFromCorpus(corpus)].map((seed) => [
+      seed.id,
+      seed
+    ])
+  );
   for (const pkg of packages) {
     const override = config.routing?.options?.ownership?.[pkg.id];
     const fm = fmSeeds.get(pkg.id);
     const agentDoc = override?.agentDoc ?? fm?.agentDoc ?? guessAgentDocForPackage(corpus, pkg.id) ?? config.corpus.agent.index;
     const startHere = agentDoc ?? "";
     const purpose = override?.purpose ?? fm?.purpose;
-    const humanDoc = override?.humanDoc ?? fm?.humanDoc ?? humanDocs[pkg.id];
+    const path = override?.path ?? fm?.path ?? pkg.path;
+    const checks = [
+      ...override?.checks ?? fm?.checks ?? defaultChecksForTarget(root, {
+        packageId: pkg.id,
+        packagePath: path,
+        ...pkg.name ? { packageName: pkg.name } : {},
+        strict
+      })
+    ];
+    const humanDoc = resolveHumanDoc(pkg.id, override?.humanDoc, fm?.humanDoc, humanDocs);
     const record = {
       id: pkg.id,
-      path: override?.path ?? fm?.path ?? pkg.path,
-      checks: [...override?.checks ?? fm?.checks ?? checks],
+      path,
+      checks,
       ...override?.group ? { group: override.group } : {},
       ...override?.layer ? { layer: override.layer } : {},
       ...purpose ? { purpose } : {},
@@ -972,7 +1157,7 @@ var buildLookup = (config, packages, corpus, indexOutFile, humanDocs = {}) => {
 };
 
 // src/version.ts
-var PACKAGE_VERSION = "0.1.0-alpha.1";
+var PACKAGE_VERSION = "0.1.0-alpha.3";
 
 // src/index-builder/capabilities.ts
 var renderCapabilitiesJson = (config, index, paths) => {
@@ -1041,13 +1226,13 @@ ${lines.join("\n")}
 };
 
 // src/index-builder/human-adapters/docusaurus.ts
-import { existsSync as existsSync2, readFileSync as readFileSync4 } from "fs";
-import { join as join5 } from "path";
+import { existsSync as existsSync3, readFileSync as readFileSync5 } from "fs";
+import { join as join6 } from "path";
 import vm2 from "vm";
 
 // src/index-builder/human-adapters/core.ts
-import { readFileSync as readFileSync3 } from "fs";
-import { join as join4 } from "path";
+import { readFileSync as readFileSync4 } from "fs";
+import { join as join5 } from "path";
 var optionString = (options, keys) => {
   for (const key of keys) {
     const value = options?.[key];
@@ -1078,10 +1263,10 @@ var humanUrl = (slug, urlPrefix) => {
 };
 var scanMarkdownDocs = (root, humanRoot, options) => {
   const out = [];
-  const absRoot = join4(root, humanRoot);
+  const absRoot = join5(root, humanRoot);
   for (const abs of walkFiles(absRoot, { extensions: [".md", ".mdx"] })) {
     const relToHumanRoot = toPosix(abs.replace(`${toPosix(absRoot)}/`, ""));
-    const raw = readFileSync3(abs, "utf8");
+    const raw = readFileSync4(abs, "utf8");
     if (options?.includeRelPath && !options.includeRelPath(relToHumanRoot, raw)) continue;
     out.push({
       id: options?.idForDoc?.(relToHumanRoot, raw) ?? docId(relToHumanRoot, raw),
@@ -1120,8 +1305,8 @@ var docusaurusRecordId = (relPath, raw) => {
   return frontmatter.package ?? frontmatter.module ?? docusaurusSidebarId(relPath, raw);
 };
 var sidebarsValue = (file) => {
-  if (!existsSync2(file)) return void 0;
-  const raw = readFileSync4(file, "utf8").replace(/import\s+type\s+[\s\S]*?;?\n/g, "").replace(/:\s*[A-Za-z0-9_.$<>{}\[\],\s]+(?=\s*=)/g, "").replace(/\s+satisfies\s+[A-Za-z0-9_.$<>{}\[\],\s]+(?=\s*(?:;|\n|$))/g, "").replace(/export\s+default/, "module.exports =");
+  if (!existsSync3(file)) return void 0;
+  const raw = readFileSync5(file, "utf8").replace(/import\s+type\s+[\s\S]*?;?\n/g, "").replace(/:\s*[A-Za-z0-9_.$<>{}\[\],\s]+(?=\s*=)/g, "").replace(/\s+satisfies\s+[A-Za-z0-9_.$<>{}\[\],\s]+(?=\s*(?:;|\n|$))/g, "").replace(/export\s+default/, "module.exports =");
   const sandbox = { module: { exports: {} }, exports: {} };
   vm2.runInNewContext(raw, sandbox, { timeout: 250 });
   return sandbox.module.exports;
@@ -1151,7 +1336,7 @@ var visitSidebar = (value, filter) => {
 };
 var readSidebars = (root, sidebarsFile) => {
   if (!sidebarsFile) return { enabled: false, ids: /* @__PURE__ */ new Set(), autogenDirs: [] };
-  const value = sidebarsValue(join5(root, sidebarsFile));
+  const value = sidebarsValue(join6(root, sidebarsFile));
   const filter = { ids: /* @__PURE__ */ new Set(), autogenDirs: [] };
   visitSidebar(value, filter);
   return { enabled: true, ...filter };
@@ -1180,13 +1365,13 @@ var docusaurusAdapter = {
 };
 
 // src/index-builder/human-adapters/fumadocs.ts
-import { existsSync as existsSync3, readFileSync as readFileSync5 } from "fs";
-import { join as join6 } from "path";
+import { existsSync as existsSync4, readFileSync as readFileSync6 } from "fs";
+import { join as join7 } from "path";
 var readMetaPages = (dir) => {
-  const file = join6(dir, "meta.json");
-  if (!existsSync3(file)) return void 0;
+  const file = join7(dir, "meta.json");
+  if (!existsSync4(file)) return void 0;
   try {
-    const meta = JSON.parse(readFileSync5(file, "utf8"));
+    const meta = JSON.parse(readFileSync6(file, "utf8"));
     return Array.isArray(meta.pages) ? meta.pages.filter((page) => typeof page === "string") : void 0;
   } catch {
     return void 0;
@@ -1201,7 +1386,7 @@ var isListedByMeta = (contentRoot, relPath) => {
   if (isDotFile(relPath)) return false;
   const parts = relPath.split("/");
   for (let i = 0; i < parts.length; i += 1) {
-    const dir = join6(contentRoot, ...parts.slice(0, i));
+    const dir = join7(contentRoot, ...parts.slice(0, i));
     const pages = readMetaPages(dir);
     if (!pages?.length || pages.includes("...")) continue;
     const key = pageKey(parts[i] ?? "");
@@ -1214,9 +1399,16 @@ var fumadocsAdapter = {
   scan: ({ root, config }) => {
     const contentDir = optionString(config.options, ["contentDir", "root"]);
     if (!contentDir) return [];
-    const contentRoot = join6(root, contentDir);
+    const contentRoot = join7(root, contentDir);
+    const excludePrefixes = Array.isArray(config.options?.excludePrefixes) ? config.options.excludePrefixes.filter((v) => typeof v === "string") : typeof config.options?.excludePrefix === "string" ? [config.options.excludePrefix] : [];
+    if (!excludePrefixes.includes("for-agents")) excludePrefixes.push("for-agents");
     return scanMarkdownDocs(root, contentDir, {
-      includeRelPath: (relPath) => isListedByMeta(contentRoot, relPath),
+      includeRelPath: (relPath) => {
+        if (excludePrefixes.some((prefix) => relPath === prefix || relPath.startsWith(`${prefix}/`))) {
+          return false;
+        }
+        return isListedByMeta(contentRoot, relPath);
+      },
       urlPrefix: config.options?.urlPrefix,
       stripGroups: true
     });
@@ -1227,7 +1419,7 @@ var fumadocsAdapter = {
 var plainMarkdownAdapter = {
   plugin: "plain-markdown",
   scan: ({ root, config }) => {
-    const humanRoot = optionString(config.options, ["root"]) ?? "docs";
+    const humanRoot = optionString(config.options, ["contentDir", "root", "docsDir"]) ?? "docs";
     return scanMarkdownDocs(root, humanRoot, { urlPrefix: config.options?.urlPrefix });
   }
 };
@@ -1246,10 +1438,14 @@ var humanConfigs = (config) => {
 var scanHumanDocRecords = (root, config) => {
   const out = [];
   const seen = /* @__PURE__ */ new Set();
+  const agentRoot = config.corpus.agent.root.replace(/\/$/, "");
   for (const human of humanConfigs(config)) {
     const adapter = ADAPTERS.find((candidate) => candidate.plugin === human.plugin);
     if (!adapter) continue;
     for (const record of adapter.scan({ root, config: human })) {
+      if (record.path === agentRoot || record.path.startsWith(`${agentRoot}/`) || record.path.includes("/for-agents/") || record.path.endsWith("/for-agents")) {
+        continue;
+      }
       if (seen.has(record.id)) continue;
       seen.add(record.id);
       out.push(record);
@@ -1260,26 +1456,26 @@ var scanHumanDocRecords = (root, config) => {
 var scanHumanDocs = (root, config) => Object.fromEntries(scanHumanDocRecords(root, config).map((doc) => [doc.id, doc.url]));
 
 // src/index-builder/plugins/pnpm-monorepo.ts
-import { existsSync as existsSync5, readFileSync as readFileSync6 } from "fs";
-import { basename as basename2, join as join8 } from "path";
+import { existsSync as existsSync6, readFileSync as readFileSync7 } from "fs";
+import { basename as basename2, join as join9 } from "path";
 
 // src/lib/glob-expand.ts
-import { existsSync as existsSync4, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
-import { join as join7 } from "path";
+import { existsSync as existsSync5, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
+import { join as join8 } from "path";
 var expandWorkspaceGlobs = (root, patterns) => {
   const dirs = /* @__PURE__ */ new Set();
   for (const pattern of patterns) {
     const normalized = toPosix(pattern).replace(/\/$/, "");
     if (!normalized.includes("*")) {
-      const abs = join7(root, normalized);
-      if (existsSync4(abs)) dirs.add(toPosix(abs));
+      const abs = join8(root, normalized);
+      if (existsSync5(abs)) dirs.add(toPosix(abs));
       continue;
     }
     const star = normalized.indexOf("*");
-    const base = join7(root, normalized.slice(0, star).replace(/\/$/, ""));
-    if (!existsSync4(base)) continue;
+    const base = join8(root, normalized.slice(0, star).replace(/\/$/, ""));
+    if (!existsSync5(base)) continue;
     for (const name of readdirSync2(base)) {
-      const abs = join7(base, name);
+      const abs = join8(base, name);
       try {
         if (statSync2(abs).isDirectory()) dirs.add(toPosix(abs));
       } catch {
@@ -1311,10 +1507,10 @@ var parsePnpmWorkspace = (yaml) => {
   return patterns;
 };
 var readPackageJson = (dir) => {
-  const file = join8(dir, "package.json");
-  if (!existsSync5(file)) return null;
+  const file = join9(dir, "package.json");
+  if (!existsSync6(file)) return null;
   try {
-    return JSON.parse(readFileSync6(file, "utf8"));
+    return JSON.parse(readFileSync7(file, "utf8"));
   } catch {
     return null;
   }
@@ -1323,9 +1519,9 @@ var discoverPnpmPackages = (root, config) => {
   const explicit = config.routing?.options?.packages;
   let patterns = explicit;
   if (!patterns?.length) {
-    const workspaceFile = join8(root, "pnpm-workspace.yaml");
-    if (existsSync5(workspaceFile)) {
-      patterns = parsePnpmWorkspace(readFileSync6(workspaceFile, "utf8"));
+    const workspaceFile = join9(root, "pnpm-workspace.yaml");
+    if (existsSync6(workspaceFile)) {
+      patterns = parsePnpmWorkspace(readFileSync7(workspaceFile, "utf8"));
     }
   }
   if (!patterns?.length) return [];
@@ -1346,7 +1542,7 @@ var discoverPnpmPackages = (root, config) => {
 var projectName = (root, config) => {
   if (config.project?.name) return config.project.name;
   try {
-    const pkg = JSON.parse(readFileSync7(join9(root, "package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync8(join10(root, "package.json"), "utf8"));
     if (pkg.name) return pkg.name;
   } catch {
   }
@@ -1354,7 +1550,7 @@ var projectName = (root, config) => {
 };
 var existingGeneratedAt = (indexPath, contentHash) => {
   try {
-    const index = JSON.parse(readFileSync7(indexPath, "utf8"));
+    const index = JSON.parse(readFileSync8(indexPath, "utf8"));
     return index.contentHash === contentHash && typeof index.generatedAt === "string" ? index.generatedAt : void 0;
   } catch {
     return void 0;
@@ -1365,14 +1561,14 @@ var buildDocBridgeIndex = (opts) => {
   const config = opts.config;
   const write = opts.write ?? true;
   const outFile = config.index?.outFile ?? ".doc-bridge/index.json";
-  const indexPath = join9(root, outFile);
+  const indexPath = join10(root, outFile);
   const corpus = scanAgentCorpus(root, config);
   const knowledge = corpus.map(({ absPath: _a, relPath: _r, frontmatter: _f, ...entry }) => entry);
   const shouldDiscover = config.routing?.plugin === "pnpm-monorepo" || Boolean(config.routing?.options?.packages?.length) || config.routing?.plugin === "npm-workspaces" || config.routing?.plugin === "yarn-workspaces";
   const discovered = shouldDiscover ? discoverPnpmPackages(root, config) : [];
   const packages = collectPackages(config, discovered, corpus);
   const humanDocs = scanHumanDocs(root, config);
-  const { lookup, handoffs } = buildLookup(config, packages, corpus, outFile, humanDocs);
+  const { lookup, handoffs } = buildLookup(config, packages, corpus, outFile, humanDocs, root);
   const hashPayload = {
     schemaVersion: 1,
     knowledge,
@@ -1400,7 +1596,7 @@ var buildDocBridgeIndex = (opts) => {
   if (config.index?.llmsTxt?.enabled !== false) {
     const llmsOut = config.index?.llmsTxt?.outFile ?? "llms.txt";
     llmsTxtRelPath = toPosix(llmsOut);
-    llmsTxtPath = join9(root, llmsOut);
+    llmsTxtPath = join10(root, llmsOut);
     if (write) {
       writeFileSync(
         llmsTxtPath,
@@ -1412,7 +1608,7 @@ var buildDocBridgeIndex = (opts) => {
   let capabilitiesPath;
   if (config.index?.capabilities?.enabled !== false) {
     const capabilitiesOut = config.index?.capabilities?.outFile ?? ".doc-bridge/capabilities.json";
-    capabilitiesPath = join9(root, capabilitiesOut);
+    capabilitiesPath = join10(root, capabilitiesOut);
     if (write) {
       mkdirSync(dirname3(capabilitiesPath), { recursive: true });
       writeFileSync(
@@ -1434,11 +1630,11 @@ var buildDocBridgeIndex = (opts) => {
 };
 
 // src/gates/run-gates.ts
-import { readFileSync as readFileSync9 } from "fs";
+import { readFileSync as readFileSync10 } from "fs";
 
 // src/query/load-index.ts
-import { existsSync as existsSync6, readFileSync as readFileSync8 } from "fs";
-import { join as join10, resolve as resolve3 } from "path";
+import { existsSync as existsSync7, readFileSync as readFileSync9 } from "fs";
+import { join as join11, resolve as resolve3 } from "path";
 var IndexNotFoundError = class extends Error {
   constructor(path) {
     super(`Missing index at ${path}. Run: ak-docs index`);
@@ -1447,11 +1643,11 @@ var IndexNotFoundError = class extends Error {
   }
   path;
 };
-var indexFilePath = (root, config) => join10(root, config.index?.outFile ?? ".doc-bridge/index.json");
+var indexFilePath = (root, config) => join11(root, config.index?.outFile ?? ".doc-bridge/index.json");
 var loadDocBridgeIndex = (root, config) => {
   const path = indexFilePath(root, config);
-  if (!existsSync6(path)) throw new IndexNotFoundError(path);
-  const raw = JSON.parse(readFileSync8(path, "utf8"));
+  if (!existsSync7(path)) throw new IndexNotFoundError(path);
+  const raw = JSON.parse(readFileSync9(path, "utf8"));
   return parseDocBridgeIndex(raw);
 };
 var resolveRoot = (cwd) => resolve3(cwd ?? process.cwd());
@@ -1516,7 +1712,7 @@ var runOkfTypeGate = (root, config) => {
   const required = config.corpus.agent.okf?.requireType ?? config.gates?.preset === "strict";
   if (!required) return { id: "okf-type", ok: true, message: "OKF type frontmatter not required" };
   const allowed = config.corpus.agent.okf?.allowedTypes;
-  const bad = scanAgentCorpus(root, config).filter((doc) => doc.path !== config.corpus.agent.index).map((doc) => ({ path: doc.path, type: frontmatterType(readFileSync9(doc.absPath, "utf8")) })).filter((doc) => !doc.type || allowed && !allowed.includes(doc.type));
+  const bad = scanAgentCorpus(root, config).filter((doc) => doc.path !== config.corpus.agent.index).map((doc) => ({ path: doc.path, type: frontmatterType(readFileSync10(doc.absPath, "utf8")) })).filter((doc) => !doc.type || allowed && !allowed.includes(doc.type));
   if (bad.length) {
     return {
       id: "okf-type",
@@ -1537,13 +1733,22 @@ var DOCS_STYLE_RULES = {
     "examples",
     "no-stale-wording"
   ],
-  "playbook-okf": ["title", "purpose", "owner-source", "no-stale-wording"]
+  /** Full playbook OKF style (strict). */
+  "playbook-okf": ["title", "purpose", "owner-source", "no-stale-wording"],
+  /** Soft profile for large existing OKF corpora (title + no stale placeholders). */
+  "playbook-okf-soft": ["title", "no-stale-wording"],
+  "title-only": ["title"]
 };
 var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var docsStyleOptions = (config) => {
   const raw = config.gates?.options?.["docs-style"];
-  if (!isRecord(raw)) return { profile: "playbook-okf", required: DOCS_STYLE_RULES["playbook-okf"] };
-  const profile = raw.profile === "google-dev-docs" || raw.profile === "playbook-okf" || raw.profile === "custom" ? raw.profile : "playbook-okf";
+  if (!isRecord(raw)) {
+    if (config.gates?.preset === "playbook") {
+      return { profile: "playbook-okf-soft", required: DOCS_STYLE_RULES["playbook-okf-soft"] };
+    }
+    return { profile: "playbook-okf", required: DOCS_STYLE_RULES["playbook-okf"] };
+  }
+  const profile = raw.profile === "google-dev-docs" || raw.profile === "playbook-okf" || raw.profile === "playbook-okf-soft" || raw.profile === "title-only" || raw.profile === "custom" ? raw.profile : "playbook-okf";
   const customRequired = Array.isArray(raw.required) ? raw.required.filter(
     (rule) => [
       "title",
@@ -1581,7 +1786,7 @@ var runDocsStyleGate = (root, config) => {
   }
   const bad = scanAgentCorpus(root, config).filter((doc) => doc.path !== config.corpus.agent.index).map((doc) => ({
     path: doc.path,
-    missing: missingStyleRules(readFileSync9(doc.absPath, "utf8"), required)
+    missing: missingStyleRules(readFileSync10(doc.absPath, "utf8"), required)
   })).filter((doc) => doc.missing.length > 0);
   if (bad.length) {
     return {
@@ -1605,7 +1810,10 @@ var runGates = (root, config, ids) => {
 var resolveGateIds = (config) => {
   const preset = config.gates?.preset ?? "minimal";
   const ids = new Set(
-    preset === "minimal" ? ["index-freshness"] : preset === "strict" ? ["index-freshness", "human-guide-links", "okf-type"] : ["index-freshness", "human-guide-links"]
+    preset === "minimal" ? ["index-freshness"] : preset === "strict" ? ["index-freshness", "human-guide-links", "okf-type", "docs-style"] : preset === "playbook" ? (
+      // okf-type only — docs-style soft is opt-in via include (large corpora vary)
+      ["index-freshness", "okf-type"]
+    ) : ["index-freshness", "human-guide-links"]
   );
   for (const id of config.gates?.include ?? []) {
     if (SUPPORTED_GATES.includes(id)) ids.add(id);
@@ -1617,24 +1825,63 @@ var resolveGateIds = (config) => {
 };
 
 // src/mcp/server.ts
-import { readFileSync as readFileSync11, realpathSync } from "fs";
+import { readFileSync as readFileSync12, realpathSync } from "fs";
 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,
@@ -1644,22 +1891,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
@@ -1689,15 +1945,15 @@ var createDocBridgeRetriever = (index, options = {}) => ({
 });
 
 // src/memory/ingest.ts
-import { existsSync as existsSync7, readFileSync as readFileSync10 } from "fs";
-import { join as join11 } from "path";
+import { existsSync as existsSync8, readFileSync as readFileSync11 } from "fs";
+import { join as join12 } from "path";
 var memoryFact = (raw, id) => firstParagraph(raw) ?? firstHeading(raw) ?? id;
 var relativePath = (root, abs) => toPosix(abs).replace(`${toPosix(root)}/`, "");
 var ingestMarkdownDir = (root, dir, source, confidence) => {
-  if (!existsSync7(dir)) return [];
+  if (!existsSync8(dir)) return [];
   return walkFiles(dir, { extensions: [".md", ".mdc"] }).map((abs) => {
     const rel = relativePath(root, abs);
-    const raw = readFileSync10(abs, "utf8");
+    const raw = readFileSync11(abs, "utf8");
     const id = slugFromPath(rel);
     return {
       schemaVersion: 1,
@@ -1712,10 +1968,10 @@ var ingestMarkdownDir = (root, dir, source, confidence) => {
   });
 };
 var ingestCursorRules = (root) => {
-  const dir = join11(root, ".cursor", "rules");
+  const dir = join12(root, ".cursor", "rules");
   return ingestMarkdownDir(root, dir, "cursor", 0.6);
 };
-var ingestAgentMemory = (root) => ingestMarkdownDir(root, join11(root, ".agent-memory"), "agent-memory", 0.7);
+var ingestAgentMemory = (root) => ingestMarkdownDir(root, join12(root, ".agent-memory"), "agent-memory", 0.7);
 var ingestMemoryCandidates = (root) => [
   ...ingestAgentMemory(root),
   ...ingestCursorRules(root)
@@ -2020,7 +2276,7 @@ var handleMcpRequest = (ctx, request) => {
     return {
       protocolVersion: "2024-11-05",
       capabilities: { tools: {} },
-      serverInfo: { name: "ak-docs", version: "0.1.0-alpha.1" }
+      serverInfo: { name: "ak-docs", version: PACKAGE_VERSION }
     };
   }
   if (request.method === "tools/list") return { tools: MCP_TOOLS };
@@ -2045,7 +2301,7 @@ var handleMcpRequest = (ctx, request) => {
     }
     if (name === "doc.get") {
       const relPath = findDocPath(index(), parseToolArgs("doc.get", DocGetArgsSchema, args));
-      return textResult(readFileSync11(resolveDocPath(ctx.root, relPath), "utf8"));
+      return textResult(readFileSync12(resolveDocPath(ctx.root, relPath), "utf8"));
     }
     if (name === "gate.status") return textResult(runGates(ctx.root, ctx.config));
     if (name === "retriever.query") {
@@ -2123,7 +2379,7 @@ var startMcpStdioServer = (ctx) => {
 };
 
 // src/federation/llms.ts
-import { existsSync as existsSync8, readFileSync as readFileSync12 } from "fs";
+import { existsSync as existsSync9, readFileSync as readFileSync13 } from "fs";
 import { resolve as resolve5 } from "path";
 var tokenize2 = (value) => value.toLowerCase().split(/[^a-z0-9]+/).filter((token) => token.length >= 2);
 var scoreText = (query, text) => {
@@ -2137,10 +2393,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 (!existsSync8(path)) throw new Error(`Federation source not found: ${source}`);
-  return readFileSync12(path, "utf8");
+  try {
+    if (/^https?:\/\//.test(source)) return await fetchText(source);
+    const path = resolve5(root, source);
+    if (!existsSync9(path)) return null;
+    return readFileSync13(path, "utf8");
+  } catch {
+    return null;
+  }
 };
 var sameOrigin = (base, target) => {
   if (!/^https?:\/\//.test(base) || !/^https?:\/\//.test(target)) return true;
@@ -2179,22 +2439,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 = {}) => {
@@ -2216,11 +2482,11 @@ var retrieveHybridChunks = async (root, config, index, query, options = {}) => {
 };
 
 // src/intelligence/rag.ts
-import { readFileSync as readFileSync13 } from "fs";
-import { join as join13 } from "path";
+import { readFileSync as readFileSync14 } from "fs";
+import { join as join14 } from "path";
 
 // src/intelligence/adapter.ts
-import { join as join12 } from "path";
+import { join as join13 } from "path";
 
 // src/intelligence/peers.ts
 var PeerMissingError = class extends Error {
@@ -2335,7 +2601,7 @@ var resolveIntelligenceRuntime = async (config) => {
   }
   return { adapter, embed, provider, ...model ? { model } : {} };
 };
-var defaultVectorStorePath = (root) => join12(root, ".doc-bridge", "vectors");
+var defaultVectorStorePath = (root) => join13(root, ".doc-bridge", "vectors");
 
 // src/intelligence/rag.ts
 var loadDocuments = (root, index, sources) => {
@@ -2343,10 +2609,10 @@ var loadDocuments = (root, index, sources) => {
   const docs = [];
   if (includeAgent) {
     for (const entry of index.knowledge) {
-      const abs = join13(root, entry.path);
+      const abs = join14(root, entry.path);
       let content = "";
       try {
-        content = readFileSync13(abs, "utf8");
+        content = readFileSync14(abs, "utf8");
       } catch {
         content = [entry.title, entry.description].filter(Boolean).join("\n\n");
       }
@@ -2364,7 +2630,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" ? join13(root, config.intelligence.retriever.options.storePath) : defaultVectorStorePath(root);
+  const storePath = typeof config.intelligence?.retriever?.options?.storePath === "string" ? join14(root, config.intelligence.retriever.options.storePath) : defaultVectorStorePath(root);
   const store = memoryMod.fileVectorMemory({ path: storePath });
   const rag = ragMod.createRAG({
     embed,