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

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",
@@ -695,16 +698,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) => {
@@ -780,7 +847,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 +861,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,13 +885,13 @@ 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;
@@ -842,16 +909,29 @@ var scanAgentCorpus = (root, config) => {
   });
 };
 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 +947,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 +1013,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 +1029,51 @@ 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$/, "")
+  ];
+  for (const alias of aliases) {
+    if (humanDocs[alias]) return humanDocs[alias];
+  }
+  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 +1127,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.2";
 
 // src/index-builder/capabilities.ts
 var renderCapabilitiesJson = (config, index, paths) => {
@@ -1041,13 +1196,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 +1233,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 +1275,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 +1306,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 +1335,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 +1356,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 +1369,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 +1389,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 +1408,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 +1426,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 +1477,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 +1489,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 +1512,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 +1520,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 +1531,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 +1566,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 +1578,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 +1600,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 +1613,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 +1682,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 +1703,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 +1756,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 +1780,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,7 +1795,7 @@ 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";
 
@@ -1689,15 +1867,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 +1890,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 +2198,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 +2223,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 +2301,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) => {
@@ -2139,8 +2317,8 @@ var defaultFetchText = async (url) => {
 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");
+  if (!existsSync9(path)) throw new Error(`Federation source not found: ${source}`);
+  return readFileSync13(path, "utf8");
 };
 var sameOrigin = (base, target) => {
   if (!/^https?:\/\//.test(base) || !/^https?:\/\//.test(target)) return true;
@@ -2216,11 +2394,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 +2513,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 +2521,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 +2542,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,