@agentskit/doc-bridge 1.2.4 → 1.3.0

package/dist/index.js

@@ -64,6 +64,8 @@ var HumanCorpusPluginIdSchema = z.enum([
   "docusaurus",
   "mkdocs",
   "vitepress",
+  "starlight",
+  "nextra",
   "custom"
 ]);
 var AgentCorpusConfigSchema = z.object({
@@ -103,7 +105,7 @@ 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", "pattern-files", "custom"]).optional(),
+  plugin: z.enum(["pnpm-monorepo", "npm-workspaces", "yarn-workspaces", "nx", "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). */
@@ -1028,8 +1030,8 @@ ${zodIssues(result.error).map((i) => `  - ${i.path}: ${i.message}`).join("\n")}`
 };
 
 // src/index-builder/build-index.ts
-import { mkdirSync, readFileSync as readFileSync6, writeFileSync } from "fs";
-import { dirname as dirname3, join as join7 } from "path";
+import { mkdirSync, readFileSync as readFileSync7, writeFileSync } from "fs";
+import { dirname as dirname4, join as join7 } from "path";
 
 // src/lib/paths.ts
 import { existsSync as existsSync2, realpathSync } from "fs";
@@ -1298,17 +1300,17 @@ var scanAgentCorpus = (root, config) => {
     };
   });
 };
-var guessAgentDocForPackage = (corpus, packageId) => {
+var guessAgentDocForPackage = (corpus, packageId2) => {
   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}/`)
+    (doc) => frontmatterString(doc.frontmatter, "package") === packageId2,
+    (doc) => doc.id === packageId2,
+    (doc) => doc.relPath.endsWith(`/packages/${packageId2}.md`),
+    (doc) => doc.relPath.endsWith(`/packages/${packageId2}.mdx`),
+    (doc) => doc.relPath.endsWith(`/packages/${packageId2}/index.md`),
+    (doc) => doc.relPath.endsWith(`/packages/${packageId2}/index.mdx`),
+    (doc) => doc.relPath.endsWith(`/${packageId2}.md`),
+    (doc) => doc.relPath.endsWith(`/${packageId2}.mdx`),
+    (doc) => doc.relPath.includes(`/packages/${packageId2}/`)
   ];
   for (const match of candidates) {
     const hit = corpus.find(match);
@@ -1400,7 +1402,8 @@ var collectPackages = (config, discovered, corpus) => {
     byId.set(pkg.id, {
       id: pkg.id,
       path: existing.path || pkg.path,
-      ...pkg.name ? { name: pkg.name } : existing.name ? { name: existing.name } : {}
+      ...pkg.name ? { name: pkg.name } : existing.name ? { name: existing.name } : {},
+      ...pkg.checks ? { checks: pkg.checks } : existing.checks ? { checks: existing.checks } : {}
     });
   }
   const seeds = [
@@ -1419,24 +1422,24 @@ var collectPackages = (config, discovered, corpus) => {
   }
   return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
 };
-var resolveHumanDoc = (packageId, override, fmHuman, humanDocs = {}) => {
+var resolveHumanDoc = (packageId2, override, fmHuman, humanDocs = {}) => {
   if (override) return override;
   if (fmHuman) return fmHuman;
-  if (humanDocs[packageId]) return humanDocs[packageId];
+  if (humanDocs[packageId2]) return humanDocs[packageId2];
   const aliases = [
-    packageId,
-    packageId.replace(/^@[^/]+\//, ""),
-    packageId.replace(/^os-/, ""),
-    packageId.replace(/-pattern$/, ""),
-    `packages/${packageId}`,
-    `reference/packages/${packageId}`,
-    `packages/${packageId}/index`
+    packageId2,
+    packageId2.replace(/^@[^/]+\//, ""),
+    packageId2.replace(/^os-/, ""),
+    packageId2.replace(/-pattern$/, ""),
+    `packages/${packageId2}`,
+    `reference/packages/${packageId2}`,
+    `packages/${packageId2}/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}`)) {
+    if (key === packageId2 || key.endsWith(`/${packageId2}`) || key.endsWith(`/${packageId2}/index`) || key.endsWith(`-${packageId2}`)) {
       return url;
     }
   }
@@ -1460,7 +1463,7 @@ var buildLookup = (config, packages, corpus, indexOutFile, humanDocs = {}, root
     const purpose = override?.purpose ?? fm?.purpose;
     const path = override?.path ?? fm?.path ?? pkg.path;
     const checks = [
-      ...override?.checks ?? fm?.checks ?? defaultChecksForTarget(root, {
+      ...override?.checks ?? fm?.checks ?? pkg.checks ?? defaultChecksForTarget(root, {
         packageId: pkg.id,
         packagePath: path,
         ...pkg.name ? { packageName: pkg.name } : {},
@@ -1534,7 +1537,7 @@ var buildLookup = (config, packages, corpus, indexOutFile, humanDocs = {}, root
 };
 
 // src/version.ts
-var PACKAGE_VERSION = "1.2.4";
+var PACKAGE_VERSION = "1.3.0";
 
 // src/index-builder/capabilities.ts
 var renderCapabilitiesJson = (config, index, paths) => {
@@ -1791,6 +1794,38 @@ var fumadocsAdapter = {
   }
 };
 
+// src/index-builder/human-adapters/nextra.ts
+var nextraRecordId = (relPath, raw) => {
+  const frontmatter = parseFrontmatter2(raw);
+  return frontmatter.package ?? frontmatter.module ?? frontmatter.id ?? (routeSlug(relPath) || "index");
+};
+var isIndexPage = (path) => /(^|[/\\])index\.mdx?$/i.test(path);
+var resolveRouteCollisions = (records) => {
+  const byUrl = /* @__PURE__ */ new Map();
+  for (const record of records) {
+    const normalized = { ...record, url: record.url || "/" };
+    const indexPage = isIndexPage(record.path);
+    const existing = byUrl.get(normalized.url);
+    if (!existing || indexPage || !existing.indexPage) {
+      byUrl.set(normalized.url, { record: normalized, indexPage });
+    }
+  }
+  return [...byUrl.values()].map(({ record }) => record);
+};
+var nextraAdapter = {
+  plugin: "nextra",
+  scan: ({ root, config }) => {
+    const contentDir = optionString(config.options, ["contentDir", "docsDir", "root"]);
+    if (!contentDir) return [];
+    return resolveRouteCollisions(
+      scanMarkdownDocs(root, contentDir, {
+        idForDoc: nextraRecordId,
+        urlPrefix: optionString(config.options, ["urlPrefix", "contentDirBasePath"]) ?? "/"
+      })
+    );
+  }
+};
+
 // src/index-builder/human-adapters/plain-markdown.ts
 var plainMarkdownAdapter = {
   plugin: "plain-markdown",
@@ -1800,11 +1835,73 @@ var plainMarkdownAdapter = {
   }
 };
 
+// src/index-builder/human-adapters/starlight.ts
+import { slug as githubSlug } from "github-slugger";
+var isStarlightPage = (relPath, raw) => {
+  if (relPath.split("/").some((part) => part.startsWith(".") || part.startsWith("_"))) return false;
+  return parseFrontmatter2(raw).draft !== "true";
+};
+var starlightFileSlug = (relPath) => routeSlug(relPath).split("/").map((part) => githubSlug(part)).filter(Boolean).join("/");
+var starlightSlug = (relPath, raw) => {
+  const slug2 = parseFrontmatter2(raw).slug;
+  return slug2 ? slug2.replace(/^\/+|\/+$/g, "") : starlightFileSlug(relPath);
+};
+var starlightAdapter = {
+  plugin: "starlight",
+  scan: ({ root, config }) => {
+    const contentDir = optionString(config.options, ["contentDir", "docsDir", "root"]);
+    if (!contentDir) return [];
+    return scanMarkdownDocs(root, contentDir, {
+      includeRelPath: isStarlightPage,
+      slugForDoc: starlightSlug,
+      urlPrefix: config.options?.urlPrefix
+    });
+  }
+};
+
+// src/index-builder/human-adapters/vitepress.ts
+import { minimatch } from "minimatch";
+var isVitePressPage = (relPath) => !relPath.split("/").some((part) => part === ".vitepress" || part.startsWith("."));
+var srcExcludePatterns = (value) => {
+  if (value === void 0) return [];
+  if (!Array.isArray(value) || value.length > 64) {
+    throw new Error("VitePress srcExclude must be an array of at most 64 glob patterns.");
+  }
+  return value.map((pattern) => {
+    if (typeof pattern !== "string" || !pattern || pattern.length > 256 || pattern.includes("\0")) {
+      throw new Error("Each VitePress srcExclude pattern must be a non-empty string up to 256 characters.");
+    }
+    return pattern;
+  });
+};
+var isExcluded = (relPath, patterns) => patterns.some((pattern) => minimatch(relPath, pattern, { dot: true }));
+var vitepressSlug = (relPath, cleanUrls) => {
+  const slug2 = routeSlug(relPath);
+  if (cleanUrls || /(?:^|\/)index\.mdx?$/.test(relPath)) return slug2;
+  return `${slug2}.html`;
+};
+var vitepressAdapter = {
+  plugin: "vitepress",
+  scan: ({ root, config }) => {
+    const docsDir = optionString(config.options, ["docsDir", "root", "srcDir"]);
+    if (!docsDir) return [];
+    const srcExclude = srcExcludePatterns(config.options?.srcExclude);
+    return scanMarkdownDocs(root, docsDir, {
+      includeRelPath: (relPath) => isVitePressPage(relPath) && !isExcluded(relPath, srcExclude),
+      slugForDoc: (relPath) => vitepressSlug(relPath, config.options?.cleanUrls === true),
+      urlPrefix: config.options?.urlPrefix
+    });
+  }
+};
+
 // src/index-builder/human-adapters/index.ts
 var ADAPTERS = [
   plainMarkdownAdapter,
   fumadocsAdapter,
-  docusaurusAdapter
+  docusaurusAdapter,
+  vitepressAdapter,
+  starlightAdapter,
+  nextraAdapter
 ];
 var humanConfigs = (config) => {
   const human = config.corpus.human;
@@ -1839,12 +1936,121 @@ var scanHumanDocRecords = (root, config) => {
 };
 var scanHumanDocs = (root, config) => Object.fromEntries(scanHumanDocRecords(root, config).map((doc) => [doc.id, doc.url]));
 
+// src/index-builder/plugins/nx.ts
+import { existsSync as existsSync6, lstatSync as lstatSync2, readFileSync as readFileSync5, realpathSync as realpathSync5 } from "fs";
+import { basename as basename2, dirname as dirname3, isAbsolute as isAbsolute3, relative as relative3, resolve as resolve5, sep as sep4 } from "path";
+var NX_SCAN_SKIP = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  ".nx",
+  "dist",
+  "coverage",
+  ".doc-bridge"
+]);
+var NX_PROJECT_NAME = /^(?:@[A-Za-z0-9._-]+\/)?[A-Za-z0-9][A-Za-z0-9._-]*$/;
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var readJsonRecord = (path) => {
+  try {
+    const parsed = JSON.parse(readFileSync5(path, "utf8"));
+    return isRecord(parsed) ? parsed : void 0;
+  } catch {
+    return void 0;
+  }
+};
+var safeProjectPath = (root, manifestDir, declaredRoot) => {
+  const candidate = typeof declaredRoot === "string" ? resolve5(root, declaredRoot) : manifestDir;
+  const rel = toPosix(relative3(root, candidate)) || ".";
+  if (isAbsolute3(rel) || rel === ".." || rel.startsWith("../")) return void 0;
+  try {
+    if (!lstatSync2(candidate).isDirectory()) return void 0;
+    const canonicalRoot = realpathSync5.native(root);
+    const canonicalCandidate = realpathSync5.native(candidate);
+    const canonicalRel = relative3(canonicalRoot, canonicalCandidate);
+    if (isAbsolute3(canonicalRel) || canonicalRel === ".." || canonicalRel.startsWith(`..${sep4}`)) {
+      return void 0;
+    }
+  } catch {
+    return void 0;
+  }
+  return rel;
+};
+var packageId = (name) => name.startsWith("@") ? name.split("/").at(-1) ?? name : name;
+var commandPrefix = (root) => {
+  const manager = detectPackageManager(root);
+  if (manager === "pnpm") return "pnpm exec nx run";
+  if (manager === "yarn") return "yarn nx run";
+  if (manager === "bun") return "bunx nx run";
+  return "npx nx run";
+};
+var inferredChecks = (root, config, projectName2, targets) => {
+  const prefix = commandPrefix(root);
+  const strict = (config.gates?.preset ?? "minimal") !== "minimal";
+  const checks = [
+    ...targets.has("test") ? [`${prefix} ${projectName2}:test`] : [],
+    ...strict && targets.has("lint") ? [`${prefix} ${projectName2}:lint`] : []
+  ];
+  return checks.length ? checks : void 0;
+};
+var discoverNxProjects = (root, config) => {
+  if (!existsSync6(resolve5(root, "nx.json"))) return [];
+  const manifests = walkFiles(root, {
+    extensions: ["project.json", "package.json"],
+    skipDirs: NX_SCAN_SKIP,
+    maxFiles: 1e4
+  });
+  const projects = /* @__PURE__ */ new Map();
+  for (const manifest of manifests) {
+    const json = readJsonRecord(manifest);
+    if (!json) continue;
+    const manifestDir = dirname3(manifest);
+    const manifestName = basename2(manifest);
+    const isProjectJson = manifestName === "project.json";
+    if (!isProjectJson && manifestName !== "package.json") continue;
+    const nx = json.nx;
+    if (!isProjectJson && !isRecord(nx)) continue;
+    const path = safeProjectPath(root, manifestDir, isProjectJson ? json.root : void 0);
+    if (!path) continue;
+    const projectPackage = isProjectJson ? readJsonRecord(resolve5(root, path, "package.json")) : void 0;
+    const projectName2 = typeof json.name === "string" ? json.name : typeof projectPackage?.name === "string" ? projectPackage.name : basename2(path === "." ? root : path);
+    if (!NX_PROJECT_NAME.test(projectName2)) continue;
+    const targets = /* @__PURE__ */ new Set();
+    const targetRecord = isProjectJson ? json.targets : isRecord(nx) ? nx.targets : void 0;
+    if (isRecord(targetRecord)) {
+      for (const target of Object.keys(targetRecord)) targets.add(target);
+    }
+    if (!isProjectJson && isRecord(json.scripts)) {
+      for (const script of Object.keys(json.scripts)) targets.add(script);
+    }
+    const id = packageId(projectName2);
+    const rank = isProjectJson ? 2 : 1;
+    const existing = projects.get(id);
+    if (existing && existing.path !== path) {
+      throw new Error(
+        `Nx project identity collision for "${id}": "${existing.name ?? id}" at "${existing.path}" and "${projectName2}" at "${path}". Use unique Nx project names.`
+      );
+    }
+    const mergedTargets = [.../* @__PURE__ */ new Set([...existing?.targets ?? [], ...targets])];
+    const projectJsonWins = rank >= (existing?.rank ?? 0);
+    const resolvedName = projectJsonWins ? projectName2 : existing?.name ?? projectName2;
+    const checks = inferredChecks(root, config, resolvedName, new Set(mergedTargets));
+    projects.set(id, {
+      id,
+      path,
+      name: resolvedName,
+      ...checks ? { checks } : {},
+      rank: projectJsonWins ? rank : existing?.rank ?? rank,
+      targets: mergedTargets
+    });
+  }
+  return [...projects.values()].sort((a, b) => a.id.localeCompare(b.id)).map(({ rank: _rank, targets: _targets, ...project }) => project);
+};
+
 // src/index-builder/plugins/pnpm-monorepo.ts
-import { existsSync as existsSync7, readFileSync as readFileSync5 } from "fs";
-import { basename as basename2, join as join6 } from "path";
+import { existsSync as existsSync8, readFileSync as readFileSync6 } from "fs";
+import { basename as basename3, join as join6 } from "path";
 
 // src/lib/glob-expand.ts
-import { existsSync as existsSync6, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
+import { existsSync as existsSync7, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
 import { join as join5 } from "path";
 var expandWorkspaceGlobs = (root, patterns) => {
   const dirs = /* @__PURE__ */ new Set();
@@ -1852,12 +2058,12 @@ var expandWorkspaceGlobs = (root, patterns) => {
     const normalized = toPosix(pattern).replace(/\/$/, "");
     if (!normalized.includes("*")) {
       const abs = join5(root, normalized);
-      if (existsSync6(abs)) dirs.add(toPosix(abs));
+      if (existsSync7(abs)) dirs.add(toPosix(abs));
       continue;
     }
     const star = normalized.indexOf("*");
     const base = join5(root, normalized.slice(0, star).replace(/\/$/, ""));
-    if (!existsSync6(base)) continue;
+    if (!existsSync7(base)) continue;
     for (const name of readdirSync2(base)) {
       const abs = join5(base, name);
       try {
@@ -1892,9 +2098,9 @@ var parsePnpmWorkspace = (yaml) => {
 };
 var readPackageJson = (dir) => {
   const file = join6(dir, "package.json");
-  if (!existsSync7(file)) return null;
+  if (!existsSync8(file)) return null;
   try {
-    return JSON.parse(readFileSync5(file, "utf8"));
+    return JSON.parse(readFileSync6(file, "utf8"));
   } catch {
     return null;
   }
@@ -1904,8 +2110,8 @@ var discoverPnpmPackages = (root, config) => {
   let patterns = explicit;
   if (!patterns?.length) {
     const workspaceFile = join6(root, "pnpm-workspace.yaml");
-    if (existsSync7(workspaceFile)) {
-      patterns = parsePnpmWorkspace(readFileSync5(workspaceFile, "utf8"));
+    if (existsSync8(workspaceFile)) {
+      patterns = parsePnpmWorkspace(readFileSync6(workspaceFile, "utf8"));
     }
   }
   if (!patterns?.length) return [];
@@ -1915,7 +2121,7 @@ var discoverPnpmPackages = (root, config) => {
     const pkg = readPackageJson(abs);
     if (!pkg) continue;
     const rel = toPosix(abs.replace(`${toPosix(root)}/`, ""));
-    const folderId = basename2(abs);
+    const folderId = basename3(abs);
     const id = pkg.name?.startsWith("@") ? pkg.name.split("/").pop() ?? folderId : pkg.name ?? folderId;
     out.push({ id, path: rel, ...pkg.name ? { name: pkg.name } : {} });
   }
@@ -1926,7 +2132,7 @@ var discoverPnpmPackages = (root, config) => {
 var projectName = (root, config) => {
   if (config.project?.name) return config.project.name;
   try {
-    const pkg = JSON.parse(readFileSync6(join7(root, "package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync7(join7(root, "package.json"), "utf8"));
     if (pkg.name) return pkg.name;
   } catch {
   }
@@ -1934,7 +2140,7 @@ var projectName = (root, config) => {
 };
 var existingGeneratedAt = (indexPath, contentHash) => {
   try {
-    const index = JSON.parse(readFileSync6(indexPath, "utf8"));
+    const index = JSON.parse(readFileSync7(indexPath, "utf8"));
     return index.contentHash === contentHash && typeof index.generatedAt === "string" ? index.generatedAt : void 0;
   } catch {
     return void 0;
@@ -1949,7 +2155,7 @@ var buildDocBridgeIndex = (opts) => {
   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 discovered = config.routing?.plugin === "nx" ? discoverNxProjects(root, config) : shouldDiscover ? discoverPnpmPackages(root, config) : [];
   const packages = collectPackages(config, discovered, corpus);
   const humanDocs = scanHumanDocs(root, config);
   const { lookup, handoffs } = buildLookup(config, packages, corpus, outFile, humanDocs, root);
@@ -1971,7 +2177,7 @@ var buildDocBridgeIndex = (opts) => {
     lookup
   };
   if (write) {
-    mkdirSync(dirname3(indexPath), { recursive: true });
+    mkdirSync(dirname4(indexPath), { recursive: true });
     writeFileSync(indexPath, `${JSON.stringify(index, null, 2)}
 `, "utf8");
   }
@@ -1994,7 +2200,7 @@ var buildDocBridgeIndex = (opts) => {
     const capabilitiesOut = config.index?.capabilities?.outFile ?? ".doc-bridge/capabilities.json";
     capabilitiesPath = join7(root, capabilitiesOut);
     if (write) {
-      mkdirSync(dirname3(capabilitiesPath), { recursive: true });
+      mkdirSync(dirname4(capabilitiesPath), { recursive: true });
       writeFileSync(
         capabilitiesPath,
         renderCapabilitiesJson(config, index, {
@@ -2040,11 +2246,11 @@ function formatEcosystemLlmsSection(options) {
 }
 
 // src/gates/run-gates.ts
-import { readFileSync as readFileSync9 } from "fs";
+import { readFileSync as readFileSync10 } from "fs";
 
 // src/conformance/documentation-standard-v1.ts
-import { existsSync as existsSync8, readFileSync as readFileSync7, realpathSync as realpathSync5, statSync as statSync3 } from "fs";
-import { isAbsolute as isAbsolute3, relative as relative3, resolve as resolve5, sep as sep4 } from "path";
+import { existsSync as existsSync9, readFileSync as readFileSync8, realpathSync as realpathSync6, statSync as statSync3 } from "fs";
+import { isAbsolute as isAbsolute4, relative as relative4, resolve as resolve6, sep as sep5 } from "path";
 
 // src/conformance/ecosystem-contract.ts
 import { z as z5 } from "zod";
@@ -2223,15 +2429,15 @@ var DOCUMENTATION_STANDARD_V1_ID = "documentation-standard-v1";
 var DOCUMENTATION_STANDARD_V1_STATUS = "stable";
 var MAX_TEXT_EVIDENCE_BYTES = 4 * 1024 * 1024;
 var safePath = (root, path) => {
-  const rootAbs = realpathSync5.native(resolve5(root));
-  const unresolved = resolve5(rootAbs, path);
-  const unresolvedRel = relative3(rootAbs, unresolved);
-  if (isAbsolute3(unresolvedRel) || unresolvedRel === ".." || unresolvedRel.startsWith(`..${sep4}`)) return void 0;
-  if (!existsSync8(unresolved)) return unresolved;
+  const rootAbs = realpathSync6.native(resolve6(root));
+  const unresolved = resolve6(rootAbs, path);
+  const unresolvedRel = relative4(rootAbs, unresolved);
+  if (isAbsolute4(unresolvedRel) || unresolvedRel === ".." || unresolvedRel.startsWith(`..${sep5}`)) return void 0;
+  if (!existsSync9(unresolved)) return unresolved;
   try {
-    const abs = realpathSync5.native(unresolved);
-    const rel = relative3(rootAbs, abs);
-    return !isAbsolute3(rel) && rel !== ".." && !rel.startsWith(`..${sep4}`) ? abs : void 0;
+    const abs = realpathSync6.native(unresolved);
+    const rel = relative4(rootAbs, abs);
+    return !isAbsolute4(rel) && rel !== ".." && !rel.startsWith(`..${sep5}`) ? abs : void 0;
   } catch {
     return void 0;
   }
@@ -2245,7 +2451,7 @@ var fileEvidence = (root, path, options) => {
       evidence: { path, detail: "Path escapes the project root." }
     };
   }
-  if (!existsSync8(abs)) {
+  if (!existsSync9(abs)) {
     return { exists: false, content: "", evidence: { path, detail: "File does not exist." } };
   }
   try {
@@ -2260,7 +2466,7 @@ var fileEvidence = (root, path, options) => {
       return {
         exists: true,
         content: "",
-        evidence: { path: toPosix(relative3(resolve5(root), abs)) || ".", detail: "File exists and is non-empty." }
+        evidence: { path: toPosix(relative4(resolve6(root), abs)) || ".", detail: "File exists and is non-empty." }
       };
     }
     if (stat.size > MAX_TEXT_EVIDENCE_BYTES) {
@@ -2270,12 +2476,12 @@ var fileEvidence = (root, path, options) => {
         evidence: { path, detail: `Text evidence exceeds ${MAX_TEXT_EVIDENCE_BYTES} bytes.` }
       };
     }
-    const content = readFileSync7(abs, "utf8");
+    const content = readFileSync8(abs, "utf8");
     return {
       exists: content.trim().length > 0,
       content,
       evidence: {
-        path: toPosix(relative3(resolve5(root), abs)) || ".",
+        path: toPosix(relative4(resolve6(root), abs)) || ".",
         detail: content.trim().length > 0 ? "File exists and is non-empty." : "File is empty."
       }
     };
@@ -2310,7 +2516,7 @@ var humanDocsRule = (root, config) => {
     passed: docs.length > 0,
     message: docs.length > 0 ? `Found ${docs.length} human document(s).` : "No human documentation was discovered.",
     evidence: docs.slice(0, 10).map((doc) => ({
-      path: toPosix(relative3(resolve5(root), doc.path)),
+      path: toPosix(relative4(resolve6(root), doc.path)),
       detail: `Human route: ${doc.url}`
     })),
     remediation: {
@@ -2321,10 +2527,10 @@ var humanDocsRule = (root, config) => {
 };
 var llmsRule = (root, config, options) => {
   const llmsPath = config.index?.llmsTxt?.outFile ?? "llms.txt";
-  const llmsKey = safePath(root, llmsPath) ?? resolve5(root, llmsPath);
+  const llmsKey = safePath(root, llmsPath) ?? resolve6(root, llmsPath);
   const rawSources = /* @__PURE__ */ new Map();
   for (const path of options.rawSources ?? []) {
-    const key = safePath(root, path) ?? resolve5(root, path);
+    const key = safePath(root, path) ?? resolve6(root, path);
     if (key !== llmsKey && !rawSources.has(key)) rawSources.set(key, path);
   }
   const paths = [llmsPath, ...rawSources.values()];
@@ -2576,8 +2782,8 @@ var formatDocumentationStandardText = (report) => [
 ];
 
 // src/query/load-index.ts
-import { existsSync as existsSync9, readFileSync as readFileSync8 } from "fs";
-import { join as join8, resolve as resolve6 } from "path";
+import { existsSync as existsSync10, readFileSync as readFileSync9 } from "fs";
+import { join as join8, resolve as resolve7 } from "path";
 var IndexNotFoundError = class extends Error {
   constructor(path) {
     super(`Missing index at ${path}. Run: ak-docs index`);
@@ -2589,11 +2795,11 @@ var IndexNotFoundError = class extends Error {
 var indexFilePath = (root, config) => join8(root, config.index?.outFile ?? ".doc-bridge/index.json");
 var loadDocBridgeIndex = (root, config) => {
   const path = indexFilePath(root, config);
-  if (!existsSync9(path)) throw new IndexNotFoundError(path);
-  const raw = JSON.parse(readFileSync8(path, "utf8"));
+  if (!existsSync10(path)) throw new IndexNotFoundError(path);
+  const raw = JSON.parse(readFileSync9(path, "utf8"));
   return parseDocBridgeIndex(raw);
 };
-var resolveRoot = (cwd) => resolve6(cwd ?? process.cwd());
+var resolveRoot = (cwd) => resolve7(cwd ?? process.cwd());
 
 // src/gates/run-gates.ts
 var RESERVED_GATE_IDS = /* @__PURE__ */ new Set(["link-rot", "routing-currency", "bootstrap-size"]);
@@ -2666,7 +2872,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",
@@ -2693,10 +2899,10 @@ var DOCS_STYLE_RULES = {
   "playbook-okf-soft": ["title", "no-stale-wording"],
   "title-only": ["title"]
 };
-var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isRecord2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var docsStyleOptions = (config) => {
   const raw = config.gates?.options?.["docs-style"];
-  if (!isRecord(raw)) {
+  if (!isRecord2(raw)) {
     if (config.gates?.preset === "playbook") {
       return { profile: "playbook-okf-soft", required: DOCS_STYLE_RULES["playbook-okf-soft"] };
     }
@@ -2740,7 +2946,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 {
@@ -2785,8 +2991,8 @@ var resolveGateIds = (config) => {
 };
 
 // src/mcp/server.ts
-import { readFileSync as readFileSync11, realpathSync as realpathSync6 } from "fs";
-import { relative as relative4, resolve as resolve7 } from "path";
+import { readFileSync as readFileSync12, realpathSync as realpathSync7 } from "fs";
+import { relative as relative5, resolve as resolve8 } from "path";
 import { z as z6, ZodError } from "zod";
 
 // src/query/search.ts
@@ -2905,15 +3111,15 @@ var createDocBridgeRetriever = (index, options = {}) => ({
 });
 
 // src/memory/ingest.ts
-import { existsSync as existsSync10, readFileSync as readFileSync10 } from "fs";
+import { existsSync as existsSync11, readFileSync as readFileSync11 } from "fs";
 import { join as join9 } 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 (!existsSync10(dir)) return [];
+  if (!existsSync11(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,
@@ -3130,7 +3336,9 @@ var runQuery = (index, config, req) => {
 var MCP_TOOLS = [
   {
     name: "handoff.resolve",
-    description: "Resolve a package or ownership id to an AgentHandoff.",
+    title: "Resolve repository handoff",
+    description: "Resolve a package or ownership id to its deterministic AgentHandoff.",
+    annotations: { readOnlyHint: true },
     inputSchema: {
       type: "object",
       properties: { id: { type: "string" }, kind: { type: "string", enum: ["package", "ownership"] } },
@@ -3139,7 +3347,9 @@ var MCP_TOOLS = [
   },
   {
     name: "doc.search",
-    description: "Search the deterministic doc-bridge index.",
+    title: "Search repository documentation",
+    description: "Search the deterministic Doc Bridge index for repository documentation.",
+    annotations: { readOnlyHint: true },
     inputSchema: {
       type: "object",
       properties: { term: { type: "string" }, limit: { type: "number" } },
@@ -3148,7 +3358,9 @@ var MCP_TOOLS = [
   },
   {
     name: "doc.get",
-    description: "Read an indexed agent documentation file by id or path.",
+    title: "Read indexed documentation",
+    description: "Read one indexed agent documentation file by id or indexed path.",
+    annotations: { readOnlyHint: true },
     inputSchema: {
       type: "object",
       properties: { id: { type: "string" }, path: { type: "string" } }
@@ -3156,12 +3368,16 @@ var MCP_TOOLS = [
   },
   {
     name: "gate.status",
-    description: "Run the index-freshness gate.",
+    title: "Check documentation gates",
+    description: "Evaluate documentation gates without writing files.",
+    annotations: { readOnlyHint: true },
     inputSchema: { type: "object", properties: {} }
   },
   {
     name: "retriever.query",
-    description: "Return local doc-bridge retriever chunks for a query.",
+    title: "Retrieve documentation context",
+    description: "Return relevant local Doc Bridge index chunks for a query.",
+    annotations: { readOnlyHint: true },
     inputSchema: {
       type: "object",
       properties: { query: { type: "string" }, limit: { type: "number" } },
@@ -3170,17 +3386,23 @@ var MCP_TOOLS = [
   },
   {
     name: "memory.classify",
-    description: "Classify local memory candidates into agent/human/playbook/discard routes.",
+    title: "Classify memory candidates",
+    description: "Classify local memory candidates into agent, human, playbook, or discard routes.",
+    annotations: { readOnlyHint: true },
     inputSchema: { type: "object", properties: {} }
   },
   {
     name: "memory.promoteDraft",
-    description: "Build a safe draft promotion body for local memory candidates.",
+    title: "Draft memory promotion",
+    description: "Build a reviewable draft promotion body from local memory candidates without publishing it.",
+    annotations: { readOnlyHint: true },
     inputSchema: { type: "object", properties: {} }
   },
   {
     name: "registry.topology",
-    description: "Return the doc-curator registry topology.",
+    title: "Inspect registry topology",
+    description: "Return the static Doc Bridge curator and delegate topology.",
+    annotations: { readOnlyHint: true },
     inputSchema: { type: "object", properties: {} }
   }
 ];
@@ -3231,12 +3453,12 @@ var findDocPath = (index, args) => {
   return doc.path;
 };
 var resolveDocPath = (root, relPath) => {
-  const rootAbs = realpathSync6.native(root);
-  const unresolved = resolve7(rootAbs, relPath);
-  const unresolvedRel = relative4(rootAbs, unresolved);
+  const rootAbs = realpathSync7.native(root);
+  const unresolved = resolve8(rootAbs, relPath);
+  const unresolvedRel = relative5(rootAbs, unresolved);
   if (unresolvedRel.startsWith("..")) throw new Error("doc.get path escapes project root");
-  const abs = realpathSync6.native(unresolved);
-  const rel = relative4(rootAbs, abs);
+  const abs = realpathSync7.native(unresolved);
+  const rel = relative5(rootAbs, abs);
   if (rel.startsWith("..")) throw new Error("doc.get path escapes project root");
   return abs;
 };
@@ -3270,7 +3492,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") {
@@ -3297,13 +3519,14 @@ var handleMcpRequest = (ctx, request) => {
   if (request.method?.startsWith("notifications/")) return void 0;
   throw new Error(`Unsupported MCP method "${request.method ?? ""}"`);
 };
-var writeFrame = (payload) => {
+var writeFrame = (payload, framing) => {
   const body = JSON.stringify(payload);
-  process.stdout.write(`Content-Length: ${Buffer.byteLength(body)}\r
+  process.stdout.write(framing === "json-line" ? `${body}
+` : `Content-Length: ${Buffer.byteLength(body)}\r
 \r
 ${body}`);
 };
-var respond = (ctx, request) => {
+var respond = (ctx, request, framing) => {
   if (request.id === void 0) {
     try {
       handleMcpRequest(ctx, request);
@@ -3313,13 +3536,13 @@ var respond = (ctx, request) => {
   }
   try {
     const result = handleMcpRequest(ctx, request);
-    writeFrame({ jsonrpc: "2.0", id: request.id, result: result ?? {} });
+    writeFrame({ jsonrpc: "2.0", id: request.id, result: result ?? {} }, framing);
   } catch (error) {
     writeFrame({
       jsonrpc: "2.0",
       id: request.id,
       error: { code: -32e3, message: error instanceof Error ? error.message : String(error) }
-    });
+    }, framing);
   }
 };
 var startMcpStdioServer = (ctx) => {
@@ -3327,30 +3550,43 @@ var startMcpStdioServer = (ctx) => {
   process.stdin.on("data", (chunk) => {
     buffer = Buffer.concat([buffer, chunk]);
     while (true) {
-      const headerEnd = buffer.indexOf("\r\n\r\n");
-      if (headerEnd === -1) return;
-      const header = buffer.subarray(0, headerEnd).toString("utf8");
-      const match = /content-length:\s*(\d+)/i.exec(header);
-      if (!match?.[1]) {
-        buffer = buffer.subarray(headerEnd + 4);
+      if (/^content-length:/i.test(buffer.subarray(0, Math.min(buffer.length, 32)).toString("utf8"))) {
+        const headerEnd = buffer.indexOf("\r\n\r\n");
+        if (headerEnd === -1) return;
+        const header = buffer.subarray(0, headerEnd).toString("utf8");
+        const match = /content-length:\s*(\d+)/i.exec(header);
+        if (!match?.[1]) {
+          buffer = buffer.subarray(headerEnd + 4);
+          continue;
+        }
+        const length = Number(match[1]);
+        const bodyStart = headerEnd + 4;
+        const bodyEnd = bodyStart + length;
+        if (buffer.length < bodyEnd) return;
+        const raw2 = buffer.subarray(bodyStart, bodyEnd).toString("utf8");
+        buffer = buffer.subarray(bodyEnd);
+        respond(ctx, JSON.parse(raw2), "content-length");
         continue;
       }
-      const length = Number(match[1]);
-      const bodyStart = headerEnd + 4;
-      const bodyEnd = bodyStart + length;
-      if (buffer.length < bodyEnd) return;
-      const raw = buffer.subarray(bodyStart, bodyEnd).toString("utf8");
-      buffer = buffer.subarray(bodyEnd);
-      respond(ctx, JSON.parse(raw));
+      const lineEnd = buffer.indexOf("\n");
+      if (lineEnd === -1) return;
+      const raw = buffer.subarray(0, lineEnd).toString("utf8").trim();
+      buffer = buffer.subarray(lineEnd + 1);
+      if (!raw) continue;
+      try {
+        respond(ctx, JSON.parse(raw), "json-line");
+      } catch {
+        writeFrame({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } }, "json-line");
+      }
     }
   });
   process.stdin.resume();
 };
 
 // src/mcp/install.ts
-import { existsSync as existsSync11, mkdirSync as mkdirSync2, readFileSync as readFileSync12, writeFileSync as writeFileSync2 } from "fs";
+import { existsSync as existsSync12, mkdirSync as mkdirSync2, readFileSync as readFileSync13, writeFileSync as writeFileSync2 } from "fs";
 import { homedir } from "os";
-import { dirname as dirname4, join as join10, resolve as resolve8 } from "path";
+import { dirname as dirname5, join as join10, resolve as resolve9 } from "path";
 var SERVER_NAME = "ak-docs";
 var mcpServerEntry = (root) => ({
   command: "npx",
@@ -3358,26 +3594,26 @@ var mcpServerEntry = (root) => ({
   cwd: root
 });
 var readJson = (path) => {
-  if (!existsSync11(path)) return {};
+  if (!existsSync12(path)) return {};
   try {
-    const parsed = JSON.parse(readFileSync12(path, "utf8"));
+    const parsed = JSON.parse(readFileSync13(path, "utf8"));
     return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
   } catch {
     return {};
   }
 };
 var writeJson = (path, value) => {
-  mkdirSync2(dirname4(path), { recursive: true });
+  mkdirSync2(dirname5(path), { recursive: true });
   writeFileSync2(path, `${JSON.stringify(value, null, 2)}
 `, "utf8");
 };
 var resolveTargetPath = (target, root) => {
-  if (target === "cursor") return resolve8(root, ".cursor", "mcp.json");
+  if (target === "cursor") return resolve9(root, ".cursor", "mcp.json");
   return join10(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
 };
 var installMcpConfig = (root, target) => {
   const configPath = resolveTargetPath(target, root);
-  const created = !existsSync11(configPath);
+  const created = !existsSync12(configPath);
   const existing = readJson(configPath);
   const servers = existing.mcpServers && typeof existing.mcpServers === "object" && !Array.isArray(existing.mcpServers) ? { ...existing.mcpServers } : {};
   servers[SERVER_NAME] = mcpServerEntry(root);
@@ -3643,22 +3879,23 @@ var formatDoctorText = (report) => {
 };
 
 // src/index-builder/watch-index.ts
-import { existsSync as existsSync12, watch } from "fs";
-import { dirname as dirname5, resolve as resolve9 } from "path";
+import { existsSync as existsSync13, watch } from "fs";
+import { dirname as dirname6, resolve as resolve10 } from "path";
 var WATCH_PATTERN = /\.(md|mdx|json|ya?ml|mdc)$/i;
+var NX_MANIFEST_PATTERN = /(^|[/\\])(project|package)\.json$/i;
 var collectWatchRoots = (root, config, configPath) => {
   const roots = /* @__PURE__ */ new Set();
-  roots.add(resolve9(root, config.corpus.agent.root));
+  roots.add(resolve10(root, config.corpus.agent.root));
   const humanSources = config.corpus.human ? Array.isArray(config.corpus.human) ? config.corpus.human : [config.corpus.human] : [];
   for (const source of humanSources) {
     const humanOpts = source.options ?? {};
-    for (const key of ["contentDir", "docsDir", "root"]) {
+    for (const key of ["contentDir", "docsDir", "root", "srcDir"]) {
       const value = humanOpts[key];
-      if (typeof value === "string" && value.length) roots.add(resolve9(root, value));
+      if (typeof value === "string" && value.length) roots.add(resolve10(root, value));
     }
   }
-  if (configPath) roots.add(dirname5(resolve9(configPath)));
-  return [...roots].filter((dir) => existsSync12(dir));
+  if (configPath) roots.add(dirname6(resolve10(configPath)));
+  return [...roots].filter((dir) => existsSync13(dir));
 };
 var watchDocBridgeIndex = (opts) => {
   const debounceMs = opts.debounceMs ?? 350;
@@ -3699,8 +3936,15 @@ var watchDocBridgeIndex = (opts) => {
       rebuild();
     });
   }
-  const configDir = resolve9(opts.root);
-  if (existsSync12(configDir)) {
+  const nxRoot = resolve10(opts.root);
+  if (opts.config.routing?.plugin === "nx" && existsSync13(nxRoot)) {
+    watch(nxRoot, { recursive: true }, (_event, filename) => {
+      if (!filename || !NX_MANIFEST_PATTERN.test(filename)) return;
+      rebuild();
+    });
+  }
+  const configDir = resolve10(opts.root);
+  if (existsSync13(configDir)) {
     watch(configDir, (_event, filename) => {
       if (!filename || !/doc-bridge\.config/.test(filename)) return;
       rebuild();
@@ -3719,7 +3963,7 @@ var watchDocBridgeIndex = (opts) => {
 
 // src/memory/github-pr.ts
 import { execFileSync, spawnSync } from "child_process";
-import { existsSync as existsSync13, mkdirSync as mkdirSync3, writeFileSync as writeFileSync3 } from "fs";
+import { existsSync as existsSync14, mkdirSync as mkdirSync3, writeFileSync as writeFileSync3 } from "fs";
 import { join as join12 } from "path";
 var run = (cmd, args, cwd) => {
   const result = spawnSync(cmd, [...args], { cwd, encoding: "utf8" });
@@ -3767,7 +4011,7 @@ var promoteMemoryToGithubPr = (root, draft, options = {}) => {
       message: `Wrote draft to ${relDraft}. Run the printed git/gh commands to open a draft PR.`
     };
   }
-  if (!existsSync13(join12(root, ".git"))) {
+  if (!existsSync14(join12(root, ".git"))) {
     return {
       ok: false,
       dryRun: false,
@@ -3870,8 +4114,8 @@ ${auth.out}`
 };
 
 // src/federation/llms.ts
-import { existsSync as existsSync14, readFileSync as readFileSync13 } from "fs";
-import { resolve as resolve10 } from "path";
+import { existsSync as existsSync15, readFileSync as readFileSync14 } from "fs";
+import { resolve as resolve11 } from "path";
 var tokenize2 = (value) => value.toLowerCase().split(/[^a-z0-9]+/).filter((token) => token.length >= 2);
 var scoreText = (query, text) => {
   const hay = text.toLowerCase();
@@ -3886,9 +4130,9 @@ var defaultFetchText = async (url) => {
 var sourceText = async (root, source, fetchText) => {
   try {
     if (/^https?:\/\//.test(source)) return await fetchText(source);
-    const path = resolve10(root, source);
-    if (!existsSync14(path)) return null;
-    return readFileSync13(path, "utf8");
+    const path = resolve11(root, source);
+    if (!existsSync15(path)) return null;
+    return readFileSync14(path, "utf8");
   } catch {
     return null;
   }
@@ -3973,7 +4217,7 @@ var retrieveHybridChunks = async (root, config, index, query, options = {}) => {
 };
 
 // src/intelligence/rag.ts
-import { readFileSync as readFileSync14 } from "fs";
+import { readFileSync as readFileSync15 } from "fs";
 import { join as join14 } from "path";
 
 // src/intelligence/adapter.ts
@@ -4115,7 +4359,7 @@ var loadDocuments = (root, index, sources) => {
       const abs = join14(root, entry.path);
       let content = "";
       try {
-        content = readFileSync14(abs, "utf8");
+        content = readFileSync15(abs, "utf8");
       } catch {
         content = [entry.title, entry.description].filter(Boolean).join("\n\n");
       }
@@ -4425,6 +4669,7 @@ export {
   createDocBridgeRetriever,
   defaultPromotionDraftPath,
   defineConfig,
+  discoverNxProjects,
   docBridgePatternMarkdown,
   docBridgePatternPayload,
   doctorBadgeMetrics,