@agentskit/doc-bridge 1.0.2 → 1.2.1

package/dist/index.js

@@ -137,7 +137,8 @@ var GatesConfigSchema = z.object({
       "okf-type",
       "docs-style",
       "routing-currency",
-      "bootstrap-size"
+      "bootstrap-size",
+      "documentation-standard-v1"
     ])
   ).max(16).optional(),
   exclude: z.array(
@@ -148,7 +149,8 @@ var GatesConfigSchema = z.object({
       "okf-type",
       "docs-style",
       "routing-currency",
-      "bootstrap-size"
+      "bootstrap-size",
+      "documentation-standard-v1"
     ])
   ).max(16).optional(),
   options: z.record(z.string(), z.unknown()).optional()
@@ -227,6 +229,69 @@ var FederationConfigSchema = z.object({
     }).strict()
   ).max(16).optional()
 }).strict();
+var DocumentationEvidenceFileSchema = z.object({
+  path: z.string().min(1).max(512),
+  contains: z.array(z.string().min(1).max(512)).min(1).max(32)
+}).strict();
+var DocumentationLinkEvidenceSchema = z.object({
+  url: z.string().url().max(512),
+  paths: z.array(z.string().min(1).max(512)).min(1).max(32)
+}).strict();
+var DocumentationQuickstartEvidenceSchema = z.object({
+  id: z.string().regex(/^[a-z][a-z0-9-]*$/).max(128),
+  doc: z.string().min(1).max(512),
+  test: z.string().min(1).max(512),
+  command: z.string().min(1).max(512),
+  testContains: z.array(z.string().min(1).max(256)).min(1).max(16)
+}).strict();
+var EcosystemContractEvidenceSchema = z.object({
+  manifest: z.string().min(1).max(512),
+  claims: z.string().min(1).max(512),
+  productId: z.string().regex(/^[a-z][a-z0-9-]*$/).max(128)
+}).strict();
+var DocumentationStandardRuleIdSchema = z.enum([
+  "human-docs",
+  "llms-and-raw-source",
+  "agent-handoffs",
+  "contribution",
+  "metadata",
+  "cross-links",
+  "tested-quickstarts",
+  "visual-explanations",
+  "structured-diagrams"
+]);
+var DocumentationStandardExceptionSchema = z.object({
+  ruleId: DocumentationStandardRuleIdSchema,
+  reason: z.string().min(10).max(1024),
+  approvedBy: z.string().min(1).max(256),
+  trackingUrl: z.string().url().max(512)
+}).strict();
+var DocumentationStandardV1ConfigSchema = z.object({
+  rawSources: z.array(z.string().min(1).max(512)).max(64).optional(),
+  contributionPaths: z.array(z.string().min(1).max(512)).max(16).optional(),
+  metadata: z.array(DocumentationEvidenceFileSchema).max(32).optional(),
+  links: z.array(DocumentationLinkEvidenceSchema).max(64).optional(),
+  quickstarts: z.array(DocumentationQuickstartEvidenceSchema).max(32).optional(),
+  visuals: z.array(z.string().min(1).max(512)).max(64).optional(),
+  diagrams: z.array(DocumentationEvidenceFileSchema).max(32).optional(),
+  ecosystemContract: EcosystemContractEvidenceSchema.optional(),
+  exceptions: z.array(DocumentationStandardExceptionSchema).max(32).optional()
+}).strict().superRefine((value, context) => {
+  const seen = /* @__PURE__ */ new Set();
+  for (const [index, exception] of (value.exceptions ?? []).entries()) {
+    if (seen.has(exception.ruleId)) {
+      context.addIssue({
+        code: "custom",
+        path: ["exceptions", index, "ruleId"],
+        message: `Duplicate exception for rule ${exception.ruleId}`
+      });
+    }
+    seen.add(exception.ruleId);
+  }
+});
+var ConformanceConfigSchema = z.object({
+  documentationStandardV1: DocumentationStandardV1ConfigSchema.optional()
+}).strict();
 var DocBridgeConfigV1Schema = z.object({
   schemaVersion: z.literal(CONFIG_SCHEMA_VERSION),
   project: z.object({
@@ -242,7 +307,8 @@ var DocBridgeConfigV1Schema = z.object({
   gates: GatesConfigSchema.optional(),
   surfaces: SurfacesConfigSchema.optional(),
   intelligence: IntelligenceConfigSchema.optional(),
-  federation: FederationConfigSchema.optional()
+  federation: FederationConfigSchema.optional(),
+  conformance: ConformanceConfigSchema.optional()
 }).strict();
 
 // src/config/define-config.ts
@@ -251,7 +317,268 @@ var defineConfig = (config) => applyConfigDefaults(DocBridgeConfigV1Schema.parse
 // src/config/load-config.ts
 import { existsSync, readFileSync } from "fs";
 import { basename, dirname, join, resolve } from "path";
-import vm from "vm";
+
+// src/lib/static-js-literal.ts
+var stripComments = (source) => {
+  let out = "";
+  let index = 0;
+  let quote;
+  while (index < source.length) {
+    const char = source[index] ?? "";
+    const next = source[index + 1] ?? "";
+    if (quote) {
+      out += char;
+      if (char === "\\") {
+        out += next;
+        index += 2;
+        continue;
+      }
+      if (char === quote) quote = void 0;
+      index += 1;
+      continue;
+    }
+    if (char === '"' || char === "'" || char === "`") {
+      quote = char;
+      out += char;
+      index += 1;
+      continue;
+    }
+    if (char === "/" && next === "/") {
+      while (index < source.length && source[index] !== "\n") index += 1;
+      out += "\n";
+      index += 1;
+      continue;
+    }
+    if (char === "/" && next === "*") {
+      index += 2;
+      while (index < source.length && !(source[index] === "*" && source[index + 1] === "/")) index += 1;
+      index += 2;
+      out += " ";
+      continue;
+    }
+    out += char;
+    index += 1;
+  }
+  if (quote) throw new Error("Unterminated string in static JavaScript literal.");
+  return out;
+};
+var LiteralParser = class {
+  constructor(source) {
+    this.source = source;
+  }
+  source;
+  index = 0;
+  parseAt(index) {
+    this.index = index;
+    const value = this.value();
+    this.space();
+    return value;
+  }
+  space() {
+    while (/\s/.test(this.source[this.index] ?? "")) this.index += 1;
+  }
+  value() {
+    this.space();
+    const char = this.source[this.index];
+    if (char === "{") return this.object();
+    if (char === "[") return this.array();
+    if (char === '"' || char === "'") return this.string();
+    const word = this.word();
+    if (word === "true") return true;
+    if (word === "false") return false;
+    if (word === "null") return null;
+    if (/^-?\d+(?:\.\d+)?$/.test(word)) return Number(word);
+    throw new Error(`Unsupported dynamic sidebar expression near "${word || char || "EOF"}".`);
+  }
+  object() {
+    const result = {};
+    this.index += 1;
+    this.space();
+    while (this.source[this.index] !== "}") {
+      const key = this.source[this.index] === '"' || this.source[this.index] === "'" ? this.string() : this.word();
+      if (!key) throw new Error("Static sidebar object key is required.");
+      this.space();
+      if (this.source[this.index] !== ":") throw new Error(`Static sidebar key "${key}" requires a literal value.`);
+      this.index += 1;
+      result[key] = this.value();
+      this.space();
+      if (this.source[this.index] === ",") {
+        this.index += 1;
+        this.space();
+        continue;
+      }
+      if (this.source[this.index] !== "}") throw new Error("Expected comma or closing brace in static sidebar.");
+    }
+    this.index += 1;
+    return result;
+  }
+  array() {
+    const result = [];
+    this.index += 1;
+    this.space();
+    while (this.source[this.index] !== "]") {
+      result.push(this.value());
+      this.space();
+      if (this.source[this.index] === ",") {
+        this.index += 1;
+        this.space();
+        continue;
+      }
+      if (this.source[this.index] !== "]") throw new Error("Expected comma or closing bracket in static sidebar.");
+    }
+    this.index += 1;
+    return result;
+  }
+  string() {
+    const quote = this.source[this.index] ?? "";
+    this.index += 1;
+    let result = "";
+    while (this.index < this.source.length) {
+      const char = this.source[this.index] ?? "";
+      if (char === quote) {
+        this.index += 1;
+        return result;
+      }
+      if (char === "\\") {
+        const escaped = this.source[this.index + 1];
+        if (escaped === void 0) break;
+        const escapes = { n: "\n", r: "\r", t: "	" };
+        result += escapes[escaped] ?? escaped;
+        this.index += 2;
+        continue;
+      }
+      result += char;
+      this.index += 1;
+    }
+    throw new Error("Unterminated string in static sidebar.");
+  }
+  word() {
+    this.space();
+    const start = this.index;
+    while (/[A-Za-z0-9_$.-]/.test(this.source[this.index] ?? "")) this.index += 1;
+    return this.source.slice(start, this.index);
+  }
+};
+var maskStrings = (source) => {
+  const chars = [...source];
+  let quote;
+  let previousToken;
+  const regexPrefixKeywords = /* @__PURE__ */ new Set([
+    "await",
+    "case",
+    "delete",
+    "do",
+    "else",
+    "in",
+    "instanceof",
+    "new",
+    "of",
+    "return",
+    "throw",
+    "typeof",
+    "void",
+    "yield"
+  ]);
+  const canStartRegex = () => previousToken === void 0 || "=(:,[!&|?{};".includes(previousToken) || previousToken === "=>" || regexPrefixKeywords.has(previousToken);
+  for (let index = 0; index < chars.length; index += 1) {
+    const char = chars[index] ?? "";
+    if (quote) {
+      chars[index] = " ";
+      if (char === "\\") {
+        if (index + 1 < chars.length) chars[index + 1] = " ";
+        index += 1;
+      } else if (char === quote) {
+        quote = void 0;
+        previousToken = "literal";
+      }
+      continue;
+    }
+    if (char === '"' || char === "'" || char === "`") {
+      quote = char;
+      chars[index] = " ";
+      continue;
+    }
+    if (char === "/" && canStartRegex()) {
+      chars[index] = " ";
+      let inClass = false;
+      for (index += 1; index < chars.length; index += 1) {
+        const regexChar = chars[index] ?? "";
+        chars[index] = " ";
+        if (regexChar === "\\") {
+          if (index + 1 < chars.length) chars[index + 1] = " ";
+          index += 1;
+        } else if (regexChar === "[") {
+          inClass = true;
+        } else if (regexChar === "]") {
+          inClass = false;
+        } else if (regexChar === "/" && !inClass) {
+          while (/[A-Za-z]/.test(chars[index + 1] ?? "")) {
+            index += 1;
+            chars[index] = " ";
+          }
+          break;
+        }
+      }
+      previousToken = "literal";
+      continue;
+    }
+    if (/[A-Za-z_$]/.test(char)) {
+      const start = index;
+      while (/[A-Za-z0-9_$]/.test(chars[index + 1] ?? "")) index += 1;
+      previousToken = chars.slice(start, index + 1).join("");
+      continue;
+    }
+    if (char === "=" && chars[index + 1] === ">") {
+      previousToken = "=>";
+      index += 1;
+      continue;
+    }
+    if (!/\s/.test(char)) previousToken = char;
+  }
+  return chars.join("");
+};
+var nonSpace = (source, start) => {
+  let index = start;
+  while (/\s/.test(source[index] ?? "")) index += 1;
+  return index;
+};
+var escapedRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+var parseStaticJsObject = (source) => {
+  const clean = stripComments(source);
+  const mask = maskStrings(clean);
+  const parseBinding = (identifier) => {
+    const declaration = new RegExp(`\\b(?:const|let|var)\\s+${escapedRegex(identifier)}(?:\\s*:[^=;]+)?\\s*=`).exec(mask);
+    if (!declaration) throw new Error(`Exported binding "${identifier}" must reference a static object declaration.`);
+    const start = nonSpace(mask, declaration.index + declaration[0].length);
+    if (mask[start] !== "{") throw new Error(`Exported binding "${identifier}" must be a static object literal.`);
+    return new LiteralParser(clean).parseAt(start);
+  };
+  const commonJs = /\bmodule\.exports\s*=/.exec(mask);
+  if (commonJs) {
+    const start = nonSpace(mask, commonJs.index + commonJs[0].length);
+    if (mask[start] === "{") return new LiteralParser(clean).parseAt(start);
+    const identifier = /^[A-Za-z_$][\w$]*/.exec(mask.slice(start))?.[0];
+    if (identifier) return parseBinding(identifier);
+    throw new Error("module.exports must be assigned a static object literal or binding.");
+  }
+  const exported = /\bexport\s+default\b/.exec(mask);
+  if (exported) {
+    let start = nonSpace(mask, exported.index + exported[0].length);
+    if (mask.slice(start).startsWith("defineConfig")) {
+      start = nonSpace(mask, start + "defineConfig".length);
+      if (mask[start] !== "(") throw new Error("defineConfig must be called with a static object literal.");
+      start = nonSpace(mask, start + 1);
+      if (mask[start] !== "{") throw new Error("defineConfig must be called with a static object literal.");
+      return new LiteralParser(clean).parseAt(start);
+    }
+    if (mask[start] === "{") return new LiteralParser(clean).parseAt(start);
+    const identifier = /^[A-Za-z_$][\w$]*/.exec(mask.slice(start))?.[0];
+    if (identifier) return parseBinding(identifier);
+  }
+  throw new Error("Docusaurus sidebar must export a static object or assign one to a const.");
+};
+
+// src/config/load-config.ts
 var CONFIG_CANDIDATES = [
   "doc-bridge.config.ts",
   "doc-bridge.config.mts",
@@ -295,22 +622,16 @@ var parseJsonConfig = (raw, path) => {
   }
 };
 var parseCodeConfig = (raw, path) => {
-  const code = raw.replace(/import\s+type\s+[\s\S]*?;?\n/g, "").replace(/import\s+\{\s*defineConfig\s*\}\s+from\s+['"]@agentskit\/doc-bridge(?:\/config)?['"];?\n?/g, "").replace(/\s+satisfies\s+[A-Za-z0-9_.$<>{}\[\],\s]+(?=\s*(?:;|\)|$))/g, "").replace(/export\s+default/, "module.exports.default =");
-  if (/\bimport\b/.test(code)) {
+  const unsupportedImports = raw.replace(/import\s+type\s+[\s\S]*?;?\n/g, "").replace(/import\s+\{\s*defineConfig\s*\}\s+from\s+['"]@agentskit\/doc-bridge(?:\/config)?['"];?\n?/g, "");
+  if (/\bimport\b/.test(unsupportedImports)) {
     throw new Error(`Unsupported import in ${path}. Static config only supports defineConfig imports.`);
   }
-  const sandbox = {
-    module: { exports: {} },
-    exports: {},
-    defineConfig: (config) => config
-  };
   try {
-    vm.runInNewContext(code, sandbox, { timeout: 250, filename: path });
+    return parseStaticJsObject(raw);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     throw new Error(`Failed to load config at ${path}: ${message}`);
   }
-  return sandbox.module.exports.default;
 };
 var parseConfig = (input) => {
   const result = DocBridgeConfigV1Schema.safeParse(input);
@@ -707,23 +1028,33 @@ ${zodIssues(result.error).map((i) => `  - ${i.path}: ${i.message}`).join("\n")}`
 };
 
 // src/index-builder/build-index.ts
-import { mkdirSync, readFileSync as readFileSync8, writeFileSync } from "fs";
-import { dirname as dirname3, join as join10 } from "path";
+import { mkdirSync, readFileSync as readFileSync6, writeFileSync } from "fs";
+import { dirname as dirname3, join as join7 } from "path";
 
 // src/lib/paths.ts
-import { resolve as resolve2 } from "path";
+import { existsSync as existsSync2, realpathSync } from "fs";
+import { isAbsolute, relative, resolve as resolve2, sep } from "path";
 var toPosix = (value) => value.split("\\").join("/");
+var containedProjectPath = (root, path) => {
+  const projectRoot = realpathSync.native(resolve2(root));
+  const unresolved = resolve2(projectRoot, path);
+  const unresolvedRelative = relative(projectRoot, unresolved);
+  if (isAbsolute(unresolvedRelative) || unresolvedRelative === ".." || unresolvedRelative.startsWith(`..${sep}`)) return void 0;
+  const canonical = existsSync2(unresolved) ? realpathSync.native(unresolved) : unresolved;
+  const canonicalRelative = relative(projectRoot, canonical);
+  return isAbsolute(canonicalRelative) || canonicalRelative === ".." || canonicalRelative.startsWith(`..${sep}`) ? void 0 : canonical;
+};
 
 // src/lib/package-manager.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { existsSync as existsSync3, 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"))) {
+  if (existsSync3(join2(root, "pnpm-lock.yaml")) || existsSync3(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";
+  if (existsSync3(join2(root, "yarn.lock"))) return "yarn";
+  if (existsSync3(join2(root, "bun.lockb")) || existsSync3(join2(root, "bun.lock"))) return "bun";
+  if (existsSync3(join2(root, "package-lock.json"))) return "npm";
   try {
     const pkg = JSON.parse(readFileSync2(join2(root, "package.json"), "utf8"));
     const pm = pkg.packageManager?.split("@")[0];
@@ -744,7 +1075,7 @@ var defaultChecksForTarget = (root, opts) => {
     } catch {
     }
   }
-  const isWorkspace = existsSync2(join2(root, "pnpm-workspace.yaml")) || existsSync2(join2(root, "lerna.json")) || Boolean(
+  const isWorkspace = existsSync3(join2(root, "pnpm-workspace.yaml")) || existsSync3(join2(root, "lerna.json")) || Boolean(
     (() => {
       try {
         const pkg = JSON.parse(readFileSync2(join2(root, "package.json"), "utf8"));
@@ -778,9 +1109,24 @@ var defaultChecksForTarget = (root, opts) => {
   return opts.strict ? ["npm test", "npm run lint"] : ["npm test"];
 };
 
-// src/index-builder/scan-corpus.ts
-import { readFileSync as readFileSync3 } from "fs";
-import { join as join4 } from "path";
+// src/lib/bounded-text.ts
+import { readFileSync as readFileSync3, statSync } from "fs";
+var MAX_DOCUMENT_BYTES = 4 * 1024 * 1024;
+var MAX_CORPUS_BYTES = 64 * 1024 * 1024;
+var readBoundedText = (path, budget, limits) => {
+  const maxFileBytes = limits?.maxFileBytes ?? MAX_DOCUMENT_BYTES;
+  const maxCorpusBytes = limits?.maxCorpusBytes ?? MAX_CORPUS_BYTES;
+  const stat = statSync(path);
+  if (!stat.isFile()) throw new Error(`Documentation path is not a regular file: ${path}`);
+  if (stat.size > maxFileBytes) {
+    throw new Error(`Documentation file exceeds the ${maxFileBytes} byte limit: ${path}`);
+  }
+  if (budget.used + stat.size > maxCorpusBytes) {
+    throw new Error(`Documentation corpus exceeds the ${maxCorpusBytes} byte read budget.`);
+  }
+  budget.used += stat.size;
+  return readFileSync3(path, "utf8");
+};
 
 // src/lib/markdown.ts
 var parseFrontmatter = (markdown) => {
@@ -871,14 +1217,24 @@ var slugFromPath = (relPath) => {
 };
 
 // src/lib/walk.ts
-import { readdirSync, statSync } from "fs";
+import { lstatSync, readdirSync, realpathSync as realpathSync2 } from "fs";
 import { join as join3 } from "path";
 var DEFAULT_SKIP = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", "coverage", ".doc-bridge"]);
+var DEFAULT_MAX_FILES = 1e4;
 var walkFiles = (root, opts) => {
   const extensions = opts?.extensions ?? [".md"];
   const skip = opts?.skipDirs ?? DEFAULT_SKIP;
   const out = [];
+  const visited = /* @__PURE__ */ new Set();
   const visit = (dir) => {
+    let canonicalDir;
+    try {
+      canonicalDir = realpathSync2.native(dir);
+    } catch {
+      return;
+    }
+    if (visited.has(canonicalDir)) return;
+    visited.add(canonicalDir);
     let entries = [];
     try {
       entries = readdirSync(dir);
@@ -889,10 +1245,11 @@ var walkFiles = (root, opts) => {
       const abs = join3(dir, name);
       let st;
       try {
-        st = statSync(abs);
+        st = lstatSync(abs);
       } catch {
         continue;
       }
+      if (st.isSymbolicLink()) continue;
       if (st.isDirectory()) {
         if (skip.has(name)) continue;
         visit(abs);
@@ -900,6 +1257,9 @@ var walkFiles = (root, opts) => {
       }
       if (!st.isFile()) continue;
       if (extensions.some((ext) => name.endsWith(ext))) {
+        if (out.length >= (opts?.maxFiles ?? DEFAULT_MAX_FILES)) {
+          throw new Error(`Documentation corpus exceeds the ${opts?.maxFiles ?? DEFAULT_MAX_FILES} file limit.`);
+        }
         out.push(toPosix(abs));
       }
     }
@@ -910,13 +1270,15 @@ var walkFiles = (root, opts) => {
 
 // src/index-builder/scan-corpus.ts
 var scanAgentCorpus = (root, config) => {
-  const agentRoot = join4(root, config.corpus.agent.root);
+  const agentRoot = containedProjectPath(root, config.corpus.agent.root);
+  if (!agentRoot) throw new Error("Agent corpus root escapes the project root.");
   const files = walkFiles(agentRoot, { extensions: [".md", ".mdx"] });
   const corpusRelRoot = toPosix(config.corpus.agent.root);
+  const budget = { used: 0 };
   return files.map((abs) => {
     const relToCorpus = toPosix(abs.replace(`${toPosix(agentRoot)}/`, ""));
     const relPath = `${corpusRelRoot}/${relToCorpus}`;
-    const raw = readFileSync3(abs, "utf8");
+    const raw = readBoundedText(abs, budget);
     const { data: frontmatter } = parseFrontmatter(raw);
     const id = frontmatterString(frontmatter, "id") ?? frontmatterString(frontmatter, "package") ?? slugFromPath(relToCorpus);
     const title = firstHeading(raw) ?? id;
@@ -1172,7 +1534,7 @@ var buildLookup = (config, packages, corpus, indexOutFile, humanDocs = {}, root
 };
 
 // src/version.ts
-var PACKAGE_VERSION = "1.0.2";
+var PACKAGE_VERSION = "1.2.1";
 
 // src/index-builder/capabilities.ts
 var renderCapabilitiesJson = (config, index, paths) => {
@@ -1240,14 +1602,16 @@ ${lines.join("\n")}
 `;
 };
 
+// src/index-builder/human-adapters/index.ts
+import { realpathSync as realpathSync4 } from "fs";
+import { resolve as resolve4, sep as sep3 } from "path";
+
 // src/index-builder/human-adapters/docusaurus.ts
-import { existsSync as existsSync3, readFileSync as readFileSync5 } from "fs";
-import { join as join6 } from "path";
-import vm2 from "vm";
+import { existsSync as existsSync4 } from "fs";
 
 // src/index-builder/human-adapters/core.ts
-import { readFileSync as readFileSync4 } from "fs";
-import { join as join5 } from "path";
+import { realpathSync as realpathSync3 } from "fs";
+import { isAbsolute as isAbsolute2, relative as relative2, resolve as resolve3, sep as sep2 } from "path";
 var optionString = (options, keys) => {
   for (const key of keys) {
     const value = options?.[key];
@@ -1278,10 +1642,16 @@ var humanUrl = (slug2, urlPrefix) => {
 };
 var scanMarkdownDocs = (root, humanRoot, options) => {
   const out = [];
-  const absRoot = join5(root, humanRoot);
+  const projectRoot = realpathSync3.native(resolve3(root));
+  const absRoot = containedProjectPath(root, humanRoot);
+  if (!absRoot) return out;
+  const budget = { used: 0 };
   for (const abs of walkFiles(absRoot, { extensions: [".md", ".mdx"] })) {
+    const canonical = realpathSync3.native(abs);
+    const fileRelative = relative2(projectRoot, canonical);
+    if (isAbsolute2(fileRelative) || fileRelative === ".." || fileRelative.startsWith(`..${sep2}`)) continue;
     const relToHumanRoot = toPosix(abs.replace(`${toPosix(absRoot)}/`, ""));
-    const raw = readFileSync4(abs, "utf8");
+    const raw = readBoundedText(abs, budget);
     if (options?.includeRelPath && !options.includeRelPath(relToHumanRoot, raw)) continue;
     out.push({
       id: options?.idForDoc?.(relToHumanRoot, raw) ?? docId(relToHumanRoot, raw),
@@ -1319,41 +1689,31 @@ var docusaurusRecordId = (relPath, raw) => {
   const frontmatter = parseFrontmatter2(raw);
   return frontmatter.package ?? frontmatter.module ?? docusaurusSidebarId(relPath, raw);
 };
-var sidebarsValue = (file) => {
-  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;
-};
-var visitSidebar = (value, filter) => {
-  if (typeof value === "string") {
-    filter.ids.add(value);
-    return;
-  }
-  if (Array.isArray(value)) {
-    for (const item2 of value) visitSidebar(item2, filter);
-    return;
-  }
-  if (!value || typeof value !== "object") return;
-  const item = value;
-  if ((item.type === "doc" || item.type === "ref") && typeof item.id === "string") {
-    filter.ids.add(item.id);
-  }
-  if (item.type === "autogenerated" && typeof item.dirName === "string") {
-    filter.autogenDirs.push(item.dirName);
-  }
-  if (Array.isArray(item.items)) visitSidebar(item.items, filter);
-  if (item.link && typeof item.link === "object") visitSidebar(item.link, filter);
-  for (const child of Object.values(item)) {
-    if (Array.isArray(child)) visitSidebar(child, filter);
-  }
-};
-var readSidebars = (root, sidebarsFile) => {
+var readSidebars = (sidebarsFile) => {
   if (!sidebarsFile) return { enabled: false, ids: /* @__PURE__ */ new Set(), autogenDirs: [] };
-  const value = sidebarsValue(join6(root, sidebarsFile));
+  if (!existsSync4(sidebarsFile)) return { enabled: false, ids: /* @__PURE__ */ new Set(), autogenDirs: [] };
+  const raw = readBoundedText(sidebarsFile, { used: 0 }, { maxFileBytes: 1048576, maxCorpusBytes: 1048576 });
   const filter = { ids: /* @__PURE__ */ new Set(), autogenDirs: [] };
-  visitSidebar(value, filter);
+  const visit = (value) => {
+    if (typeof value === "string") {
+      filter.ids.add(value);
+      return;
+    }
+    if (Array.isArray(value)) {
+      for (const item2 of value) visit(item2);
+      return;
+    }
+    if (!value || typeof value !== "object") return;
+    const item = value;
+    if ((item.type === "doc" || item.type === "ref") && typeof item.id === "string") filter.ids.add(item.id);
+    if (item.type === "autogenerated" && typeof item.dirName === "string") filter.autogenDirs.push(item.dirName);
+    if (Array.isArray(item.items)) visit(item.items);
+    if (item.link && typeof item.link === "object") visit(item.link);
+    for (const child of Object.values(item)) {
+      if (Array.isArray(child)) visit(child);
+    }
+  };
+  visit(parseStaticJsObject(raw));
   return { enabled: true, ...filter };
 };
 var isIncludedBySidebar = (filter, id) => {
@@ -1369,7 +1729,8 @@ var docusaurusAdapter = {
   scan: ({ root, config }) => {
     const docsDir = optionString(config.options, ["docsDir", "root"]);
     if (!docsDir) return [];
-    const sidebarFilter = readSidebars(root, optionString(config.options, ["sidebarsFile"]));
+    const sidebarsFile = optionString(config.options, ["sidebarsFile"]);
+    const sidebarFilter = readSidebars(sidebarsFile ? containedProjectPath(root, sidebarsFile) : void 0);
     return scanMarkdownDocs(root, docsDir, {
       includeRelPath: (relPath, raw) => isIncludedBySidebar(sidebarFilter, docusaurusSidebarId(relPath, raw)),
       idForDoc: docusaurusRecordId,
@@ -1380,13 +1741,13 @@ var docusaurusAdapter = {
 };
 
 // src/index-builder/human-adapters/fumadocs.ts
-import { existsSync as existsSync4, readFileSync as readFileSync6 } from "fs";
-import { join as join7 } from "path";
+import { existsSync as existsSync5, readFileSync as readFileSync4 } from "fs";
+import { join as join4 } from "path";
 var readMetaPages = (dir) => {
-  const file = join7(dir, "meta.json");
-  if (!existsSync4(file)) return void 0;
+  const file = join4(dir, "meta.json");
+  if (!existsSync5(file)) return void 0;
   try {
-    const meta = JSON.parse(readFileSync6(file, "utf8"));
+    const meta = JSON.parse(readFileSync4(file, "utf8"));
     return Array.isArray(meta.pages) ? meta.pages.filter((page) => typeof page === "string") : void 0;
   } catch {
     return void 0;
@@ -1401,7 +1762,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 = join7(contentRoot, ...parts.slice(0, i));
+    const dir = join4(contentRoot, ...parts.slice(0, i));
     const pages = readMetaPages(dir);
     if (!pages?.length || pages.includes("...")) continue;
     const key = pageKey(parts[i] ?? "");
@@ -1414,7 +1775,7 @@ var fumadocsAdapter = {
   scan: ({ root, config }) => {
     const contentDir = optionString(config.options, ["contentDir", "root"]);
     if (!contentDir) return [];
-    const contentRoot = join7(root, contentDir);
+    const contentRoot = join4(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, {
@@ -1450,15 +1811,23 @@ var humanConfigs = (config) => {
   if (!human) return [];
   return Array.isArray(human) ? human : [human];
 };
+var canonicalPath = (path) => {
+  try {
+    return realpathSync4.native(path);
+  } catch {
+    return resolve4(path);
+  }
+};
 var scanHumanDocRecords = (root, config) => {
   const out = [];
   const seen = /* @__PURE__ */ new Set();
-  const agentRoot = config.corpus.agent.root.replace(/\/$/, "");
+  const agentRoot = canonicalPath(resolve4(root, config.corpus.agent.root));
   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")) {
+      const recordPath = canonicalPath(record.path);
+      if (recordPath === agentRoot || recordPath.startsWith(`${agentRoot}${sep3}`) || record.path.includes("/for-agents/") || record.path.endsWith("/for-agents")) {
         continue;
       }
       if (seen.has(record.id)) continue;
@@ -1471,26 +1840,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 existsSync6, readFileSync as readFileSync7 } from "fs";
-import { basename as basename2, join as join9 } from "path";
+import { existsSync as existsSync7, readFileSync as readFileSync5 } from "fs";
+import { basename as basename2, join as join6 } from "path";
 
 // src/lib/glob-expand.ts
-import { existsSync as existsSync5, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
-import { join as join8 } from "path";
+import { existsSync as existsSync6, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
+import { join as join5 } 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 = join8(root, normalized);
-      if (existsSync5(abs)) dirs.add(toPosix(abs));
+      const abs = join5(root, normalized);
+      if (existsSync6(abs)) dirs.add(toPosix(abs));
       continue;
     }
     const star = normalized.indexOf("*");
-    const base = join8(root, normalized.slice(0, star).replace(/\/$/, ""));
-    if (!existsSync5(base)) continue;
+    const base = join5(root, normalized.slice(0, star).replace(/\/$/, ""));
+    if (!existsSync6(base)) continue;
     for (const name of readdirSync2(base)) {
-      const abs = join8(base, name);
+      const abs = join5(base, name);
       try {
         if (statSync2(abs).isDirectory()) dirs.add(toPosix(abs));
       } catch {
@@ -1522,10 +1891,10 @@ var parsePnpmWorkspace = (yaml) => {
   return patterns;
 };
 var readPackageJson = (dir) => {
-  const file = join9(dir, "package.json");
-  if (!existsSync6(file)) return null;
+  const file = join6(dir, "package.json");
+  if (!existsSync7(file)) return null;
   try {
-    return JSON.parse(readFileSync7(file, "utf8"));
+    return JSON.parse(readFileSync5(file, "utf8"));
   } catch {
     return null;
   }
@@ -1534,9 +1903,9 @@ var discoverPnpmPackages = (root, config) => {
   const explicit = config.routing?.options?.packages;
   let patterns = explicit;
   if (!patterns?.length) {
-    const workspaceFile = join9(root, "pnpm-workspace.yaml");
-    if (existsSync6(workspaceFile)) {
-      patterns = parsePnpmWorkspace(readFileSync7(workspaceFile, "utf8"));
+    const workspaceFile = join6(root, "pnpm-workspace.yaml");
+    if (existsSync7(workspaceFile)) {
+      patterns = parsePnpmWorkspace(readFileSync5(workspaceFile, "utf8"));
     }
   }
   if (!patterns?.length) return [];
@@ -1557,7 +1926,7 @@ var discoverPnpmPackages = (root, config) => {
 var projectName = (root, config) => {
   if (config.project?.name) return config.project.name;
   try {
-    const pkg = JSON.parse(readFileSync8(join10(root, "package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync6(join7(root, "package.json"), "utf8"));
     if (pkg.name) return pkg.name;
   } catch {
   }
@@ -1565,7 +1934,7 @@ var projectName = (root, config) => {
 };
 var existingGeneratedAt = (indexPath, contentHash) => {
   try {
-    const index = JSON.parse(readFileSync8(indexPath, "utf8"));
+    const index = JSON.parse(readFileSync6(indexPath, "utf8"));
     return index.contentHash === contentHash && typeof index.generatedAt === "string" ? index.generatedAt : void 0;
   } catch {
     return void 0;
@@ -1576,7 +1945,7 @@ var buildDocBridgeIndex = (opts) => {
   const config = opts.config;
   const write = opts.write ?? true;
   const outFile = config.index?.outFile ?? ".doc-bridge/index.json";
-  const indexPath = join10(root, outFile);
+  const indexPath = join7(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";
@@ -1611,7 +1980,7 @@ var buildDocBridgeIndex = (opts) => {
   if (config.index?.llmsTxt?.enabled !== false) {
     const llmsOut = config.index?.llmsTxt?.outFile ?? "llms.txt";
     llmsTxtRelPath = toPosix(llmsOut);
-    llmsTxtPath = join10(root, llmsOut);
+    llmsTxtPath = join7(root, llmsOut);
     if (write) {
       writeFileSync(
         llmsTxtPath,
@@ -1623,7 +1992,7 @@ var buildDocBridgeIndex = (opts) => {
   let capabilitiesPath;
   if (config.index?.capabilities?.enabled !== false) {
     const capabilitiesOut = config.index?.capabilities?.outFile ?? ".doc-bridge/capabilities.json";
-    capabilitiesPath = join10(root, capabilitiesOut);
+    capabilitiesPath = join7(root, capabilitiesOut);
     if (write) {
       mkdirSync(dirname3(capabilitiesPath), { recursive: true });
       writeFileSync(
@@ -1645,11 +2014,531 @@ var buildDocBridgeIndex = (opts) => {
 };
 
 // src/gates/run-gates.ts
-import { readFileSync as readFileSync10 } from "fs";
+import { readFileSync as readFileSync9 } 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";
+
+// src/conformance/ecosystem-contract.ts
+import { z as z5 } from "zod";
+var NonEmptyStringSchema = z5.string().refine((value) => value.trim().length > 0, "must be non-empty");
+var HttpsUrlSchema = z5.string().url().refine((value) => value.startsWith("https://"), "must use https");
+var RepoSchema = z5.string().regex(/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/);
+var SlugSchema = z5.string().regex(/^[a-z][a-z0-9-]*$/);
+var SurfaceSchema = z5.object({
+  home: HttpsUrlSchema.optional(),
+  docs: HttpsUrlSchema.optional(),
+  llms: HttpsUrlSchema.optional(),
+  stats: HttpsUrlSchema.optional(),
+  documentation: z5.enum(["fumadocs", "repository"]),
+  chat: z5.enum(["agentschat", "custom", "none"])
+}).passthrough();
+var ProductSchema = z5.object({
+  id: SlugSchema,
+  name: NonEmptyStringSchema,
+  shortName: NonEmptyStringSchema,
+  kind: NonEmptyStringSchema,
+  role: NonEmptyStringSchema,
+  promise: NonEmptyStringSchema,
+  maturity: z5.enum(["planning", "alpha", "beta", "stable", "deprecated"]),
+  repo: RepoSchema,
+  accent: z5.string().regex(/^#[0-9A-Fa-f]{6}$/),
+  surfaces: SurfaceSchema,
+  navigation: z5.object({
+    showInBar: z5.boolean(),
+    order: z5.number().int().nonnegative().optional(),
+    next: z5.array(SlugSchema)
+  }).passthrough()
+}).passthrough();
+var LegacyPropertySchema = z5.object({
+  id: SlugSchema,
+  name: NonEmptyStringSchema,
+  barLabel: NonEmptyStringSchema,
+  domain: NonEmptyStringSchema,
+  url: HttpsUrlSchema,
+  repo: RepoSchema,
+  tagline: NonEmptyStringSchema,
+  kind: NonEmptyStringSchema,
+  accent: z5.string().regex(/^#[0-9A-Fa-f]{6}$/),
+  llms: HttpsUrlSchema.optional(),
+  stats: HttpsUrlSchema.optional()
+}).passthrough();
+var ManifestSchema = z5.object({
+  schemaVersion: z5.literal(2),
+  parentBrand: z5.object({ id: NonEmptyStringSchema, name: NonEmptyStringSchema }).passthrough(),
+  products: z5.array(ProductSchema).min(1),
+  properties: z5.array(LegacyPropertySchema).length(4),
+  builder: z5.object({ id: NonEmptyStringSchema, name: NonEmptyStringSchema, url: HttpsUrlSchema }).passthrough().optional()
+}).passthrough();
+var EvidenceSchema = z5.discriminatedUnion("type", [
+  z5.object({
+    type: z5.literal("repository-derivation"),
+    repo: RepoSchema,
+    path: NonEmptyStringSchema,
+    summary: NonEmptyStringSchema
+  }).passthrough(),
+  z5.object({ type: z5.literal("endpoint"), url: HttpsUrlSchema, summary: NonEmptyStringSchema }).passthrough()
+]);
+var ClaimSchema = z5.object({
+  id: NonEmptyStringSchema,
+  value: z5.number().finite().nonnegative(),
+  noun: NonEmptyStringSchema,
+  conservativeFloor: z5.number().int().nonnegative().optional(),
+  evidence: EvidenceSchema
+}).passthrough();
+var ClaimProductSchema = z5.object({
+  productId: SlugSchema,
+  source: z5.discriminatedUnion("type", [
+    z5.object({ type: z5.literal("endpoint"), url: HttpsUrlSchema }).passthrough(),
+    z5.object({ type: z5.literal("repository"), repo: RepoSchema }).passthrough()
+  ]),
+  verification: z5.enum(["verified", "declared"]),
+  claims: z5.array(ClaimSchema)
+}).passthrough();
+var ClaimsSchema = z5.object({
+  schemaVersion: z5.literal(1),
+  manifestSchemaVersion: z5.literal(2),
+  products: z5.array(ClaimProductSchema)
+}).passthrough();
+var LEGACY_PRODUCT_IDS = ["agentskit", "akos", "playbook", "registry"];
+var parseCanonicalEcosystemContract = (manifestInput, claimsInput) => {
+  const manifest = ManifestSchema.parse(manifestInput);
+  const claims = ClaimsSchema.parse(claimsInput);
+  const products = new Map(manifest.products.map((product) => [product.id, product]));
+  if (products.size !== manifest.products.length) throw new Error("Manifest product IDs must be unique.");
+  const navigationOrders = /* @__PURE__ */ new Set();
+  for (const product of manifest.products) {
+    if (product.surfaces.documentation === "fumadocs" && !product.surfaces.docs) {
+      throw new Error(`Product ${product.id} requires a docs surface for Fumadocs.`);
+    }
+    if (product.navigation.showInBar) {
+      if (!product.surfaces.home || product.navigation.order === void 0) {
+        throw new Error(`Product ${product.id} requires home and order for shared navigation.`);
+      }
+      if (navigationOrders.has(product.navigation.order)) throw new Error("Navigation orders must be unique.");
+      navigationOrders.add(product.navigation.order);
+    }
+    const next = new Set(product.navigation.next);
+    if (next.size !== product.navigation.next.length || next.has(product.id)) {
+      throw new Error(`Product ${product.id} has duplicate or self-referential navigation.`);
+    }
+    for (const nextId of next) {
+      if (!products.has(nextId)) throw new Error(`Product ${product.id} references unknown product ${nextId}.`);
+    }
+  }
+  for (const [index, id] of LEGACY_PRODUCT_IDS.entries()) {
+    const legacy = manifest.properties[index];
+    const product = products.get(id);
+    if (!legacy || !product || legacy.id !== id || !product.surfaces.home) {
+      throw new Error(`Legacy property ${index} must project product ${id}.`);
+    }
+    const expected = {
+      name: product.name,
+      barLabel: product.shortName,
+      domain: new URL(product.surfaces.home).host,
+      url: product.surfaces.home,
+      repo: product.repo,
+      tagline: product.promise,
+      kind: product.kind,
+      accent: product.accent,
+      llms: product.surfaces.llms,
+      stats: product.surfaces.stats
+    };
+    for (const [key, value] of Object.entries(expected)) {
+      if (legacy[key] !== value) throw new Error(`Legacy ${id}.${key} must match v2.`);
+    }
+  }
+  const claimProducts = new Map(claims.products.map((product) => [product.productId, product]));
+  if (claimProducts.size !== claims.products.length || claimProducts.size !== products.size) {
+    throw new Error("Claims must include every manifest product exactly once.");
+  }
+  for (const [productId, product] of products) {
+    const claimProduct = claimProducts.get(productId);
+    if (!claimProduct) throw new Error(`Claims are missing product ${productId}.`);
+    if (claimProduct.source.type === "endpoint") {
+      if (claimProduct.source.url !== product.surfaces.stats) throw new Error(`Claims source for ${productId} must match stats.`);
+    } else if (claimProduct.source.repo !== product.repo) {
+      throw new Error(`Claims source for ${productId} must match repo.`);
+    }
+    if (claimProduct.verification === "declared" && claimProduct.claims.length > 0) {
+      throw new Error(`Declared product ${productId} cannot publish claims.`);
+    }
+    const claimIds = /* @__PURE__ */ new Set();
+    for (const claim of claimProduct.claims) {
+      if (claimIds.has(claim.id)) throw new Error(`Product ${productId} has duplicate claim ${claim.id}.`);
+      claimIds.add(claim.id);
+      if (claim.conservativeFloor !== void 0 && claim.conservativeFloor > claim.value) {
+        throw new Error(`Claim ${productId}:${claim.id} has a floor above its value.`);
+      }
+      if (claim.evidence.type === "repository-derivation" && claim.evidence.repo !== product.repo) {
+        throw new Error(`Claim ${productId}:${claim.id} evidence must match the product repo.`);
+      }
+    }
+  }
+  return { manifest, claims };
+};
+
+// src/conformance/documentation-standard-v1.ts
+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;
+  try {
+    const abs = realpathSync5.native(unresolved);
+    const rel = relative3(rootAbs, abs);
+    return !isAbsolute3(rel) && rel !== ".." && !rel.startsWith(`..${sep4}`) ? abs : void 0;
+  } catch {
+    return void 0;
+  }
+};
+var fileEvidence = (root, path, options) => {
+  const abs = safePath(root, path);
+  if (!abs) {
+    return {
+      exists: false,
+      content: "",
+      evidence: { path, detail: "Path escapes the project root." }
+    };
+  }
+  if (!existsSync8(abs)) {
+    return { exists: false, content: "", evidence: { path, detail: "File does not exist." } };
+  }
+  try {
+    const stat = statSync3(abs);
+    if (!stat.isFile()) {
+      return { exists: false, content: "", evidence: { path, detail: "Path is not a regular file." } };
+    }
+    if (stat.size === 0) {
+      return { exists: false, content: "", evidence: { path, detail: "File is empty." } };
+    }
+    if (options?.readContent === false) {
+      return {
+        exists: true,
+        content: "",
+        evidence: { path: toPosix(relative3(resolve5(root), abs)) || ".", detail: "File exists and is non-empty." }
+      };
+    }
+    if (stat.size > MAX_TEXT_EVIDENCE_BYTES) {
+      return {
+        exists: false,
+        content: "",
+        evidence: { path, detail: `Text evidence exceeds ${MAX_TEXT_EVIDENCE_BYTES} bytes.` }
+      };
+    }
+    const content = readFileSync7(abs, "utf8");
+    return {
+      exists: content.trim().length > 0,
+      content,
+      evidence: {
+        path: toPosix(relative3(resolve5(root), abs)) || ".",
+        detail: content.trim().length > 0 ? "File exists and is non-empty." : "File is empty."
+      }
+    };
+  } catch {
+    return { exists: false, content: "", evidence: { path, detail: "File is not readable text." } };
+  }
+};
+var resultWithException = (draft, options) => {
+  if (draft.passed) {
+    const { passed: _passed2, ...result2 } = draft;
+    return { ...result2, status: "pass", ok: true };
+  }
+  const exception = options.exceptions?.find((candidate) => candidate.ruleId === draft.id);
+  const { passed: _passed, ...result } = draft;
+  if (!exception) return { ...result, status: "fail", ok: false };
+  return {
+    ...result,
+    status: "excepted",
+    ok: true,
+    exception: {
+      reason: exception.reason,
+      approvedBy: exception.approvedBy,
+      trackingUrl: exception.trackingUrl
+    }
+  };
+};
+var humanDocsRule = (root, config) => {
+  const docs = scanHumanDocRecords(root, config);
+  return {
+    id: "human-docs",
+    level: "required",
+    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)),
+      detail: `Human route: ${doc.url}`
+    })),
+    remediation: {
+      command: "edit doc-bridge.config.json",
+      detail: "Configure corpus.human with a supported adapter and a non-agent documentation root."
+    }
+  };
+};
+var llmsRule = (root, config, options) => {
+  const llmsPath = config.index?.llmsTxt?.outFile ?? "llms.txt";
+  const llmsKey = safePath(root, llmsPath) ?? resolve5(root, llmsPath);
+  const rawSources = /* @__PURE__ */ new Map();
+  for (const path of options.rawSources ?? []) {
+    const key = safePath(root, path) ?? resolve5(root, path);
+    if (key !== llmsKey && !rawSources.has(key)) rawSources.set(key, path);
+  }
+  const paths = [llmsPath, ...rawSources.values()];
+  const evidence = paths.map((path) => fileEvidence(root, path));
+  const generated = buildDocBridgeIndex({ root, config, write: false }).index;
+  const expectedLlms = renderLlmsTxt(config, generated.knowledge, generated.project?.name ?? "project");
+  const llmsIsFresh = evidence[0]?.content === expectedLlms;
+  if (evidence[0]?.exists) {
+    evidence[0] = {
+      ...evidence[0],
+      evidence: {
+        ...evidence[0].evidence,
+        detail: llmsIsFresh ? "File matches the deterministic ak-docs output." : "File is stale or was not generated by the current ak-docs inputs."
+      }
+    };
+  }
+  const passed = config.index?.llmsTxt?.enabled !== false && paths.length > 1 && llmsIsFresh && evidence.every((item) => item.exists);
+  return {
+    id: "llms-and-raw-source",
+    level: "required",
+    passed,
+    message: passed ? `Resolved llms.txt and ${paths.length - 1} raw source(s).` : "llms.txt must be enabled, current, and accompanied by at least one readable raw source.",
+    evidence: evidence.map((item) => item.evidence),
+    remediation: {
+      command: "ak-docs index",
+      detail: "Generate llms.txt and configure conformance.documentationStandardV1.rawSources."
+    }
+  };
+};
+var normalizedUrl = (value) => value.replace(/\/$/, "");
+var ecosystemContract = (root, options) => {
+  const declaration = options.ecosystemContract;
+  if (!declaration) {
+    return {
+      passed: false,
+      urls: /* @__PURE__ */ new Set(),
+      evidence: [{ path: "doc-bridge.config.json", detail: "Canonical ecosystem contract evidence is not declared." }]
+    };
+  }
+  const manifestFile = fileEvidence(root, declaration.manifest);
+  const claimsFile = fileEvidence(root, declaration.claims);
+  const evidence = [manifestFile.evidence, claimsFile.evidence];
+  if (!manifestFile.exists || !claimsFile.exists) return { passed: false, urls: /* @__PURE__ */ new Set(), evidence };
+  try {
+    const manifest = JSON.parse(manifestFile.content);
+    const claims = JSON.parse(claimsFile.content);
+    const contract = parseCanonicalEcosystemContract(manifest, claims);
+    const productIds = contract.manifest.products.map((product) => product.id);
+    if (!productIds.includes(declaration.productId)) throw new Error(`Manifest is missing product ${declaration.productId}.`);
+    const urls = /* @__PURE__ */ new Set();
+    for (const product of contract.manifest.products) {
+      for (const value of [
+        product.surfaces.home,
+        product.surfaces.docs,
+        product.surfaces.llms,
+        product.surfaces.stats
+      ]) {
+        if (typeof value === "string" && /^https:\/\//.test(value)) urls.add(normalizedUrl(value));
+      }
+    }
+    evidence[0] = { path: declaration.manifest, detail: `Validated ${productIds.length} canonical product(s), including ${declaration.productId}.` };
+    evidence[1] = { path: declaration.claims, detail: `Validated claim-ledger identity for ${contract.claims.products.length} product(s).` };
+    return { passed: urls.size > 0, urls, evidence };
+  } catch (error) {
+    evidence.push({
+      path: `${declaration.manifest}, ${declaration.claims}`,
+      detail: error instanceof Error ? error.message : "Canonical ecosystem contract is invalid."
+    });
+    return { passed: false, urls: /* @__PURE__ */ new Set(), evidence };
+  }
+};
+var handoffsRule = (root, config) => {
+  const index = buildDocBridgeIndex({ root, config, write: false }).index;
+  const handoffs = Object.values(index.handoffs ?? {});
+  const ready = handoffs.filter(
+    (handoff) => handoff.startHere.length > 0 && handoff.editRoots.length > 0 && handoff.checks.length > 0 && (handoff.bridge?.humanDoc === "linked" || handoff.bridge?.humanDoc === "external")
+  );
+  return {
+    id: "agent-handoffs",
+    level: "required",
+    passed: ready.length > 0 && ready.length === handoffs.length,
+    message: ready.length > 0 && ready.length === handoffs.length ? `${ready.length} handoff(s) are action-ready and human-linked.` : `${ready.length}/${handoffs.length} handoff(s) are action-ready and human-linked.`,
+    evidence: handoffs.map((handoff) => ({
+      path: handoff.startHere,
+      detail: `${handoff.target.id}: ${handoff.editRoots.length} edit root(s), ${handoff.checks.length} check(s), bridge=${handoff.bridge?.humanDoc ?? "none"}`
+    })),
+    remediation: {
+      command: "ak-docs bootstrap agent-docs && ak-docs index",
+      detail: "Add ownership checks and a resolvable humanDoc for every handoff."
+    }
+  };
+};
+var contributionRule = (root, options) => {
+  const paths = options.contributionPaths?.length ? options.contributionPaths : ["CONTRIBUTING.md"];
+  const evidence = paths.map((path) => fileEvidence(root, path));
+  return {
+    id: "contribution",
+    level: "required",
+    passed: evidence.some((item) => item.exists),
+    message: evidence.some((item) => item.exists) ? "Contribution guidance is available." : "Contribution guidance is missing.",
+    evidence: evidence.map((item) => item.evidence),
+    remediation: {
+      command: "edit CONTRIBUTING.md",
+      detail: "Document setup, validation commands, and the pull-request workflow."
+    }
+  };
+};
+var markersRule = (root, options, kind, level) => {
+  const declarations = options[kind === "metadata" ? "metadata" : "diagrams"] ?? [];
+  const evidence = [];
+  let passed = declarations.length > 0;
+  for (const declaration of declarations) {
+    const file = fileEvidence(root, declaration.path);
+    const missing = declaration.contains.filter((marker) => !file.content.includes(marker));
+    if (!file.exists || missing.length > 0) passed = false;
+    evidence.push({
+      path: declaration.path,
+      detail: !file.exists ? file.evidence.detail : missing.length ? `Missing marker(s): ${missing.join(", ")}` : `Found marker(s): ${declaration.contains.join(", ")}`
+    });
+  }
+  return {
+    id: kind,
+    level,
+    passed,
+    message: passed ? `${kind} evidence is complete.` : `${kind} evidence is incomplete.`,
+    evidence,
+    remediation: {
+      command: "edit doc-bridge.config.json",
+      detail: `Declare ${kind} evidence paths and markers that exist in the repository.`
+    }
+  };
+};
+var linksRule = (root, options) => {
+  const links = options.links ?? [];
+  const contract = ecosystemContract(root, options);
+  const evidence = [...contract.evidence];
+  let passed = links.length > 0 && contract.passed;
+  for (const link of links) {
+    const sources = link.paths.map((path) => ({ path, file: fileEvidence(root, path) }));
+    const matches = sources.filter(({ file }) => file.exists && file.content.includes(link.url));
+    const canonical = contract.urls.has(normalizedUrl(link.url));
+    if (matches.length === 0 || !canonical) passed = false;
+    evidence.push({
+      path: sources.map((source) => source.path).join(", "),
+      detail: matches.length === 0 ? `Missing ${link.url}` : canonical ? `Found canonical ecosystem URL ${link.url}` : `Found ${link.url}, but it is absent from the canonical ecosystem manifest.`
+    });
+  }
+  return {
+    id: "cross-links",
+    level: "required",
+    passed,
+    message: passed ? `${links.length} required ecosystem link(s) resolve in source.` : "One or more required ecosystem links are missing from source.",
+    evidence,
+    remediation: {
+      command: "edit README.md",
+      detail: "Sync the canonical ecosystem snapshots and add each configured canonical URL to a declared documentation source."
+    }
+  };
+};
+var quickstartsRule = (root, options) => {
+  const quickstarts = options.quickstarts ?? [];
+  const evidence = [];
+  let passed = quickstarts.length > 0;
+  for (const quickstart of quickstarts) {
+    const doc = fileEvidence(root, quickstart.doc);
+    const test = fileEvidence(root, quickstart.test);
+    const missingMarkers = quickstart.testContains.filter((marker) => !test.content.includes(marker));
+    if (!doc.exists || !test.exists || missingMarkers.length > 0 || !quickstart.command.trim()) passed = false;
+    evidence.push(
+      { path: quickstart.doc, detail: `${quickstart.id}: ${doc.evidence.detail}` },
+      {
+        path: quickstart.test,
+        detail: missingMarkers.length ? `${quickstart.id}: missing test marker(s): ${missingMarkers.join(", ")}` : `${quickstart.id}: test evidence; CI command: ${quickstart.command}`
+      }
+    );
+  }
+  return {
+    id: "tested-quickstarts",
+    level: "required",
+    passed,
+    message: passed ? `${quickstarts.length} quickstart(s) have executable test evidence.` : "Quickstart test evidence is incomplete.",
+    evidence,
+    remediation: {
+      command: "pnpm test",
+      detail: "Map every quickstart to a documentation path, test file, identifying marker, and CI command."
+    }
+  };
+};
+var visualsRule = (root, options) => {
+  const visuals = options.visuals ?? [];
+  const evidence = visuals.map((path) => fileEvidence(root, path, { readContent: false }));
+  return {
+    id: "visual-explanations",
+    level: "recommended",
+    passed: visuals.length > 0 && evidence.every((item) => item.exists),
+    message: visuals.length > 0 && evidence.every((item) => item.exists) ? `${visuals.length} visual asset(s) found.` : "Visual explanation evidence is incomplete.",
+    evidence: evidence.map((item) => item.evidence),
+    remediation: {
+      command: "edit doc-bridge.config.json",
+      detail: "Declare the images or animations that explain the product workflow."
+    }
+  };
+};
+var count = (results, level, status) => results.filter((result) => result.level === level && result.status === status).length;
+var runDocumentationStandardV1 = (root, config) => {
+  const options = config.conformance?.documentationStandardV1 ?? {};
+  const drafts = [
+    humanDocsRule(root, config),
+    llmsRule(root, config, options),
+    handoffsRule(root, config),
+    contributionRule(root, options),
+    markersRule(root, options, "metadata", "required"),
+    linksRule(root, options),
+    quickstartsRule(root, options),
+    visualsRule(root, options),
+    markersRule(root, options, "structured-diagrams", "recommended")
+  ];
+  const results = drafts.map((draft) => resultWithException(draft, options));
+  return {
+    schemaVersion: 1,
+    profile: { id: DOCUMENTATION_STANDARD_V1_ID, version: 1, status: DOCUMENTATION_STANDARD_V1_STATUS },
+    ok: results.filter((result) => result.level === "required").every((result) => result.ok),
+    recommendedOk: results.filter((result) => result.level === "recommended").every((result) => result.ok),
+    summary: {
+      required: {
+        passed: count(results, "required", "pass"),
+        failed: count(results, "required", "fail"),
+        excepted: count(results, "required", "excepted")
+      },
+      recommended: {
+        passed: count(results, "recommended", "pass"),
+        failed: count(results, "recommended", "fail"),
+        excepted: count(results, "recommended", "excepted")
+      }
+    },
+    results
+  };
+};
+var formatDocumentationStandardText = (report) => [
+  `Documentation Standard v1 (${report.profile.status})`,
+  `Required: ${report.summary.required.passed} passed \xB7 ${report.summary.required.failed} failed \xB7 ${report.summary.required.excepted} excepted`,
+  `Recommended: ${report.summary.recommended.passed} passed \xB7 ${report.summary.recommended.failed} failed \xB7 ${report.summary.recommended.excepted} excepted`,
+  "",
+  ...report.results.flatMap((result) => [
+    `${result.status === "pass" ? "PASS" : result.status === "excepted" ? "EXCEPTED" : "FAIL"} [${result.level}] ${result.id}: ${result.message}`,
+    ...result.evidence.map((evidence) => `  evidence: ${evidence.path} \u2014 ${evidence.detail}`),
+    ...result.exception ? [`  exception: ${result.exception.reason} \u2014 ${result.exception.approvedBy} (${result.exception.trackingUrl})`] : result.ok ? [] : [`  fix: ${result.remediation.command} \u2014 ${result.remediation.detail}`]
+  ])
+];
 
 // src/query/load-index.ts
-import { existsSync as existsSync7, readFileSync as readFileSync9 } from "fs";
-import { join as join11, resolve as resolve3 } from "path";
+import { existsSync as existsSync9, readFileSync as readFileSync8 } from "fs";
+import { join as join8, resolve as resolve6 } from "path";
 var IndexNotFoundError = class extends Error {
   constructor(path) {
     super(`Missing index at ${path}. Run: ak-docs index`);
@@ -1658,18 +2547,29 @@ var IndexNotFoundError = class extends Error {
   }
   path;
 };
-var indexFilePath = (root, config) => join11(root, config.index?.outFile ?? ".doc-bridge/index.json");
+var indexFilePath = (root, config) => join8(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 (!existsSync9(path)) throw new IndexNotFoundError(path);
+  const raw = JSON.parse(readFileSync8(path, "utf8"));
   return parseDocBridgeIndex(raw);
 };
-var resolveRoot = (cwd) => resolve3(cwd ?? process.cwd());
+var resolveRoot = (cwd) => resolve6(cwd ?? process.cwd());
 
 // src/gates/run-gates.ts
-var SUPPORTED_GATES = ["index-freshness", "human-guide-links", "okf-type", "docs-style"];
+var RESERVED_GATE_IDS = /* @__PURE__ */ new Set(["link-rot", "routing-currency", "bootstrap-size"]);
 var runGate = (root, config, id) => {
+  if (id === "documentation-standard-v1") {
+    const details = runDocumentationStandardV1(root, config);
+    return {
+      id,
+      ok: details.ok,
+      message: details.ok ? "Documentation Standard v1 required rules pass" : `${details.summary.required.failed} Documentation Standard v1 required rule(s) failed`,
+      expected: "all required rules pass or have approved exceptions",
+      actual: `${details.summary.required.passed} passed, ${details.summary.required.failed} failed, ${details.summary.required.excepted} excepted`,
+      details
+    };
+  }
   if (id === "human-guide-links") return runHumanGuideLinksGate(root, config);
   if (id === "okf-type") return runOkfTypeGate(root, config);
   if (id === "docs-style") return runDocsStyleGate(root, config);
@@ -1727,7 +2627,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(readFileSync9(doc.absPath, "utf8")) })).filter((doc) => !doc.type || allowed && !allowed.includes(doc.type));
   if (bad.length) {
     return {
       id: "okf-type",
@@ -1801,7 +2701,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(readFileSync9(doc.absPath, "utf8"), required)
   })).filter((doc) => doc.missing.length > 0);
   if (bad.length) {
     return {
@@ -1831,18 +2731,24 @@ var resolveGateIds = (config) => {
     ) : ["index-freshness", "human-guide-links"]
   );
   for (const id of config.gates?.include ?? []) {
-    if (SUPPORTED_GATES.includes(id)) ids.add(id);
+    if (RESERVED_GATE_IDS.has(id)) {
+      process.emitWarning(`Gate "${id}" is reserved and has no runtime implementation; it was not executed.`, {
+        code: "AK_DOCS_RESERVED_GATE"
+      });
+      continue;
+    }
+    ids.add(id);
   }
   for (const id of config.gates?.exclude ?? []) {
-    if (SUPPORTED_GATES.includes(id)) ids.delete(id);
+    if (!RESERVED_GATE_IDS.has(id)) ids.delete(id);
   }
   return [...ids];
 };
 
 // src/mcp/server.ts
-import { readFileSync as readFileSync12, realpathSync } from "fs";
-import { relative, resolve as resolve4 } from "path";
-import { z as z5, ZodError } from "zod";
+import { readFileSync as readFileSync11, realpathSync as realpathSync6 } from "fs";
+import { relative as relative4, resolve as resolve7 } from "path";
+import { z as z6, ZodError } from "zod";
 
 // src/query/search.ts
 var tokenize = (value) => value.toLowerCase().split(/[^a-z0-9@/_-]+/).filter((t) => t.length >= 2);
@@ -1960,15 +2866,15 @@ var createDocBridgeRetriever = (index, options = {}) => ({
 });
 
 // src/memory/ingest.ts
-import { existsSync as existsSync8, readFileSync as readFileSync11 } from "fs";
-import { join as join12 } from "path";
+import { existsSync as existsSync10, readFileSync as readFileSync10 } 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 (!existsSync8(dir)) return [];
+  if (!existsSync10(dir)) return [];
   return walkFiles(dir, { extensions: [".md", ".mdc"] }).map((abs) => {
     const rel = relativePath(root, abs);
-    const raw = readFileSync11(abs, "utf8");
+    const raw = readFileSync10(abs, "utf8");
     const id = slugFromPath(rel);
     return {
       schemaVersion: 1,
@@ -1983,10 +2889,10 @@ var ingestMarkdownDir = (root, dir, source, confidence) => {
   });
 };
 var ingestCursorRules = (root) => {
-  const dir = join12(root, ".cursor", "rules");
+  const dir = join9(root, ".cursor", "rules");
   return ingestMarkdownDir(root, dir, "cursor", 0.6);
 };
-var ingestAgentMemory = (root) => ingestMarkdownDir(root, join12(root, ".agent-memory"), "agent-memory", 0.7);
+var ingestAgentMemory = (root) => ingestMarkdownDir(root, join9(root, ".agent-memory"), "agent-memory", 0.7);
 var ingestMemoryCandidates = (root) => [
   ...ingestAgentMemory(root),
   ...ingestCursorRules(root)
@@ -2240,21 +3146,21 @@ var MCP_TOOLS = [
   }
 ];
 var asRecord = (value) => value && typeof value === "object" ? value : {};
-var HandoffResolveArgsSchema = z5.object({
-  id: z5.string().min(1),
-  kind: z5.enum(["package", "ownership"]).optional()
+var HandoffResolveArgsSchema = z6.object({
+  id: z6.string().min(1),
+  kind: z6.enum(["package", "ownership"]).optional()
 });
-var DocSearchArgsSchema = z5.object({
-  term: z5.string().min(1),
-  limit: z5.number().int().positive().max(100).optional()
+var DocSearchArgsSchema = z6.object({
+  term: z6.string().min(1),
+  limit: z6.number().int().positive().max(100).optional()
 });
-var RetrieverQueryArgsSchema = z5.object({
-  query: z5.string().min(1),
-  limit: z5.number().int().positive().max(100).optional()
+var RetrieverQueryArgsSchema = z6.object({
+  query: z6.string().min(1),
+  limit: z6.number().int().positive().max(100).optional()
 });
-var DocGetArgsSchema = z5.object({
-  id: z5.string().min(1).optional(),
-  path: z5.string().min(1).optional()
+var DocGetArgsSchema = z6.object({
+  id: z6.string().min(1).optional(),
+  path: z6.string().min(1).optional()
 }).refine((args) => args.id || args.path, "doc.get requires id or path");
 var parseToolArgs = (tool, schema, value) => {
   try {
@@ -2286,12 +3192,12 @@ var findDocPath = (index, args) => {
   return doc.path;
 };
 var resolveDocPath = (root, relPath) => {
-  const rootAbs = realpathSync.native(root);
-  const unresolved = resolve4(rootAbs, relPath);
-  const unresolvedRel = relative(rootAbs, unresolved);
+  const rootAbs = realpathSync6.native(root);
+  const unresolved = resolve7(rootAbs, relPath);
+  const unresolvedRel = relative4(rootAbs, unresolved);
   if (unresolvedRel.startsWith("..")) throw new Error("doc.get path escapes project root");
-  const abs = realpathSync.native(unresolved);
-  const rel = relative(rootAbs, abs);
+  const abs = realpathSync6.native(unresolved);
+  const rel = relative4(rootAbs, abs);
   if (rel.startsWith("..")) throw new Error("doc.get path escapes project root");
   return abs;
 };
@@ -2325,7 +3231,7 @@ var handleMcpRequest = (ctx, request) => {
     }
     if (name === "doc.get") {
       const relPath = findDocPath(index(), parseToolArgs("doc.get", DocGetArgsSchema, args));
-      return textResult(readFileSync12(resolveDocPath(ctx.root, relPath), "utf8"));
+      return textResult(readFileSync11(resolveDocPath(ctx.root, relPath), "utf8"));
     }
     if (name === "gate.status") return textResult(runGates(ctx.root, ctx.config));
     if (name === "retriever.query") {
@@ -2403,9 +3309,9 @@ var startMcpStdioServer = (ctx) => {
 };
 
 // src/mcp/install.ts
-import { existsSync as existsSync9, mkdirSync as mkdirSync2, readFileSync as readFileSync13, writeFileSync as writeFileSync2 } from "fs";
+import { existsSync as existsSync11, mkdirSync as mkdirSync2, readFileSync as readFileSync12, writeFileSync as writeFileSync2 } from "fs";
 import { homedir } from "os";
-import { dirname as dirname4, join as join13, resolve as resolve5 } from "path";
+import { dirname as dirname4, join as join10, resolve as resolve8 } from "path";
 var SERVER_NAME = "ak-docs";
 var mcpServerEntry = (root) => ({
   command: "npx",
@@ -2413,9 +3319,9 @@ var mcpServerEntry = (root) => ({
   cwd: root
 });
 var readJson = (path) => {
-  if (!existsSync9(path)) return {};
+  if (!existsSync11(path)) return {};
   try {
-    const parsed = JSON.parse(readFileSync13(path, "utf8"));
+    const parsed = JSON.parse(readFileSync12(path, "utf8"));
     return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
   } catch {
     return {};
@@ -2427,12 +3333,12 @@ var writeJson = (path, value) => {
 `, "utf8");
 };
 var resolveTargetPath = (target, root) => {
-  if (target === "cursor") return resolve5(root, ".cursor", "mcp.json");
-  return join13(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+  if (target === "cursor") return resolve8(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 = !existsSync9(configPath);
+  const created = !existsSync11(configPath);
   const existing = readJson(configPath);
   const servers = existing.mcpServers && typeof existing.mcpServers === "object" && !Array.isArray(existing.mcpServers) ? { ...existing.mcpServers } : {};
   servers[SERVER_NAME] = mcpServerEntry(root);
@@ -2698,22 +3604,22 @@ var formatDoctorText = (report) => {
 };
 
 // src/index-builder/watch-index.ts
-import { existsSync as existsSync10, watch } from "fs";
-import { dirname as dirname5, resolve as resolve6 } from "path";
+import { existsSync as existsSync12, watch } from "fs";
+import { dirname as dirname5, resolve as resolve9 } from "path";
 var WATCH_PATTERN = /\.(md|mdx|json|ya?ml|mdc)$/i;
 var collectWatchRoots = (root, config, configPath) => {
   const roots = /* @__PURE__ */ new Set();
-  roots.add(resolve6(root, config.corpus.agent.root));
+  roots.add(resolve9(root, config.corpus.agent.root));
   const humanSources = config.corpus.human ? Array.isArray(config.corpus.human) ? config.corpus.human : [config.corpus.human] : [];
   for (const source of humanSources) {
     const humanOpts = source.options ?? {};
     for (const key of ["contentDir", "docsDir", "root"]) {
       const value = humanOpts[key];
-      if (typeof value === "string" && value.length) roots.add(resolve6(root, value));
+      if (typeof value === "string" && value.length) roots.add(resolve9(root, value));
     }
   }
-  if (configPath) roots.add(dirname5(resolve6(configPath)));
-  return [...roots].filter((dir) => existsSync10(dir));
+  if (configPath) roots.add(dirname5(resolve9(configPath)));
+  return [...roots].filter((dir) => existsSync12(dir));
 };
 var watchDocBridgeIndex = (opts) => {
   const debounceMs = opts.debounceMs ?? 350;
@@ -2754,8 +3660,8 @@ var watchDocBridgeIndex = (opts) => {
       rebuild();
     });
   }
-  const configDir = resolve6(opts.root);
-  if (existsSync10(configDir)) {
+  const configDir = resolve9(opts.root);
+  if (existsSync12(configDir)) {
     watch(configDir, (_event, filename) => {
       if (!filename || !/doc-bridge\.config/.test(filename)) return;
       rebuild();
@@ -2774,8 +3680,8 @@ var watchDocBridgeIndex = (opts) => {
 
 // src/memory/github-pr.ts
 import { execFileSync, spawnSync } from "child_process";
-import { existsSync as existsSync11, mkdirSync as mkdirSync3, writeFileSync as writeFileSync3 } from "fs";
-import { join as join15 } from "path";
+import { existsSync as existsSync13, 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" });
   const out = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
@@ -2783,10 +3689,10 @@ var run = (cmd, args, cwd) => {
 };
 var hasGh = () => run("gh", ["--version"], process.cwd()).ok;
 var slug = () => (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19);
-var defaultPromotionDraftPath = (root) => join15(root, ".doc-bridge", "drafts", `memory-promotion-${slug()}.md`);
+var defaultPromotionDraftPath = (root) => join12(root, ".doc-bridge", "drafts", `memory-promotion-${slug()}.md`);
 var writePromotionDraft = (root, draft, path) => {
   const draftPath = path ?? defaultPromotionDraftPath(root);
-  mkdirSync3(join15(root, ".doc-bridge", "drafts"), { recursive: true });
+  mkdirSync3(join12(root, ".doc-bridge", "drafts"), { recursive: true });
   writeFileSync3(draftPath, `${draft.body}
 `, "utf8");
   return draftPath;
@@ -2822,7 +3728,7 @@ var promoteMemoryToGithubPr = (root, draft, options = {}) => {
       message: `Wrote draft to ${relDraft}. Run the printed git/gh commands to open a draft PR.`
     };
   }
-  if (!existsSync11(join15(root, ".git"))) {
+  if (!existsSync13(join12(root, ".git"))) {
     return {
       ok: false,
       dryRun: false,
@@ -2925,8 +3831,8 @@ ${auth.out}`
 };
 
 // src/federation/llms.ts
-import { existsSync as existsSync12, readFileSync as readFileSync14 } from "fs";
-import { resolve as resolve7 } from "path";
+import { existsSync as existsSync14, readFileSync as readFileSync13 } from "fs";
+import { resolve as resolve10 } from "path";
 var tokenize2 = (value) => value.toLowerCase().split(/[^a-z0-9]+/).filter((token) => token.length >= 2);
 var scoreText = (query, text) => {
   const hay = text.toLowerCase();
@@ -2941,9 +3847,9 @@ var defaultFetchText = async (url) => {
 var sourceText = async (root, source, fetchText) => {
   try {
     if (/^https?:\/\//.test(source)) return await fetchText(source);
-    const path = resolve7(root, source);
-    if (!existsSync12(path)) return null;
-    return readFileSync14(path, "utf8");
+    const path = resolve10(root, source);
+    if (!existsSync14(path)) return null;
+    return readFileSync13(path, "utf8");
   } catch {
     return null;
   }
@@ -3028,11 +3934,11 @@ var retrieveHybridChunks = async (root, config, index, query, options = {}) => {
 };
 
 // src/intelligence/rag.ts
-import { readFileSync as readFileSync15 } from "fs";
-import { join as join17 } from "path";
+import { readFileSync as readFileSync14 } from "fs";
+import { join as join14 } from "path";
 
 // src/intelligence/adapter.ts
-import { join as join16 } from "path";
+import { join as join13 } from "path";
 
 // src/intelligence/peers.ts
 var PeerMissingError = class extends Error {
@@ -3159,7 +4065,7 @@ var resolveIntelligenceRuntime = async (config) => {
   }
   return { adapter, embed, provider, ...model ? { model } : {} };
 };
-var defaultVectorStorePath = (root) => join16(root, ".doc-bridge", "vectors");
+var defaultVectorStorePath = (root) => join13(root, ".doc-bridge", "vectors");
 
 // src/intelligence/rag.ts
 var loadDocuments = (root, index, sources) => {
@@ -3167,10 +4073,10 @@ var loadDocuments = (root, index, sources) => {
   const docs = [];
   if (includeAgent) {
     for (const entry of index.knowledge) {
-      const abs = join17(root, entry.path);
+      const abs = join14(root, entry.path);
       let content = "";
       try {
-        content = readFileSync15(abs, "utf8");
+        content = readFileSync14(abs, "utf8");
       } catch {
         content = [entry.title, entry.description].filter(Boolean).join("\n\n");
       }
@@ -3188,7 +4094,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" ? join17(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,
@@ -3447,12 +4353,17 @@ export {
   AgentHandoffV1Schema,
   AgentSearchV1Schema,
   ConfigNotFoundError,
+  DOCUMENTATION_STANDARD_V1_ID,
+  DOCUMENTATION_STANDARD_V1_STATUS,
   DOC_BRIDGE_PATTERN_ID,
   DOC_BRIDGE_PATTERN_META,
   DocBridgeConfigV1Schema,
   DocBridgeIndexV1JsonSchema,
   DocBridgeIndexV1Schema,
   DocBridgeJsonSchemas,
+  DocumentationStandardRuleIdSchema,
+  DocumentationStandardV1ConfigSchema,
+  EcosystemContractEvidenceSchema,
   HANDOFF_SCHEMA_VERSION,
   HandoffBridgeSchema,
   HandoffTargetTypeSchema,
@@ -3482,6 +4393,7 @@ export {
   formatDoctorBadgeJson,
   formatDoctorBadgeMarkdown,
   formatDoctorText,
+  formatDocumentationStandardText,
   handleMcpRequest,
   indexFilePath,
   ingestAgentMemory,
@@ -3509,6 +4421,7 @@ export {
   retrieveHybridChunks,
   runChatOnce,
   runDoctor,
+  runDocumentationStandardV1,
   runGate,
   runGates,
   runQuery,