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

package/dist/cli/program.js

@@ -1,5 +1,5 @@
 // src/cli/program.ts
-import { existsSync as existsSync9, mkdirSync as mkdirSync2, readFileSync as readFileSync14, writeFileSync as writeFileSync2 } from "fs";
+import { existsSync as existsSync10, mkdirSync as mkdirSync2, readFileSync as readFileSync15, writeFileSync as writeFileSync2 } from "fs";
 import { dirname as dirname4, resolve as resolve6 } from "path";
 import { createInterface } from "readline/promises";
 
@@ -20,7 +20,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]
       }
     },
@@ -113,9 +113,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({
@@ -135,7 +137,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",
@@ -343,16 +346,80 @@ var projectRootFromConfigPath = (configFilePath, projectRootField) => {
 };
 
 // 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) => {
@@ -402,7 +469,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 = [];
@@ -414,11 +481,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?$/, "");
@@ -428,7 +511,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"];
@@ -442,7 +525,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);
@@ -466,17 +549,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",
@@ -485,21 +570,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");
@@ -515,13 +614,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 ?? {})) {
@@ -539,7 +680,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 });
@@ -551,22 +696,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 } : {},
@@ -620,7 +802,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) => {
@@ -689,13 +871,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];
@@ -726,10 +908,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),
@@ -768,8 +950,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;
@@ -799,7 +981,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 };
@@ -828,13 +1010,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;
@@ -849,7 +1031,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] ?? "");
@@ -862,9 +1044,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
     });
@@ -875,7 +1064,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 });
   }
 };
@@ -894,10 +1083,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);
@@ -908,26 +1101,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 {
@@ -959,10 +1152,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;
   }
@@ -971,9 +1164,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 [];
@@ -994,7 +1187,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 {
   }
@@ -1002,7 +1195,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;
@@ -1013,14 +1206,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,
@@ -1048,7 +1241,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,
@@ -1060,7 +1253,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(
@@ -1082,23 +1275,62 @@ var buildDocBridgeIndex = (opts) => {
 };
 
 // src/federation/llms.ts
-import { existsSync as existsSync6, readFileSync as readFileSync8 } from "fs";
+import { existsSync as existsSync7, readFileSync as readFileSync9 } from "fs";
 import { resolve as resolve3 } from "path";
 
 // 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,
@@ -1108,22 +1340,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
@@ -1162,10 +1403,14 @@ var defaultFetchText = async (url) => {
   return res.text();
 };
 var sourceText = async (root, source, fetchText) => {
-  if (/^https?:\/\//.test(source)) return fetchText(source);
-  const path = resolve3(root, source);
-  if (!existsSync6(path)) throw new Error(`Federation source not found: ${source}`);
-  return readFileSync8(path, "utf8");
+  try {
+    if (/^https?:\/\//.test(source)) return await fetchText(source);
+    const path = resolve3(root, source);
+    if (!existsSync7(path)) return null;
+    return readFileSync9(path, "utf8");
+  } catch {
+    return null;
+  }
 };
 var sameOrigin = (base, target) => {
   if (!/^https?:\/\//.test(base) || !/^https?:\/\//.test(target)) return true;
@@ -1204,22 +1449,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 = {}) => {
@@ -1241,11 +1492,11 @@ var retrieveHybridChunks = async (root, config, index, query, options = {}) => {
 };
 
 // src/gates/run-gates.ts
-import { readFileSync as readFileSync10 } from "fs";
+import { readFileSync as readFileSync11 } from "fs";
 
 // src/query/load-index.ts
-import { existsSync as existsSync7, readFileSync as readFileSync9 } from "fs";
-import { join as join10, resolve as resolve4 } from "path";
+import { existsSync as existsSync8, readFileSync as readFileSync10 } from "fs";
+import { join as join11, resolve as resolve4 } from "path";
 
 // src/schemas/agent-handoff.ts
 import { z as z2 } from "zod";
@@ -1319,7 +1570,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();
@@ -1450,11 +1703,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 (!existsSync7(path)) throw new IndexNotFoundError(path);
-  const raw = JSON.parse(readFileSync9(path, "utf8"));
+  if (!existsSync8(path)) throw new IndexNotFoundError(path);
+  const raw = JSON.parse(readFileSync10(path, "utf8"));
   return parseDocBridgeIndex(raw);
 };
 
@@ -1518,7 +1771,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(readFileSync10(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(readFileSync11(doc.absPath, "utf8")) })).filter((doc) => !doc.type || allowed && !allowed.includes(doc.type));
   if (bad.length) {
     return {
       id: "okf-type",
@@ -1539,13 +1792,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",
@@ -1583,7 +1845,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(readFileSync10(doc.absPath, "utf8"), required)
+    missing: missingStyleRules(readFileSync11(doc.absPath, "utf8"), required)
   })).filter((doc) => doc.missing.length > 0);
   if (bad.length) {
     return {
@@ -1607,7 +1869,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);
@@ -1720,7 +1985,7 @@ var runQuery = (index, config, req) => {
 };
 
 // src/intelligence/adapter.ts
-import { join as join11 } from "path";
+import { join as join12 } from "path";
 
 // src/intelligence/peers.ts
 var PeerMissingError = class extends Error {
@@ -1835,20 +2100,20 @@ var resolveIntelligenceRuntime = async (config) => {
   }
   return { adapter, embed, provider, ...model ? { model } : {} };
 };
-var defaultVectorStorePath = (root) => join11(root, ".doc-bridge", "vectors");
+var defaultVectorStorePath = (root) => join12(root, ".doc-bridge", "vectors");
 
 // src/intelligence/rag.ts
-import { readFileSync as readFileSync11 } from "fs";
-import { join as join12 } from "path";
+import { readFileSync as readFileSync12 } from "fs";
+import { join as join13 } from "path";
 var loadDocuments = (root, index, sources) => {
   const includeAgent = sources.includes("agent") || sources.length === 0;
   const docs = [];
   if (includeAgent) {
     for (const entry of index.knowledge) {
-      const abs = join12(root, entry.path);
+      const abs = join13(root, entry.path);
       let content = "";
       try {
-        content = readFileSync11(abs, "utf8");
+        content = readFileSync12(abs, "utf8");
       } catch {
         content = [entry.title, entry.description].filter(Boolean).join("\n\n");
       }
@@ -1866,7 +2131,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" ? join12(root, config.intelligence.retriever.options.storePath) : defaultVectorStorePath(root);
+  const storePath = typeof config.intelligence?.retriever?.options?.storePath === "string" ? join13(root, config.intelligence.retriever.options.storePath) : defaultVectorStorePath(root);
   const store = memoryMod.fileVectorMemory({ path: storePath });
   const rag = ragMod.createRAG({
     embed,
@@ -2001,15 +2266,15 @@ var startInkChat = async (root, config, index) => {
 };
 
 // src/memory/ingest.ts
-import { existsSync as existsSync8, readFileSync as readFileSync12 } from "fs";
-import { join as join13 } from "path";
+import { existsSync as existsSync9, readFileSync as readFileSync13 } from "fs";
+import { join as join14 } 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 (!existsSync8(dir)) return [];
+  if (!existsSync9(dir)) return [];
   return walkFiles(dir, { extensions: [".md", ".mdc"] }).map((abs) => {
     const rel = relativePath(root, abs);
-    const raw = readFileSync12(abs, "utf8");
+    const raw = readFileSync13(abs, "utf8");
     const id = slugFromPath(rel);
     return {
       schemaVersion: 1,
@@ -2024,10 +2289,10 @@ var ingestMarkdownDir = (root, dir, source, confidence) => {
   });
 };
 var ingestCursorRules = (root) => {
-  const dir = join13(root, ".cursor", "rules");
+  const dir = join14(root, ".cursor", "rules");
   return ingestMarkdownDir(root, dir, "cursor", 0.6);
 };
-var ingestAgentMemory = (root) => ingestMarkdownDir(root, join13(root, ".agent-memory"), "agent-memory", 0.7);
+var ingestAgentMemory = (root) => ingestMarkdownDir(root, join14(root, ".agent-memory"), "agent-memory", 0.7);
 var ingestMemoryCandidates = (root) => [
   ...ingestAgentMemory(root),
   ...ingestCursorRules(root)
@@ -2113,7 +2378,7 @@ var draftMemoryPromotion = (classifications) => {
 };
 
 // src/mcp/server.ts
-import { readFileSync as readFileSync13, realpathSync } from "fs";
+import { readFileSync as readFileSync14, realpathSync } from "fs";
 import { relative, resolve as resolve5 } from "path";
 import { z as z5, ZodError } from "zod";
 var MCP_TOOLS = [
@@ -2234,7 +2499,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 };
@@ -2259,7 +2524,7 @@ var handleMcpRequest = (ctx, request) => {
     }
     if (name === "doc.get") {
       const relPath = findDocPath(index(), parseToolArgs("doc.get", DocGetArgsSchema, args));
-      return textResult(readFileSync13(resolveDocPath(ctx.root, relPath), "utf8"));
+      return textResult(readFileSync14(resolveDocPath(ctx.root, relPath), "utf8"));
     }
     if (name === "gate.status") return textResult(runGates(ctx.root, ctx.config));
     if (name === "retriever.query") {
@@ -2436,35 +2701,38 @@ var writeTextQuery = (payload) => {
     writeLines([
       `Search: ${String(data.term ?? "")}`,
       `Matches: ${String(data.count ?? matches.length)}`,
-      ...matches.map(
-        (match) => [match.type, match.id, match.path, match.summary].filter(Boolean).join("	")
-      )
+      ...matches.length ? matches.map(
+        (match) => formatSearchMatch(match)
+      ) : ["  (none)"]
     ]);
     return;
   }
   writeLines([textValue(result.data)]);
 };
+var formatSearchMatch = (match) => {
+  const summary = match.summary ? match.summary.replace(/\s+/g, " ").slice(0, 100) : "";
+  const score = typeof match.score === "number" ? ` score=${match.score}` : "";
+  return `  [${match.type}] ${match.id}${score}
+    ${match.path}${summary ? `
+    ${summary}` : ""}`;
+};
 var writeTextSearch = (term, matches) => {
   writeLines([
     `Search: ${term}`,
     `Matches: ${matches.length}`,
-    ...matches.map(
-      (match) => [match.type, match.id, match.path, match.summary].filter(Boolean).join("	")
-    )
+    ...matches.length ? matches.map(formatSearchMatch) : ["  (none)"]
   ]);
 };
 var writeAsk = (question, matches, index) => {
-  const best = matches[0];
-  const owner = matches.find((match) => match.type === "ownership" || index.lookup?.ownership?.[match.id]);
-  const bestQuery = owner ? `ak-docs query ownership ${owner.id} --agent` : "ak-docs list knowledge --text";
+  const owner = matches.find((match) => match.type === "ownership") ?? matches.find((match) => Boolean(index.lookup?.ownership?.[match.id]));
+  const best = owner ?? matches[0];
+  const bestQuery = best && (best.type === "ownership" || index.lookup?.ownership?.[best.id]) ? `ak-docs query ownership ${best.id} --agent` : "ak-docs list knowledge --text";
   writeLines([
     `Question: ${question}`,
     best ? `Best match: ${best.type} ${best.id} (${best.path})` : "Best match: none",
     "",
     "Matches:",
-    ...matches.length ? matches.slice(0, 5).map(
-      (match) => [match.type, match.id, match.path, match.summary].filter(Boolean).join("	")
-    ) : ["No local matches. Try: ak-docs search <term>"],
+    ...matches.length ? matches.slice(0, 5).map(formatSearchMatch) : ["  No local matches. Try: ak-docs search <term>"],
     "",
     "Next commands:",
     ...best ? [
@@ -2482,7 +2750,7 @@ var readIndexedDoc = (root, config, idOrPath) => {
   if (abs !== rootAbs && !abs.startsWith(`${rootAbs}/`)) {
     throw new Error(`Indexed doc escapes project root: ${entry.path}`);
   }
-  return readFileSync14(abs, "utf8");
+  return readFileSync15(abs, "utf8");
 };
 var runAskRepl = async (root, config) => {
   const index = loadDocBridgeIndex(root, config);
@@ -2558,7 +2826,7 @@ var diagnosticNextCommands = (config, result) => {
   ];
 };
 var writeIfMissing = (path, contents) => {
-  if (existsSync9(path)) return false;
+  if (existsSync10(path)) return false;
   mkdirSync2(dirname4(path), { recursive: true });
   writeFileSync2(path, contents, "utf8");
   return true;
@@ -2673,7 +2941,7 @@ var bootstrapAgentDocs = (root, config) => {
   const created = [];
   const skipped = [];
   for (const doc of scanHumanDocRecords(root, config)) {
-    const raw = readFileSync14(doc.path, "utf8");
+    const raw = readFileSync15(doc.path, "utf8");
     const body = raw.replace(/^---\n[\s\S]*?\n---\n?/, "");
     const title = firstHeading(body) ?? doc.id;
     const description = firstParagraph(body);
@@ -2742,7 +3010,7 @@ var runCli = (argv) => {
     }
     try {
       const abs = resolve6(file);
-      const raw = readFileSync14(abs, "utf8");
+      const raw = readFileSync15(abs, "utf8");
       const handoff = parseAgentHandoff(JSON.parse(raw));
       writeJson({ ok: true, handoff });
       return 0;