@agentskit/doc-bridge 1.0.1 → 1.1.1

package/dist/cli/program.js

@@ -1,12 +1,271 @@
 // src/cli/program.ts
-import { existsSync as existsSync14, mkdirSync as mkdirSync5, readFileSync as readFileSync17, writeFileSync as writeFileSync4 } from "fs";
-import { dirname as dirname7, resolve as resolve9 } from "path";
+import { existsSync as existsSync16, mkdirSync as mkdirSync5, readFileSync as readFileSync16, writeFileSync as writeFileSync4 } from "fs";
+import { dirname as dirname7, resolve as resolve12 } from "path";
 import { createInterface } from "readline/promises";
 
 // 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/defaults.ts
 var DEFAULT_AGENT_EXCLUDE = ["**/node_modules/**", "**/.git/**"];
@@ -147,7 +406,8 @@ var GatesConfigSchema = z.object({
       "okf-type",
       "docs-style",
       "routing-currency",
-      "bootstrap-size"
+      "bootstrap-size",
+      "documentation-standard-v1"
     ])
   ).max(16).optional(),
   exclude: z.array(
@@ -158,7 +418,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()
@@ -237,6 +498,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({
@@ -252,7 +576,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/load-config.ts
@@ -299,22 +624,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);
@@ -345,24 +664,197 @@ var projectRootFromConfigPath = (configFilePath, projectRootField) => {
   return configDir;
 };
 
+// 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 z2 } from "zod";
+var NonEmptyStringSchema = z2.string().refine((value) => value.trim().length > 0, "must be non-empty");
+var HttpsUrlSchema = z2.string().url().refine((value) => value.startsWith("https://"), "must use https");
+var RepoSchema = z2.string().regex(/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/);
+var SlugSchema = z2.string().regex(/^[a-z][a-z0-9-]*$/);
+var SurfaceSchema = z2.object({
+  home: HttpsUrlSchema.optional(),
+  docs: HttpsUrlSchema.optional(),
+  llms: HttpsUrlSchema.optional(),
+  stats: HttpsUrlSchema.optional(),
+  documentation: z2.enum(["fumadocs", "repository"]),
+  chat: z2.enum(["agentschat", "custom", "none"])
+}).passthrough();
+var ProductSchema = z2.object({
+  id: SlugSchema,
+  name: NonEmptyStringSchema,
+  shortName: NonEmptyStringSchema,
+  kind: NonEmptyStringSchema,
+  role: NonEmptyStringSchema,
+  promise: NonEmptyStringSchema,
+  maturity: z2.enum(["planning", "alpha", "beta", "stable", "deprecated"]),
+  repo: RepoSchema,
+  accent: z2.string().regex(/^#[0-9A-Fa-f]{6}$/),
+  surfaces: SurfaceSchema,
+  navigation: z2.object({
+    showInBar: z2.boolean(),
+    order: z2.number().int().nonnegative().optional(),
+    next: z2.array(SlugSchema)
+  }).passthrough()
+}).passthrough();
+var LegacyPropertySchema = z2.object({
+  id: SlugSchema,
+  name: NonEmptyStringSchema,
+  barLabel: NonEmptyStringSchema,
+  domain: NonEmptyStringSchema,
+  url: HttpsUrlSchema,
+  repo: RepoSchema,
+  tagline: NonEmptyStringSchema,
+  kind: NonEmptyStringSchema,
+  accent: z2.string().regex(/^#[0-9A-Fa-f]{6}$/),
+  llms: HttpsUrlSchema.optional(),
+  stats: HttpsUrlSchema.optional()
+}).passthrough();
+var ManifestSchema = z2.object({
+  schemaVersion: z2.literal(2),
+  parentBrand: z2.object({ id: NonEmptyStringSchema, name: NonEmptyStringSchema }).passthrough(),
+  products: z2.array(ProductSchema).min(1),
+  properties: z2.array(LegacyPropertySchema).length(4),
+  builder: z2.object({ id: NonEmptyStringSchema, name: NonEmptyStringSchema, url: HttpsUrlSchema }).passthrough().optional()
+}).passthrough();
+var EvidenceSchema = z2.discriminatedUnion("type", [
+  z2.object({
+    type: z2.literal("repository-derivation"),
+    repo: RepoSchema,
+    path: NonEmptyStringSchema,
+    summary: NonEmptyStringSchema
+  }).passthrough(),
+  z2.object({ type: z2.literal("endpoint"), url: HttpsUrlSchema, summary: NonEmptyStringSchema }).passthrough()
+]);
+var ClaimSchema = z2.object({
+  id: NonEmptyStringSchema,
+  value: z2.number().finite().nonnegative(),
+  noun: NonEmptyStringSchema,
+  conservativeFloor: z2.number().int().nonnegative().optional(),
+  evidence: EvidenceSchema
+}).passthrough();
+var ClaimProductSchema = z2.object({
+  productId: SlugSchema,
+  source: z2.discriminatedUnion("type", [
+    z2.object({ type: z2.literal("endpoint"), url: HttpsUrlSchema }).passthrough(),
+    z2.object({ type: z2.literal("repository"), repo: RepoSchema }).passthrough()
+  ]),
+  verification: z2.enum(["verified", "declared"]),
+  claims: z2.array(ClaimSchema)
+}).passthrough();
+var ClaimsSchema = z2.object({
+  schemaVersion: z2.literal(1),
+  manifestSchemaVersion: z2.literal(2),
+  products: z2.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/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];
@@ -383,7 +875,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"));
@@ -417,9 +909,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) => {
@@ -510,14 +1017,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);
@@ -528,10 +1045,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);
@@ -539,6 +1057,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));
       }
     }
@@ -549,13 +1070,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;
@@ -811,7 +1334,7 @@ var buildLookup = (config, packages, corpus, indexOutFile, humanDocs = {}, root
 };
 
 // src/version.ts
-var PACKAGE_VERSION = "1.0.0";
+var PACKAGE_VERSION = "1.1.1";
 
 // src/index-builder/capabilities.ts
 var renderCapabilitiesJson = (config, index, paths) => {
@@ -879,14 +1402,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];
@@ -917,10 +1442,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),
@@ -958,41 +1489,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) => {
@@ -1008,7 +1529,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,
@@ -1019,13 +1541,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;
@@ -1040,7 +1562,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] ?? "");
@@ -1053,7 +1575,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, {
@@ -1089,15 +1611,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;
@@ -1110,26 +1640,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 {
@@ -1161,10 +1691,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;
   }
@@ -1173,9 +1703,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 [];
@@ -1196,7 +1726,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 {
   }
@@ -1204,7 +1734,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;
@@ -1215,7 +1745,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";
@@ -1250,7 +1780,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,
@@ -1262,7 +1792,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(
@@ -1283,9 +1813,366 @@ var buildDocBridgeIndex = (opts) => {
   };
 };
 
+// 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/federation/llms.ts
-import { existsSync as existsSync7, readFileSync as readFileSync9 } from "fs";
-import { resolve as resolve3 } from "path";
+import { existsSync as existsSync9, readFileSync as readFileSync8 } from "fs";
+import { resolve as resolve6 } from "path";
 
 // src/query/search.ts
 var tokenize = (value) => value.toLowerCase().split(/[^a-z0-9@/_-]+/).filter((t) => t.length >= 2);
@@ -1414,9 +2301,9 @@ var defaultFetchText = async (url) => {
 var sourceText = async (root, source, fetchText) => {
   try {
     if (/^https?:\/\//.test(source)) return await fetchText(source);
-    const path = resolve3(root, source);
-    if (!existsSync7(path)) return null;
-    return readFileSync9(path, "utf8");
+    const path = resolve6(root, source);
+    if (!existsSync9(path)) return null;
+    return readFileSync8(path, "utf8");
   } catch {
     return null;
   }
@@ -1501,16 +2388,16 @@ var retrieveHybridChunks = async (root, config, index, query, options = {}) => {
 };
 
 // src/gates/run-gates.ts
-import { readFileSync as readFileSync11 } from "fs";
+import { readFileSync as readFileSync10 } from "fs";
 
 // src/query/load-index.ts
-import { existsSync as existsSync8, readFileSync as readFileSync10 } from "fs";
-import { join as join11, resolve as resolve4 } from "path";
+import { existsSync as existsSync10, readFileSync as readFileSync9 } from "fs";
+import { join as join8, resolve as resolve7 } from "path";
 
 // src/schemas/agent-handoff.ts
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 var HANDOFF_SCHEMA_VERSION = 1;
-var HandoffTargetTypeSchema = z2.enum([
+var HandoffTargetTypeSchema = z3.enum([
   "package",
   "module",
   "app",
@@ -1521,133 +2408,133 @@ var HandoffTargetTypeSchema = z2.enum([
   "change",
   "search"
 ]);
-var HandoffTargetSchema = z2.object({
+var HandoffTargetSchema = z3.object({
   type: HandoffTargetTypeSchema,
-  id: z2.string().min(1).max(256),
-  path: z2.string().min(1).max(512).optional(),
-  group: z2.string().min(1).max(128).optional(),
-  layer: z2.string().min(1).max(32).optional()
+  id: z3.string().min(1).max(256),
+  path: z3.string().min(1).max(512).optional(),
+  group: z3.string().min(1).max(128).optional(),
+  layer: z3.string().min(1).max(32).optional()
 }).strict();
-var HandoffBridgeSchema = z2.object({
-  humanDoc: z2.enum(["linked", "missing", "external"]),
-  action: z2.string().min(1).max(256).optional(),
-  bootstrap: z2.string().min(1).max(256).optional()
+var HandoffBridgeSchema = z3.object({
+  humanDoc: z3.enum(["linked", "missing", "external"]),
+  action: z3.string().min(1).max(256).optional(),
+  bootstrap: z3.string().min(1).max(256).optional()
 }).strict();
-var AgentHandoffV1Schema = z2.object({
-  type: z2.literal("agent-handoff"),
-  schemaVersion: z2.literal(HANDOFF_SCHEMA_VERSION).default(HANDOFF_SCHEMA_VERSION),
-  source: z2.string().min(1).max(512),
+var AgentHandoffV1Schema = z3.object({
+  type: z3.literal("agent-handoff"),
+  schemaVersion: z3.literal(HANDOFF_SCHEMA_VERSION).default(HANDOFF_SCHEMA_VERSION),
+  source: z3.string().min(1).max(512),
   target: HandoffTargetSchema,
-  startHere: z2.string().min(1).max(512),
-  readBeforeEditing: z2.array(z2.string().min(1).max(512)).max(64),
-  editRoots: z2.array(z2.string().min(1).max(512)).max(32),
-  checks: z2.array(z2.string().min(1).max(256)).max(32),
-  humanDoc: z2.string().min(1).max(512).nullable().optional(),
+  startHere: z3.string().min(1).max(512),
+  readBeforeEditing: z3.array(z3.string().min(1).max(512)).max(64),
+  editRoots: z3.array(z3.string().min(1).max(512)).max(32),
+  checks: z3.array(z3.string().min(1).max(256)).max(32),
+  humanDoc: z3.string().min(1).max(512).nullable().optional(),
   bridge: HandoffBridgeSchema.optional(),
-  playbookPatterns: z2.array(z2.string().url()).max(16).optional(),
-  notes: z2.array(z2.string().min(1).max(1024)).max(16)
+  playbookPatterns: z3.array(z3.string().url()).max(16).optional(),
+  notes: z3.array(z3.string().min(1).max(1024)).max(16)
 }).strict();
 var AgentHandoffLegacySchema = AgentHandoffV1Schema.omit({ schemaVersion: true }).extend({
-  schemaVersion: z2.literal(HANDOFF_SCHEMA_VERSION).optional()
+  schemaVersion: z3.literal(HANDOFF_SCHEMA_VERSION).optional()
 });
-var AgentSearchMatchSchema = z2.object({
-  type: z2.string().min(1).max(64),
-  id: z2.string().min(1).max(256),
-  path: z2.string().min(1).max(512),
-  summary: z2.string().max(2048).optional(),
-  score: z2.number().optional(),
-  refs: z2.number().int().nonnegative().optional()
+var AgentSearchMatchSchema = z3.object({
+  type: z3.string().min(1).max(64),
+  id: z3.string().min(1).max(256),
+  path: z3.string().min(1).max(512),
+  summary: z3.string().max(2048).optional(),
+  score: z3.number().optional(),
+  refs: z3.number().int().nonnegative().optional()
 }).strict();
-var AgentSearchV1Schema = z2.object({
-  type: z2.literal("agent-search"),
-  schemaVersion: z2.literal(HANDOFF_SCHEMA_VERSION).default(HANDOFF_SCHEMA_VERSION),
-  source: z2.string().min(1).max(512),
-  term: z2.string().min(1).max(512),
-  count: z2.number().int().nonnegative(),
+var AgentSearchV1Schema = z3.object({
+  type: z3.literal("agent-search"),
+  schemaVersion: z3.literal(HANDOFF_SCHEMA_VERSION).default(HANDOFF_SCHEMA_VERSION),
+  source: z3.string().min(1).max(512),
+  term: z3.string().min(1).max(512),
+  count: z3.number().int().nonnegative(),
   bestMatch: AgentSearchMatchSchema.nullable(),
-  matches: z2.array(AgentSearchMatchSchema).max(32),
-  nextCommands: z2.array(z2.string().min(1).max(512)).max(16)
+  matches: z3.array(AgentSearchMatchSchema).max(32),
+  nextCommands: z3.array(z3.string().min(1).max(512)).max(16)
 }).strict();
 var normalizeAgentHandoff = (input) => AgentHandoffV1Schema.parse(AgentHandoffLegacySchema.parse(input));
 
 // src/schemas/doc-bridge-index.ts
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 var INDEX_SCHEMA_VERSION = 1;
-var ContentHashAlgoSchema = z3.literal("sha256-normalized-v1");
-var EcosystemPropertySchema = z3.object({
-  id: z3.string().min(1).max(64),
-  name: z3.string().min(1).max(128),
-  url: z3.string().url().optional(),
-  llms: z3.string().url().optional()
+var ContentHashAlgoSchema = z4.literal("sha256-normalized-v1");
+var EcosystemPropertySchema = z4.object({
+  id: z4.string().min(1).max(64),
+  name: z4.string().min(1).max(128),
+  url: z4.string().url().optional(),
+  llms: z4.string().url().optional()
 }).strict();
-var KnowledgeEntrySchema = z3.object({
-  id: z3.string().min(1).max(256),
-  type: z3.string().min(1).max(128),
-  title: z3.string().min(1).max(256),
-  path: z3.string().min(1).max(512),
-  description: z3.string().max(2048).optional(),
+var KnowledgeEntrySchema = z4.object({
+  id: z4.string().min(1).max(256),
+  type: z4.string().min(1).max(128),
+  title: z4.string().min(1).max(256),
+  path: z4.string().min(1).max(512),
+  description: z4.string().max(2048).optional(),
   /** Flattened body excerpt for full-text search (not for display). */
-  body: z3.string().max(8e3).optional(),
-  links: z3.array(z3.string().min(1).max(512)).max(64).optional(),
-  tags: z3.array(z3.string().min(1).max(64)).max(32).optional()
+  body: z4.string().max(8e3).optional(),
+  links: z4.array(z4.string().min(1).max(512)).max(64).optional(),
+  tags: z4.array(z4.string().min(1).max(64)).max(32).optional()
 }).strict();
-var CapabilityRefSchema = z3.object({
-  id: z3.string().min(1).max(256),
-  kind: z3.string().min(1).max(64),
-  description: z3.string().max(512).optional()
+var CapabilityRefSchema = z4.object({
+  id: z4.string().min(1).max(256),
+  kind: z4.string().min(1).max(64),
+  description: z4.string().max(512).optional()
 }).strict();
-var OwnershipRecordSchema = z3.object({
-  id: z3.string().min(1).max(256),
-  path: z3.string().min(1).max(512),
-  group: z3.string().min(1).max(128).optional(),
-  layer: z3.string().min(1).max(32).optional(),
-  purpose: z3.string().max(1024).optional(),
-  checks: z3.array(z3.string().min(1).max(256)).max(32),
-  agentDoc: z3.string().min(1).max(512).optional(),
-  humanDoc: z3.string().min(1).max(512).optional(),
-  readme: z3.string().min(1).max(512).optional()
+var OwnershipRecordSchema = z4.object({
+  id: z4.string().min(1).max(256),
+  path: z4.string().min(1).max(512),
+  group: z4.string().min(1).max(128).optional(),
+  layer: z4.string().min(1).max(32).optional(),
+  purpose: z4.string().max(1024).optional(),
+  checks: z4.array(z4.string().min(1).max(256)).max(32),
+  agentDoc: z4.string().min(1).max(512).optional(),
+  humanDoc: z4.string().min(1).max(512).optional(),
+  readme: z4.string().min(1).max(512).optional()
 }).strict();
-var IndexLookupSchema = z3.object({
-  packages: z3.array(z3.string().min(1).max(256)).max(2e3),
-  ownership: z3.record(z3.string().min(1).max(256), OwnershipRecordSchema).optional(),
-  intents: z3.record(
-    z3.string().min(1).max(128),
-    z3.object({
-      id: z3.string().min(1).max(128),
-      title: z3.string().min(1).max(256),
-      paths: z3.array(z3.string().min(1).max(512)).max(32)
+var IndexLookupSchema = z4.object({
+  packages: z4.array(z4.string().min(1).max(256)).max(2e3),
+  ownership: z4.record(z4.string().min(1).max(256), OwnershipRecordSchema).optional(),
+  intents: z4.record(
+    z4.string().min(1).max(128),
+    z4.object({
+      id: z4.string().min(1).max(128),
+      title: z4.string().min(1).max(256),
+      paths: z4.array(z4.string().min(1).max(512)).max(32)
     }).strict()
   ).optional(),
-  changes: z3.record(
-    z3.string().min(1).max(128),
-    z3.object({
-      id: z3.string().min(1).max(128),
-      title: z3.string().min(1).max(256),
-      startHere: z3.string().min(1).max(512),
-      relatedPackages: z3.array(z3.string().min(1).max(256)).max(32).optional()
+  changes: z4.record(
+    z4.string().min(1).max(128),
+    z4.object({
+      id: z4.string().min(1).max(128),
+      title: z4.string().min(1).max(256),
+      startHere: z4.string().min(1).max(512),
+      relatedPackages: z4.array(z4.string().min(1).max(256)).max(32).optional()
     }).strict()
   ).optional()
 }).strict();
-var DocBridgeIndexV1Schema = z3.object({
-  schemaVersion: z3.literal(INDEX_SCHEMA_VERSION),
-  contentHash: z3.string().regex(/^[a-f0-9]{64}$/),
+var DocBridgeIndexV1Schema = z4.object({
+  schemaVersion: z4.literal(INDEX_SCHEMA_VERSION),
+  contentHash: z4.string().regex(/^[a-f0-9]{64}$/),
   contentHashAlgo: ContentHashAlgoSchema,
-  generatedAt: z3.string().datetime().optional(),
-  project: z3.object({
-    name: z3.string().min(1).max(128),
-    root: z3.string().min(1).max(512).optional()
+  generatedAt: z4.string().datetime().optional(),
+  project: z4.object({
+    name: z4.string().min(1).max(128),
+    root: z4.string().min(1).max(512).optional()
   }).strict().optional(),
-  properties: z3.array(EcosystemPropertySchema).max(16).optional(),
-  knowledge: z3.array(KnowledgeEntrySchema).max(1e4),
-  capabilities: z3.array(CapabilityRefSchema).max(5e3).optional(),
-  handoffs: z3.record(z3.string().min(1).max(256), AgentHandoffLegacySchema).optional(),
+  properties: z4.array(EcosystemPropertySchema).max(16).optional(),
+  knowledge: z4.array(KnowledgeEntrySchema).max(1e4),
+  capabilities: z4.array(CapabilityRefSchema).max(5e3).optional(),
+  handoffs: z4.record(z4.string().min(1).max(256), AgentHandoffLegacySchema).optional(),
   lookup: IndexLookupSchema.optional()
 }).strict();
 
 // src/schemas/memory-candidate.ts
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 var MEMORY_CANDIDATE_SCHEMA_VERSION = 1;
-var MemorySourceSchema = z4.enum([
+var MemorySourceSchema = z5.enum([
   "cursor",
   "claude",
   "codex",
@@ -1655,24 +2542,24 @@ var MemorySourceSchema = z4.enum([
   "agent-memory",
   "manual"
 ]);
-var MemorySuggestedTypeSchema = z4.enum([
+var MemorySuggestedTypeSchema = z5.enum([
   "user",
   "feedback",
   "project",
   "reference",
   "unknown"
 ]);
-var MemoryCandidateV1Schema = z4.object({
-  schemaVersion: z4.literal(MEMORY_CANDIDATE_SCHEMA_VERSION),
-  id: z4.string().min(1).max(256),
+var MemoryCandidateV1Schema = z5.object({
+  schemaVersion: z5.literal(MEMORY_CANDIDATE_SCHEMA_VERSION),
+  id: z5.string().min(1).max(256),
   source: MemorySourceSchema,
-  rawPath: z4.string().min(1).max(512).optional(),
-  fact: z4.string().min(1).max(8e3),
-  why: z4.string().max(4e3).optional(),
-  howToApply: z4.string().max(4e3).optional(),
+  rawPath: z5.string().min(1).max(512).optional(),
+  fact: z5.string().min(1).max(8e3),
+  why: z5.string().max(4e3).optional(),
+  howToApply: z5.string().max(4e3).optional(),
   suggestedType: MemorySuggestedTypeSchema,
-  confidence: z4.number().min(0).max(1),
-  references: z4.array(z4.string().min(1).max(512)).max(64)
+  confidence: z5.number().min(0).max(1),
+  references: z5.array(z5.string().min(1).max(512)).max(64)
 }).strict();
 
 // src/validate.ts
@@ -1718,17 +2605,28 @@ 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 (!existsSync8(path)) throw new IndexNotFoundError(path);
-  const raw = JSON.parse(readFileSync10(path, "utf8"));
+  if (!existsSync10(path)) throw new IndexNotFoundError(path);
+  const raw = JSON.parse(readFileSync9(path, "utf8"));
   return parseDocBridgeIndex(raw);
 };
 
 // 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);
@@ -1786,7 +2684,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(readFileSync11(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",
@@ -1860,7 +2758,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(readFileSync11(doc.absPath, "utf8"), required)
+    missing: missingStyleRules(readFileSync10(doc.absPath, "utf8"), required)
   })).filter((doc) => doc.missing.length > 0);
   if (bad.length) {
     return {
@@ -1890,10 +2788,16 @@ 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];
 };
@@ -2009,7 +2913,7 @@ var runQuery = (index, config, req) => {
 };
 
 // src/intelligence/adapter.ts
-import { join as join12 } from "path";
+import { join as join9 } from "path";
 
 // src/intelligence/peers.ts
 var PeerMissingError = class extends Error {
@@ -2136,20 +3040,20 @@ var resolveIntelligenceRuntime = async (config) => {
   }
   return { adapter, embed, provider, ...model ? { model } : {} };
 };
-var defaultVectorStorePath = (root) => join12(root, ".doc-bridge", "vectors");
+var defaultVectorStorePath = (root) => join9(root, ".doc-bridge", "vectors");
 
 // src/intelligence/rag.ts
-import { readFileSync as readFileSync12 } from "fs";
-import { join as join13 } from "path";
+import { readFileSync as readFileSync11 } from "fs";
+import { join as join10 } from "path";
 var loadDocuments = (root, index, sources) => {
   const includeAgent = sources.includes("agent") || sources.length === 0;
   const docs = [];
   if (includeAgent) {
     for (const entry of index.knowledge) {
-      const abs = join13(root, entry.path);
+      const abs = join10(root, entry.path);
       let content = "";
       try {
-        content = readFileSync12(abs, "utf8");
+        content = readFileSync11(abs, "utf8");
       } catch {
         content = [entry.title, entry.description].filter(Boolean).join("\n\n");
       }
@@ -2167,7 +3071,7 @@ var createDocBridgeRag = async (root, config, index) => {
   const { embed } = await resolveIntelligenceRuntime(config);
   const ragMod = await importPeer("@agentskit/rag");
   const memoryMod = await importPeer("@agentskit/memory");
-  const storePath = typeof config.intelligence?.retriever?.options?.storePath === "string" ? join13(root, config.intelligence.retriever.options.storePath) : defaultVectorStorePath(root);
+  const storePath = typeof config.intelligence?.retriever?.options?.storePath === "string" ? join10(root, config.intelligence.retriever.options.storePath) : defaultVectorStorePath(root);
   const store = memoryMod.fileVectorMemory({ path: storePath });
   const rag = ragMod.createRAG({
     embed,
@@ -2302,15 +3206,15 @@ var startInkChat = async (root, config, index) => {
 };
 
 // src/memory/ingest.ts
-import { existsSync as existsSync9, readFileSync as readFileSync13 } from "fs";
-import { join as join14 } from "path";
+import { existsSync as existsSync11, readFileSync as readFileSync12 } from "fs";
+import { join as join11 } 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 (!existsSync9(dir)) return [];
+  if (!existsSync11(dir)) return [];
   return walkFiles(dir, { extensions: [".md", ".mdc"] }).map((abs) => {
     const rel = relativePath(root, abs);
-    const raw = readFileSync13(abs, "utf8");
+    const raw = readFileSync12(abs, "utf8");
     const id = slugFromPath(rel);
     return {
       schemaVersion: 1,
@@ -2325,10 +3229,10 @@ var ingestMarkdownDir = (root, dir, source, confidence) => {
   });
 };
 var ingestCursorRules = (root) => {
-  const dir = join14(root, ".cursor", "rules");
+  const dir = join11(root, ".cursor", "rules");
   return ingestMarkdownDir(root, dir, "cursor", 0.6);
 };
-var ingestAgentMemory = (root) => ingestMarkdownDir(root, join14(root, ".agent-memory"), "agent-memory", 0.7);
+var ingestAgentMemory = (root) => ingestMarkdownDir(root, join11(root, ".agent-memory"), "agent-memory", 0.7);
 var ingestMemoryCandidates = (root) => [
   ...ingestAgentMemory(root),
   ...ingestCursorRules(root)
@@ -2415,8 +3319,8 @@ var draftMemoryPromotion = (classifications) => {
 
 // src/memory/github-pr.ts
 import { execFileSync, spawnSync } from "child_process";
-import { existsSync as existsSync10, mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "fs";
-import { join as join15 } from "path";
+import { existsSync as existsSync12, mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } 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();
@@ -2424,10 +3328,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);
-  mkdirSync2(join15(root, ".doc-bridge", "drafts"), { recursive: true });
+  mkdirSync2(join12(root, ".doc-bridge", "drafts"), { recursive: true });
   writeFileSync2(draftPath, `${draft.body}
 `, "utf8");
   return draftPath;
@@ -2463,7 +3367,7 @@ var promoteMemoryToGithubPr = (root, draft, options = {}) => {
       message: `Wrote draft to ${relDraft}. Run the printed git/gh commands to open a draft PR.`
     };
   }
-  if (!existsSync10(join15(root, ".git"))) {
+  if (!existsSync12(join12(root, ".git"))) {
     return {
       ok: false,
       dryRun: false,
@@ -2566,22 +3470,22 @@ ${auth.out}`
 };
 
 // src/index-builder/watch-index.ts
-import { existsSync as existsSync11, watch } from "fs";
-import { dirname as dirname4, resolve as resolve5 } from "path";
+import { existsSync as existsSync13, watch } from "fs";
+import { dirname as dirname4, resolve as resolve8 } from "path";
 var WATCH_PATTERN = /\.(md|mdx|json|ya?ml|mdc)$/i;
 var collectWatchRoots = (root, config, configPath) => {
   const roots = /* @__PURE__ */ new Set();
-  roots.add(resolve5(root, config.corpus.agent.root));
+  roots.add(resolve8(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(resolve5(root, value));
+      if (typeof value === "string" && value.length) roots.add(resolve8(root, value));
     }
   }
-  if (configPath) roots.add(dirname4(resolve5(configPath)));
-  return [...roots].filter((dir) => existsSync11(dir));
+  if (configPath) roots.add(dirname4(resolve8(configPath)));
+  return [...roots].filter((dir) => existsSync13(dir));
 };
 var watchDocBridgeIndex = (opts) => {
   const debounceMs = opts.debounceMs ?? 350;
@@ -2622,8 +3526,8 @@ var watchDocBridgeIndex = (opts) => {
       rebuild();
     });
   }
-  const configDir = resolve5(opts.root);
-  if (existsSync11(configDir)) {
+  const configDir = resolve8(opts.root);
+  if (existsSync13(configDir)) {
     watch(configDir, (_event, filename) => {
       if (!filename || !/doc-bridge\.config/.test(filename)) return;
       rebuild();
@@ -2799,15 +3703,15 @@ var docBridgePatternPayload = () => ({
 });
 
 // src/cli/demo.ts
-import { cpSync, existsSync as existsSync13, mkdtempSync, readFileSync as readFileSync15, rmSync } from "fs";
+import { cpSync, existsSync as existsSync15, mkdtempSync, readFileSync as readFileSync14, rmSync } from "fs";
 import { tmpdir } from "os";
-import { dirname as dirname6, join as join18, resolve as resolve7 } from "path";
+import { dirname as dirname6, join as join15, resolve as resolve10 } from "path";
 import { fileURLToPath } from "url";
 
 // src/mcp/install.ts
-import { existsSync as existsSync12, mkdirSync as mkdirSync3, readFileSync as readFileSync14, writeFileSync as writeFileSync3 } from "fs";
+import { existsSync as existsSync14, mkdirSync as mkdirSync3, readFileSync as readFileSync13, writeFileSync as writeFileSync3 } from "fs";
 import { homedir } from "os";
-import { dirname as dirname5, join as join17, resolve as resolve6 } from "path";
+import { dirname as dirname5, join as join14, resolve as resolve9 } from "path";
 var SERVER_NAME = "ak-docs";
 var mcpServerEntry = (root) => ({
   command: "npx",
@@ -2815,9 +3719,9 @@ var mcpServerEntry = (root) => ({
   cwd: root
 });
 var readJson = (path) => {
-  if (!existsSync12(path)) return {};
+  if (!existsSync14(path)) return {};
   try {
-    const parsed = JSON.parse(readFileSync14(path, "utf8"));
+    const parsed = JSON.parse(readFileSync13(path, "utf8"));
     return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
   } catch {
     return {};
@@ -2829,12 +3733,12 @@ var writeJson = (path, value) => {
 `, "utf8");
 };
 var resolveTargetPath = (target, root) => {
-  if (target === "cursor") return resolve6(root, ".cursor", "mcp.json");
-  return join17(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+  if (target === "cursor") return resolve9(root, ".cursor", "mcp.json");
+  return join14(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
 };
 var installMcpConfig = (root, target) => {
   const configPath = resolveTargetPath(target, root);
-  const created = !existsSync12(configPath);
+  const created = !existsSync14(configPath);
   const existing = readJson(configPath);
   const servers = existing.mcpServers && typeof existing.mcpServers === "object" && !Array.isArray(existing.mcpServers) ? { ...existing.mcpServers } : {};
   servers[SERVER_NAME] = mcpServerEntry(root);
@@ -2859,12 +3763,12 @@ var installMcpConfig = (root, target) => {
 var mcpSnippet = (root) => JSON.stringify({ mcpServers: { [SERVER_NAME]: mcpServerEntry(root) } }, null, 2);
 
 // src/cli/demo.ts
-var packageRoot = resolve7(dirname6(fileURLToPath(import.meta.url)), "..", "..");
+var packageRoot = resolve10(dirname6(fileURLToPath(import.meta.url)), "..", "..");
 var fixturePath = (fixture) => {
   if (fixture === "monorepo") {
-    return join18(packageRoot, "examples", "demo-monorepo");
+    return join15(packageRoot, "examples", "demo-monorepo");
   }
-  return join18(packageRoot, "examples", "demo-example");
+  return join15(packageRoot, "examples", "demo-example");
 };
 var formatHandoffText = (handoff) => {
   const bridge = handoff.bridge?.humanDoc === "missing" ? `human guide: missing \u2192 ${handoff.bridge.action ?? "ak-docs bootstrap agent-docs"}` : handoff.humanDoc ? `human guide: ${handoff.humanDoc}` : "human guide: (none)";
@@ -2880,11 +3784,11 @@ var formatHandoffText = (handoff) => {
 var runDemo = (root, config, fixture = "example", options = {}) => {
   const targetPackage = fixture === "monorepo" ? "auth" : "example";
   const fixtureDir = fixturePath(fixture);
-  if (options.copyFixture && existsSync13(fixtureDir)) {
+  if (options.copyFixture && existsSync15(fixtureDir)) {
     for (const rel of ["doc-bridge.config.json", "docs", "packages", "pnpm-workspace.yaml", "package.json"]) {
-      const src = join18(fixtureDir, rel);
-      if (!existsSync13(src)) continue;
-      const dest = join18(root, rel);
+      const src = join15(fixtureDir, rel);
+      if (!existsSync15(src)) continue;
+      const dest = join15(root, rel);
       cpSync(src, dest, { recursive: true });
     }
   }
@@ -2939,14 +3843,14 @@ var formatDemoText = (result) => {
   return lines;
 };
 var withDemoWorkspace = (fixture, fn) => {
-  const dir = mkdtempSync(join18(tmpdir(), "ak-docs-demo-"));
+  const dir = mkdtempSync(join15(tmpdir(), "ak-docs-demo-"));
   try {
     const fixtureDir = fixturePath(fixture);
-    if (!existsSync13(fixtureDir)) {
+    if (!existsSync15(fixtureDir)) {
       throw new Error(`Demo fixture "${fixture}" not found at ${fixtureDir}`);
     }
     cpSync(fixtureDir, dir, { recursive: true });
-    const config = JSON.parse(readFileSync15(join18(dir, "doc-bridge.config.json"), "utf8"));
+    const config = JSON.parse(readFileSync14(join15(dir, "doc-bridge.config.json"), "utf8"));
     return fn(dir, config);
   } finally {
     rmSync(dir, { recursive: true, force: true });
@@ -3157,9 +4061,9 @@ var formatDoctorText = (report) => {
 };
 
 // src/mcp/server.ts
-import { readFileSync as readFileSync16, realpathSync } from "fs";
-import { relative, resolve as resolve8 } from "path";
-import { z as z5, ZodError } from "zod";
+import { readFileSync as readFileSync15, realpathSync as realpathSync6 } from "fs";
+import { relative as relative4, resolve as resolve11 } from "path";
+import { z as z6, ZodError } from "zod";
 var MCP_TOOLS = [
   {
     name: "handoff.resolve",
@@ -3218,21 +4122,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 {
@@ -3264,12 +4168,12 @@ var findDocPath = (index, args) => {
   return doc.path;
 };
 var resolveDocPath = (root, relPath) => {
-  const rootAbs = realpathSync.native(root);
-  const unresolved = resolve8(rootAbs, relPath);
-  const unresolvedRel = relative(rootAbs, unresolved);
+  const rootAbs = realpathSync6.native(root);
+  const unresolved = resolve11(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;
 };
@@ -3303,7 +4207,7 @@ var handleMcpRequest = (ctx, request) => {
     }
     if (name === "doc.get") {
       const relPath = findDocPath(index(), parseToolArgs("doc.get", DocGetArgsSchema, args));
-      return textResult(readFileSync16(resolveDocPath(ctx.root, relPath), "utf8"));
+      return textResult(readFileSync15(resolveDocPath(ctx.root, relPath), "utf8"));
     }
     if (name === "gate.status") return textResult(runGates(ctx.root, ctx.config));
     if (name === "retriever.query") {
@@ -3388,11 +4292,12 @@ Core (no API key):
   ak-docs demo [--fixture example|monorepo] [--text] [--in-project]
   ak-docs doctor [--text] [--badge] [--write-badge]
   ak-docs index [--watch]
-  ak-docs query <package|ownership|intent|change> <id> [--agent] [--text]
+  ak-docs query [package|ownership|intent|change] <id> [--agent] [--text]
   ak-docs search <term> [--agent] [--text]
   ak-docs list <packages|intents|changes|knowledge> [--text]
   ak-docs ask [question]          local consult (no LLM)
   ak-docs gate run [gate-id]
+  ak-docs conformance run documentation-standard-v1 [--text|--json]
   ak-docs mcp
   ak-docs mcp install --cursor | --claude
   ak-docs memory ingest|classify|promote [--pr] [--dry-run]
@@ -3416,7 +4321,13 @@ Global flags:
 `;
 var QUERY_KINDS = /* @__PURE__ */ new Set(["package", "ownership", "intent", "change", "search"]);
 var LIST_KINDS = /* @__PURE__ */ new Set(["packages", "intents", "changes", "knowledge"]);
-var GATE_IDS = /* @__PURE__ */ new Set(["index-freshness", "human-guide-links", "okf-type", "docs-style"]);
+var GATE_IDS = /* @__PURE__ */ new Set([
+  "index-freshness",
+  "human-guide-links",
+  "okf-type",
+  "docs-style",
+  "documentation-standard-v1"
+]);
 var parseArgs = (argv) => {
   const flags = /* @__PURE__ */ new Set();
   let configPath;
@@ -3457,6 +4368,7 @@ var parseArgs = (argv) => {
   else if (positional[0] === "chat") command = "chat";
   else if (positional[0] === "rag") command = "rag";
   else if (positional[0] === "list") command = "list";
+  else if (positional[0] === "conformance") command = "conformance";
   return { command, flags, configPath, positional };
 };
 var writeJson2 = (payload) => {
@@ -3550,12 +4462,12 @@ var readIndexedDoc = (root, config, idOrPath) => {
   const index = loadDocBridgeIndex(root, config);
   const entry = index.knowledge.find((doc) => doc.id === idOrPath || doc.path === idOrPath);
   if (!entry) throw new Error(`Unknown indexed doc "${idOrPath}". Try: search ${idOrPath}`);
-  const abs = resolve9(root, entry.path);
-  const rootAbs = resolve9(root);
+  const abs = resolve12(root, entry.path);
+  const rootAbs = resolve12(root);
   if (abs !== rootAbs && !abs.startsWith(`${rootAbs}/`)) {
     throw new Error(`Indexed doc escapes project root: ${entry.path}`);
   }
-  return readFileSync17(abs, "utf8");
+  return readFileSync16(abs, "utf8");
 };
 var runAskRepl = async (root, config) => {
   const index = loadDocBridgeIndex(root, config);
@@ -3631,7 +4543,7 @@ var diagnosticNextCommands = (config, result) => {
   ];
 };
 var writeIfMissing = (path, contents) => {
-  if (existsSync14(path)) return false;
+  if (existsSync16(path)) return false;
   mkdirSync5(dirname7(path), { recursive: true });
   writeFileSync4(path, contents, "utf8");
   return true;
@@ -3736,7 +4648,7 @@ var scaffoldWorkspaceDocs = (root, config) => {
   const created = [];
   const skipped = [];
   for (const pkg of discoverPnpmPackages(root, config)) {
-    const path = resolve9(root, config.corpus.agent.root, "packages", `${pkg.id}.md`);
+    const path = resolve12(root, config.corpus.agent.root, "packages", `${pkg.id}.md`);
     if (writeIfMissing(path, workspaceDocDraft(pkg.id, pkg.path))) created.push(path);
     else skipped.push(path);
   }
@@ -3746,11 +4658,11 @@ var bootstrapAgentDocs = (root, config) => {
   const created = [];
   const skipped = [];
   for (const doc of scanHumanDocRecords(root, config)) {
-    const raw = readFileSync17(doc.path, "utf8");
+    const raw = readFileSync16(doc.path, "utf8");
     const body = raw.replace(/^---\n[\s\S]*?\n---\n?/, "");
     const title = firstHeading(body) ?? doc.id;
     const description = firstParagraph(body);
-    const draftPath = resolve9(root, config.corpus.agent.root, "human", `${doc.id}.md`);
+    const draftPath = resolve12(root, config.corpus.agent.root, "human", `${doc.id}.md`);
     const draft = [
       "---",
       "type: knowledge",
@@ -3814,8 +4726,8 @@ var runCli = (argv) => {
       return 1;
     }
     try {
-      const abs = resolve9(file);
-      const raw = readFileSync17(abs, "utf8");
+      const abs = resolve12(file);
+      const raw = readFileSync16(abs, "utf8");
       const handoff = parseAgentHandoff(JSON.parse(raw));
       writeJson2({ ok: true, handoff });
       return 0;
@@ -3828,10 +4740,10 @@ var runCli = (argv) => {
   if (command === "init") {
     const root = process.cwd();
     const withDemo = flags.has("--demo") || !flags.has("--no-demo");
-    const configFile = resolve9(root, configPath ?? "doc-bridge.config.json");
-    const docsIndex = resolve9(root, "docs/for-agents/INDEX.md");
-    const exampleDoc = resolve9(root, "docs/for-agents/packages/example.md");
-    const agentsMd = resolve9(root, "AGENTS.md");
+    const configFile = resolve12(root, configPath ?? "doc-bridge.config.json");
+    const docsIndex = resolve12(root, "docs/for-agents/INDEX.md");
+    const exampleDoc = resolve12(root, "docs/for-agents/packages/example.md");
+    const agentsMd = resolve12(root, "AGENTS.md");
     const configWritten = writeIfMissing(configFile, initConfigContents(configFile, withDemo));
     const indexWritten = writeIfMissing(
       docsIndex,
@@ -3839,7 +4751,7 @@ var runCli = (argv) => {
     );
     const exampleWritten = withDemo ? writeIfMissing(exampleDoc, exampleAgentDoc) : false;
     const agentsWritten = writeIfMissing(agentsMd, agentsMdSnippet);
-    if (withDemo) writeIfMissing(resolve9(root, "src/.gitkeep"), "");
+    if (withDemo) writeIfMissing(resolve12(root, "src/.gitkeep"), "");
     const scaffold = flags.has("--scaffold-workspaces") ? scaffoldWorkspaceDocs(root, loadProject(configFile).config) : void 0;
     writeJson2({
       ok: true,
@@ -3997,12 +4909,12 @@ var runCli = (argv) => {
     const action = positional[1];
     const gateId = positional[2];
     if (action !== "run") {
-      process.stderr.write("Usage: ak-docs gate run [index-freshness]\n");
+      process.stderr.write("Usage: ak-docs gate run [gate-id]\n");
       return 1;
     }
     if (gateId && !GATE_IDS.has(gateId)) {
       process.stderr.write(
-        `Unsupported gate "${gateId}". Supported gates: index-freshness, human-guide-links, okf-type, docs-style
+        `Unsupported gate "${gateId}". Supported gates: ${[...GATE_IDS].join(", ")}
 `
       );
       return 1;
@@ -4014,6 +4926,26 @@ var runCli = (argv) => {
       return result.ok ? 0 : 1;
     } catch (error) {
       process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+      return 1;
+    }
+  }
+  if (command === "conformance") {
+    const action = positional[1];
+    const profile = positional[2];
+    if (action !== "run" || profile !== DOCUMENTATION_STANDARD_V1_ID) {
+      process.stderr.write(`Usage: ak-docs conformance run ${DOCUMENTATION_STANDARD_V1_ID} [--text|--json]
+`);
+      return 1;
+    }
+    try {
+      const { config, root } = loadProject(configPath);
+      const report = runDocumentationStandardV1(root, config);
+      if (wantsTextOutput(flags, config)) writeLines(formatDocumentationStandardText(report));
+      else writeJson2(report);
+      return report.ok ? 0 : 1;
+    } catch (error) {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}
 `);
       return 1;
     }
@@ -4062,7 +4994,7 @@ var runCli = (argv) => {
       const { config, root } = loadProject(configPath);
       const report = runDoctor(root, config);
       if (flags.has("--write-badge")) {
-        const badgePath = resolve9(root, ".doc-bridge", "coverage-badge.json");
+        const badgePath = resolve12(root, ".doc-bridge", "coverage-badge.json");
         mkdirSync5(dirname7(badgePath), { recursive: true });
         writeFileSync4(badgePath, `${formatDoctorBadgeJson(report.badge)}
 `, "utf8");
@@ -4116,15 +5048,15 @@ var runCli = (argv) => {
     }
   }
   if (command === "query") {
-    const kind = positional[1];
-    const id = positional[2];
-    if (!kind || !QUERY_KINDS.has(kind) || kind === "search") {
-      process.stderr.write("Usage: ak-docs query <package|ownership|intent|change> <id> [--agent]\n");
+    const maybeKind = positional[1];
+    if (maybeKind === "search") {
+      process.stderr.write("Usage: ak-docs query [package|ownership|intent|change] <id> [--agent]\n");
       return 1;
     }
+    const kind = maybeKind && QUERY_KINDS.has(maybeKind) ? maybeKind : "package";
+    const id = kind === maybeKind ? positional[2] : positional[1];
     if (!id) {
-      process.stderr.write(`Missing id for query kind "${kind}".
-`);
+      process.stderr.write("Usage: ak-docs query [package|ownership|intent|change] <id> [--agent]\n");
       return 1;
     }
     try {