@agentskit/doc-bridge 1.4.1 → 1.5.0

package/dist/cli/program.js

@@ -1,6 +1,6 @@
 // src/cli/program.ts
-import { existsSync as existsSync17, mkdirSync as mkdirSync5, readFileSync as readFileSync17, writeFileSync as writeFileSync4 } from "fs";
-import { dirname as dirname8, resolve as resolve13 } from "path";
+import { existsSync as existsSync21, mkdirSync as mkdirSync8, readFileSync as readFileSync21, writeFileSync as writeFileSync8 } from "fs";
+import { dirname as dirname10, resolve as resolve18 } from "path";
 import { createInterface } from "readline/promises";
 
 // src/config/load-config.ts
@@ -302,6 +302,14 @@ var applyConfigDefaults = (config) => {
       preset: "minimal",
       ...config.gates
     },
+    rules: {
+      mode: "default",
+      ...config.rules
+    },
+    safety: {
+      redactSecrets: true,
+      ...config.safety
+    },
     surfaces: {
       cli: {
         bin: "ak-docs",
@@ -310,7 +318,22 @@ var applyConfigDefaults = (config) => {
       },
       mcp: {
         enabled: true,
-        tools: ["handoff.resolve", "doc.search", "doc.get", "gate.status"],
+        tools: [
+          "handoff.resolve",
+          "doc.search",
+          "doc.get",
+          "gate.status",
+          "retriever.query",
+          "memory.classify",
+          "memory.promoteDraft",
+          "registry.topology",
+          "docbridge.snapshot",
+          "docbridge.report",
+          "docbridge.diagnostics",
+          "docbridge.relations",
+          "docbridge.run",
+          "docbridge.proposals"
+        ],
         transport: "stdio",
         ...config.surfaces?.mcp
       },
@@ -356,7 +379,9 @@ var IndexConfigSchema = z.object({
   llmsTxt: z.object({
     enabled: z.boolean().optional(),
     outFile: z.string().min(1).max(512).optional(),
-    preamble: z.string().max(4e3).optional()
+    preamble: z.string().max(4e3).optional(),
+    urlPrefix: z.string().url().optional(),
+    pathPrefix: z.string().min(1).max(512).optional()
   }).strict().optional(),
   capabilities: z.object({
     enabled: z.boolean().optional(),
@@ -426,6 +451,39 @@ var GatesConfigSchema = z.object({
   ).max(16).optional(),
   options: z.record(z.string(), z.unknown()).optional()
 }).strict();
+var RuleIdSchema = z.enum([
+  "documentation-quality",
+  "graph-undocumented-relation",
+  "declared-unobserved-relation",
+  "unresolved-reference",
+  "conflicting-declaration",
+  "not-analyzed-coverage",
+  "stale-documentation",
+  "centrality-risk",
+  "critical-path-risk",
+  "freshness",
+  "ownership"
+]);
+var RuleSeveritySchema = z.enum(["off", "info", "warn", "error"]);
+var RulesConfigSchema = z.object({
+  mode: z.enum(["default", "recommended", "strict"]).optional(),
+  severity: z.record(RuleIdSchema, RuleSeveritySchema).optional(),
+  ignore: z.array(RuleIdSchema).max(128).optional(),
+  criticalEntities: z.array(z.string().min(1).max(256)).max(128).optional(),
+  criticalPaths: z.array(z.string().min(1).max(512)).max(128).optional(),
+  warningThresholds: z.record(RuleIdSchema, z.number().int().min(1).max(1e5)).optional()
+}).strict();
+var WorkflowConfigSchema = z.object({
+  stateDir: z.string().min(1).max(512).optional()
+}).strict();
+var RepositorySafetyConfigSchema = z.object({
+  exclude: z.array(z.string().min(1).max(512)).max(128).optional(),
+  maxFiles: z.number().int().positive().max(1e6).optional(),
+  maxBytes: z.number().int().positive().max(1e10).optional(),
+  maxTimeMs: z.number().int().positive().max(864e5).optional(),
+  maxMemoryMb: z.number().int().positive().max(1048576).optional(),
+  redactSecrets: z.boolean().optional()
+}).strict();
 var SurfacesConfigSchema = z.object({
   cli: z.object({
     bin: z.string().min(1).max(64).optional(),
@@ -443,7 +501,13 @@ var SurfacesConfigSchema = z.object({
         "retriever.query",
         "memory.classify",
         "memory.promoteDraft",
-        "registry.topology"
+        "registry.topology",
+        "docbridge.snapshot",
+        "docbridge.report",
+        "docbridge.diagnostics",
+        "docbridge.relations",
+        "docbridge.run",
+        "docbridge.proposals"
       ])
     ).max(16).optional(),
     transport: z.enum(["stdio", "http"]).optional(),
@@ -486,7 +550,13 @@ var IntelligenceConfigSchema = z.object({
     }).strict().optional()
   }).strict().optional(),
   runtime: z.enum(["agentskit", "custom"]).optional(),
-  runtimeModule: z.string().min(1).max(512).optional()
+  runtimeModule: z.string().min(1).max(512).optional(),
+  registry: z.object({
+    enabled: z.boolean().optional(),
+    agentId: z.string().min(1).max(256).optional(),
+    agentRoot: z.string().min(1).max(512).optional(),
+    runnerModule: z.string().min(1).max(512).optional()
+  }).strict().optional()
 }).strict();
 var FederationConfigSchema = z.object({
   enabled: z.boolean().optional(),
@@ -576,6 +646,9 @@ var DocBridgeConfigV1Schema = z.object({
   index: IndexConfigSchema.optional(),
   routing: RoutingConfigSchema.optional(),
   gates: GatesConfigSchema.optional(),
+  rules: RulesConfigSchema.optional(),
+  workflow: WorkflowConfigSchema.optional(),
+  safety: RepositorySafetyConfigSchema.optional(),
   surfaces: SurfacesConfigSchema.optional(),
   intelligence: IntelligenceConfigSchema.optional(),
   federation: FederationConfigSchema.optional(),
@@ -692,7 +765,7 @@ var ProductSchema = z2.object({
   role: NonEmptyStringSchema,
   promise: NonEmptyStringSchema,
   maturity: z2.enum(["planning", "alpha", "beta", "stable", "deprecated"]),
-  repo: RepoSchema,
+  repo: RepoSchema.nullable(),
   accent: z2.string().regex(/^#[0-9A-Fa-f]{6}$/),
   surfaces: SurfaceSchema,
   navigation: z2.object({
@@ -707,7 +780,7 @@ var LegacyPropertySchema = z2.object({
   barLabel: NonEmptyStringSchema,
   domain: NonEmptyStringSchema,
   url: HttpsUrlSchema,
-  repo: RepoSchema,
+  repo: RepoSchema.nullable(),
   tagline: NonEmptyStringSchema,
   kind: NonEmptyStringSchema,
   accent: z2.string().regex(/^#[0-9A-Fa-f]{6}$/),
@@ -744,7 +817,8 @@ 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()
+    z2.object({ type: z2.literal("repository"), repo: RepoSchema }).passthrough(),
+    z2.object({ type: z2.literal("declaration"), summary: NonEmptyStringSchema }).passthrough()
   ]),
   verification: z2.enum(["verified", "declared"]),
   claims: z2.array(ClaimSchema)
@@ -821,8 +895,10 @@ var parseCanonicalEcosystemContract = (manifestInput, claimsInput) => {
     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) {
+    } else if (claimProduct.source.type === "repository" && claimProduct.source.repo !== product.repo) {
       throw new Error(`Claims source for ${productId} must match repo.`);
+    } else if (claimProduct.source.type === "declaration" && product.repo !== null) {
+      throw new Error(`Declaration source for ${productId} requires a null repo.`);
     }
     if (claimProduct.verification === "declared" && claimProduct.claims.length > 0) {
       throw new Error(`Declared product ${productId} cannot publish claims.`);
@@ -924,6 +1000,9 @@ var defaultChecksForTarget = (root, opts) => {
   return opts.strict ? ["npm test", "npm run lint"] : ["npm test"];
 };
 
+// src/index-builder/scan-corpus.ts
+import { minimatch } from "minimatch";
+
 // src/lib/bounded-text.ts
 import { readFileSync as readFileSync3, statSync } from "fs";
 var MAX_DOCUMENT_BYTES = 4 * 1024 * 1024;
@@ -1084,10 +1163,20 @@ var walkFiles = (root, opts) => {
 };
 
 // src/index-builder/scan-corpus.ts
+var configuredPathMatches = (relPath, include, exclude) => {
+  const normalize = (pattern) => toPosix(pattern).replace(/^\.\//, "");
+  const included = include?.filter(Boolean).map(normalize) ?? [];
+  const excluded = exclude?.filter(Boolean).map(normalize) ?? [];
+  if (excluded.some((pattern) => minimatch(relPath, pattern, { dot: true }))) return false;
+  return included.length === 0 || included.some((pattern) => minimatch(relPath, pattern, { dot: true }));
+};
 var scanAgentCorpus = (root, config) => {
   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 files = walkFiles(agentRoot, { extensions: [".md", ".mdx"] }).filter((abs) => {
+    const relToCorpus = toPosix(abs.replace(`${toPosix(agentRoot)}/`, ""));
+    return configuredPathMatches(relToCorpus, config.corpus.agent.include, config.corpus.agent.exclude);
+  });
   const corpusRelRoot = toPosix(config.corpus.agent.root);
   const budget = { used: 0 };
   return files.map((abs) => {
@@ -1350,7 +1439,7 @@ var buildLookup = (config, packages, corpus, indexOutFile, humanDocs = {}, root
 };
 
 // src/version.ts
-var PACKAGE_VERSION = "1.4.1";
+var PACKAGE_VERSION = "1.5.0";
 
 // src/index-builder/capabilities.ts
 var renderCapabilitiesJson = (config, index, paths) => {
@@ -1395,12 +1484,29 @@ var sortValue = (value) => {
   }
   return value;
 };
+var canonicalJsonV1 = (payload) => JSON.stringify(sortValue(payload));
 var sha256NormalizedV1 = (payload) => {
-  const normalized = JSON.stringify(sortValue(payload));
+  const normalized = canonicalJsonV1(payload);
   return createHash("sha256").update(normalized, "utf8").digest("hex");
 };
+var contentHashForArtifactV1 = (artifact2) => {
+  const { contentHash: _contentHash, ...payload } = artifact2;
+  return sha256NormalizedV1(payload);
+};
 
 // src/index-builder/llms-txt.ts
+var routePath = (path, pathPrefix) => {
+  const normalizedPath = path.replaceAll("\\", "/").replace(/\.(?:md|mdx)$/, "");
+  const normalizedPrefix = pathPrefix?.replaceAll("\\", "/").replace(/\/$/, "");
+  const relativePath3 = normalizedPrefix && normalizedPath.startsWith(`${normalizedPrefix}/`) ? normalizedPath.slice(normalizedPrefix.length + 1) : normalizedPath;
+  return relativePath3.replace(/^\/+/, "");
+};
+var knowledgeUrl = (path, options = {}) => {
+  const relativePath3 = routePath(path, options.pathPrefix);
+  if (!options.urlPrefix) return path;
+  const base = options.urlPrefix.endsWith("/") ? options.urlPrefix : `${options.urlPrefix}/`;
+  return new URL(relativePath3, base).toString();
+};
 var renderLlmsTxt = (config, knowledge, projectName2) => {
   const preamble = config.index?.llmsTxt?.preamble ?? `# ${projectName2}
 
@@ -1408,7 +1514,8 @@ var renderLlmsTxt = (config, knowledge, projectName2) => {
 `;
   const lines = knowledge.slice(0, 500).map((entry) => {
     const desc = entry.description ? `: ${entry.description}` : "";
-    return `- [${entry.title}](${entry.path})${desc}`;
+    const url = knowledgeUrl(entry.path, config.index?.llmsTxt);
+    return `- [${entry.title}](${url})${desc}`;
   });
   return `${preamble.trim()}
 
@@ -1640,11 +1747,23 @@ var nextraAdapter = {
 };
 
 // src/index-builder/human-adapters/plain-markdown.ts
+import { minimatch as minimatch2 } from "minimatch";
+var stringPatterns = (value) => Array.isArray(value) ? value.filter((item) => typeof item === "string" && item.length > 0) : [];
+var matchesConfiguredPath = (relPath, options) => {
+  const normalize = (pattern) => pattern.replaceAll("\\", "/").replace(/^\.\//, "");
+  const include = stringPatterns(options?.include).map(normalize);
+  const exclude = stringPatterns(options?.exclude).map(normalize);
+  if (exclude.some((pattern) => minimatch2(relPath, pattern, { dot: true }))) return false;
+  return include.length === 0 || include.some((pattern) => minimatch2(relPath, pattern, { dot: true }));
+};
 var plainMarkdownAdapter = {
   plugin: "plain-markdown",
   scan: ({ root, config }) => {
     const humanRoot = optionString(config.options, ["contentDir", "root", "docsDir"]) ?? "docs";
-    return scanMarkdownDocs(root, humanRoot, { urlPrefix: config.options?.urlPrefix });
+    return scanMarkdownDocs(root, humanRoot, {
+      urlPrefix: config.options?.urlPrefix,
+      includeRelPath: (relPath) => matchesConfiguredPath(relPath, config.options)
+    });
   }
 };
 
@@ -1673,7 +1792,7 @@ var starlightAdapter = {
 };
 
 // src/index-builder/human-adapters/vitepress.ts
-import { minimatch } from "minimatch";
+import { minimatch as minimatch3 } from "minimatch";
 var isVitePressPage = (relPath) => !relPath.split("/").some((part) => part === ".vitepress" || part.startsWith("."));
 var srcExcludePatterns = (value) => {
   if (value === void 0) return [];
@@ -1687,7 +1806,7 @@ var srcExcludePatterns = (value) => {
     return pattern;
   });
 };
-var isExcluded = (relPath, patterns) => patterns.some((pattern) => minimatch(relPath, pattern, { dot: true }));
+var isExcluded = (relPath, patterns) => patterns.some((pattern) => minimatch3(relPath, pattern, { dot: true }));
 var vitepressSlug = (relPath, cleanUrls) => {
   const slug2 = routeSlug(relPath);
   if (cleanUrls || /(?:^|\/)index\.mdx?$/.test(relPath)) return slug2;
@@ -2142,26 +2261,26 @@ var llmsRule = (root, config, options) => {
     if (key !== llmsKey && !rawSources.has(key)) rawSources.set(key, path);
   }
   const paths = [llmsPath, ...rawSources.values()];
-  const evidence = paths.map((path) => fileEvidence(root, path));
+  const evidence2 = 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],
+  const llmsIsFresh = evidence2[0]?.content === expectedLlms;
+  if (evidence2[0]?.exists) {
+    evidence2[0] = {
+      ...evidence2[0],
       evidence: {
-        ...evidence[0].evidence,
+        ...evidence2[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);
+  const passed = config.index?.llmsTxt?.enabled !== false && paths.length > 1 && llmsIsFresh && evidence2.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),
+    evidence: evidence2.map((item) => item.evidence),
     remediation: {
       command: "ak-docs index",
       detail: "Generate llms.txt and configure conformance.documentationStandardV1.rawSources."
@@ -2180,8 +2299,8 @@ var ecosystemContract = (root, options) => {
   }
   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 };
+  const evidence2 = [manifestFile.evidence, claimsFile.evidence];
+  if (!manifestFile.exists || !claimsFile.exists) return { passed: false, urls: /* @__PURE__ */ new Set(), evidence: evidence2 };
   try {
     const manifest = JSON.parse(manifestFile.content);
     const claims = JSON.parse(claimsFile.content);
@@ -2199,15 +2318,15 @@ var ecosystemContract = (root, options) => {
         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 };
+    evidence2[0] = { path: declaration.manifest, detail: `Validated ${productIds.length} canonical product(s), including ${declaration.productId}.` };
+    evidence2[1] = { path: declaration.claims, detail: `Validated claim-ledger identity for ${contract.claims.products.length} product(s).` };
+    return { passed: urls.size > 0, urls, evidence: evidence2 };
   } catch (error) {
-    evidence.push({
+    evidence2.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 };
+    return { passed: false, urls: /* @__PURE__ */ new Set(), evidence: evidence2 };
   }
 };
 var handoffsRule = (root, config) => {
@@ -2233,13 +2352,13 @@ var handoffsRule = (root, config) => {
 };
 var contributionRule = (root, options) => {
   const paths = options.contributionPaths?.length ? options.contributionPaths : ["CONTRIBUTING.md"];
-  const evidence = paths.map((path) => fileEvidence(root, path));
+  const evidence2 = 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),
+    passed: evidence2.some((item) => item.exists),
+    message: evidence2.some((item) => item.exists) ? "Contribution guidance is available." : "Contribution guidance is missing.",
+    evidence: evidence2.map((item) => item.evidence),
     remediation: {
       command: "edit CONTRIBUTING.md",
       detail: "Document setup, validation commands, and the pull-request workflow."
@@ -2248,13 +2367,13 @@ var contributionRule = (root, options) => {
 };
 var markersRule = (root, options, kind, level) => {
   const declarations = options[kind === "metadata" ? "metadata" : "diagrams"] ?? [];
-  const evidence = [];
+  const evidence2 = [];
   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({
+    evidence2.push({
       path: declaration.path,
       detail: !file.exists ? file.evidence.detail : missing.length ? `Missing marker(s): ${missing.join(", ")}` : `Found marker(s): ${declaration.contains.join(", ")}`
     });
@@ -2264,7 +2383,7 @@ var markersRule = (root, options, kind, level) => {
     level,
     passed,
     message: passed ? `${kind} evidence is complete.` : `${kind} evidence is incomplete.`,
-    evidence,
+    evidence: evidence2,
     remediation: {
       command: "edit doc-bridge.config.json",
       detail: `Declare ${kind} evidence paths and markers that exist in the repository.`
@@ -2274,14 +2393,14 @@ var markersRule = (root, options, kind, level) => {
 var linksRule = (root, options) => {
   const links = options.links ?? [];
   const contract = ecosystemContract(root, options);
-  const evidence = [...contract.evidence];
+  const evidence2 = [...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({
+    evidence2.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.`
     });
@@ -2291,7 +2410,7 @@ var linksRule = (root, options) => {
     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,
+    evidence: evidence2,
     remediation: {
       command: "edit README.md",
       detail: "Sync the canonical ecosystem snapshots and add each configured canonical URL to a declared documentation source."
@@ -2300,14 +2419,14 @@ var linksRule = (root, options) => {
 };
 var quickstartsRule = (root, options) => {
   const quickstarts = options.quickstarts ?? [];
-  const evidence = [];
+  const evidence2 = [];
   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(
+    evidence2.push(
       { path: quickstart.doc, detail: `${quickstart.id}: ${doc.evidence.detail}` },
       {
         path: quickstart.test,
@@ -2320,7 +2439,7 @@ var quickstartsRule = (root, options) => {
     level: "required",
     passed,
     message: passed ? `${quickstarts.length} quickstart(s) have executable test evidence.` : "Quickstart test evidence is incomplete.",
-    evidence,
+    evidence: evidence2,
     remediation: {
       command: "pnpm test",
       detail: "Map every quickstart to a documentation path, test file, identifying marker, and CI command."
@@ -2329,13 +2448,13 @@ var quickstartsRule = (root, options) => {
 };
 var visualsRule = (root, options) => {
   const visuals = options.visuals ?? [];
-  const evidence = visuals.map((path) => fileEvidence(root, path, { readContent: false }));
+  const evidence2 = 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),
+    passed: visuals.length > 0 && evidence2.every((item) => item.exists),
+    message: visuals.length > 0 && evidence2.every((item) => item.exists) ? `${visuals.length} visual asset(s) found.` : "Visual explanation evidence is incomplete.",
+    evidence: evidence2.map((item) => item.evidence),
     remediation: {
       command: "edit doc-bridge.config.json",
       detail: "Declare the images or animations that explain the product workflow."
@@ -2384,14 +2503,941 @@ var formatDocumentationStandardText = (report) => [
   "",
   ...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.evidence.map((evidence2) => `  evidence: ${evidence2.path} \u2014 ${evidence2.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
+// src/schemas/knowledge.ts
+import { z as z3 } from "zod";
+var KNOWLEDGE_SCHEMA_VERSION = 1;
+var KNOWLEDGE_CONTENT_HASH_ALGO = "sha256-normalized-v1";
+var hash = z3.string().regex(/^[a-f0-9]{64}$/);
+var boundedString = (max) => z3.string().min(1).max(max);
+var ProvenanceSchema = z3.enum(["observed", "declared", "proposed"]);
+var FindingStatusSchema = z3.enum([
+  "confirmed",
+  "undocumented",
+  "stale-or-unverified",
+  "conflict",
+  "unresolved",
+  "not-analyzed"
+]);
+var DiagnosticSeveritySchema = z3.enum(["off", "info", "warn", "error"]);
+var EvidenceSourceSchema = z3.enum([
+  "code",
+  "configuration",
+  "documentation",
+  "agent",
+  "derived"
+]);
+var EvidenceSchema2 = z3.object({
+  source: EvidenceSourceSchema,
+  path: boundedString(512),
+  lineStart: z3.number().int().positive().optional(),
+  lineEnd: z3.number().int().positive().optional(),
+  contentHash: hash.optional(),
+  context: z3.string().max(1024).optional()
+}).strict().superRefine((value, context) => {
+  if (value.lineStart !== void 0 && value.lineEnd !== void 0 && value.lineEnd < value.lineStart) {
+    context.addIssue({
+      code: z3.ZodIssueCode.custom,
+      path: ["lineEnd"],
+      message: "Must be greater than or equal to lineStart"
+    });
+  }
+});
+var CoverageStatusSchema = z3.enum(["complete", "partial", "not-analyzed"]);
+var CoverageSchema = z3.object({
+  analyzer: boundedString(128),
+  scope: boundedString(512),
+  status: CoverageStatusSchema,
+  reason: z3.string().max(1024).optional(),
+  evidence: z3.array(EvidenceSchema2).max(32).optional()
+}).strict();
+var ProjectIdentitySchema = z3.object({
+  name: boundedString(128),
+  root: boundedString(512).optional()
+}).strict();
+var ArtifactMetadata = {
+  schemaVersion: z3.literal(KNOWLEDGE_SCHEMA_VERSION),
+  contentHash: hash,
+  contentHashAlgo: z3.literal(KNOWLEDGE_CONTENT_HASH_ALGO),
+  project: ProjectIdentitySchema,
+  sourceRevision: boundedString(128),
+  sourceRevisionKind: z3.enum(["git", "content"]),
+  configurationHash: hash,
+  pipelineVersion: boundedString(64),
+  analyzerVersions: z3.record(boundedString(128), boundedString(64))
+};
+var EntitySchema = z3.object({
+  id: boundedString(256),
+  kind: boundedString(128),
+  name: boundedString(256),
+  path: boundedString(512).optional(),
+  aliases: z3.array(boundedString(256)).max(32).optional(),
+  provenance: ProvenanceSchema,
+  evidence: z3.array(EvidenceSchema2).max(64),
+  metadata: z3.record(z3.unknown()).optional()
+}).strict();
+var RelationSchema = z3.object({
+  id: boundedString(256),
+  kind: boundedString(128),
+  from: boundedString(256),
+  to: boundedString(256),
+  discriminator: boundedString(256).optional(),
+  provenance: ProvenanceSchema,
+  evidence: z3.array(EvidenceSchema2).max(64),
+  metadata: z3.record(z3.unknown()).optional()
+}).strict();
+var DiscoverySnapshotV1Schema = z3.object({
+  type: z3.literal("discovery-snapshot"),
+  ...ArtifactMetadata,
+  entities: z3.array(EntitySchema).max(5e4),
+  relations: z3.array(RelationSchema).max(1e5),
+  coverage: z3.array(CoverageSchema).max(1e3)
+}).strict().superRefine((value, context) => {
+  const entityIds = /* @__PURE__ */ new Set();
+  for (const [index, entity] of value.entities.entries()) {
+    if (entityIds.has(entity.id)) {
+      context.addIssue({ code: z3.ZodIssueCode.custom, path: ["entities", index, "id"], message: `Duplicate entity id: ${entity.id}` });
+    }
+    entityIds.add(entity.id);
+  }
+  const relationIds = /* @__PURE__ */ new Set();
+  for (const [index, relation] of value.relations.entries()) {
+    if (relationIds.has(relation.id)) {
+      context.addIssue({ code: z3.ZodIssueCode.custom, path: ["relations", index, "id"], message: `Duplicate relation id: ${relation.id}` });
+    }
+    relationIds.add(relation.id);
+  }
+});
+var DiagnosticSchema = z3.object({
+  id: boundedString(256),
+  code: boundedString(128),
+  status: FindingStatusSchema,
+  severity: DiagnosticSeveritySchema,
+  message: boundedString(2048),
+  evidence: z3.array(EvidenceSchema2).max(64),
+  entityIds: z3.array(boundedString(256)).max(64).optional(),
+  relationIds: z3.array(boundedString(256)).max(64).optional(),
+  remediation: z3.string().max(2048).optional()
+}).strict();
+var ReconciliationReportV1Schema = z3.object({
+  type: z3.literal("reconciliation-report"),
+  ...ArtifactMetadata,
+  snapshotHash: hash,
+  diagnostics: z3.array(DiagnosticSchema).max(1e5),
+  summary: z3.object({
+    entityCount: z3.number().int().nonnegative(),
+    relationCount: z3.number().int().nonnegative(),
+    diagnosticCount: z3.number().int().nonnegative()
+  }).strict()
+}).strict();
+var WorkflowStateSchema = z3.enum([
+  "created",
+  "discovering",
+  "analyzed",
+  "compared",
+  "awaiting-agent",
+  "proposed",
+  "awaiting-approval",
+  "validating",
+  "delivered",
+  "failed",
+  "cancelled",
+  "stale",
+  "superseded"
+]);
+var WorkflowStepSchema = z3.object({
+  name: boundedString(128),
+  status: z3.enum(["pending", "running", "completed", "failed", "skipped"]),
+  inputHash: hash,
+  outputHash: hash.optional(),
+  artifactRefs: z3.array(boundedString(512)).max(32).optional()
+}).strict();
+var WorkflowTransitionSchema = z3.object({
+  from: WorkflowStateSchema.nullable(),
+  to: WorkflowStateSchema,
+  at: z3.string().datetime(),
+  reason: z3.string().max(1024).optional()
+}).strict();
+var WorkflowRunV1Schema = z3.object({
+  type: z3.literal("workflow-run"),
+  ...ArtifactMetadata,
+  runId: boundedString(128),
+  state: WorkflowStateSchema,
+  steps: z3.array(WorkflowStepSchema).max(32),
+  transitions: z3.array(WorkflowTransitionSchema).max(1e3),
+  artifactRefs: z3.array(boundedString(512)).max(128)
+}).strict();
+var ProposalOriginSchema = z3.object({
+  kind: z3.enum(["registry-agent", "manual", "deterministic"]),
+  id: boundedString(256).optional(),
+  version: boundedString(64).optional(),
+  provider: boundedString(128).optional(),
+  model: boundedString(256).optional(),
+  capabilities: z3.array(boundedString(128)).max(32).optional()
+}).strict().superRefine((value, context) => {
+  if (value.kind === "registry-agent" && value.id === void 0) {
+    context.addIssue({ code: z3.ZodIssueCode.custom, path: ["id"], message: "Registry agent origin requires an id" });
+  }
+});
+var AgentProposalV1Schema = z3.object({
+  type: z3.literal("agent-proposal"),
+  ...ArtifactMetadata,
+  proposalId: boundedString(128),
+  baseSnapshotHash: hash,
+  baseReportHash: hash,
+  relatedDiagnosticIds: z3.array(boundedString(256)).max(64),
+  rationale: boundedString(4e3),
+  confidence: z3.number().min(0).max(1),
+  evidence: z3.array(EvidenceSchema2).max(128),
+  intendedChanges: z3.array(boundedString(4e3)).max(64),
+  origin: ProposalOriginSchema,
+  checks: z3.array(boundedString(512)).max(32)
+}).strict();
+var FixProposalStatusSchema = z3.enum(["proposed", "approved", "rejected", "stale", "applied", "failed"]);
+var AffectedFileSchema = z3.object({
+  path: boundedString(512),
+  contentHash: hash
+}).strict();
+var FixChangeSchema = z3.object({
+  path: boundedString(512),
+  before: z3.string().max(1e5),
+  after: z3.string().max(1e5)
+}).strict();
+var FixProposalV1Schema = z3.object({
+  type: z3.literal("fix-proposal"),
+  ...ArtifactMetadata,
+  proposalId: boundedString(128),
+  baseRevision: boundedString(128),
+  affectedFiles: z3.array(AffectedFileSchema).max(256),
+  changes: z3.array(FixChangeSchema).max(256).optional(),
+  preconditions: z3.array(boundedString(2048)).max(64),
+  diff: boundedString(1e5),
+  postconditions: z3.array(boundedString(2048)).max(64),
+  approval: z3.object({
+    proposalHash: hash,
+    approvedAt: z3.string().datetime(),
+    approvedBy: boundedString(256)
+  }).strict().optional(),
+  status: FixProposalStatusSchema
+}).strict().superRefine((value, context) => {
+  if ((value.status === "approved" || value.status === "applied") && value.approval === void 0) {
+    context.addIssue({
+      code: z3.ZodIssueCode.custom,
+      path: ["approval"],
+      message: `Fix proposal status ${value.status} requires an approval record`
+    });
+  }
+});
+
+// src/discovery/documentation.ts
+var detectionValues = /* @__PURE__ */ new Set(["static", "dynamic", "external"]);
+var evidence = (path, lineStart, lineEnd = lineStart) => ({
+  source: "documentation",
+  path,
+  lineStart,
+  lineEnd
+});
+var diagnostic = (path, code, message, lineStart, lineEnd = lineStart) => ({ code, message, path: "docbridge", evidence: evidence(path, lineStart, lineEnd) });
+var scalar = (value) => {
+  const trimmed = value.trim();
+  if (trimmed.startsWith('"') && trimmed.endsWith('"') || trimmed.startsWith("'") && trimmed.endsWith("'")) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+};
+var list = (value) => {
+  const trimmed = value.trim();
+  if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) return void 0;
+  const body = trimmed.slice(1, -1).trim();
+  return body ? body.split(",").map(scalar).filter(Boolean) : [];
+};
+var findFrontmatter = (content) => {
+  const lines = content.replace(/^\uFEFF/, "").split(/\r?\n/);
+  if (lines[0] !== "---") return void 0;
+  const end = lines.findIndex((line, index) => index > 0 && line === "---");
+  return end < 0 ? void 0 : { lines, end };
+};
+var addDiagnostic = (diagnostics, input, code, message, line, endLine = line) => {
+  diagnostics.push(diagnostic(input.path, code, message, line, endLine));
+};
+var resolveEntity = (reference, entities, input, lineStart, unresolved) => {
+  const resolved = entities.find((entity2) => entity2.id === reference || entity2.aliases?.includes(reference));
+  if (resolved) return resolved;
+  const id = `unresolved:${reference}`;
+  const existing = unresolved.get(id);
+  if (existing) return existing;
+  const entity = {
+    id,
+    kind: "unresolved-reference",
+    name: reference,
+    provenance: "declared",
+    evidence: [evidence(input.path, lineStart)]
+  };
+  unresolved.set(id, entity);
+  return entity;
+};
+var relationKey = (from, to, kind) => `${from}\0${to}\0${kind}`;
+var parseBlock = (input) => {
+  const frontmatter = findFrontmatter(input.content);
+  if (!frontmatter) {
+    if (input.content.replace(/^\uFEFF/, "").startsWith("---")) {
+      return {
+        covers: [],
+        relations: [],
+        hasDocbridge: true,
+        diagnostics: [diagnostic(input.path, "DOCBRIDGE_FRONTMATTER_MALFORMED", "Frontmatter must close with a line containing only ---.", 1)]
+      };
+    }
+    return { covers: [], relations: [], diagnostics: [], hasDocbridge: false };
+  }
+  const { lines, end } = frontmatter;
+  const docbridgeLine = lines.findIndex((line, index) => index > 0 && index < end && /^docbridge\s*:/.test(line));
+  if (docbridgeLine < 0) return { covers: [], relations: [], diagnostics: [], hasDocbridge: false };
+  const diagnostics = [];
+  const covers = [];
+  const relations = [];
+  const inline = lines[docbridgeLine]?.slice("docbridge:".length).trim() ?? "";
+  if (inline && inline !== "{}") addDiagnostic(diagnostics, input, "DOCBRIDGE_BLOCK_MALFORMED", "docbridge must be a nested frontmatter object.", docbridgeLine + 1);
+  let section;
+  let current;
+  const finishRelation = () => {
+    if (current) relations.push(current);
+    current = void 0;
+  };
+  for (let index = docbridgeLine + 1; index < end; index += 1) {
+    const raw = lines[index] ?? "";
+    const trimmed = raw.trim();
+    const line = index + 1;
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    if (/\t/.test(raw)) {
+      addDiagnostic(diagnostics, input, "DOCBRIDGE_INDENTATION_INVALID", "docbridge indentation must use spaces.", line);
+      continue;
+    }
+    if (!raw.startsWith(" ")) {
+      finishRelation();
+      section = void 0;
+      continue;
+    }
+    if (/^ {2}[A-Za-z][A-Za-z0-9_-]*\s*:/.test(raw)) {
+      finishRelation();
+      const match = /^ {2}([A-Za-z][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(raw);
+      const key = match?.[1];
+      const value = match?.[2] ?? "";
+      if (key !== "covers" && key !== "relations") {
+        addDiagnostic(diagnostics, input, "DOCBRIDGE_FIELD_UNKNOWN", `Unknown docbridge field: ${key ?? "(missing)"}.`, line);
+        section = void 0;
+      } else if (key === "covers") {
+        section = "covers";
+        if (value) {
+          const values = list(value);
+          if (!values) addDiagnostic(diagnostics, input, "DOCBRIDGE_COVERS_INVALID", "covers must be a list of entity references.", line);
+          else values.forEach((item) => covers.push({ value: item, line }));
+        }
+      } else {
+        section = "relations";
+        if (value) addDiagnostic(diagnostics, input, "DOCBRIDGE_RELATIONS_INVALID", "relations must be a list of relation objects.", line);
+      }
+      continue;
+    }
+    if (section === "covers" && /^ {4}-\s*/.test(raw)) {
+      const value = scalar(raw.replace(/^ {4}-\s*/, ""));
+      if (!value) addDiagnostic(diagnostics, input, "DOCBRIDGE_REFERENCE_MISSING", "covers entries must not be empty.", line);
+      else covers.push({ value, line });
+      continue;
+    }
+    if (section === "relations" && /^ {4}-\s*/.test(raw)) {
+      finishRelation();
+      const firstField = /^ {4}-\s*([A-Za-z][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(raw);
+      current = { startLine: line, endLine: line, fields: /* @__PURE__ */ new Set() };
+      if (firstField?.[1]) {
+        current.fields.add(firstField[1]);
+        current[firstField[1]] = scalar(firstField[2] ?? "");
+      } else if (raw.replace(/^ {4}-\s*/, "").trim()) {
+        addDiagnostic(diagnostics, input, "DOCBRIDGE_RELATION_INVALID", "Relation entries must be field mappings.", line);
+      }
+      continue;
+    }
+    if (section === "relations" && current && /^ {6}[A-Za-z][A-Za-z0-9_-]*\s*:/.test(raw)) {
+      const field = /^ {6}([A-Za-z][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(raw);
+      const key = field?.[1];
+      current.endLine = line;
+      if (!key || !["from", "to", "kind", "detection"].includes(key)) {
+        addDiagnostic(diagnostics, input, "DOCBRIDGE_FIELD_UNKNOWN", `Unknown relation field: ${key ?? "(missing)"}.`, line);
+      } else if (current.fields.has(key)) {
+        addDiagnostic(diagnostics, input, "DOCBRIDGE_FIELD_DUPLICATE", `Duplicate relation field: ${key}.`, line);
+      } else {
+        current.fields.add(key);
+        current[key] = scalar(field?.[2] ?? "");
+      }
+      continue;
+    }
+    addDiagnostic(diagnostics, input, "DOCBRIDGE_STRUCTURE_INVALID", `Invalid docbridge structure at line ${line}.`, line);
+  }
+  finishRelation();
+  return { covers, relations, diagnostics, hasDocbridge: true };
+};
+var parseDocumentationDeclarations = (input, options) => {
+  const parsed = parseBlock(input);
+  if (!parsed.hasDocbridge) return { hasDocbridge: false, entities: [], relations: [], diagnostics: [] };
+  const diagnostics = [...parsed.diagnostics];
+  const unresolved = /* @__PURE__ */ new Map();
+  const relations = [];
+  const documentId = options.documentId ?? `document:${input.path}`;
+  const relationClaims = /* @__PURE__ */ new Map();
+  if (!parsed.covers.length && !parsed.relations.length) {
+    addDiagnostic(diagnostics, input, "DOCBRIDGE_CONTENT_MISSING", "docbridge must declare covers or relations.", 1);
+  }
+  for (const [index, cover] of parsed.covers.entries()) {
+    const target = resolveEntity(cover.value, options.snapshot.entities, input, cover.line, unresolved);
+    relations.push({
+      id: `relation:declared:${input.path}:covers:${index}`,
+      kind: "covers",
+      from: documentId,
+      to: target.id,
+      provenance: "declared",
+      evidence: [evidence(input.path, cover.line)]
+    });
+  }
+  for (const [index, declaration] of parsed.relations.entries()) {
+    const basePath = `relations[${index}]`;
+    const missing = ["from", "to", "kind", "detection"].filter((field) => !declaration[field]);
+    if (missing.length) {
+      addDiagnostic(diagnostics, input, "DOCBRIDGE_RELATION_FIELD_MISSING", `Relation is missing required field(s): ${missing.join(", ")}.`, declaration.startLine, declaration.endLine);
+      continue;
+    }
+    const from = declaration.from;
+    const to = declaration.to;
+    const kind = declaration.kind;
+    const detection = declaration.detection;
+    if (!detectionValues.has(detection)) {
+      addDiagnostic(diagnostics, input, "DOCBRIDGE_DETECTION_INVALID", `Invalid relation detection: ${detection}.`, declaration.startLine, declaration.endLine);
+      continue;
+    }
+    const fromEntity = resolveEntity(from, options.snapshot.entities, input, declaration.startLine, unresolved);
+    const toEntity = resolveEntity(to, options.snapshot.entities, input, declaration.startLine, unresolved);
+    const key = relationKey(fromEntity.id, toEntity.id, kind);
+    const previousDetection = relationClaims.get(key);
+    if (previousDetection === detection) addDiagnostic(diagnostics, input, "DOCBRIDGE_DECLARATION_DUPLICATE", "Duplicate relation declaration.", declaration.startLine, declaration.endLine);
+    if (previousDetection && previousDetection !== detection) addDiagnostic(diagnostics, input, "DOCBRIDGE_DECLARATION_CONFLICT", "Conflicting relation declarations use different detection values.", declaration.startLine, declaration.endLine);
+    relationClaims.set(key, previousDetection ?? detection);
+    relations.push({
+      id: `relation:declared:${input.path}:${basePath}`,
+      kind,
+      from: fromEntity.id,
+      to: toEntity.id,
+      discriminator: detection,
+      provenance: "declared",
+      evidence: [evidence(input.path, declaration.startLine, declaration.endLine)],
+      metadata: { detection }
+    });
+  }
+  return {
+    hasDocbridge: true,
+    entities: [...unresolved.values()].sort((a, b) => a.id.localeCompare(b.id)),
+    relations,
+    diagnostics
+  };
+};
+var applyDocumentationDeclarations = (snapshot, documents) => {
+  const entities = new Map(snapshot.entities.map((entity) => [entity.id, entity]));
+  const relations = new Map(snapshot.relations.map((relation) => [relation.id, relation]));
+  const diagnostics = [];
+  for (const document of documents) {
+    const result = parseDocumentationDeclarations(document, { snapshot });
+    diagnostics.push(...result.diagnostics);
+    for (const entity of result.entities) entities.set(entity.id, entity);
+    for (const relation of result.relations) relations.set(relation.id, relation);
+  }
+  const base = { ...snapshot, contentHash: "0".repeat(64), entities: [...entities.values()], relations: [...relations.values()] };
+  return {
+    snapshot: DiscoverySnapshotV1Schema.parse({ ...base, contentHash: contentHashForArtifactV1(base) }),
+    diagnostics
+  };
+};
+
+// src/discovery/repository.ts
+import { execFileSync } from "child_process";
 import { existsSync as existsSync10, readFileSync as readFileSync9 } from "fs";
-import { resolve as resolve7 } from "path";
+import { basename as basename4, dirname as dirname5, extname, join as join8, relative as relative6, resolve as resolve8, sep as sep7 } from "path";
+import * as ts from "typescript";
+
+// src/safety/repository.ts
+import { lstatSync as lstatSync3, readdirSync as readdirSync3, realpathSync as realpathSync7, statSync as statSync4 } from "fs";
+import { isAbsolute as isAbsolute5, relative as relative5, resolve as resolve7, sep as sep6 } from "path";
+import { minimatch as minimatch4 } from "minimatch";
+var DEFAULT_SAFETY_EXCLUDES = ["**/.git/**", "**/node_modules/**", "**/dist/**", "**/build/**", "**/coverage/**", "**/.doc-bridge/**", "**/.env", "**/.env.*", "**/*secret*", "**/*credential*", "**/*.pem", "**/*.key"];
+var containedPath = (root, candidate) => {
+  const projectRoot = realpathSync7.native(resolve7(root));
+  const unresolved = resolve7(projectRoot, candidate);
+  const unresolvedRelative = relative5(projectRoot, unresolved);
+  if (isAbsolute5(unresolvedRelative) || unresolvedRelative === ".." || unresolvedRelative.startsWith(`..${sep6}`)) return void 0;
+  try {
+    const canonical = realpathSync7.native(unresolved);
+    const canonicalRelative = relative5(projectRoot, canonical);
+    return isAbsolute5(canonicalRelative) || canonicalRelative === ".." || canonicalRelative.startsWith(`..${sep6}`) ? void 0 : canonical;
+  } catch {
+    return unresolved;
+  }
+};
+var safeWalkFiles = (root, options = {}) => {
+  const projectRoot = resolve7(root);
+  const extensions = options.extensions ?? [];
+  const excludes = options.exclude ?? DEFAULT_SAFETY_EXCLUDES;
+  const files = [];
+  let bytes = 0;
+  let reason;
+  const started = Date.now();
+  const matchesExclude = (path) => excludes.some((pattern) => minimatch4(path, pattern, { dot: true }));
+  const visit = (directory) => {
+    if (reason) return;
+    if (options.maxTimeMs !== void 0 && Date.now() - started >= options.maxTimeMs) {
+      reason = `Repository scan exceeded the ${options.maxTimeMs} ms time limit.`;
+      return;
+    }
+    if (options.maxMemoryMb !== void 0 && process.memoryUsage().heapUsed > options.maxMemoryMb * 1024 * 1024) {
+      reason = `Repository scan exceeded the ${options.maxMemoryMb} MiB memory limit.`;
+      return;
+    }
+    let entries;
+    try {
+      entries = readdirSync3(directory);
+    } catch {
+      return;
+    }
+    for (const name of entries.sort()) {
+      const absolute = resolve7(directory, name);
+      const relativePath3 = relative5(projectRoot, absolute).split(sep6).join("/");
+      if (matchesExclude(relativePath3) || name === ".git") continue;
+      let stats;
+      try {
+        stats = lstatSync3(absolute);
+      } catch {
+        continue;
+      }
+      if (stats.isSymbolicLink()) continue;
+      if (stats.isDirectory()) {
+        visit(absolute);
+        if (reason) return;
+        continue;
+      }
+      if (!stats.isFile() || extensions.length > 0 && !extensions.some((extension) => name.endsWith(extension))) continue;
+      if (files.length >= (options.maxFiles ?? 1e4)) {
+        reason = `Repository scan exceeded the ${options.maxFiles ?? 1e4} file limit.`;
+        return;
+      }
+      bytes += statSync4(absolute).size;
+      if (options.maxBytes !== void 0 && bytes > options.maxBytes) {
+        reason = `Repository scan exceeded the ${options.maxBytes} byte limit.`;
+        return;
+      }
+      files.push(absolute);
+    }
+  };
+  visit(projectRoot);
+  return { files: files.sort(), incomplete: reason !== void 0, ...reason ? { reason } : {} };
+};
+var SECRET_PATTERNS = [
+  /\b(?:sk|pk)[_-](?:live|test)[_-][A-Za-z0-9_-]{12,}\b/g,
+  /\b(?:ghp|github_pat|xox[baprs])_[A-Za-z0-9_-]{12,}\b/g,
+  /\bAKIA[0-9A-Z]{16}\b/g,
+  /(?:password|passwd|secret|token|api[_-]?key)\s*[:=]\s*["']?[^\s,"']+/gi
+];
+var redactSecrets = (value) => SECRET_PATTERNS.reduce((result, pattern) => result.replace(pattern, "[REDACTED]"), value);
+var redactValue = (value) => Array.isArray(value) ? value.map(redactValue) : value && typeof value === "object" ? Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redactValue(item)])) : typeof value === "string" ? redactSecrets(value) : value;
+
+// src/discovery/repository.ts
+var SOURCE_EXTENSIONS = [".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".mts", ".cts"];
+var DOCUMENT_EXTENSIONS = [".md", ".mdx"];
+var DEFAULT_MAX_FILES2 = 1e4;
+var EMPTY_HASH = "0".repeat(64);
+var isRecord2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var readJson = (path) => {
+  try {
+    const value = JSON.parse(readFileSync9(path, "utf8"));
+    return isRecord2(value) ? { value } : { error: "JSON root is not an object" };
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) };
+  }
+};
+var relativePath = (root, path) => toPosix(relative6(root, path)) || ".";
+var MAX_ID_LENGTH = 256;
+var ID_HASH_LENGTH = 32;
+var entityId = (kind, value) => {
+  const fullId = `${kind}:${value}`;
+  if (fullId.length <= MAX_ID_LENGTH) return fullId;
+  const suffix = `:${sha256NormalizedV1(fullId).slice(0, ID_HASH_LENGTH)}`;
+  return `${fullId.slice(0, MAX_ID_LENGTH - suffix.length)}${suffix}`;
+};
+var lineEvidence = (source, root, path, lineStart, lineEnd) => ({
+  source,
+  path: relativePath(root, path),
+  ...lineStart !== void 0 ? { lineStart } : {},
+  ...lineEnd !== void 0 ? { lineEnd } : {}
+});
+var firstLineContaining = (text, pattern) => {
+  const line = text.split(/\r?\n/).findIndex((value) => value.includes(pattern));
+  return line >= 0 ? line + 1 : void 0;
+};
+var packageName = (manifest, fallback) => typeof manifest.name === "string" && manifest.name.length > 0 ? manifest.name : fallback || void 0;
+var workspacePatterns = (root, rootManifest) => {
+  const fromPackageJson = rootManifest?.workspaces;
+  if (Array.isArray(fromPackageJson)) return fromPackageJson.filter((value) => typeof value === "string");
+  if (isRecord2(fromPackageJson) && Array.isArray(fromPackageJson.packages)) {
+    return fromPackageJson.packages.filter((value) => typeof value === "string");
+  }
+  const workspacePath = join8(root, "pnpm-workspace.yaml");
+  if (!existsSync10(workspacePath)) return [];
+  const patterns = [];
+  let inPackages = false;
+  for (const line of readFileSync9(workspacePath, "utf8").split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed === "packages:") {
+      inPackages = true;
+      continue;
+    }
+    if (!inPackages) continue;
+    if (trimmed.startsWith("- ")) {
+      patterns.push(trimmed.slice(2).trim().replace(/^['"]|['"]$/g, ""));
+      continue;
+    }
+    if (trimmed && !trimmed.startsWith("#")) inPackages = false;
+  }
+  return patterns;
+};
+var discoverPackages = (root, rootManifest, config) => {
+  const packages = [];
+  const coverage = [];
+  const rootManifestPath = join8(root, "package.json");
+  if (rootManifest) {
+    const name = packageName(rootManifest, "");
+    packages.push({
+      id: entityId("package", packageName(rootManifest, "root") ?? "root"),
+      ...name ? { name } : {},
+      path: ".",
+      absPath: root,
+      manifestPath: rootManifestPath,
+      manifest: rootManifest
+    });
+  }
+  const configuredPatterns = config?.routing?.options?.packages;
+  const patterns = configuredPatterns?.length ? [...configuredPatterns] : workspacePatterns(root, rootManifest);
+  if (!patterns.length) {
+    coverage.push({ status: "complete" });
+    return { packages, coverage };
+  }
+  const dirs = expandWorkspaceGlobs(root, patterns);
+  for (const absPath of dirs) {
+    const manifestPath = join8(absPath, "package.json");
+    const parsed = readJson(manifestPath);
+    if (!parsed.value) {
+      coverage.push({ status: "partial", reason: `${relativePath(root, manifestPath)}: ${parsed.error ?? "invalid package.json"}` });
+      continue;
+    }
+    const path = relativePath(root, absPath);
+    const name = packageName(parsed.value, path);
+    const id = entityId("package", name ?? path);
+    const duplicate = packages.find((pkg) => pkg.id === id);
+    if (duplicate && duplicate.absPath !== absPath) {
+      throw new Error(`Package identity collision for "${id}": "${duplicate.path}" and "${path}".`);
+    }
+    if (!duplicate) packages.push({ id, ...name ? { name } : {}, path, absPath, manifestPath, manifest: parsed.value });
+  }
+  coverage.push({ status: "complete" });
+  return { packages: packages.sort((a, b) => a.id.localeCompare(b.id)), coverage };
+};
+var packageForModule = (packages, absPath) => [...packages].filter((pkg) => absPath === pkg.absPath || absPath.startsWith(`${pkg.absPath}${sep7}`)).sort((a, b) => b.absPath.length - a.absPath.length)[0];
+var readCompilerOptions = (root) => {
+  const configPath = ts.findConfigFile(root, ts.sys.fileExists, "tsconfig.json");
+  if (!configPath) return { options: {} };
+  const parsed = ts.readConfigFile(configPath, ts.sys.readFile);
+  if (parsed.error) return { options: {}, error: ts.flattenDiagnosticMessageText(parsed.error.messageText, "\n") };
+  const config = ts.parseJsonConfigFileContent(parsed.config, ts.sys, dirname5(configPath));
+  if (config.errors.length) {
+    return {
+      options: config.options,
+      error: ts.flattenDiagnosticMessageText(config.errors[0]?.messageText ?? "Invalid tsconfig", "\n")
+    };
+  }
+  return { options: config.options };
+};
+var scriptKind = (path) => {
+  switch (extname(path)) {
+    case ".js":
+      return ts.ScriptKind.JS;
+    case ".jsx":
+      return ts.ScriptKind.JSX;
+    case ".mjs":
+      return ts.ScriptKind.JS;
+    case ".cjs":
+      return ts.ScriptKind.JS;
+    case ".ts":
+      return ts.ScriptKind.TS;
+    case ".tsx":
+      return ts.ScriptKind.TSX;
+    case ".mts":
+      return ts.ScriptKind.TS;
+    case ".cts":
+      return ts.ScriptKind.TS;
+    default:
+      return ts.ScriptKind.Unknown;
+  }
+};
+var nodeEvidence = (root, path, sourceFile, node) => {
+  const start = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
+  const end = sourceFile.getLineAndCharacterOfPosition(node.getEnd()).line + 1;
+  return lineEvidence("code", root, path, start, end);
+};
+var isExported = (node) => {
+  const modifiers = ts.canHaveModifiers(node) ? ts.getModifiers(node) : void 0;
+  return modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+};
+var exportedNames = (sourceFile) => {
+  const names = /* @__PURE__ */ new Set();
+  const addDeclarationName = (node) => {
+    if (!isExported(node)) return;
+    const name = ts.getNameOfDeclaration(node);
+    if (name && ts.isIdentifier(name)) names.add(name.text);
+  };
+  const visit = (node) => {
+    if (ts.isExportDeclaration(node)) {
+      if (!node.exportClause) names.add("*");
+      else if (ts.isNamedExports(node.exportClause)) {
+        for (const element of node.exportClause.elements) names.add(element.name.text);
+      }
+    } else if (ts.isExportAssignment(node)) {
+      names.add("default");
+    } else if (ts.isClassDeclaration(node) || ts.isFunctionDeclaration(node) || ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node) || ts.isEnumDeclaration(node) || ts.isModuleDeclaration(node)) {
+      addDeclarationName(node);
+    } else if (ts.isVariableStatement(node) && isExported(node)) {
+      for (const declaration of node.declarationList.declarations) {
+        if (ts.isIdentifier(declaration.name)) names.add(declaration.name.text);
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return [...names].sort();
+};
+var moduleReferences = (root, path, sourceFile) => {
+  const references = [];
+  let hasDynamic = false;
+  let hasRuntimeWiring = false;
+  const addReference = (specifier, kind, node) => {
+    references.push({ specifier: specifier.text, kind, evidence: nodeEvidence(root, path, sourceFile, node) });
+  };
+  const visit = (node) => {
+    if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+      addReference(node.moduleSpecifier, "imports", node);
+    } else if (ts.isExportDeclaration(node) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
+      addReference(node.moduleSpecifier, "re-exports", node);
+    } else if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference) && ts.isStringLiteral(node.moduleReference.expression)) {
+      addReference(node.moduleReference.expression, "imports", node);
+    } else if (ts.isCallExpression(node)) {
+      if (node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+        if (!node.arguments[0] || !ts.isStringLiteralLike(node.arguments[0])) hasDynamic = true;
+      } else if (ts.isIdentifier(node.expression) && node.expression.text === "require") {
+        const argument = node.arguments[0];
+        if (argument && ts.isStringLiteralLike(argument)) addReference(argument, "imports", node);
+        else hasDynamic = true;
+      } else if (ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === "register") {
+        hasRuntimeWiring = true;
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return {
+    references,
+    exports: exportedNames(sourceFile),
+    hasDynamic,
+    hasRuntimeWiring
+  };
+};
+var resolveRelativeModule = (specifier, containingFile, modulePaths) => {
+  const base = resolve8(dirname5(containingFile), specifier);
+  const extension = extname(base);
+  const extensionlessBase = extension ? base.slice(0, -extension.length) : base;
+  const candidates = [
+    base,
+    ...SOURCE_EXTENSIONS.map((extension2) => `${base}${extension2}`),
+    ...SOURCE_EXTENSIONS.map((extension2) => join8(base, `index${extension2}`)),
+    ...SOURCE_EXTENSIONS.map((extension2) => `${extensionlessBase}${extension2}`),
+    ...SOURCE_EXTENSIONS.map((extension2) => join8(extensionlessBase, `index${extension2}`))
+  ];
+  return candidates.map((candidate) => modulePaths.get(resolve8(candidate))).find(Boolean);
+};
+var resolveReference = (reference, containingFile, modules, packages, compilerOptions) => {
+  if (reference.specifier.startsWith(".") || reference.specifier.startsWith("/")) {
+    const relativeTarget = resolveRelativeModule(reference.specifier, containingFile, modules);
+    return relativeTarget ? { targetId: relativeTarget.entityId } : void 0;
+  }
+  const packageTarget = [...packages].filter((pkg) => pkg.name && (reference.specifier === pkg.name || reference.specifier.startsWith(`${pkg.name}/`))).sort((a, b) => (b.name?.length ?? 0) - (a.name?.length ?? 0))[0];
+  if (packageTarget) return { targetId: packageTarget.id };
+  const resolved = ts.resolveModuleName(reference.specifier, containingFile, compilerOptions, ts.sys).resolvedModule?.resolvedFileName;
+  const resolvedTarget = resolved ? modules.get(resolve8(resolved)) : void 0;
+  if (resolvedTarget) return { targetId: resolvedTarget.entityId };
+  return { targetId: entityId("external", reference.specifier) };
+};
+var dependencyEntries = (manifest) => {
+  const sections = ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"];
+  return sections.flatMap((type) => {
+    const value = manifest[type];
+    if (!isRecord2(value)) return [];
+    return Object.keys(value).sort().map((name) => ({ name, type }));
+  });
+};
+var sourceRevision = (root, files) => {
+  const contentRevision = () => ({
+    value: sha256NormalizedV1(
+      files.map((path) => ({
+        path: relativePath(root, path),
+        contentHash: sha256NormalizedV1(readFileSync9(path, "utf8"))
+      }))
+    ),
+    kind: "content"
+  });
+  try {
+    const status = execFileSync("git", ["status", "--porcelain", "--untracked-files=all"], {
+      cwd: root,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    if (status) return contentRevision();
+    const value = execFileSync("git", ["rev-parse", "HEAD"], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    if (value) return { value, kind: "git" };
+  } catch {
+  }
+  return contentRevision();
+};
+var hasPackageManagerMetadata = (root, rootManifest) => Boolean(
+  rootManifest?.packageManager || existsSync10(join8(root, "pnpm-lock.yaml")) || existsSync10(join8(root, "pnpm-workspace.yaml")) || existsSync10(join8(root, "yarn.lock")) || existsSync10(join8(root, "bun.lock")) || existsSync10(join8(root, "bun.lockb")) || existsSync10(join8(root, "package-lock.json"))
+);
+var artifact = (root, config, files, entities, relations, coverage) => {
+  const revision = sourceRevision(root, files);
+  const base = {
+    type: "discovery-snapshot",
+    schemaVersion: 1,
+    contentHash: EMPTY_HASH,
+    contentHashAlgo: "sha256-normalized-v1",
+    project: { name: entities.find((entity) => entity.kind === "package" && entity.path === ".")?.name ?? basename4(root), root: "." },
+    sourceRevision: revision.value,
+    sourceRevisionKind: revision.kind,
+    configurationHash: sha256NormalizedV1(config ?? {}),
+    pipelineVersion: "1.0.0",
+    analyzerVersions: { repository: "1.0.0", "js-ts": "1.0.0" },
+    entities: [...entities].sort((a, b) => a.id.localeCompare(b.id)),
+    relations: [...relations].sort((a, b) => a.id.localeCompare(b.id)),
+    coverage: [...coverage]
+  };
+  return DiscoverySnapshotV1Schema.parse({ ...base, contentHash: contentHashForArtifactV1(base) });
+};
+var discoverRepository = (opts = {}) => {
+  const root = resolve8(opts.root ?? process.cwd());
+  const maxFiles = opts.maxFiles ?? DEFAULT_MAX_FILES2;
+  const safety = opts.config?.safety;
+  const maxBytes = opts.maxBytes ?? safety?.maxBytes;
+  const safeOptions = {
+    exclude: [...DEFAULT_SAFETY_EXCLUDES, ...safety?.exclude ?? []],
+    maxFiles,
+    ...maxBytes !== void 0 ? { maxBytes } : {},
+    ...safety?.maxTimeMs !== void 0 ? { maxTimeMs: safety.maxTimeMs } : {},
+    ...safety?.maxMemoryMb !== void 0 ? { maxMemoryMb: safety.maxMemoryMb } : {}
+  };
+  const rootManifestPath = join8(root, "package.json");
+  const rootManifest = readJson(rootManifestPath).value;
+  const packageResult = discoverPackages(root, rootManifest, opts.config);
+  const sourceWalk = safeWalkFiles(root, { extensions: SOURCE_EXTENSIONS, ...safeOptions });
+  const documentWalk = safeWalkFiles(root, { extensions: DOCUMENT_EXTENSIONS, ...safeOptions });
+  const configWalk = safeWalkFiles(root, { extensions: [".json", ".yaml", ".yml", ".js", ".ts"], ...safeOptions });
+  const sourcePaths = sourceWalk.files;
+  const documentPaths = documentWalk.files;
+  const configPaths = configWalk.files.filter((path) => /(?:^|\/)(?:tsconfig|jsconfig|vite\.config|webpack\.config|rollup\.config|next\.config|jest\.config|eslint\.config|vitest\.config)/.test(relativePath(root, path)));
+  const allFiles = [...new Set([rootManifestPath, ...sourcePaths, ...documentPaths, ...configPaths].filter(existsSync10))].sort();
+  const entities = /* @__PURE__ */ new Map();
+  const relations = /* @__PURE__ */ new Map();
+  const addEntity = (entity) => {
+    const existing = entities.get(entity.id);
+    if (existing && (existing.kind !== entity.kind || existing.path !== entity.path)) throw new Error(`Entity identity collision for "${entity.id}".`);
+    entities.set(entity.id, existing ?? entity);
+  };
+  const addRelation = (relation) => {
+    const existing = relations.get(relation.id);
+    if (!existing) {
+      relations.set(relation.id, relation);
+      return;
+    }
+    const evidence2 = new Map(
+      [...existing.evidence, ...relation.evidence].map((item) => [
+        `${item.path}:${item.lineStart ?? ""}:${item.lineEnd ?? ""}:${item.source}`,
+        item
+      ])
+    );
+    relations.set(relation.id, { ...existing, evidence: [...evidence2.values()] });
+  };
+  for (const pkg of packageResult.packages) {
+    const text = readFileSync9(pkg.manifestPath, "utf8");
+    addEntity({ id: pkg.id, kind: "package", name: pkg.name ?? pkg.path, path: pkg.path, provenance: "observed", evidence: [lineEvidence("configuration", root, pkg.manifestPath, firstLineContaining(text, '"name"'))] });
+  }
+  const modules = /* @__PURE__ */ new Map();
+  for (const absPath of sourcePaths) {
+    const path = relativePath(root, absPath);
+    const pkg = packageForModule(packageResult.packages, absPath);
+    const id = entityId("module", path);
+    const text = readFileSync9(absPath, "utf8");
+    const sourceFile = ts.createSourceFile(absPath, text, ts.ScriptTarget.Latest, true, scriptKind(absPath));
+    const exports = exportedNames(sourceFile);
+    modules.set(resolve8(absPath), { absPath, path, entityId: id, ...pkg ? { packageId: pkg.id } : {} });
+    addEntity({ id, kind: "module", name: basename4(absPath), path, provenance: "observed", evidence: [lineEvidence("code", root, absPath, 1, sourceFile.getLineAndCharacterOfPosition(sourceFile.getEnd()).line + 1)], ...exports.length ? { metadata: { exports, test: /(?:\.test|\.spec|__tests__)/.test(path) } } : {} });
+    if (pkg) addRelation({ id: entityId("relation", `${pkg.id}:contains:${id}`), kind: "contains", from: pkg.id, to: id, provenance: "observed", evidence: [lineEvidence("code", root, absPath, 1)] });
+  }
+  for (const absPath of documentPaths) {
+    const path = relativePath(root, absPath);
+    addEntity({ id: entityId("document", path), kind: "document", name: basename4(absPath), path, provenance: "observed", evidence: [lineEvidence("documentation", root, absPath, 1)] });
+  }
+  const compiler = readCompilerOptions(root);
+  const coverage = [
+    ...[sourceWalk, documentWalk, configWalk].flatMap((walk, index) => walk.incomplete ? [{ analyzer: "repository", scope: `limits:${["source", "documentation", "configuration"][index]}`, status: "partial", reason: walk.reason }] : []),
+    { analyzer: "repository", scope: "package-manager", status: hasPackageManagerMetadata(root, rootManifest) ? "complete" : "partial", ...!hasPackageManagerMetadata(root, rootManifest) ? { reason: `No package manager metadata found; default helper would fall back to ${detectPackageManager(root)}.` } : {} },
+    { analyzer: "repository", scope: "workspace-packages", status: packageResult.coverage.some((item) => item.status === "partial") ? "partial" : "complete", ...packageResult.coverage.find((item) => item.reason)?.reason ? { reason: packageResult.coverage.find((item) => item.reason)?.reason } : {} },
+    { analyzer: "js-ts", scope: "static-imports-and-exports", status: compiler.error ? "partial" : "complete", ...compiler.error ? { reason: compiler.error } : {} },
+    { analyzer: "js-ts", scope: "dynamic-imports", status: "not-analyzed", reason: "Dynamic import expressions and non-literal require calls are not resolved." },
+    { analyzer: "js-ts", scope: "runtime-wiring", status: "not-analyzed", reason: "Reflection, dependency injection and runtime wiring are not inferred." },
+    { analyzer: "js-ts", scope: "generated-code", status: "not-analyzed", reason: "Generated code is not interpreted as source architecture." }
+  ];
+  for (const pkg of packageResult.packages) {
+    const text = readFileSync9(pkg.manifestPath, "utf8");
+    for (const dependency of dependencyEntries(pkg.manifest)) {
+      const target = packageResult.packages.find((candidate) => candidate.name === dependency.name)?.id ?? entityId("external", dependency.name);
+      if (!entities.has(target)) addEntity({ id: target, kind: "external", name: dependency.name, provenance: "observed", evidence: [lineEvidence("configuration", root, pkg.manifestPath, firstLineContaining(text, `"${dependency.name}"`))] });
+      addRelation({ id: entityId("relation", `${pkg.id}:depends-on:${target}:${dependency.type}`), kind: "depends-on", from: pkg.id, to: target, provenance: "observed", evidence: [lineEvidence("configuration", root, pkg.manifestPath, firstLineContaining(text, `"${dependency.name}"`))], metadata: { dependencyType: dependency.type } });
+    }
+  }
+  for (const module of modules.values()) {
+    const text = readFileSync9(module.absPath, "utf8");
+    const sourceFile = ts.createSourceFile(module.absPath, text, ts.ScriptTarget.Latest, true, scriptKind(module.absPath));
+    const references = moduleReferences(root, module.absPath, sourceFile);
+    for (const reference of references.references) {
+      const target = resolveReference(reference, module.absPath, modules, packageResult.packages, compiler.options);
+      if (!target) continue;
+      if (!entities.has(target.targetId)) {
+        const externalName = target.targetId.replace(/^external:/, "");
+        addEntity({ id: target.targetId, kind: "external", name: externalName, provenance: "observed", evidence: [reference.evidence] });
+      }
+      addRelation({ id: entityId("relation", `${module.entityId}:${reference.kind}:${target.targetId}`), kind: reference.kind, from: module.entityId, to: target.targetId, provenance: "observed", evidence: [reference.evidence] });
+    }
+    if (references.hasDynamic) coverage.push({ analyzer: "js-ts", scope: `dynamic-imports:${module.path}`, status: "not-analyzed", reason: "A dynamic import or non-literal require was found.", evidence: [lineEvidence("code", root, module.absPath)] });
+    if (references.hasRuntimeWiring) coverage.push({ analyzer: "js-ts", scope: `runtime-wiring:${module.path}`, status: "not-analyzed", reason: "A possible runtime registration/wiring call was found.", evidence: [lineEvidence("code", root, module.absPath)] });
+  }
+  return artifact(root, opts.config, allFiles, [...entities.values()], [...relations.values()], coverage);
+};
+
+// src/federation/llms.ts
+import { existsSync as existsSync11, readFileSync as readFileSync10 } from "fs";
+import { resolve as resolve9 } from "path";
 
 // src/query/search.ts
 var tokenize = (value) => value.toLowerCase().split(/[^a-z0-9@/_-]+/).filter((t) => t.length >= 2);
@@ -2520,9 +3566,9 @@ var defaultFetchText = async (url) => {
 var sourceText = async (root, source, fetchText) => {
   try {
     if (/^https?:\/\//.test(source)) return await fetchText(source);
-    const path = resolve7(root, source);
-    if (!existsSync10(path)) return null;
-    return readFileSync9(path, "utf8");
+    const path = resolve9(root, source);
+    if (!existsSync11(path)) return null;
+    return readFileSync10(path, "utf8");
   } catch {
     return null;
   }
@@ -2607,16 +3653,16 @@ var retrieveHybridChunks = async (root, config, index, query, options = {}) => {
 };
 
 // src/gates/run-gates.ts
-import { readFileSync as readFileSync11 } from "fs";
+import { readFileSync as readFileSync12 } from "fs";
 
 // src/query/load-index.ts
-import { existsSync as existsSync11, readFileSync as readFileSync10 } from "fs";
-import { join as join8, resolve as resolve8 } from "path";
+import { existsSync as existsSync12, readFileSync as readFileSync11 } from "fs";
+import { join as join9, resolve as resolve10 } from "path";
 
 // src/schemas/agent-handoff.ts
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 var HANDOFF_SCHEMA_VERSION = 1;
-var HandoffTargetTypeSchema = z3.enum([
+var HandoffTargetTypeSchema = z4.enum([
   "package",
   "module",
   "app",
@@ -2627,133 +3673,133 @@ var HandoffTargetTypeSchema = z3.enum([
   "change",
   "search"
 ]);
-var HandoffTargetSchema = z3.object({
+var HandoffTargetSchema = z4.object({
   type: HandoffTargetTypeSchema,
-  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()
+  id: z4.string().min(1).max(256),
+  path: z4.string().min(1).max(512).optional(),
+  group: z4.string().min(1).max(128).optional(),
+  layer: z4.string().min(1).max(32).optional()
 }).strict();
-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()
+var HandoffBridgeSchema = z4.object({
+  humanDoc: z4.enum(["linked", "missing", "external"]),
+  action: z4.string().min(1).max(256).optional(),
+  bootstrap: z4.string().min(1).max(256).optional()
 }).strict();
-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),
+var AgentHandoffV1Schema = z4.object({
+  type: z4.literal("agent-handoff"),
+  schemaVersion: z4.literal(HANDOFF_SCHEMA_VERSION).default(HANDOFF_SCHEMA_VERSION),
+  source: z4.string().min(1).max(512),
   target: HandoffTargetSchema,
-  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(),
+  startHere: z4.string().min(1).max(512),
+  readBeforeEditing: z4.array(z4.string().min(1).max(512)).max(64),
+  editRoots: z4.array(z4.string().min(1).max(512)).max(32),
+  checks: z4.array(z4.string().min(1).max(256)).max(32),
+  humanDoc: z4.string().min(1).max(512).nullable().optional(),
   bridge: HandoffBridgeSchema.optional(),
-  playbookPatterns: z3.array(z3.string().url()).max(16).optional(),
-  notes: z3.array(z3.string().min(1).max(1024)).max(16)
+  playbookPatterns: z4.array(z4.string().url()).max(16).optional(),
+  notes: z4.array(z4.string().min(1).max(1024)).max(16)
 }).strict();
 var AgentHandoffLegacySchema = AgentHandoffV1Schema.omit({ schemaVersion: true }).extend({
-  schemaVersion: z3.literal(HANDOFF_SCHEMA_VERSION).optional()
+  schemaVersion: z4.literal(HANDOFF_SCHEMA_VERSION).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()
+var AgentSearchMatchSchema = z4.object({
+  type: z4.string().min(1).max(64),
+  id: z4.string().min(1).max(256),
+  path: z4.string().min(1).max(512),
+  summary: z4.string().max(2048).optional(),
+  score: z4.number().optional(),
+  refs: z4.number().int().nonnegative().optional()
 }).strict();
-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(),
+var AgentSearchV1Schema = z4.object({
+  type: z4.literal("agent-search"),
+  schemaVersion: z4.literal(HANDOFF_SCHEMA_VERSION).default(HANDOFF_SCHEMA_VERSION),
+  source: z4.string().min(1).max(512),
+  term: z4.string().min(1).max(512),
+  count: z4.number().int().nonnegative(),
   bestMatch: AgentSearchMatchSchema.nullable(),
-  matches: z3.array(AgentSearchMatchSchema).max(32),
-  nextCommands: z3.array(z3.string().min(1).max(512)).max(16)
+  matches: z4.array(AgentSearchMatchSchema).max(32),
+  nextCommands: z4.array(z4.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 z4 } from "zod";
+import { z as z5 } from "zod";
 var INDEX_SCHEMA_VERSION = 1;
-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()
+var ContentHashAlgoSchema = z5.literal("sha256-normalized-v1");
+var EcosystemPropertySchema = z5.object({
+  id: z5.string().min(1).max(64),
+  name: z5.string().min(1).max(128),
+  url: z5.string().url().optional(),
+  llms: z5.string().url().optional()
 }).strict();
-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(),
+var KnowledgeEntrySchema = z5.object({
+  id: z5.string().min(1).max(256),
+  type: z5.string().min(1).max(128),
+  title: z5.string().min(1).max(256),
+  path: z5.string().min(1).max(512),
+  description: z5.string().max(2048).optional(),
   /** Flattened body excerpt for full-text search (not for display). */
-  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()
+  body: z5.string().max(8e3).optional(),
+  links: z5.array(z5.string().min(1).max(512)).max(64).optional(),
+  tags: z5.array(z5.string().min(1).max(64)).max(32).optional()
 }).strict();
-var CapabilityRefSchema = z4.object({
-  id: z4.string().min(1).max(256),
-  kind: z4.string().min(1).max(64),
-  description: z4.string().max(512).optional()
+var CapabilityRefSchema = z5.object({
+  id: z5.string().min(1).max(256),
+  kind: z5.string().min(1).max(64),
+  description: z5.string().max(512).optional()
 }).strict();
-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()
+var OwnershipRecordSchema = z5.object({
+  id: z5.string().min(1).max(256),
+  path: z5.string().min(1).max(512),
+  group: z5.string().min(1).max(128).optional(),
+  layer: z5.string().min(1).max(32).optional(),
+  purpose: z5.string().max(1024).optional(),
+  checks: z5.array(z5.string().min(1).max(256)).max(32),
+  agentDoc: z5.string().min(1).max(512).optional(),
+  humanDoc: z5.string().min(1).max(512).optional(),
+  readme: z5.string().min(1).max(512).optional()
 }).strict();
-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)
+var IndexLookupSchema = z5.object({
+  packages: z5.array(z5.string().min(1).max(256)).max(2e3),
+  ownership: z5.record(z5.string().min(1).max(256), OwnershipRecordSchema).optional(),
+  intents: z5.record(
+    z5.string().min(1).max(128),
+    z5.object({
+      id: z5.string().min(1).max(128),
+      title: z5.string().min(1).max(256),
+      paths: z5.array(z5.string().min(1).max(512)).max(32)
     }).strict()
   ).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()
+  changes: z5.record(
+    z5.string().min(1).max(128),
+    z5.object({
+      id: z5.string().min(1).max(128),
+      title: z5.string().min(1).max(256),
+      startHere: z5.string().min(1).max(512),
+      relatedPackages: z5.array(z5.string().min(1).max(256)).max(32).optional()
     }).strict()
   ).optional()
 }).strict();
-var DocBridgeIndexV1Schema = z4.object({
-  schemaVersion: z4.literal(INDEX_SCHEMA_VERSION),
-  contentHash: z4.string().regex(/^[a-f0-9]{64}$/),
+var DocBridgeIndexV1Schema = z5.object({
+  schemaVersion: z5.literal(INDEX_SCHEMA_VERSION),
+  contentHash: z5.string().regex(/^[a-f0-9]{64}$/),
   contentHashAlgo: ContentHashAlgoSchema,
-  generatedAt: z4.string().datetime().optional(),
-  project: z4.object({
-    name: z4.string().min(1).max(128),
-    root: z4.string().min(1).max(512).optional()
+  generatedAt: z5.string().datetime().optional(),
+  project: z5.object({
+    name: z5.string().min(1).max(128),
+    root: z5.string().min(1).max(512).optional()
   }).strict().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(),
+  properties: z5.array(EcosystemPropertySchema).max(16).optional(),
+  knowledge: z5.array(KnowledgeEntrySchema).max(1e4),
+  capabilities: z5.array(CapabilityRefSchema).max(5e3).optional(),
+  handoffs: z5.record(z5.string().min(1).max(256), AgentHandoffLegacySchema).optional(),
   lookup: IndexLookupSchema.optional()
 }).strict();
 
 // src/schemas/memory-candidate.ts
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 var MEMORY_CANDIDATE_SCHEMA_VERSION = 1;
-var MemorySourceSchema = z5.enum([
+var MemorySourceSchema = z6.enum([
   "cursor",
   "claude",
   "codex",
@@ -2761,24 +3807,24 @@ var MemorySourceSchema = z5.enum([
   "agent-memory",
   "manual"
 ]);
-var MemorySuggestedTypeSchema = z5.enum([
+var MemorySuggestedTypeSchema = z6.enum([
   "user",
   "feedback",
   "project",
   "reference",
   "unknown"
 ]);
-var MemoryCandidateV1Schema = z5.object({
-  schemaVersion: z5.literal(MEMORY_CANDIDATE_SCHEMA_VERSION),
-  id: z5.string().min(1).max(256),
+var MemoryCandidateV1Schema = z6.object({
+  schemaVersion: z6.literal(MEMORY_CANDIDATE_SCHEMA_VERSION),
+  id: z6.string().min(1).max(256),
   source: MemorySourceSchema,
-  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(),
+  rawPath: z6.string().min(1).max(512).optional(),
+  fact: z6.string().min(1).max(8e3),
+  why: z6.string().max(4e3).optional(),
+  howToApply: z6.string().max(4e3).optional(),
   suggestedType: MemorySuggestedTypeSchema,
-  confidence: z5.number().min(0).max(1),
-  references: z5.array(z5.string().min(1).max(512)).max(64)
+  confidence: z6.number().min(0).max(1),
+  references: z6.array(z6.string().min(1).max(512)).max(64)
 }).strict();
 
 // src/validate.ts
@@ -2804,6 +3850,8 @@ ${result.issues.map((i) => `  - ${i.path}: ${i.message}`).join("\n")}`
   return result.value;
 };
 var parseDocBridgeIndex = (input) => DocBridgeIndexV1Schema.parse(input);
+var parseDiscoverySnapshot = (input) => DiscoverySnapshotV1Schema.parse(input);
+var parseReconciliationReport = (input) => ReconciliationReportV1Schema.parse(input);
 var parseDocBridgeConfig = (input) => {
   const result = DocBridgeConfigV1Schema.safeParse(input);
   if (!result.success) {
@@ -2824,11 +3872,11 @@ var IndexNotFoundError = class extends Error {
   }
   path;
 };
-var indexFilePath = (root, config) => join8(root, config.index?.outFile ?? ".doc-bridge/index.json");
+var indexFilePath = (root, config) => join9(root, config.index?.outFile ?? ".doc-bridge/index.json");
 var loadDocBridgeIndex = (root, config) => {
   const path = indexFilePath(root, config);
-  if (!existsSync11(path)) throw new IndexNotFoundError(path);
-  const raw = JSON.parse(readFileSync10(path, "utf8"));
+  if (!existsSync12(path)) throw new IndexNotFoundError(path);
+  const raw = JSON.parse(readFileSync11(path, "utf8"));
   return parseDocBridgeIndex(raw);
 };
 
@@ -2903,7 +3951,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(readFileSync12(doc.absPath, "utf8")) })).filter((doc) => !doc.type || allowed && !allowed.includes(doc.type));
   if (bad.length) {
     return {
       id: "okf-type",
@@ -2930,10 +3978,10 @@ var DOCS_STYLE_RULES = {
   "playbook-okf-soft": ["title", "no-stale-wording"],
   "title-only": ["title"]
 };
-var isRecord2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isRecord3 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var docsStyleOptions = (config) => {
   const raw = config.gates?.options?.["docs-style"];
-  if (!isRecord2(raw)) {
+  if (!isRecord3(raw)) {
     if (config.gates?.preset === "playbook") {
       return { profile: "playbook-okf-soft", required: DOCS_STYLE_RULES["playbook-okf-soft"] };
     }
@@ -2977,7 +4025,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(readFileSync12(doc.absPath, "utf8"), required)
   })).filter((doc) => doc.missing.length > 0);
   if (bad.length) {
     return {
@@ -3021,6 +4069,112 @@ var resolveGateIds = (config) => {
   return [...ids];
 };
 
+// src/rules/engine.ts
+import { minimatch as minimatch5 } from "minimatch";
+var diagnosticRules = {
+  DOCUMENTATION_QUALITY: "documentation-quality",
+  RELATION_UNDOCUMENTED: "graph-undocumented-relation",
+  DECLARED_RELATION_STALE: "declared-unobserved-relation",
+  UNRESOLVED_ENTITY_REFERENCE: "unresolved-reference",
+  CONFLICTING_DECLARATIONS: "conflicting-declaration",
+  RELATION_NOT_ANALYZED: "not-analyzed-coverage",
+  STALE_DOCUMENTATION: "stale-documentation",
+  FRESHNESS_FAILURE: "freshness",
+  OWNERSHIP_GAP: "ownership",
+  CENTRALITY_RISK: "centrality-risk",
+  CRITICAL_PATH_RISK: "critical-path-risk"
+};
+var defaultSeverity = (mode, ruleId) => {
+  if (mode === "default") return "info";
+  if (mode === "strict") return ruleId === "not-analyzed-coverage" ? "warn" : "error";
+  return ruleId === "not-analyzed-coverage" ? "info" : "warn";
+};
+var resolvedOptions = (options) => {
+  const config = RulesConfigSchema.parse(options.config ?? {});
+  const mode = options.preset ?? config.mode ?? "default";
+  const severity = { ...config.severity, ...options.severity };
+  const ignore = /* @__PURE__ */ new Set([...config.ignore ?? [], ...options.ignore ?? []]);
+  return {
+    mode,
+    severity,
+    ignore,
+    criticalEntities: options.criticalEntities ?? config.criticalEntities ?? [],
+    criticalPaths: options.criticalPaths ?? config.criticalPaths ?? [],
+    warningThresholds: { ...config.warningThresholds, ...options.warningThresholds }
+  };
+};
+var severityFor = (ruleId, mode, overrides) => overrides[ruleId] ?? defaultSeverity(mode, ruleId);
+var findingFromDiagnostic = (diagnostic2, ruleId, severity) => ({
+  id: `${diagnostic2.id}:${ruleId}`,
+  ruleId,
+  code: ruleId,
+  status: diagnostic2.status,
+  severity,
+  message: diagnostic2.message,
+  evidence: diagnostic2.evidence,
+  ...diagnostic2.entityIds ? { entityIds: diagnostic2.entityIds } : {},
+  ...diagnostic2.relationIds ? { relationIds: diagnostic2.relationIds } : {},
+  ...diagnostic2.remediation ? { remediation: diagnostic2.remediation } : {},
+  sourceDiagnosticCode: diagnostic2.code
+});
+var criticalFinding = (finding, severity, target) => ({
+  ...finding,
+  id: `${finding.id}:critical:${target}`,
+  ruleId: "critical-path-risk",
+  code: "critical-path-risk",
+  severity,
+  message: `Critical path or entity is affected: ${target}. ${finding.message}`
+});
+var evaluateRules = (report, options = {}) => {
+  const resolved = resolvedOptions(options);
+  const findings = [];
+  for (const diagnostic2 of [...report.diagnostics].sort((a, b) => a.id.localeCompare(b.id))) {
+    const ruleId = diagnosticRules[diagnostic2.code];
+    if (!ruleId || resolved.ignore.has(ruleId)) continue;
+    const severity = severityFor(ruleId, resolved.mode, resolved.severity);
+    if (severity !== "off") findings.push(findingFromDiagnostic(diagnostic2, ruleId, severity));
+  }
+  const criticalSeverity = severityFor("critical-path-risk", resolved.mode, resolved.severity);
+  const criticalEntitySet = new Set(resolved.criticalEntities);
+  for (const finding of [...findings]) {
+    const matchingEntity = (finding.entityIds ?? []).find((id) => criticalEntitySet.has(id));
+    if (matchingEntity && !resolved.ignore.has("critical-path-risk") && criticalSeverity !== "off") {
+      findings.push(criticalFinding(finding, criticalSeverity, matchingEntity));
+    }
+    for (const path of resolved.criticalPaths) {
+      if (finding.evidence.some((item) => minimatch5(item.path, path, { dot: true })) && !resolved.ignore.has("critical-path-risk") && criticalSeverity !== "off") {
+        findings.push(criticalFinding(finding, criticalSeverity, path));
+      }
+    }
+  }
+  const centralityThreshold = resolved.warningThresholds["centrality-risk"] ?? 3;
+  const centralitySeverity = severityFor("centrality-risk", resolved.mode, resolved.severity);
+  if (!resolved.ignore.has("centrality-risk") && centralitySeverity !== "off") {
+    const counts = /* @__PURE__ */ new Map();
+    for (const finding of findings.filter((item) => item.ruleId === "graph-undocumented-relation")) {
+      for (const entityId2 of finding.entityIds ?? []) counts.set(entityId2, (counts.get(entityId2) ?? 0) + 1);
+    }
+    for (const [entityId2, count2] of [...counts.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+      if (count2 < centralityThreshold || !criticalEntitySet.has(entityId2)) continue;
+      findings.push({
+        id: `centrality-risk:${entityId2}`,
+        ruleId: "centrality-risk",
+        code: "centrality-risk",
+        status: "unresolved",
+        severity: centralitySeverity,
+        message: `Critical entity has ${count2} undocumented relation finding(s); static centrality is a review signal, not a runtime availability claim.`,
+        evidence: findings.filter((item) => item.ruleId === "graph-undocumented-relation" && item.entityIds?.includes(entityId2)).flatMap((item) => item.evidence),
+        entityIds: [entityId2],
+        remediation: "Review ownership, dependency boundaries, and runtime availability before declaring an SPOF."
+      });
+    }
+  }
+  const sortedFindings = [...findings].sort((a, b) => a.id.localeCompare(b.id));
+  return { mode: resolved.mode, findings: sortedFindings, exitCode: sortedFindings.some((finding) => finding.severity === "error") ? 1 : 0 };
+};
+var parseRuleId = (value) => RuleIdSchema.parse(value);
+var parseRuleSeverity = (value) => RuleSeveritySchema.parse(value);
+
 // src/query/query.ts
 var handoffForPackage = (index, id, config) => {
   const fromIndex = index.handoffs?.[id];
@@ -3132,7 +4286,7 @@ var runQuery = (index, config, req) => {
 };
 
 // src/intelligence/adapter.ts
-import { join as join9 } from "path";
+import { join as join10 } from "path";
 
 // src/intelligence/peers.ts
 var PeerMissingError = class extends Error {
@@ -3259,20 +4413,20 @@ var resolveIntelligenceRuntime = async (config) => {
   }
   return { adapter, embed, provider, ...model ? { model } : {} };
 };
-var defaultVectorStorePath = (root) => join9(root, ".doc-bridge", "vectors");
+var defaultVectorStorePath = (root) => join10(root, ".doc-bridge", "vectors");
 
 // src/intelligence/rag.ts
-import { readFileSync as readFileSync12 } from "fs";
-import { join as join10 } from "path";
+import { readFileSync as readFileSync13 } from "fs";
+import { join as join11 } 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 = join10(root, entry.path);
+      const abs = join11(root, entry.path);
       let content = "";
       try {
-        content = readFileSync12(abs, "utf8");
+        content = readFileSync13(abs, "utf8");
       } catch {
         content = [entry.title, entry.description].filter(Boolean).join("\n\n");
       }
@@ -3290,7 +4444,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" ? join10(root, config.intelligence.retriever.options.storePath) : defaultVectorStorePath(root);
+  const storePath = typeof config.intelligence?.retriever?.options?.storePath === "string" ? join11(root, config.intelligence.retriever.options.storePath) : defaultVectorStorePath(root);
   const store = memoryMod.fileVectorMemory({ path: storePath });
   const rag = ragMod.createRAG({
     embed,
@@ -3425,15 +4579,15 @@ var startInkChat = async (root, config, index) => {
 };
 
 // src/memory/ingest.ts
-import { existsSync as existsSync12, readFileSync as readFileSync13 } from "fs";
-import { join as join11 } from "path";
+import { existsSync as existsSync13, readFileSync as readFileSync14 } from "fs";
+import { join as join12 } from "path";
 var memoryFact = (raw, id) => firstParagraph(raw) ?? firstHeading(raw) ?? id;
-var relativePath = (root, abs) => toPosix(abs).replace(`${toPosix(root)}/`, "");
+var relativePath2 = (root, abs) => toPosix(abs).replace(`${toPosix(root)}/`, "");
 var ingestMarkdownDir = (root, dir, source, confidence) => {
-  if (!existsSync12(dir)) return [];
+  if (!existsSync13(dir)) return [];
   return walkFiles(dir, { extensions: [".md", ".mdc"] }).map((abs) => {
-    const rel = relativePath(root, abs);
-    const raw = readFileSync13(abs, "utf8");
+    const rel = relativePath2(root, abs);
+    const raw = readFileSync14(abs, "utf8");
     const id = slugFromPath(rel);
     return {
       schemaVersion: 1,
@@ -3448,10 +4602,10 @@ var ingestMarkdownDir = (root, dir, source, confidence) => {
   });
 };
 var ingestCursorRules = (root) => {
-  const dir = join11(root, ".cursor", "rules");
+  const dir = join12(root, ".cursor", "rules");
   return ingestMarkdownDir(root, dir, "cursor", 0.6);
 };
-var ingestAgentMemory = (root) => ingestMarkdownDir(root, join11(root, ".agent-memory"), "agent-memory", 0.7);
+var ingestAgentMemory = (root) => ingestMarkdownDir(root, join12(root, ".agent-memory"), "agent-memory", 0.7);
 var ingestMemoryCandidates = (root) => [
   ...ingestAgentMemory(root),
   ...ingestCursorRules(root)
@@ -3537,9 +4691,9 @@ var draftMemoryPromotion = (classifications) => {
 };
 
 // src/memory/github-pr.ts
-import { execFileSync, spawnSync } from "child_process";
-import { existsSync as existsSync13, mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "fs";
-import { join as join12 } from "path";
+import { execFileSync as execFileSync2, spawnSync } from "child_process";
+import { existsSync as existsSync14, mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "fs";
+import { join as join13 } from "path";
 var run = (cmd, args, cwd) => {
   const result = spawnSync(cmd, [...args], { cwd, encoding: "utf8" });
   const out = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
@@ -3547,10 +4701,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) => join12(root, ".doc-bridge", "drafts", `memory-promotion-${slug()}.md`);
+var defaultPromotionDraftPath = (root) => join13(root, ".doc-bridge", "drafts", `memory-promotion-${slug()}.md`);
 var writePromotionDraft = (root, draft, path) => {
   const draftPath = path ?? defaultPromotionDraftPath(root);
-  mkdirSync2(join12(root, ".doc-bridge", "drafts"), { recursive: true });
+  mkdirSync2(join13(root, ".doc-bridge", "drafts"), { recursive: true });
   writeFileSync2(draftPath, `${draft.body}
 `, "utf8");
   return draftPath;
@@ -3586,7 +4740,7 @@ var promoteMemoryToGithubPr = (root, draft, options = {}) => {
       message: `Wrote draft to ${relDraft}. Run the printed git/gh commands to open a draft PR.`
     };
   }
-  if (!existsSync13(join12(root, ".git"))) {
+  if (!existsSync14(join13(root, ".git"))) {
     return {
       ok: false,
       dryRun: false,
@@ -3664,7 +4818,7 @@ ${auth.out}`
   ];
   let prUrl = "";
   try {
-    prUrl = execFileSync("gh", prArgs, { cwd: root, encoding: "utf8" }).trim();
+    prUrl = execFileSync2("gh", prArgs, { cwd: root, encoding: "utf8" }).trim();
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     return {
@@ -3689,23 +4843,23 @@ ${auth.out}`
 };
 
 // src/index-builder/watch-index.ts
-import { existsSync as existsSync14, watch } from "fs";
-import { dirname as dirname5, resolve as resolve9 } from "path";
+import { existsSync as existsSync15, watch } from "fs";
+import { dirname as dirname6, resolve as resolve11 } from "path";
 var WATCH_PATTERN = /\.(md|mdx|json|ya?ml|mdc)$/i;
 var NX_MANIFEST_PATTERN = /(^|[/\\])(project|package)\.json$/i;
 var collectWatchRoots = (root, config, configPath) => {
   const roots = /* @__PURE__ */ new Set();
-  roots.add(resolve9(root, config.corpus.agent.root));
+  roots.add(resolve11(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", "srcDir"]) {
       const value = humanOpts[key];
-      if (typeof value === "string" && value.length) roots.add(resolve9(root, value));
+      if (typeof value === "string" && value.length) roots.add(resolve11(root, value));
     }
   }
-  if (configPath) roots.add(dirname5(resolve9(configPath)));
-  return [...roots].filter((dir) => existsSync14(dir));
+  if (configPath) roots.add(dirname6(resolve11(configPath)));
+  return [...roots].filter((dir) => existsSync15(dir));
 };
 var watchDocBridgeIndex = (opts) => {
   const debounceMs = opts.debounceMs ?? 350;
@@ -3746,15 +4900,15 @@ var watchDocBridgeIndex = (opts) => {
       rebuild();
     });
   }
-  const nxRoot = resolve9(opts.root);
-  if (opts.config.routing?.plugin === "nx" && existsSync14(nxRoot)) {
+  const nxRoot = resolve11(opts.root);
+  if (opts.config.routing?.plugin === "nx" && existsSync15(nxRoot)) {
     watch(nxRoot, { recursive: true }, (_event, filename) => {
       if (!filename || !NX_MANIFEST_PATTERN.test(filename)) return;
       rebuild();
     });
   }
-  const configDir = resolve9(opts.root);
-  if (existsSync14(configDir)) {
+  const configDir = resolve11(opts.root);
+  if (existsSync15(configDir)) {
     watch(configDir, (_event, filename) => {
       if (!filename || !/doc-bridge\.config/.test(filename)) return;
       rebuild();
@@ -3771,6 +4925,179 @@ var watchDocBridgeIndex = (opts) => {
   });
 };
 
+// src/workflow/engine.ts
+import { appendFileSync, existsSync as existsSync16, mkdirSync as mkdirSync3, readFileSync as readFileSync15, renameSync, rmSync, writeFileSync as writeFileSync3 } from "fs";
+import { join as join15, relative as relative7, resolve as resolve12 } from "path";
+var WORKFLOW_STAGES = ["collect", "normalize", "reconcile", "evaluate", "report"];
+var stageState = {
+  collect: "discovering",
+  normalize: "analyzed",
+  reconcile: "compared",
+  evaluate: "proposed",
+  report: "delivered"
+};
+var defaultStateDir = (root) => join15(root, ".doc-bridge", "workflow");
+var atomicWrite = (path, value) => {
+  const temp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync3(temp, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+  renameSync(temp, path);
+};
+var writeManifest = (stateDir, run2) => {
+  atomicWrite(join15(stateDir, "manifest.json"), run2);
+};
+var appendTransition = (stateDir, transition2) => {
+  appendFileSync(join15(stateDir, "transitions.jsonl"), `${JSON.stringify(transition2)}
+`, "utf8");
+};
+var transition = (run2, to, reason) => {
+  const item = {
+    from: run2.state,
+    to,
+    at: (/* @__PURE__ */ new Date()).toISOString(),
+    ...reason ? { reason } : {}
+  };
+  return { ...run2, state: to, transitions: [...run2.transitions, item] };
+};
+var runId = () => `${Date.now()}-${process.pid}`;
+var stageInputHash = (options, stage, input) => sha256NormalizedV1({ stage, input, sourceRevision: options.sourceRevision, configurationHash: options.configurationHash, toolVersion: options.toolVersion ?? "1.0.0" });
+var stageArtifactPath = (stateDir, stage, inputHash) => join15(stateDir, "artifacts", `${stage}-${inputHash}.json`);
+var readArtifact = (path) => JSON.parse(readFileSync15(path, "utf8"));
+var stepArtifactPath = (stateDir, step) => resolve12(stateDir, step.artifactRefs?.[0] ?? "");
+var stepOutput = (stateDir, run2, stage) => {
+  const step = run2.steps.find((item) => item.name === stage);
+  if (!step || step.status !== "completed" || !step.artifactRefs?.[0]) return null;
+  return readArtifact(stepArtifactPath(stateDir, step)).value;
+};
+var acquireLock = (stateDir) => {
+  const lock = join15(stateDir, ".lock");
+  try {
+    mkdirSync3(lock);
+  } catch {
+    const ownerPath = join15(lock, "owner.json");
+    try {
+      const owner = JSON.parse(readFileSync15(ownerPath, "utf8"));
+      if (typeof owner.pid === "number") process.kill(owner.pid, 0);
+      throw new Error(`Workflow is already running (pid ${owner.pid ?? "unknown"}).`);
+    } catch (error) {
+      if (error instanceof Error && error.message.startsWith("Workflow is already running")) throw error;
+      rmSync(lock, { recursive: true, force: true });
+      mkdirSync3(lock);
+    }
+  }
+  writeFileSync3(join15(lock, "owner.json"), JSON.stringify({ pid: process.pid, startedAt: (/* @__PURE__ */ new Date()).toISOString() }), "utf8");
+  return () => rmSync(lock, { recursive: true, force: true });
+};
+var loadManifest = (stateDir) => {
+  const path = join15(stateDir, "manifest.json");
+  if (!existsSync16(path)) return void 0;
+  return WorkflowRunV1Schema.parse(JSON.parse(readFileSync15(path, "utf8")));
+};
+var baseRun = (options, stateDir, supersedes) => {
+  const inputHash = sha256NormalizedV1({ sourceRevision: options.sourceRevision, configurationHash: options.configurationHash, toolVersion: options.toolVersion ?? "1.0.0" });
+  return WorkflowRunV1Schema.parse({
+    type: "workflow-run",
+    schemaVersion: 1,
+    contentHash: "0".repeat(64),
+    contentHashAlgo: "sha256-normalized-v1",
+    project: { name: resolve12(options.root).split("/").pop() ?? "project", root: "." },
+    sourceRevision: options.sourceRevision,
+    sourceRevisionKind: "content",
+    configurationHash: options.configurationHash,
+    pipelineVersion: "1.0.0",
+    analyzerVersions: { workflow: options.toolVersion ?? "1.0.0" },
+    runId: options.runId ?? runId(),
+    state: "created",
+    steps: WORKFLOW_STAGES.map((name) => ({ name, status: "pending", inputHash })),
+    transitions: [{ from: null, to: "created", at: (/* @__PURE__ */ new Date()).toISOString() }],
+    artifactRefs: [relative7(resolve12(options.root), stateDir), ...supersedes ? [`supersedes:${supersedes}`] : []]
+  });
+};
+var withHash = (run2) => WorkflowRunV1Schema.parse({ ...run2, contentHash: contentHashForArtifactV1(run2) });
+var sameInputs = (run2, options) => run2.sourceRevision === options.sourceRevision && run2.configurationHash === options.configurationHash && run2.analyzerVersions.workflow === (options.toolVersion ?? "1.0.0");
+var selectedStages = (stage) => stage && stage !== "all" ? [stage] : WORKFLOW_STAGES;
+var runWorkflow = (options) => {
+  const root = resolve12(options.root);
+  const stateDir = resolve12(root, options.stateDir ?? defaultStateDir(root));
+  mkdirSync3(join15(stateDir, "artifacts"), { recursive: true });
+  const release = acquireLock(stateDir);
+  try {
+    let run2 = loadManifest(stateDir);
+    let supersedes;
+    if (run2 && !sameInputs(run2, options)) {
+      supersedes = run2.runId;
+      run2 = withHash(transition(run2, "stale", "Source revision, configuration hash, or tool version changed."));
+      appendTransition(stateDir, run2.transitions[run2.transitions.length - 1]);
+      writeManifest(stateDir, run2);
+      run2 = void 0;
+    }
+    if (!run2) {
+      run2 = withHash(baseRun(options, stateDir, supersedes));
+      appendTransition(stateDir, run2.transitions[0]);
+      writeManifest(stateDir, run2);
+    }
+    if (!run2) throw new Error("Workflow manifest was not initialized.");
+    const firstSelectedStage = selectedStages(options.stage)[0];
+    const previousStageIndex = firstSelectedStage ? WORKFLOW_STAGES.indexOf(firstSelectedStage) - 1 : -1;
+    let previousOutput = previousStageIndex >= 0 ? stepOutput(stateDir, run2, WORKFLOW_STAGES[previousStageIndex]) : null;
+    const reusedStages = [];
+    for (const stage of selectedStages(options.stage)) {
+      const input = options.inputs?.[stage] ?? previousOutput;
+      const inputHash = stageInputHash(options, stage, input);
+      const existing = run2.steps.find((step) => step.name === stage);
+      const artifactPath = existing?.artifactRefs?.[0] ? resolve12(stateDir, existing.artifactRefs[0]) : stageArtifactPath(stateDir, stage, inputHash);
+      if (existing?.status === "completed" && existing.inputHash === inputHash && existing.outputHash && existsSync16(artifactPath)) {
+        previousOutput = readArtifact(artifactPath).value;
+        reusedStages.push(stage);
+        continue;
+      }
+      const handler = options.handlers[stage];
+      if (!handler) throw new Error(`No handler configured for workflow stage "${stage}".`);
+      run2 = withHash(transition(run2, stageState[stage]));
+      appendTransition(stateDir, run2.transitions[run2.transitions.length - 1]);
+      const runningStep = { name: stage, status: "running", inputHash };
+      run2 = withHash({ ...run2, steps: run2.steps.map((step) => step.name === stage ? runningStep : step) });
+      writeManifest(stateDir, run2);
+      try {
+        const value = handler({ root, stage, input, previousOutput });
+        const outputHash = sha256NormalizedV1(value);
+        const artifact2 = { type: "workflow-step-artifact", stage, inputHash, outputHash, value };
+        mkdirSync3(join15(stateDir, "artifacts"), { recursive: true });
+        if (existsSync16(artifactPath)) {
+          const existingArtifact = readArtifact(artifactPath);
+          if (existingArtifact.outputHash !== outputHash) throw new Error(`Immutable workflow artifact collision for stage "${stage}".`);
+        } else {
+          atomicWrite(artifactPath, artifact2);
+        }
+        const ref = relative7(stateDir, artifactPath);
+        const completedStep = { name: stage, status: "completed", inputHash, outputHash, artifactRefs: [ref] };
+        run2 = withHash({ ...run2, steps: run2.steps.map((step) => step.name === stage ? completedStep : step) });
+        writeManifest(stateDir, run2);
+        previousOutput = value;
+      } catch (error) {
+        run2 = withHash(transition(run2, "failed", error instanceof Error ? error.message : String(error)));
+        appendTransition(stateDir, run2.transitions[run2.transitions.length - 1]);
+        writeManifest(stateDir, run2);
+        throw error;
+      }
+    }
+    if (selectedStages(options.stage).every((stage) => run2.steps.find((step) => step.name === stage)?.status === "completed")) {
+      const complete = selectedStages(options.stage).includes("report") && run2.state !== "delivered" ? withHash(transition(run2, "delivered")) : run2;
+      if (complete !== run2) {
+        appendTransition(stateDir, complete.transitions[complete.transitions.length - 1]);
+        run2 = complete;
+      }
+      writeManifest(stateDir, run2);
+      if (run2.state === "delivered") atomicWrite(join15(stateDir, "last-known-good.json"), { runId: run2.runId, manifestHash: run2.contentHash, report: run2.steps.find((step) => step.name === "report")?.artifactRefs?.[0] });
+    }
+    return { run: run2, stateDir, reusedStages };
+  } finally {
+    release();
+  }
+};
+var loadWorkflowManifest = (stateDir) => WorkflowRunV1Schema.parse(JSON.parse(readFileSync15(join15(resolve12(stateDir), "manifest.json"), "utf8")));
+var loadWorkflowStepOutput = (stateDir, stage) => stepOutput(resolve12(stateDir), loadWorkflowManifest(stateDir), stage);
+
 // src/doctor/badge.ts
 var doctorBadgeMetrics = (report) => {
   const { packages } = report.coverage;
@@ -3930,43 +5257,43 @@ var docBridgePatternPayload = () => ({
 });
 
 // src/cli/demo.ts
-import { cpSync, existsSync as existsSync16, mkdtempSync, readFileSync as readFileSync15, rmSync } from "fs";
+import { cpSync, existsSync as existsSync18, mkdtempSync, readFileSync as readFileSync17, rmSync as rmSync2 } from "fs";
 import { tmpdir } from "os";
-import { dirname as dirname7, join as join15, resolve as resolve11 } from "path";
+import { dirname as dirname8, join as join17, resolve as resolve14 } from "path";
 import { fileURLToPath } from "url";
 
 // src/mcp/install.ts
-import { existsSync as existsSync15, mkdirSync as mkdirSync3, readFileSync as readFileSync14, writeFileSync as writeFileSync3 } from "fs";
+import { existsSync as existsSync17, mkdirSync as mkdirSync4, readFileSync as readFileSync16, writeFileSync as writeFileSync4 } from "fs";
 import { homedir } from "os";
-import { dirname as dirname6, join as join14, resolve as resolve10 } from "path";
+import { dirname as dirname7, join as join16, resolve as resolve13 } from "path";
 var SERVER_NAME = "ak-docs";
 var mcpServerEntry = (root) => ({
   command: "npx",
   args: ["ak-docs", "mcp"],
   cwd: root
 });
-var readJson = (path) => {
-  if (!existsSync15(path)) return {};
+var readJson2 = (path) => {
+  if (!existsSync17(path)) return {};
   try {
-    const parsed = JSON.parse(readFileSync14(path, "utf8"));
+    const parsed = JSON.parse(readFileSync16(path, "utf8"));
     return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
   } catch {
     return {};
   }
 };
 var writeJson = (path, value) => {
-  mkdirSync3(dirname6(path), { recursive: true });
-  writeFileSync3(path, `${JSON.stringify(value, null, 2)}
+  mkdirSync4(dirname7(path), { recursive: true });
+  writeFileSync4(path, `${JSON.stringify(value, null, 2)}
 `, "utf8");
 };
 var resolveTargetPath = (target, root) => {
-  if (target === "cursor") return resolve10(root, ".cursor", "mcp.json");
-  return join14(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+  if (target === "cursor") return resolve13(root, ".cursor", "mcp.json");
+  return join16(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
 };
 var installMcpConfig = (root, target) => {
   const configPath = resolveTargetPath(target, root);
-  const created = !existsSync15(configPath);
-  const existing = readJson(configPath);
+  const created = !existsSync17(configPath);
+  const existing = readJson2(configPath);
   const servers = existing.mcpServers && typeof existing.mcpServers === "object" && !Array.isArray(existing.mcpServers) ? { ...existing.mcpServers } : {};
   servers[SERVER_NAME] = mcpServerEntry(root);
   writeJson(configPath, { ...existing, mcpServers: servers });
@@ -3990,12 +5317,12 @@ var installMcpConfig = (root, target) => {
 var mcpSnippet = (root) => JSON.stringify({ mcpServers: { [SERVER_NAME]: mcpServerEntry(root) } }, null, 2);
 
 // src/cli/demo.ts
-var packageRoot = resolve11(dirname7(fileURLToPath(import.meta.url)), "..", "..");
+var packageRoot = resolve14(dirname8(fileURLToPath(import.meta.url)), "..", "..");
 var fixturePath = (fixture) => {
   if (fixture === "monorepo") {
-    return join15(packageRoot, "examples", "demo-monorepo");
+    return join17(packageRoot, "examples", "demo-monorepo");
   }
-  return join15(packageRoot, "examples", "demo-example");
+  return join17(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)";
@@ -4011,11 +5338,11 @@ var formatHandoffText = (handoff) => {
 var runDemo = (root, config, fixture = "example", options = {}) => {
   const targetPackage = fixture === "monorepo" ? "auth" : "example";
   const fixtureDir = fixturePath(fixture);
-  if (options.copyFixture && existsSync16(fixtureDir)) {
+  if (options.copyFixture && existsSync18(fixtureDir)) {
     for (const rel of ["doc-bridge.config.json", "docs", "packages", "pnpm-workspace.yaml", "package.json"]) {
-      const src = join15(fixtureDir, rel);
-      if (!existsSync16(src)) continue;
-      const dest = join15(root, rel);
+      const src = join17(fixtureDir, rel);
+      if (!existsSync18(src)) continue;
+      const dest = join17(root, rel);
       cpSync(src, dest, { recursive: true });
     }
   }
@@ -4070,17 +5397,17 @@ var formatDemoText = (result) => {
   return lines;
 };
 var withDemoWorkspace = (fixture, fn) => {
-  const dir = mkdtempSync(join15(tmpdir(), "ak-docs-demo-"));
+  const dir = mkdtempSync(join17(tmpdir(), "ak-docs-demo-"));
   try {
     const fixtureDir = fixturePath(fixture);
-    if (!existsSync16(fixtureDir)) {
+    if (!existsSync18(fixtureDir)) {
       throw new Error(`Demo fixture "${fixture}" not found at ${fixtureDir}`);
     }
     cpSync(fixtureDir, dir, { recursive: true });
-    const config = JSON.parse(readFileSync15(join15(dir, "doc-bridge.config.json"), "utf8"));
+    const config = JSON.parse(readFileSync17(join17(dir, "doc-bridge.config.json"), "utf8"));
     return fn(dir, config);
   } finally {
-    rmSync(dir, { recursive: true, force: true });
+    rmSync2(dir, { recursive: true, force: true });
   }
 };
 
@@ -4288,9 +5615,220 @@ var formatDoctorText = (report) => {
 };
 
 // src/mcp/server.ts
-import { readFileSync as readFileSync16, realpathSync as realpathSync7 } from "fs";
-import { relative as relative5, resolve as resolve12 } from "path";
-import { z as z6, ZodError } from "zod";
+import { mkdirSync as mkdirSync7, readFileSync as readFileSync20, realpathSync as realpathSync9, writeFileSync as writeFileSync7 } from "fs";
+import { join as join20, relative as relative9, resolve as resolve17 } from "path";
+import { z as z8, ZodError } from "zod";
+
+// src/fixes/proposals.ts
+import { existsSync as existsSync19, readdirSync as readdirSync4, readFileSync as readFileSync18, realpathSync as realpathSync8, renameSync as renameSync2, statSync as statSync5, unlinkSync, writeFileSync as writeFileSync5 } from "fs";
+import { basename as basename5, dirname as dirname9, extname as extname2, join as join18, relative as relative8, resolve as resolve15, sep as sep8 } from "path";
+var hash2 = (value) => sha256NormalizedV1(value);
+var artifactMetadata = (root, options) => ({
+  schemaVersion: 1,
+  contentHash: "0".repeat(64),
+  contentHashAlgo: "sha256-normalized-v1",
+  project: { name: options.projectName ?? basename5(resolve15(root)), root: "." },
+  sourceRevision: options.baseRevision,
+  sourceRevisionKind: options.baseRevision.length === 40 ? "git" : "content",
+  configurationHash: options.configurationHash,
+  pipelineVersion: "1.0.0",
+  analyzerVersions: { fixes: options.toolVersion ?? "1.0.0" }
+});
+var unifiedDiff = (changes) => changes.map((change) => {
+  const before = change.before.split("\n").map((line) => `-${line}`).join("\n");
+  const after = change.after.split("\n").map((line) => `+${line}`).join("\n");
+  return `--- a/${change.path}
++++ b/${change.path}
+@@
+${before}
+${after}`;
+}).join("\n");
+var makeProposal = (root, options, changes, preconditions, postconditions) => {
+  const draft = {
+    ...artifactMetadata(root, options),
+    type: "fix-proposal",
+    proposalId: `fix-${hash2(changes).slice(0, 20)}`,
+    baseRevision: options.baseRevision,
+    affectedFiles: changes.map(({ path, before }) => ({ path, contentHash: sha256NormalizedV1(before) })),
+    changes,
+    preconditions,
+    diff: unifiedDiff(changes),
+    postconditions,
+    status: "proposed"
+  };
+  return FixProposalV1Schema.parse({ ...draft, contentHash: contentHashForArtifactV1(draft) });
+};
+var walkMarkdown = (root, directory = root) => readdirSync4(directory, { withFileTypes: true }).flatMap((entry) => {
+  if (entry.name === ".git" || entry.name === "node_modules" || entry.name === "dist" || entry.name === "build") return [];
+  const path = join18(directory, entry.name);
+  if (entry.isDirectory()) return walkMarkdown(root, path);
+  return entry.isFile() && [".md", ".mdx"].includes(extname2(entry.name).toLowerCase()) ? [relative8(root, path).split(sep8).join("/")] : [];
+});
+var localLink = /(!?)\[([^\]]*)\]\(([^)\s]+)(?:\s+["'][^)]*["'])?\)/g;
+var sortJson = (value) => Array.isArray(value) ? value.map(sortJson) : value && typeof value === "object" ? Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => [key, sortJson(item)])) : value;
+var createMarkdownLinkFixProposal = (root, options) => {
+  const projectRoot = realpathSync8.native(resolve15(root));
+  const paths = walkMarkdown(projectRoot);
+  const changes = [];
+  for (const path of paths) {
+    const content = readFileSync18(join18(projectRoot, path), "utf8");
+    let next = content;
+    for (const match of content.matchAll(localLink)) {
+      const target = match[3];
+      if (!target || match[1] === "!" || /^(?:[a-z]+:|\/|#)/i.test(target)) continue;
+      const targetPath = target.split("#")[0]?.split("?")[0];
+      if (!targetPath || existsSync19(resolve15(projectRoot, dirname9(path), targetPath))) continue;
+      const targetStem = basename5(targetPath, extname2(targetPath)).toLowerCase();
+      const labelStem = (match[2] ?? "").trim().toLowerCase().replace(/[^a-z0-9]+/g, "");
+      const candidates = paths.filter((candidate) => basename5(candidate, extname2(candidate)).toLowerCase() === targetStem || basename5(candidate, extname2(candidate)).toLowerCase().replace(/[^a-z0-9]+/g, "") === labelStem);
+      if (candidates.length !== 1) continue;
+      let replacement = relative8(dirname9(path), candidates[0]).split(sep8).join("/");
+      if (target.startsWith("./") && !replacement.startsWith(".")) replacement = `./${replacement}`;
+      next = next.replace(match[0], match[0].replace(target, replacement));
+    }
+    if (next !== content) changes.push({ path, before: content, after: next });
+  }
+  return changes.length ? makeProposal(projectRoot, options, changes, ["Each replacement has exactly one Markdown target."], ["All corrected local Markdown links resolve."]) : void 0;
+};
+var createArtifactNormalizationProposal = (root, artifactPath, options) => {
+  const projectRoot = realpathSync8.native(resolve15(root));
+  const path = artifactPath.split(sep8).join("/");
+  const absolute = containedPath(projectRoot, path);
+  if (!absolute || !existsSync19(absolute) || !statSync5(absolute).isFile()) return void 0;
+  const before = readFileSync18(absolute, "utf8");
+  let after;
+  try {
+    after = `${JSON.stringify(sortJson(JSON.parse(before)), null, 2)}
+`;
+  } catch {
+    return void 0;
+  }
+  return after === before ? void 0 : makeProposal(projectRoot, options, [{ path: relative8(projectRoot, absolute).split(sep8).join("/"), before, after }], ["The artifact contains valid JSON."], ["The artifact is valid canonical JSON with one trailing newline."]);
+};
+var approveFixProposal = (proposalInput, approvedBy, approvedAt = (/* @__PURE__ */ new Date()).toISOString()) => {
+  const proposal = FixProposalV1Schema.parse(proposalInput);
+  if (proposal.status !== "proposed") throw new Error(`Only proposed fixes can be approved; received "${proposal.status}".`);
+  const approved = { ...proposal, status: "approved", approval: { proposalHash: proposal.contentHash, approvedAt, approvedBy }, contentHash: "0".repeat(64) };
+  return FixProposalV1Schema.parse({ ...approved, contentHash: contentHashForArtifactV1(approved) });
+};
+var bindingHash = (proposal) => {
+  const { approval: _approval, contentHash: _contentHash, status: _status, ...rest } = proposal;
+  return contentHashForArtifactV1({ ...rest, contentHash: "0".repeat(64), status: "proposed" });
+};
+var applyFixProposal = (root, proposalInput, options = {}) => {
+  const proposal = FixProposalV1Schema.parse(proposalInput);
+  if (proposal.status !== "approved" || !proposal.approval) throw new Error("Only an explicitly approved fix proposal can be applied.");
+  if (proposal.approval.proposalHash !== bindingHash(proposal)) throw new Error("Approval is not bound to the exact proposal content.");
+  if (options.currentRevision && options.currentRevision !== proposal.baseRevision) throw new Error("The repository revision changed since this proposal was created.");
+  if (!proposal.changes?.length) throw new Error("This proposal has no executable changes.");
+  const projectRoot = realpathSync8.native(resolve15(root));
+  const originals = /* @__PURE__ */ new Map();
+  const affected = new Map(proposal.affectedFiles.map((file) => [file.path, file]));
+  if (proposal.changes.some((change) => !affected.has(change.path) || affected.get(change.path)?.contentHash !== sha256NormalizedV1(change.before)) || affected.size !== proposal.changes.length) {
+    throw new Error("Proposal changes do not match its affected-file hashes.");
+  }
+  for (const file of proposal.affectedFiles) {
+    const absolute = containedPath(projectRoot, file.path);
+    if (!absolute || !existsSync19(absolute)) throw new Error(`Affected file is unavailable or escapes the repository root: ${file.path}`);
+    const current = readFileSync18(absolute, "utf8");
+    if (sha256NormalizedV1(current) !== file.contentHash) throw new Error(`Affected file changed since proposal creation: ${file.path}`);
+    originals.set(absolute, current);
+  }
+  try {
+    for (const change of proposal.changes) {
+      const absolute = resolve15(projectRoot, change.path);
+      writeFileSync5(`${absolute}.docbridge-${process.pid}.tmp`, change.after, "utf8");
+    }
+    for (const change of proposal.changes) {
+      const absolute = resolve15(projectRoot, change.path);
+      renameSync2(`${absolute}.docbridge-${process.pid}.tmp`, absolute);
+    }
+    for (const change of proposal.changes) {
+      if (readFileSync18(resolve15(projectRoot, change.path), "utf8") !== change.after) throw new Error(`Postcondition failed for ${change.path}`);
+    }
+    options.verify?.(proposal.changes.map((change) => change.path));
+  } catch (error) {
+    for (const [absolute, content] of originals) writeFileSync5(absolute, content, "utf8");
+    for (const change of proposal.changes) {
+      const temp = `${resolve15(projectRoot, change.path)}.docbridge-${process.pid}.tmp`;
+      if (existsSync19(temp)) unlinkSync(temp);
+    }
+    throw error;
+  }
+  const applied = { ...proposal, status: "applied", contentHash: "0".repeat(64) };
+  return FixProposalV1Schema.parse({ ...applied, contentHash: contentHashForArtifactV1(applied) });
+};
+
+// src/agents/registry-adapter.ts
+import { existsSync as existsSync20, readFileSync as readFileSync19, writeFileSync as writeFileSync6, mkdirSync as mkdirSync6 } from "fs";
+import { join as join19, resolve as resolve16 } from "path";
+import { pathToFileURL } from "url";
+import { z as z7 } from "zod";
+var DEFAULT_REGISTRY_AGENT_ID = "ecosystem-doc-bridge-corpus-scanner";
+var RegistryAgentMetadataSchema = z7.object({
+  id: z7.string().min(1).max(256),
+  version: z7.string().min(1).max(64),
+  provider: z7.string().min(1).max(128).optional(),
+  model: z7.string().min(1).max(256).optional(),
+  capabilities: z7.array(z7.string().min(1).max(128)).max(32).default([])
+}).strict();
+var deepFreeze = (value) => {
+  if (value && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const child of Object.values(value)) deepFreeze(child);
+  }
+  return value;
+};
+var registryConfig = (config) => config.intelligence?.registry;
+var loadRegistryAgentRunner = async (root, config) => {
+  const metadata = loadRegistryAgentMetadata(root, config);
+  const configured = registryConfig(config)?.runnerModule;
+  const modulePath = configured ? containedPath(root, configured) : containedPath(root, join19(metadata.root, "doc-bridge-adapter.js"));
+  if (!modulePath || !existsSync20(modulePath)) throw new Error(`Registry agent "${metadata.id}" has no local runner module. Configure intelligence.registry.runnerModule or add doc-bridge-adapter.js to the installed agent.`);
+  const loaded = await import(pathToFileURL(modulePath).href);
+  const runner = typeof loaded.run === "function" ? loaded.run : typeof loaded.default === "function" ? loaded.default : loaded.default && typeof loaded.default === "object" && "run" in loaded.default && typeof loaded.default.run === "function" ? loaded.default.run : void 0;
+  if (!runner) throw new Error(`Registry agent runner at ${modulePath} must export a function or { run }. `);
+  return runner;
+};
+var loadRegistryAgentMetadata = (root, config) => {
+  const settings = registryConfig(config);
+  const id = settings?.agentId ?? DEFAULT_REGISTRY_AGENT_ID;
+  const agentRoot = settings?.agentRoot ?? "agents";
+  const agentPath = containedPath(root, join19(agentRoot, id));
+  if (!agentPath || !existsSync20(agentPath)) throw new Error(`AgentsKit Registry agent "${id}" is not installed at ${join19(agentRoot, id)}. Install it with: npx agentskit add ${id}`);
+  const metadataPath = [join19(agentPath, "agent.json"), join19(agentPath, "manifest.json")].find(existsSync20);
+  if (!metadataPath) throw new Error(`Registry agent "${id}" is installed but has no agent.json or manifest.json metadata.`);
+  const metadata = RegistryAgentMetadataSchema.parse(JSON.parse(readFileSync19(metadataPath, "utf8")));
+  if (metadata.id !== id) throw new Error(`Installed Registry agent metadata id "${metadata.id}" does not match configured id "${id}".`);
+  return { ...metadata, root: agentPath };
+};
+var createRegistryAgentAdapter = (root, config, runner) => {
+  if (!registryConfig(config)?.enabled) throw new Error("Registry agents are disabled. Set intelligence.registry.enabled: true to run an assisted workflow.");
+  const metadata = loadRegistryAgentMetadata(resolve16(root), config);
+  return {
+    metadata,
+    run: async (snapshot, report, evidence2 = report.diagnostics.flatMap((diagnostic2) => diagnostic2.evidence).slice(0, 64)) => {
+      const context = deepFreeze({ snapshot: redactValue(snapshot), report: redactValue(report), evidence: redactValue(evidence2), capabilities: ["snapshot.read", "evidence.read", "proposal.write"], network: false, shell: false });
+      const proposal = AgentProposalV1Schema.parse(await runner(context));
+      if (proposal.contentHash !== contentHashForArtifactV1(proposal)) throw new Error("Registry agent proposal contentHash does not match its canonical contents.");
+      if (proposal.baseSnapshotHash !== snapshot.contentHash || proposal.baseReportHash !== report.contentHash) throw new Error("Registry agent proposal is not based on the supplied snapshot/report hashes.");
+      if (proposal.origin.kind !== "registry-agent" || proposal.origin.id !== metadata.id) throw new Error(`Registry agent proposal origin must be ${metadata.id}.`);
+      return proposal;
+    }
+  };
+};
+var persistRegistryAgentProposal = (stateDir, proposal) => {
+  AgentProposalV1Schema.parse(proposal);
+  if (proposal.contentHash !== contentHashForArtifactV1(proposal)) throw new Error("Cannot persist a Registry agent proposal with an invalid contentHash.");
+  const safeHash = contentHashForArtifactV1(proposal);
+  mkdirSync6(join19(resolve16(stateDir), "agents"), { recursive: true });
+  const path = join19(resolve16(stateDir), "agents", `${proposal.origin.id}-${safeHash}.json`);
+  writeFileSync6(path, `${JSON.stringify(proposal, null, 2)}
+`, "utf8");
+  return path;
+};
+
+// src/mcp/server.ts
 var MCP_TOOLS = [
   {
     name: "handoff.resolve",
@@ -4362,25 +5900,70 @@ var MCP_TOOLS = [
     description: "Return the static Doc Bridge curator and delegate topology.",
     annotations: { readOnlyHint: true },
     inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "docbridge.snapshot",
+    title: "Read the latest discovery snapshot",
+    description: "Read the bounded canonical repository snapshot from the latest workflow run.",
+    annotations: { readOnlyHint: true },
+    inputSchema: { type: "object", properties: { runId: { type: "string" } } }
+  },
+  {
+    name: "docbridge.report",
+    title: "Read the latest reconciliation report",
+    description: "Read the canonical reconciliation report from the latest workflow run.",
+    annotations: { readOnlyHint: true },
+    inputSchema: { type: "object", properties: { runId: { type: "string" } } }
+  },
+  {
+    name: "docbridge.diagnostics",
+    title: "Read reconciliation diagnostics",
+    description: "Read bounded diagnostics from the latest canonical reconciliation report.",
+    annotations: { readOnlyHint: true },
+    inputSchema: { type: "object", properties: { status: { type: "string" }, severity: { type: "string" } } }
+  },
+  {
+    name: "docbridge.relations",
+    title: "Read architecture relations",
+    description: "Read bounded observed and declared relations from the latest canonical snapshot.",
+    annotations: { readOnlyHint: true },
+    inputSchema: { type: "object", properties: { kind: { type: "string" }, limit: { type: "number" } } }
+  },
+  {
+    name: "docbridge.run",
+    title: "Read workflow state",
+    description: "Read the latest resumable workflow state and artifact references.",
+    annotations: { readOnlyHint: true },
+    inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "docbridge.proposals",
+    title: "Read or approve proposals",
+    description: "Create, inspect, approve and apply deterministic proposals through the shared human-gated workflow.",
+    inputSchema: { type: "object", properties: { action: { type: "string", enum: ["list", "propose-links", "propose-normalize", "suggest", "approve", "apply"] }, proposalHash: { type: "string" }, artifactPath: { type: "string" }, approvedBy: { type: "string" }, proposal: { type: "object" } } }
   }
 ];
 var asRecord = (value) => value && typeof value === "object" ? value : {};
-var HandoffResolveArgsSchema = z6.object({
-  id: z6.string().min(1),
-  kind: z6.enum(["package", "ownership"]).optional()
+var HandoffResolveArgsSchema = z8.object({
+  id: z8.string().min(1),
+  kind: z8.enum(["package", "ownership"]).optional()
 });
-var DocSearchArgsSchema = z6.object({
-  term: z6.string().min(1),
-  limit: z6.number().int().positive().max(100).optional()
+var DocSearchArgsSchema = z8.object({
+  term: z8.string().min(1),
+  limit: z8.number().int().positive().max(100).optional()
 });
-var RetrieverQueryArgsSchema = z6.object({
-  query: z6.string().min(1),
-  limit: z6.number().int().positive().max(100).optional()
+var RetrieverQueryArgsSchema = z8.object({
+  query: z8.string().min(1),
+  limit: z8.number().int().positive().max(100).optional()
 });
-var DocGetArgsSchema = z6.object({
-  id: z6.string().min(1).optional(),
-  path: z6.string().min(1).optional()
+var DocGetArgsSchema = z8.object({
+  id: z8.string().min(1).optional(),
+  path: z8.string().min(1).optional()
 }).refine((args) => args.id || args.path, "doc.get requires id or path");
+var WorkflowRunArgsSchema = z8.object({ runId: z8.string().min(1).optional() });
+var DiagnosticsArgsSchema = z8.object({ status: z8.string().min(1).optional(), severity: z8.string().min(1).optional() });
+var RelationsArgsSchema = z8.object({ kind: z8.string().min(1).optional(), limit: z8.number().int().positive().max(500).optional() });
+var ProposalsArgsSchema = z8.object({ action: z8.enum(["list", "propose-links", "propose-normalize", "suggest", "approve", "apply"]).optional(), proposalHash: z8.string().min(1).optional(), artifactPath: z8.string().min(1).optional(), approvedBy: z8.string().min(1).optional(), proposal: z8.unknown().optional() });
 var parseToolArgs = (tool, schema, value) => {
   try {
     return schema.parse(value);
@@ -4411,15 +5994,54 @@ var findDocPath = (index, args) => {
   return doc.path;
 };
 var resolveDocPath = (root, relPath) => {
-  const rootAbs = realpathSync7.native(root);
-  const unresolved = resolve12(rootAbs, relPath);
-  const unresolvedRel = relative5(rootAbs, unresolved);
+  const rootAbs = realpathSync9.native(root);
+  const unresolved = resolve17(rootAbs, relPath);
+  const unresolvedRel = relative9(rootAbs, unresolved);
   if (unresolvedRel.startsWith("..")) throw new Error("doc.get path escapes project root");
-  const abs = realpathSync7.native(unresolved);
-  const rel = relative5(rootAbs, abs);
+  const abs = realpathSync9.native(unresolved);
+  const rel = relative9(rootAbs, abs);
   if (rel.startsWith("..")) throw new Error("doc.get path escapes project root");
   return abs;
 };
+var workflowStateDir = (ctx) => resolve17(ctx.root, ctx.config.workflow?.stateDir ?? ".doc-bridge/workflow");
+var workflowRun = (ctx) => loadWorkflowManifest(workflowStateDir(ctx));
+var ensureLatestRun = (ctx, runId2) => {
+  const run2 = workflowRun(ctx);
+  if (runId2 && run2.runId !== runId2) throw new Error(`Unknown workflow run "${runId2}"`);
+  if (run2.state === "stale" || run2.state === "failed") throw new Error(`Workflow run is ${run2.state}; resume or create a valid run before reading artifacts.`);
+  return run2;
+};
+var workflowSnapshot = (ctx, runId2) => {
+  ensureLatestRun(ctx, runId2);
+  return parseDiscoverySnapshot(loadWorkflowStepOutput(workflowStateDir(ctx), "normalize"));
+};
+var workflowReport = (ctx, runId2) => {
+  ensureLatestRun(ctx, runId2);
+  return parseReconciliationReport(loadWorkflowStepOutput(workflowStateDir(ctx), "reconcile"));
+};
+var proposalPath = (ctx) => join20(ctx.root, ".doc-bridge", "proposal.json");
+var readSavedProposal = (ctx, input) => {
+  if (input !== void 0) return FixProposalV1Schema.parse(input);
+  try {
+    return FixProposalV1Schema.parse(JSON.parse(readFileSync20(proposalPath(ctx), "utf8")));
+  } catch {
+    throw new Error(`No saved fix proposal at ${proposalPath(ctx)}.`);
+  }
+};
+var saveProposal = (ctx, proposal) => {
+  mkdirSync7(join20(ctx.root, ".doc-bridge"), { recursive: true });
+  writeFileSync7(proposalPath(ctx), `${JSON.stringify(proposal, null, 2)}
+`, "utf8");
+};
+var enabledMcpTools = (ctx) => {
+  const configured = ctx.config.surfaces?.mcp?.tools;
+  if (!configured || configured.length === MCP_TOOLS.length && MCP_TOOLS.every((tool) => configured.includes(tool.name))) return MCP_TOOLS;
+  return MCP_TOOLS.filter((tool) => configured.includes(tool.name));
+};
+var assertMcpToolEnabled = (ctx, name) => {
+  if (!MCP_TOOLS.some((tool) => tool.name === name)) throw new Error(`Unknown tool "${name}"`);
+  if (!enabledMcpTools(ctx).some((tool) => tool.name === name)) throw new Error(`MCP tool "${name}" is disabled by configuration.`);
+};
 var handleMcpRequest = (ctx, request) => {
   if (request.method === "initialize") {
     return {
@@ -4428,11 +6050,13 @@ var handleMcpRequest = (ctx, request) => {
       serverInfo: { name: "ak-docs", version: PACKAGE_VERSION }
     };
   }
-  if (request.method === "tools/list") return { tools: MCP_TOOLS };
+  if (request.method === "tools/list") return { tools: enabledMcpTools(ctx) };
   if (request.method === "tools/call") {
     const params = asRecord(request.params);
     const name = params.name;
     const args = asRecord(params.arguments);
+    if (typeof name !== "string") throw new Error("MCP tools/call requires a tool name.");
+    assertMcpToolEnabled(ctx, name);
     const index = () => ctx.loadIndex?.() ?? loadDocBridgeIndex(ctx.root, ctx.config);
     if (name === "handoff.resolve") {
       const parsed = parseToolArgs("handoff.resolve", HandoffResolveArgsSchema, args);
@@ -4450,7 +6074,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(readFileSync20(resolveDocPath(ctx.root, relPath), "utf8"));
     }
     if (name === "gate.status") return textResult(runGates(ctx.root, ctx.config));
     if (name === "retriever.query") {
@@ -4472,6 +6096,81 @@ var handleMcpRequest = (ctx, request) => {
         mergePolicy: { autoMerge: false, requiresHuman: true }
       });
     }
+    if (name === "docbridge.snapshot") {
+      const parsed = parseToolArgs("docbridge.snapshot", WorkflowRunArgsSchema, args);
+      return textResult(redactValue(workflowSnapshot(ctx, parsed.runId)));
+    }
+    if (name === "docbridge.report") {
+      const parsed = parseToolArgs("docbridge.report", WorkflowRunArgsSchema, args);
+      return textResult(redactValue(workflowReport(ctx, parsed.runId)));
+    }
+    if (name === "docbridge.diagnostics") {
+      const parsed = parseToolArgs("docbridge.diagnostics", DiagnosticsArgsSchema, args);
+      const diagnostics = workflowReport(ctx).diagnostics.filter(
+        (diagnostic2) => (!parsed.status || diagnostic2.status === parsed.status) && (!parsed.severity || diagnostic2.severity === parsed.severity)
+      );
+      return textResult(redactValue({ reportHash: workflowReport(ctx).contentHash, diagnostics }));
+    }
+    if (name === "docbridge.relations") {
+      const parsed = parseToolArgs("docbridge.relations", RelationsArgsSchema, args);
+      const snapshot = workflowSnapshot(ctx);
+      return textResult({ snapshotHash: snapshot.contentHash, relations: snapshot.relations.filter((relation) => !parsed.kind || relation.kind === parsed.kind).slice(0, parsed.limit ?? 100) });
+    }
+    if (name === "docbridge.run") {
+      parseToolArgs("docbridge.run", z8.object({}), args);
+      return textResult(workflowRun(ctx));
+    }
+    if (name === "docbridge.proposals") {
+      const parsed = parseToolArgs("docbridge.proposals", ProposalsArgsSchema, args);
+      const run2 = (() => {
+        try {
+          return workflowRun(ctx);
+        } catch {
+          return void 0;
+        }
+      })();
+      if (!parsed.action || parsed.action === "list") {
+        let proposal2;
+        try {
+          proposal2 = readSavedProposal(ctx, void 0);
+        } catch {
+          proposal2 = void 0;
+        }
+        return textResult(redactValue({ ...run2 ? { runId: run2.runId } : {}, proposals: proposal2 ? [proposal2] : [] }));
+      }
+      if (parsed.action === "suggest") {
+        return loadRegistryAgentRunner(ctx.root, ctx.config).then(async (runner) => {
+          const snapshot = workflowSnapshot(ctx);
+          const report = workflowReport(ctx);
+          const adapter = createRegistryAgentAdapter(ctx.root, ctx.config, runner);
+          const proposal2 = await adapter.run(snapshot, report);
+          const savedPath = persistRegistryAgentProposal(workflowStateDir(ctx), proposal2);
+          return textResult(redactValue({ ...run2 ? { runId: run2.runId } : {}, proposal: proposal2, proposalPath: savedPath }));
+        });
+      }
+      const discovered = discoverRepository({ root: ctx.root, config: ctx.config });
+      const options = { baseRevision: discovered.sourceRevision, configurationHash: sha256NormalizedV1(ctx.config), ...ctx.config.project?.name ? { projectName: ctx.config.project.name } : {} };
+      if (parsed.action === "propose-links") {
+        const proposal2 = createMarkdownLinkFixProposal(ctx.root, options);
+        if (proposal2) saveProposal(ctx, proposal2);
+        return textResult(redactValue({ ...run2 ? { runId: run2.runId } : {}, proposal: proposal2 ?? null }));
+      }
+      if (parsed.action === "propose-normalize") {
+        if (!parsed.artifactPath) throw new Error("docbridge.proposals propose-normalize requires artifactPath");
+        const proposal2 = createArtifactNormalizationProposal(ctx.root, parsed.artifactPath, options);
+        if (proposal2) saveProposal(ctx, proposal2);
+        return textResult(redactValue({ ...run2 ? { runId: run2.runId } : {}, proposal: proposal2 ?? null }));
+      }
+      if (parsed.action === "approve") {
+        const proposal2 = approveFixProposal(readSavedProposal(ctx, parsed.proposal), parsed.approvedBy ?? "human");
+        if (parsed.proposalHash && proposal2.approval?.proposalHash !== parsed.proposalHash) throw new Error("proposalHash does not match the saved proposal");
+        saveProposal(ctx, proposal2);
+        return textResult(redactValue({ ...run2 ? { runId: run2.runId } : {}, proposal: proposal2 }));
+      }
+      const proposal = applyFixProposal(ctx.root, readSavedProposal(ctx, parsed.proposal), { currentRevision: discovered.sourceRevision });
+      saveProposal(ctx, proposal);
+      return textResult(redactValue({ ...run2 ? { runId: run2.runId } : {}, proposal }));
+    }
     throw new Error(`Unknown tool "${String(name)}"`);
   }
   if (request.method?.startsWith("notifications/")) return void 0;
@@ -4484,16 +6183,16 @@ var writeFrame = (payload, framing) => {
 \r
 ${body}`);
 };
-var respond = (ctx, request, framing) => {
+var respondMcpRequest = async (ctx, request, framing) => {
   if (request.id === void 0) {
     try {
-      handleMcpRequest(ctx, request);
+      await handleMcpRequest(ctx, request);
     } catch {
     }
     return;
   }
   try {
-    const result = handleMcpRequest(ctx, request);
+    const result = await handleMcpRequest(ctx, request);
     writeFrame({ jsonrpc: "2.0", id: request.id, result: result ?? {} }, framing);
   } catch (error) {
     writeFrame({
@@ -4505,6 +6204,10 @@ var respond = (ctx, request, framing) => {
 };
 var startMcpStdioServer = (ctx) => {
   let buffer = Buffer.alloc(0);
+  let responseChain = Promise.resolve();
+  const enqueueResponse = (request, framing) => {
+    responseChain = responseChain.then(() => respondMcpRequest(ctx, request, framing));
+  };
   process.stdin.on("data", (chunk) => {
     buffer = Buffer.concat([buffer, chunk]);
     while (true) {
@@ -4523,7 +6226,7 @@ var startMcpStdioServer = (ctx) => {
         if (buffer.length < bodyEnd) return;
         const raw2 = buffer.subarray(bodyStart, bodyEnd).toString("utf8");
         buffer = buffer.subarray(bodyEnd);
-        respond(ctx, JSON.parse(raw2), "content-length");
+        enqueueResponse(JSON.parse(raw2), "content-length");
         continue;
       }
       const lineEnd = buffer.indexOf("\n");
@@ -4532,7 +6235,7 @@ var startMcpStdioServer = (ctx) => {
       buffer = buffer.subarray(lineEnd + 1);
       if (!raw) continue;
       try {
-        respond(ctx, JSON.parse(raw), "json-line");
+        enqueueResponse(JSON.parse(raw), "json-line");
       } catch {
         writeFrame({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } }, "json-line");
       }
@@ -4541,6 +6244,237 @@ var startMcpStdioServer = (ctx) => {
   process.stdin.resume();
 };
 
+// src/reconciliation/reconcile.ts
+var ignoredDocumentationRelations = /* @__PURE__ */ new Set(["covers"]);
+var metadataDetection = (relation) => {
+  const detection = relation.metadata?.detection;
+  return typeof detection === "string" ? detection : void 0;
+};
+var relationDetection = (relation) => relation.discriminator ?? metadataDetection(relation) ?? "static";
+var entityResolver = (snapshots) => {
+  const references = /* @__PURE__ */ new Map();
+  const entities = snapshots.flatMap((snapshot) => snapshot.entities).sort((a, b) => a.id.localeCompare(b.id));
+  for (const entity of entities) {
+    references.set(entity.id, entity.id);
+    for (const alias of entity.aliases ?? []) {
+      if (!references.has(alias)) references.set(alias, entity.id);
+    }
+  }
+  return (reference) => references.get(reference) ?? reference;
+};
+var relationBase = (relation, resolveEntity2) => `${resolveEntity2(relation.from)}\0${resolveEntity2(relation.to)}\0${relation.kind}`;
+var evidenceKey = (item) => `${item.source}:${item.path}:${item.lineStart ?? ""}:${item.lineEnd ?? ""}:${item.context ?? ""}`;
+var mergeEvidence = (...relations) => {
+  const merged = /* @__PURE__ */ new Map();
+  for (const relation of relations) {
+    for (const item of relation.evidence) merged.set(evidenceKey(item), item);
+  }
+  return [...merged.values()].sort((a, b) => evidenceKey(a).localeCompare(evidenceKey(b)));
+};
+var diagnosticId = (code, value) => `reconciliation:${code}:${sha256NormalizedV1(value).slice(0, 32)}`;
+var coverageAvailable = (snapshot, relation) => {
+  const status = snapshot.coverage.find(
+    (entry) => entry.scope === "static-imports-and-exports" && (relation.kind === "imports" || relation.kind === "re-exports")
+  )?.status;
+  return status === void 0 || status === "complete";
+};
+var entityById = (snapshots) => {
+  const entities = /* @__PURE__ */ new Map();
+  for (const snapshot of snapshots) {
+    for (const entity of snapshot.entities) if (!entities.has(entity.id)) entities.set(entity.id, entity);
+  }
+  return entities;
+};
+var isUnresolved = (id, entities) => id.startsWith("unresolved:") || entities.get(id)?.kind === "unresolved-reference";
+var relationMatches = (observed, declared, resolveEntity2) => {
+  if (relationBase(observed, resolveEntity2) !== relationBase(declared, resolveEntity2)) return false;
+  return relationDetection(declared) === relationDetection(observed);
+};
+var reportDiagnostic = (code, status, severity, message, evidence2, value, entityIds, relationIds, remediation) => ({
+  id: diagnosticId(code, value),
+  code,
+  status,
+  severity,
+  message,
+  evidence: [...evidence2],
+  ...entityIds?.length ? { entityIds: [...entityIds] } : {},
+  ...relationIds?.length ? { relationIds: [...relationIds] } : {},
+  ...remediation ? { remediation } : {}
+});
+var reconcileKnowledge = (observed, declared) => {
+  const resolveEntity2 = entityResolver([observed, declared]);
+  const entities = entityById([observed, declared]);
+  const observedRelations = observed.relations.filter((relation) => relation.provenance === "observed" && !ignoredDocumentationRelations.has(relation.kind));
+  const declaredRelations = declared.relations.filter((relation) => relation.provenance === "declared" && !ignoredDocumentationRelations.has(relation.kind));
+  const diagnostics = [];
+  for (const entity of declared.entities.filter((item) => isUnresolved(item.id, entities)).sort((a, b) => a.id.localeCompare(b.id))) {
+    diagnostics.push(reportDiagnostic(
+      "UNRESOLVED_ENTITY_REFERENCE",
+      "unresolved",
+      "error",
+      `Declared reference could not be resolved: ${entity.name}.`,
+      entity.evidence,
+      entity.id,
+      [entity.id],
+      void 0,
+      "Resolve the reference to an observed entity ID or configured alias."
+    ));
+  }
+  const declaredByBase = /* @__PURE__ */ new Map();
+  for (const relation of declaredRelations) {
+    const base2 = relationBase(relation, resolveEntity2);
+    const group = declaredByBase.get(base2) ?? [];
+    group.push(relation);
+    declaredByBase.set(base2, group);
+  }
+  for (const group of declaredByBase.values()) {
+    const detections = new Set(group.map(relationDetection));
+    if (detections.size < 2) continue;
+    diagnostics.push(reportDiagnostic(
+      "CONFLICTING_DECLARATIONS",
+      "conflict",
+      "error",
+      "Declarations for the same semantic relation disagree on detection.",
+      mergeEvidence(...group),
+      [relationBase(group[0], resolveEntity2), [...detections].sort()],
+      void 0,
+      group.map((relation) => relation.id),
+      "Keep one detection value for this relation or document the intended distinction with a different relation kind."
+    ));
+  }
+  for (const relation of observedRelations) {
+    const candidates = declaredByBase.get(relationBase(relation, resolveEntity2)) ?? [];
+    const match = candidates.find((candidate) => relationMatches(relation, candidate, resolveEntity2));
+    if (match) {
+      diagnostics.push(reportDiagnostic(
+        "RELATION_CONFIRMED",
+        "confirmed",
+        "info",
+        "Observed relation is covered by a matching declaration.",
+        mergeEvidence(relation, match),
+        relation.id,
+        void 0,
+        [relation.id, match.id]
+      ));
+    } else if (coverageAvailable(observed, relation)) {
+      diagnostics.push(reportDiagnostic(
+        "RELATION_UNDOCUMENTED",
+        "undocumented",
+        "warn",
+        "Observed relation has no matching documentation declaration.",
+        relation.evidence,
+        relation.id,
+        void 0,
+        [relation.id],
+        "Add a matching relation declaration or configure this relation kind as intentionally undocumented."
+      ));
+    }
+  }
+  for (const relation of declaredRelations) {
+    const candidates = observedRelations.filter((candidate) => relationBase(candidate, resolveEntity2) === relationBase(relation, resolveEntity2));
+    const detection = relationDetection(relation);
+    if (candidates.some((candidate) => relationMatches(candidate, relation, resolveEntity2))) continue;
+    if (isUnresolved(resolveEntity2(relation.from), entities) || isUnresolved(resolveEntity2(relation.to), entities)) continue;
+    if (detection === "dynamic" || detection === "external") {
+      diagnostics.push(reportDiagnostic(
+        "RELATION_NOT_ANALYZED",
+        "not-analyzed",
+        "info",
+        `Declared ${detection} relation cannot be verified by the current static analyzer.`,
+        relation.evidence,
+        relation.id,
+        void 0,
+        [relation.id],
+        "Enable a compatible analyzer or provide explicit observed evidence before treating this relation as confirmed."
+      ));
+    } else if (coverageAvailable(observed, relation)) {
+      diagnostics.push(reportDiagnostic(
+        "DECLARED_RELATION_STALE",
+        "stale-or-unverified",
+        "warn",
+        candidates.length ? "Declared relation has incompatible observed evidence." : "Declared static relation was not observed.",
+        candidates.length ? mergeEvidence(relation, ...candidates) : relation.evidence,
+        relation.id,
+        void 0,
+        [relation.id, ...candidates.map((candidate) => candidate.id)],
+        "Update the declaration or the implementation so both graphs describe the same relation."
+      ));
+    }
+  }
+  const sortedDiagnostics = [...diagnostics].sort((a, b) => a.id.localeCompare(b.id));
+  const base = {
+    type: "reconciliation-report",
+    schemaVersion: 1,
+    contentHash: "0".repeat(64),
+    contentHashAlgo: observed.contentHashAlgo,
+    project: observed.project,
+    sourceRevision: observed.sourceRevision,
+    sourceRevisionKind: observed.sourceRevisionKind,
+    configurationHash: observed.configurationHash,
+    pipelineVersion: observed.pipelineVersion,
+    analyzerVersions: observed.analyzerVersions,
+    snapshotHash: observed.contentHash,
+    diagnostics: sortedDiagnostics,
+    summary: {
+      entityCount: observed.entities.length,
+      relationCount: observedRelations.length,
+      diagnosticCount: sortedDiagnostics.length
+    }
+  };
+  return ReconciliationReportV1Schema.parse({ ...base, contentHash: contentHashForArtifactV1(base) });
+};
+
+// src/report/html.ts
+var escapeHtml = (value) => String(value).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+var anchor = (prefix, value) => `${prefix}-${value.replace(/[^A-Za-z0-9_-]+/g, "-")}`;
+var evidenceText = (evidence2, includeSnippets) => {
+  const location = `${evidence2.path}${evidence2.lineStart ? `:${evidence2.lineStart}${evidence2.lineEnd && evidence2.lineEnd !== evidence2.lineStart ? `-${evidence2.lineEnd}` : ""}` : ""}`;
+  return `${location}${includeSnippets && evidence2.context ? ` \u2014 ${redactSecrets(evidence2.context)}` : ""}`;
+};
+var errorPage = (message) => `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Doc Bridge report error</title><style>body{font:16px system-ui;margin:3rem;color:#311}main{max-width:60rem;margin:auto;border:1px solid #d99;padding:2rem;border-radius:8px;background:#fff8f8}code{white-space:pre-wrap}</style></head><body><main><h1>Doc Bridge report unavailable</h1><p>The saved snapshot/report could not be rendered.</p><code>${escapeHtml(message)}</code><p>Run <code>ak-docs check</code> to regenerate valid artifacts.</p></main></body></html>`;
+var embeddedJson = (value) => JSON.stringify(value).replaceAll("<", "\\u003c");
+var controls = (statusOptions) => `<section id="controls"><label>Search <input id="search" type="search" placeholder="entity, relation, diagnostic"></label><label>Severity <select id="severity"><option value="">Any</option><option>error</option><option>warn</option><option>info</option></select></label><label>Provenance <select id="provenance"><option value="">Any</option><option>observed</option><option>declared</option><option>proposed</option></select></label><label>Status <select id="status"><option value="">Any</option>${statusOptions.map((value) => `<option>${value}</option>`).join("")}</select></label><label>Analyzer <input id="analyzer" type="search" placeholder="js-ts, report"></label><label>Entity <input id="entity" type="search" placeholder="entity id"></label><label>Relation <input id="relation" type="search" placeholder="relation id"></label><button id="reset">Reset filters</button></section>`;
+var renderCompact = (snapshot, report, entityAnchors, includeSnippets) => {
+  const entities = snapshot.entities.map((entity) => ({ id: entity.id, name: entity.name, kind: entity.kind, anchor: entityAnchors.get(entity.id) ?? anchor("entity", entity.id) }));
+  const entityIndexes = new Map(entities.map((entity, index) => [entity.id, index]));
+  const relations = snapshot.relations.map((relation) => ({ id: relation.id, from: entityIndexes.get(relation.from), to: entityIndexes.get(relation.to), kind: relation.kind, provenance: relation.provenance }));
+  const diagnostics = report.diagnostics.map((diagnostic2) => ({
+    ...diagnostic2,
+    evidence: diagnostic2.evidence.map(({ context, ...evidence2 }) => includeSnippets && context ? { ...evidence2, context: redactSecrets(context) } : evidence2)
+  }));
+  const data = embeddedJson({ entities, relations, diagnostics, coverage: snapshot.coverage });
+  const script = `const data=${data};const esc=(v)=>String(v).replaceAll('&','&amp;').replaceAll('<','&lt;').replaceAll('>','&gt;').replaceAll('"','&quot;').replaceAll("'",'&#39;');const entityById=new Map(data.entities.map((e)=>[e.id,e]));const entityLink=(id)=>{const e=entityById.get(id);return '<a href="#'+esc(e?.anchor??'entity-'+id)+'">'+esc(e?.name??id)+'</a>'};const evidenceText=(e)=>esc(e.path+(e.lineStart?':'+e.lineStart+(e.lineEnd&&e.lineEnd!==e.lineStart?'-'+e.lineEnd:''):'')+(e.context?' \u2014 '+e.context:''));const render=()=>{document.querySelector('#map').innerHTML=data.entities.map((e)=>'<div class="node" id="'+esc(e.anchor)+'" data-node="'+esc(e.anchor)+'" data-search="'+esc([e.id,e.name,e.kind].join(' '))+'"><a href="#'+esc(e.anchor)+'">'+esc(e.name)+'</a><br><span class="muted">'+esc(e.kind)+'</span></div>').join('');document.querySelector('#relations').innerHTML=data.relations.map((r)=>{const from=data.entities[r.from],to=data.entities[r.to];return '<tr id="relation-'+esc(r.id)+'" data-relation="'+esc(r.id)+'" data-from="'+esc(from?.anchor??'')+'" data-to="'+esc(to?.anchor??'')+'" data-kind="'+esc(r.kind)+'" data-provenance="'+esc(r.provenance)+'" data-analyzer="snapshot" data-search="'+esc([r.id,from?.id,to?.id,r.kind,r.provenance].join(' '))+'"><td>'+esc(r.kind)+'</td><td>'+entityLink(from?.id??'')+'</td><td>'+entityLink(to?.id??'')+'</td><td>'+esc(r.provenance)+'</td></tr>'}).join('');document.querySelector('#diagnostics').innerHTML=data.diagnostics.length?data.diagnostics.map((d)=>'<article id="diagnostic-'+esc(d.id)+'" class="diagnostic" data-status="'+esc(d.status)+'" data-severity="'+esc(d.severity)+'" data-analyzer="report" data-entity="'+esc((d.entityIds??[]).join(' '))+'" data-relation="'+esc((d.relationIds??[]).join(' '))+'" data-search="'+esc([d.id,d.code,d.message,...(d.entityIds??[]),...(d.relationIds??[])].join(' '))+'"><h3><a href="#diagnostic-'+esc(d.id)+'">'+esc(d.code)+'</a> <span class="badge '+esc(d.severity)+'">'+esc(d.severity)+'</span></h3><p>'+esc(d.message)+'</p><p>Status: <b>'+esc(d.status)+'</b></p><ul>'+d.evidence.map((e)=>'<li>'+evidenceText(e)+'</li>').join('')+'</ul>'+(d.entityIds?.length?'<p>Entities: '+d.entityIds.map(entityLink).join(', ')+'</p>':'')+'</article>').join(''):'<p class="muted">No diagnostics.</p>';document.querySelector('#coverage').innerHTML=data.coverage.length?data.coverage.map((c)=>'<li data-status="'+esc(c.status)+'" data-analyzer="'+esc(c.analyzer)+'" data-search="'+esc([c.analyzer,c.scope,c.status,c.reason??''].join(' '))+'"><b>'+esc(c.analyzer)+'</b> / '+esc(c.scope)+': '+esc(c.status)+(c.reason?' \u2014 '+esc(c.reason):'')+'</li>').join(''):'<li class="muted">No coverage metadata.</li>';document.querySelectorAll('[data-node]').forEach((node)=>node.onclick=()=>{const id=node.dataset.node;document.querySelectorAll('[data-from],[data-to]').forEach((edge)=>edge.classList.toggle('hidden',edge.dataset.from!==id&&edge.dataset.to!==id))});};const apply=()=>{const q=document.querySelector('#search').value.toLowerCase(),severity=document.querySelector('#severity').value,provenance=document.querySelector('#provenance').value,status=document.querySelector('#status').value,analyzer=document.querySelector('#analyzer').value.toLowerCase(),entity=document.querySelector('#entity').value.toLowerCase(),relation=document.querySelector('#relation').value.toLowerCase();document.querySelectorAll('[data-search]').forEach((el)=>el.classList.toggle('hidden',Boolean(q&&!el.dataset.search.toLowerCase().includes(q)||severity&&el.dataset.severity!==severity||provenance&&el.dataset.provenance!==provenance||status&&el.dataset.status!==status||analyzer&&!el.dataset.analyzer?.toLowerCase().includes(analyzer)||entity&&!el.dataset.entity?.toLowerCase().includes(entity)||relation&&!el.dataset.relation?.toLowerCase().includes(relation))));};render();for(const id of ['search','analyzer','entity','relation'])document.querySelector('#'+id).oninput=apply;for(const id of ['severity','provenance','status'])document.querySelector('#'+id).onchange=apply;document.querySelector('#reset').onclick=()=>{for(const id of ['search','analyzer','entity','relation'])document.querySelector('#'+id).value='';for(const id of ['severity','provenance','status'])document.querySelector('#'+id).value='';apply()};`;
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Doc Bridge \u2014 ${escapeHtml(snapshot.project.name)}</title><style>body{font:14px system-ui;margin:0;color:#18202a;background:#f5f7fa}header,main{max-width:1200px;margin:auto;padding:1.25rem}header{background:#18202a;color:white;max-width:none;padding-left:calc((100% - 1200px)/2);padding-right:calc((100% - 1200px)/2)}main{background:white}section{margin:1.5rem 0;border-top:1px solid #d7dde5;padding-top:1rem}table{border-collapse:collapse;width:100%;margin-top:.75rem}td,th{border-bottom:1px solid #e5e9ef;text-align:left;padding:.45rem;vertical-align:top}input,select,button{padding:.45rem;margin:.15rem;border:1px solid #b9c3d0;border-radius:4px;background:white}.badge{border-radius:1rem;padding:.15rem .5rem;background:#dce4ee}.error{background:#ffd9d9}.warn{background:#fff0c2}.info{background:#dcecff}.diagnostic{border:1px solid #d7dde5;border-left:4px solid #9aa7b5;padding:.75rem;margin:.75rem 0}.diagnostic:target,tr:target{background:#fff8cf}.muted{color:#5d6a78}a{color:#0b5cad}#map{display:flex;gap:1rem;flex-wrap:wrap}.node{border:1px solid #9aa7b5;padding:.5rem;border-radius:4px}.hidden{display:none}</style></head><body><header><h1>Doc Bridge: ${escapeHtml(snapshot.project.name)}</h1><p>Offline architecture and documentation reconciliation report</p><p class="muted">Snapshot ${escapeHtml(snapshot.contentHash)} \xB7 Report ${escapeHtml(report.contentHash)} \xB7 Revision ${escapeHtml(snapshot.sourceRevision)}</p></header><main>${controls(["confirmed", "undocumented", "stale-or-unverified", "conflict", "unresolved", "not-analyzed"])}<section id="architecture"><h2>Architecture map</h2><p>Large snapshots are rendered from compact canonical data after load to keep the offline report bounded.</p><div id="map"></div><h3>Relations</h3><table><thead><tr><th>Kind</th><th>From</th><th>To</th><th>Provenance</th></tr></thead><tbody id="relations"></tbody></table></section><section id="diagnostic-lens"><h2>Diagnostic lens</h2><p>Findings: ${report.diagnostics.length}</p><div id="diagnostics"></div></section><section id="coverage"><h2>Coverage and unsupported areas</h2><ul></ul></section><section id="metadata"><h2>Run metadata</h2><dl><dt>Source revision</dt><dd>${escapeHtml(snapshot.sourceRevision)} (${escapeHtml(snapshot.sourceRevisionKind)})</dd><dt>Configuration hash</dt><dd>${escapeHtml(snapshot.configurationHash)}</dd><dt>Pipeline</dt><dd>${escapeHtml(snapshot.pipelineVersion)}</dd></dl></section></main><script>${script}</script></body></html>`;
+};
+var render = (input, options) => {
+  const { snapshot, report } = input;
+  const includeSnippets = options.includeSnippets === true;
+  const entityAnchors = new Map(snapshot.entities.map((entity, index) => [entity.id, entity.id.length > 64 ? `entity-n${index}` : anchor("entity", entity.id)]));
+  if (snapshot.entities.length > 500 || report.diagnostics.length > 1e3) return renderCompact(snapshot, report, entityAnchors, includeSnippets);
+  const entityNames = new Map(snapshot.entities.map((entity) => [entity.id, entity.name]));
+  const entityAnchor = (id) => entityAnchors.get(id) ?? anchor("entity", id);
+  const entityLabel = (id) => entityNames.get(id) ?? id;
+  const entityLink = (id) => `<a href="#${entityAnchor(id)}">${escapeHtml(entityLabel(id))}</a>`;
+  const relations = snapshot.relations.map((relation) => `<tr id="${anchor("relation", relation.id)}" data-relation="${escapeHtml(relation.id)}" data-from="${entityAnchor(relation.from)}" data-to="${entityAnchor(relation.to)}" data-kind="${escapeHtml(relation.kind)}" data-provenance="${escapeHtml(relation.provenance)}" data-analyzer="snapshot" data-search="${escapeHtml(`${relation.id} ${relation.from} ${relation.to} ${relation.kind} ${relation.provenance}`)}"><td>${escapeHtml(relation.kind)}</td><td>${entityLink(relation.from)}</td><td>${entityLink(relation.to)}</td><td>${escapeHtml(relation.provenance)}</td></tr>`).join("");
+  const diagnostics = report.diagnostics.map((diagnostic2) => `<article id="${anchor("diagnostic", diagnostic2.id)}" class="diagnostic" data-status="${escapeHtml(diagnostic2.status)}" data-severity="${escapeHtml(diagnostic2.severity)}" data-analyzer="report" data-entity="${escapeHtml(diagnostic2.entityIds?.join(" ") ?? "")}" data-relation="${escapeHtml(diagnostic2.relationIds?.join(" ") ?? "")}" data-search="${escapeHtml(`${diagnostic2.id} ${diagnostic2.code} ${diagnostic2.message} ${diagnostic2.entityIds?.join(" ") ?? ""} ${diagnostic2.relationIds?.join(" ") ?? ""}`)}"><h3><a href="#${anchor("diagnostic", diagnostic2.id)}">${escapeHtml(diagnostic2.code)}</a> <span class="badge ${escapeHtml(diagnostic2.severity)}">${escapeHtml(diagnostic2.severity)}</span></h3><p>${escapeHtml(diagnostic2.message)}</p><p>Status: <b>${escapeHtml(diagnostic2.status)}</b></p><ul>${diagnostic2.evidence.map((item) => `<li>${escapeHtml(evidenceText(item, includeSnippets))}</li>`).join("")}</ul>${diagnostic2.entityIds?.length ? `<p>Entities: ${diagnostic2.entityIds.map((id) => entityLink(id)).join(", ")}</p>` : ""}</article>`).join("");
+  const coverage = snapshot.coverage.map((entry) => `<li data-status="${escapeHtml(entry.status)}" data-analyzer="${escapeHtml(entry.analyzer)}" data-search="${escapeHtml(`${entry.analyzer} ${entry.scope} ${entry.status} ${entry.reason ?? ""}`)}"><b>${escapeHtml(entry.analyzer)}</b> / ${escapeHtml(entry.scope)}: ${escapeHtml(entry.status)}${entry.reason ? ` \u2014 ${escapeHtml(entry.reason)}` : ""}</li>`).join("");
+  const nodes = snapshot.entities.map((entity) => `<div class="node" id="${entityAnchor(entity.id)}" data-node="${entityAnchor(entity.id)}"><a href="#${entityAnchor(entity.id)}">${escapeHtml(entity.name)}</a><br><span class="muted">${escapeHtml(entity.kind)}</span></div>`).join("");
+  const script = `const q=document.querySelector('#search'),severity=document.querySelector('#severity'),provenance=document.querySelector('#provenance'),status=document.querySelector('#status'),analyzer=document.querySelector('#analyzer'),entity=document.querySelector('#entity'),relation=document.querySelector('#relation');function apply(){const term=q.value.toLowerCase(),entityTerm=entity.value.toLowerCase(),relationTerm=relation.value.toLowerCase();document.querySelectorAll('[data-search]').forEach((el)=>{const match=(!term||el.dataset.search.toLowerCase().includes(term))&&(!severity.value||el.dataset.severity===severity.value)&&(!provenance.value||el.dataset.provenance===provenance.value)&&(!status.value||el.dataset.status===status.value)&&(!analyzer.value||el.dataset.analyzer?.toLowerCase().includes(analyzer.value.toLowerCase()))&&(!entityTerm||el.dataset.entity?.toLowerCase().includes(entityTerm))&&(!relationTerm||el.dataset.relation?.toLowerCase().includes(relationTerm));el.classList.toggle('hidden',!match)});}q.oninput=apply;severity.onchange=apply;provenance.onchange=apply;status.onchange=apply;analyzer.oninput=apply;entity.oninput=apply;relation.oninput=apply;document.querySelector('#reset').onclick=()=>{q.value='';severity.value='';provenance.value='';status.value='';analyzer.value='';entity.value='';relation.value='';apply()};document.querySelectorAll('[data-node]').forEach((node)=>node.onclick=()=>{const id=node.dataset.node;document.querySelectorAll('[data-from],[data-to]').forEach((edge)=>edge.classList.toggle('hidden',edge.dataset.from!==id&&edge.dataset.to!==id));});`;
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Doc Bridge \u2014 ${escapeHtml(snapshot.project.name)}</title><style>body{font:14px system-ui;margin:0;color:#18202a;background:#f5f7fa}header,main{max-width:1200px;margin:auto;padding:1.25rem}header{background:#18202a;color:white;max-width:none;padding-left:calc((100% - 1200px)/2);padding-right:calc((100% - 1200px)/2)}main{background:white}section{margin:1.5rem 0;border-top:1px solid #d7dde5;padding-top:1rem}table{border-collapse:collapse;width:100%;margin-top:.75rem}td,th{border-bottom:1px solid #e5e9ef;text-align:left;padding:.45rem;vertical-align:top}input,select,button{padding:.45rem;margin:.15rem;border:1px solid #b9c3d0;border-radius:4px;background:white}.badge{border-radius:1rem;padding:.15rem .5rem;background:#dce4ee}.error{background:#ffd9d9}.warn{background:#fff0c2}.info{background:#dcecff}.diagnostic{border:1px solid #d7dde5;border-left:4px solid #9aa7b5;padding:.75rem;margin:.75rem 0}.diagnostic:target,tr:target{background:#fff8cf}.muted{color:#5d6a78}a{color:#0b5cad}#map{display:flex;gap:1rem;flex-wrap:wrap}.node{border:1px solid #9aa7b5;padding:.5rem;border-radius:4px}.hidden{display:none}</style></head><body><header><h1>Doc Bridge: ${escapeHtml(snapshot.project.name)}</h1><p>Offline architecture and documentation reconciliation report</p><p class="muted">Snapshot ${escapeHtml(snapshot.contentHash)} \xB7 Report ${escapeHtml(report.contentHash)} \xB7 Revision ${escapeHtml(snapshot.sourceRevision)}</p></header><main><section id="controls"><label>Search <input id="search" type="search" placeholder="entity, relation, diagnostic"></label><label>Severity <select id="severity"><option value="">Any</option><option>error</option><option>warn</option><option>info</option></select></label><label>Provenance <select id="provenance"><option value="">Any</option><option>observed</option><option>declared</option><option>proposed</option></select></label><label>Status <select id="status"><option value="">Any</option>${["confirmed", "undocumented", "stale-or-unverified", "conflict", "unresolved", "not-analyzed"].map((value) => `<option>${value}</option>`).join("")}</select></label><label>Analyzer <input id="analyzer" type="search" placeholder="js-ts, report"></label><label>Entity <input id="entity" type="search" placeholder="entity id"></label><label>Relation <input id="relation" type="search" placeholder="relation id"></label><button id="reset">Reset filters</button></section><section id="architecture"><h2>Architecture map</h2><p>Observed and declared relations are rendered from the canonical snapshot; browser code does not infer edges.</p><div id="map">${nodes}</div><h3>Relations</h3><table><thead><tr><th>Kind</th><th>From</th><th>To</th><th>Provenance</th></tr></thead><tbody id="relations">${relations}</tbody></table></section><section id="diagnostic-lens"><h2>Diagnostic lens</h2><p>Findings: ${report.diagnostics.length}</p><div id="diagnostics">${diagnostics || '<p class="muted">No diagnostics.</p>'}</div></section><section id="coverage"><h2>Coverage and unsupported areas</h2><ul>${coverage || "<li>No coverage metadata.</li>"}</ul></section><section id="metadata"><h2>Run metadata</h2><dl><dt>Source revision</dt><dd>${escapeHtml(snapshot.sourceRevision)} (${escapeHtml(snapshot.sourceRevisionKind)})</dd><dt>Configuration hash</dt><dd>${escapeHtml(snapshot.configurationHash)}</dd><dt>Pipeline</dt><dd>${escapeHtml(snapshot.pipelineVersion)}</dd></dl></section></main><script>${script}</script></body></html>`;
+};
+var renderOfflineReport = (input, options = {}) => {
+  try {
+    if (!input || typeof input !== "object") throw new Error("Input must contain snapshot and report artifacts.");
+    const value = input;
+    const snapshot = DiscoverySnapshotV1Schema.parse(value.snapshot);
+    const report = ReconciliationReportV1Schema.parse(value.report);
+    if (report.snapshotHash !== snapshot.contentHash) throw new Error("Report snapshotHash does not match snapshot contentHash.");
+    return render({ snapshot, report }, options);
+  } catch (error) {
+    return errorPage(error instanceof Error ? error.message : String(error));
+  }
+};
+
 // src/cli/program.ts
 var usage = `ak-docs \u2014 human\u2194agent documentation bridge (@agentskit/doc-bridge)
 
@@ -4549,11 +6483,17 @@ 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 discover [--text|--json]
+  ak-docs scan | reconcile | check | map [--text|--json] [--html]
+  ak-docs fix propose links|normalize <artifact> [--output <file>]
+  ak-docs fix approve|apply <proposal.json> [--by <name>]
+  ak-docs suggest [--json|--text]   run the configured local Registry agent
   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 rules run <report.json> [--preset default|recommended|strict] [--severity rule=level] [--ignore rule]
   ak-docs conformance run documentation-standard-v1 [--text|--json]
   ak-docs mcp
   ak-docs mcp install --cursor | --claude
@@ -4613,8 +6553,16 @@ var parseArgs = (argv) => {
   else if (positional[0] === "memory") command = "memory";
   else if (positional[0] === "playbook") command = "playbook";
   else if (positional[0] === "registry") command = "registry";
+  else if (positional[0] === "discover") command = "discover";
+  else if (positional[0] === "scan") command = "scan";
+  else if (positional[0] === "reconcile") command = "reconcile";
+  else if (positional[0] === "check") command = "check";
+  else if (positional[0] === "map") command = "map";
+  else if (positional[0] === "fix") command = "fix";
+  else if (positional[0] === "suggest") command = "suggest";
   else if (positional[0] === "index") command = "index";
   else if (positional[0] === "gate") command = "gate";
+  else if (positional[0] === "rules") command = "rules";
   else if (positional[0] === "mcp") command = "mcp";
   else if (positional[0] === "doctor") command = "doctor";
   else if (positional[0] === "demo") command = "demo";
@@ -4628,6 +6576,28 @@ var parseArgs = (argv) => {
   else if (positional[0] === "conformance") command = "conformance";
   return { command, flags, configPath, positional };
 };
+var optionValues = (argv, name) => {
+  const values = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg?.startsWith(`${name}=`)) values.push(arg.slice(name.length + 1));
+    else if (arg === name && argv[index + 1] && !argv[index + 1]?.startsWith("-")) {
+      values.push(argv[index + 1]);
+      index += 1;
+    }
+  }
+  return values;
+};
+var parseRuleAssignments = (values, parseValue) => {
+  const result = {};
+  for (const value of values) {
+    const separator = value.indexOf("=");
+    if (separator <= 0 || separator === value.length - 1) throw new Error(`Invalid rule assignment "${value}". Use rule=value.`);
+    const key = value.slice(0, separator);
+    result[key] = parseValue(value.slice(separator + 1));
+  }
+  return result;
+};
 var writeJson2 = (payload) => {
   process.stdout.write(`${JSON.stringify(payload, null, 2)}
 `);
@@ -4719,12 +6689,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 = resolve13(root, entry.path);
-  const rootAbs = resolve13(root);
+  const abs = resolve18(root, entry.path);
+  const rootAbs = resolve18(root);
   if (abs !== rootAbs && !abs.startsWith(`${rootAbs}/`)) {
     throw new Error(`Indexed doc escapes project root: ${entry.path}`);
   }
-  return readFileSync17(abs, "utf8");
+  return readFileSync21(abs, "utf8");
 };
 var runAskRepl = async (root, config) => {
   const index = loadDocBridgeIndex(root, config);
@@ -4799,10 +6769,197 @@ var diagnosticNextCommands = (config, result) => {
     "ak-docs index"
   ];
 };
+var workflowOptions = (root, config, sourceRevision2, stage, handlers) => ({
+  root,
+  ...config.workflow?.stateDir ? { stateDir: config.workflow.stateDir } : {},
+  sourceRevision: sourceRevision2,
+  configurationHash: sha256NormalizedV1(config),
+  stage,
+  handlers
+});
+var scanWorkflow = (root, config) => {
+  const discovered = discoverRepository({ root, config });
+  runWorkflow(workflowOptions(root, config, discovered.sourceRevision, "collect", { collect: () => discovered }));
+  return runWorkflow(workflowOptions(root, config, discovered.sourceRevision, "normalize", { normalize: ({ input }) => input }));
+};
+var documentationInputs = (root, snapshot) => snapshot.entities.filter((entity) => entity.kind === "document" && entity.path).map((entity) => ({ path: entity.path, content: readFileSync21(resolve18(root, entity.path), "utf8") }));
+var reconcileWorkflow = (root, config) => {
+  const scanned = scanWorkflow(root, config);
+  const snapshot = parseDiscoverySnapshot(loadWorkflowStepOutput(scanned.stateDir, "normalize"));
+  const declared = applyDocumentationDeclarations(snapshot, documentationInputs(root, snapshot)).snapshot;
+  const report = reconcileKnowledge(snapshot, declared);
+  return runWorkflow(workflowOptions(root, config, snapshot.sourceRevision, "reconcile", { reconcile: () => report }));
+};
+var checkWorkflow = (root, config) => {
+  const reconciled = reconcileWorkflow(root, config);
+  const report = parseReconciliationReport(loadWorkflowStepOutput(reconciled.stateDir, "reconcile"));
+  const evaluated = runWorkflow(workflowOptions(root, config, report.sourceRevision, "evaluate", { evaluate: () => evaluateRules(report, { ...config.rules ? { config: config.rules } : {} }) }));
+  return runWorkflow(workflowOptions(root, config, report.sourceRevision, "report", { report: ({ input }) => input }));
+};
+var workflowOutput = (result) => {
+  const snapshot = (() => {
+    try {
+      return parseDiscoverySnapshot(loadWorkflowStepOutput(result.stateDir, "normalize"));
+    } catch {
+      return void 0;
+    }
+  })();
+  const report = (() => {
+    try {
+      return parseReconciliationReport(loadWorkflowStepOutput(result.stateDir, "reconcile"));
+    } catch {
+      return void 0;
+    }
+  })();
+  const rules = (() => {
+    try {
+      const value = loadWorkflowStepOutput(result.stateDir, "evaluate");
+      return value && typeof value === "object" ? value : void 0;
+    } catch {
+      return void 0;
+    }
+  })();
+  return {
+    ok: result.run.state !== "failed" && result.run.state !== "stale",
+    runId: result.run.runId,
+    state: result.run.state,
+    stateDir: result.stateDir,
+    artifactRefs: result.run.artifactRefs,
+    steps: result.run.steps,
+    reusedStages: result.reusedStages,
+    ...snapshot ? { snapshotHash: snapshot.contentHash, sourceRevision: snapshot.sourceRevision, configurationHash: snapshot.configurationHash, coverage: snapshot.coverage } : {},
+    ...report ? { reportHash: report.contentHash, diagnostics: report.diagnostics } : {},
+    ...rules ? { rules } : {}
+  };
+};
+var runWorkflowCommand = (command, flags, configPath, argv) => {
+  try {
+    const { config, root } = loadProject(configPath);
+    const result = command === "scan" ? scanWorkflow(root, config) : command === "reconcile" ? reconcileWorkflow(root, config) : checkWorkflow(root, config);
+    const output = workflowOutput(result);
+    if (command === "map") output.kind = "architecture-map";
+    if (command === "map" && flags.has("--html")) {
+      const snapshot = parseDiscoverySnapshot(loadWorkflowStepOutput(result.stateDir, "normalize"));
+      const report = parseReconciliationReport(loadWorkflowStepOutput(result.stateDir, "reconcile"));
+      const outputPath = optionValues(argv, "--output")[0] ?? ".doc-bridge/report.html";
+      const htmlPath = resolve18(root, outputPath);
+      mkdirSync8(dirname10(htmlPath), { recursive: true });
+      writeFileSync8(htmlPath, renderOfflineReport({ snapshot, report }), "utf8");
+      output.htmlPath = htmlPath;
+    }
+    if (wantsTextOutput(flags, config)) {
+      writeLines([`Run: ${String(output.runId)}`, `State: ${String(output.state)}`, ...output.snapshotHash ? [`Snapshot: ${String(output.snapshotHash)}`] : [], ...output.reportHash ? [`Report: ${String(output.reportHash)}`] : [], `Artifacts: ${String(output.artifactRefs.length)}`]);
+    } else writeJson2(output);
+    const ruleExitCode = output.rules && typeof output.rules === "object" && "exitCode" in output.rules && output.rules.exitCode === 1 ? 1 : 0;
+    return result.run.state === "failed" ? 1 : ruleExitCode;
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+    return 2;
+  }
+};
+var runRulesCommand = (argv, flags, positional, configPath) => {
+  const action = positional[1];
+  const reportPath = positional[2];
+  if (action !== "run" || !reportPath) {
+    process.stderr.write("Usage: ak-docs rules run <report.json> [--preset default|recommended|strict] [--severity rule=level] [--ignore rule]\n");
+    return 2;
+  }
+  try {
+    const { config } = loadProject(configPath);
+    const report = parseReconciliationReport(JSON.parse(readFileSync21(resolve18(reportPath), "utf8")));
+    const presetValue = optionValues(argv, "--preset")[0];
+    const preset = presetValue === void 0 ? void 0 : ["default", "recommended", "strict"].includes(presetValue) ? presetValue : (() => {
+      throw new Error(`Invalid rules preset "${presetValue}".`);
+    })();
+    const severity = {};
+    for (const [rule, level] of Object.entries(parseRuleAssignments(optionValues(argv, "--severity"), parseRuleSeverity))) {
+      severity[parseRuleId(rule)] = level;
+    }
+    const ignore = optionValues(argv, "--ignore").map(parseRuleId);
+    const result = evaluateRules(report, {
+      ...config.rules ? { config: config.rules } : {},
+      ...preset ? { preset } : {},
+      ...Object.keys(severity).length ? { severity } : {},
+      ...ignore.length ? { ignore } : {},
+      ...optionValues(argv, "--critical-entity").length ? { criticalEntities: optionValues(argv, "--critical-entity") } : {},
+      ...optionValues(argv, "--critical-path").length ? { criticalPaths: optionValues(argv, "--critical-path") } : {}
+    });
+    if (wantsTextOutput(flags, config)) {
+      writeLines([
+        `Rules: ${result.mode}`,
+        `Findings: ${result.findings.length}`,
+        ...result.findings.length ? result.findings.map((finding) => `  [${finding.severity}] ${finding.code}: ${finding.message}`) : ["  (none)"],
+        `Exit code: ${result.exitCode}`
+      ]);
+    } else {
+      writeJson2({ ok: result.exitCode === 0, reportHash: report.contentHash, ...result });
+    }
+    return result.exitCode;
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+    return 2;
+  }
+};
+var runFixCommand = (argv, positional, configPath) => {
+  try {
+    const { config, root } = loadProject(configPath);
+    const action = positional[1];
+    const proposalPath2 = positional[2];
+    const sourceRevision2 = discoverRepository({ root, config }).sourceRevision;
+    const fixOptions = { baseRevision: sourceRevision2, configurationHash: sha256NormalizedV1(config), ...config.project?.name ? { projectName: config.project.name } : {} };
+    if (action === "propose") {
+      const proposal2 = positional[2] === "links" ? createMarkdownLinkFixProposal(root, fixOptions) : positional[2] === "normalize" && positional[3] ? createArtifactNormalizationProposal(root, positional[3], fixOptions) : void 0;
+      if (!proposal2) {
+        writeJson2({ ok: true, proposal: null });
+        return 0;
+      }
+      const outputPath = optionValues(argv, "--output")[0];
+      if (outputPath) {
+        mkdirSync8(dirname10(resolve18(root, outputPath)), { recursive: true });
+        writeFileSync8(resolve18(root, outputPath), `${JSON.stringify(proposal2, null, 2)}
+`, "utf8");
+      }
+      writeJson2({ ok: true, proposal: proposal2, ...outputPath ? { proposalPath: resolve18(root, outputPath) } : {} });
+      return 0;
+    }
+    if (!proposalPath2 || !["approve", "apply"].includes(action ?? "")) throw new Error("Usage: ak-docs fix propose links|normalize <artifact> [--output <file>] | fix approve|apply <proposal.json> [--by <name>]");
+    const file = resolve18(root, proposalPath2);
+    const proposal = JSON.parse(readFileSync21(file, "utf8"));
+    const result = action === "approve" ? approveFixProposal(proposal, optionValues(argv, "--by")[0] ?? "human") : applyFixProposal(root, proposal, { currentRevision: sourceRevision2 });
+    writeFileSync8(file, `${JSON.stringify(result, null, 2)}
+`, "utf8");
+    writeJson2({ ok: true, proposal: result, proposalPath: file });
+    return 0;
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+    return 2;
+  }
+};
+var runSuggestCommand = async (flags, configPath) => {
+  try {
+    const { config, root } = loadProject(configPath);
+    const stateDir = resolve18(root, config.workflow?.stateDir ?? ".doc-bridge/workflow");
+    const snapshot = parseDiscoverySnapshot(loadWorkflowStepOutput(stateDir, "normalize"));
+    const report = parseReconciliationReport(loadWorkflowStepOutput(stateDir, "reconcile"));
+    const adapter = createRegistryAgentAdapter(root, config, await loadRegistryAgentRunner(root, config));
+    const proposal = await adapter.run(snapshot, report);
+    const proposalPath2 = persistRegistryAgentProposal(stateDir, proposal);
+    if (flags.has("--text")) writeLines([`Agent: ${adapter.metadata.id}`, `Proposal: ${proposal.proposalId}`, `Hash: ${proposal.contentHash}`, `Saved: ${proposalPath2}`]);
+    else writeJson2({ ok: true, proposal, proposalPath: proposalPath2 });
+    return 0;
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+    return 2;
+  }
+};
 var writeIfMissing = (path, contents) => {
-  if (existsSync17(path)) return false;
-  mkdirSync5(dirname8(path), { recursive: true });
-  writeFileSync4(path, contents, "utf8");
+  if (existsSync21(path)) return false;
+  mkdirSync8(dirname10(path), { recursive: true });
+  writeFileSync8(path, contents, "utf8");
   return true;
 };
 var demoOwnership = {
@@ -4905,7 +7062,7 @@ var scaffoldWorkspaceDocs = (root, config) => {
   const created = [];
   const skipped = [];
   for (const pkg of discoverPnpmPackages(root, config)) {
-    const path = resolve13(root, config.corpus.agent.root, "packages", `${pkg.id}.md`);
+    const path = resolve18(root, config.corpus.agent.root, "packages", `${pkg.id}.md`);
     if (writeIfMissing(path, workspaceDocDraft(pkg.id, pkg.path))) created.push(path);
     else skipped.push(path);
   }
@@ -4915,11 +7072,11 @@ var bootstrapAgentDocs = (root, config) => {
   const created = [];
   const skipped = [];
   for (const doc of scanHumanDocRecords(root, config)) {
-    const raw = readFileSync17(doc.path, "utf8");
+    const raw = readFileSync21(doc.path, "utf8");
     const body = raw.replace(/^---\n[\s\S]*?\n---\n?/, "");
     const title = firstHeading(body) ?? doc.id;
     const description = firstParagraph(body);
-    const draftPath = resolve13(root, config.corpus.agent.root, "human", `${doc.id}.md`);
+    const draftPath = resolve18(root, config.corpus.agent.root, "human", `${doc.id}.md`);
     const draft = [
       "---",
       "type: knowledge",
@@ -4983,8 +7140,8 @@ var runCli = (argv) => {
       return 1;
     }
     try {
-      const abs = resolve13(file);
-      const raw = readFileSync17(abs, "utf8");
+      const abs = resolve18(file);
+      const raw = readFileSync21(abs, "utf8");
       const handoff = parseAgentHandoff(JSON.parse(raw));
       writeJson2({ ok: true, handoff });
       return 0;
@@ -4994,13 +7151,42 @@ var runCli = (argv) => {
       return 1;
     }
   }
+  if (command === "discover") {
+    try {
+      let config;
+      let root = process.cwd();
+      try {
+        const loaded = loadProject(configPath);
+        config = loaded.config;
+        root = loaded.root;
+      } catch (error) {
+        if (!(error instanceof ConfigNotFoundError) || configPath) throw error;
+      }
+      const snapshot = discoverRepository({ root, ...config ? { config } : {} });
+      if (wantsTextOutput(flags, config ?? { surfaces: { cli: { defaultFormat: "json" } } })) {
+        writeLines([`Project: ${snapshot.project.name}`, `Entities: ${snapshot.entities.length}`, `Relations: ${snapshot.relations.length}`, `Source revision: ${snapshot.sourceRevision}`, ...config ? [] : ["No configuration found; discovery used safe defaults."]]);
+      } else {
+        writeJson2({ ok: true, snapshot, ...config ? {} : { proposedConfig: { schemaVersion: 1, corpus: { agent: { root: "docs/for-agents" } } } } });
+      }
+      return 0;
+    } catch (error) {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+      return 2;
+    }
+  }
+  if (command === "scan" || command === "reconcile" || command === "check" || command === "map") {
+    return runWorkflowCommand(command, flags, configPath, argv);
+  }
+  if (command === "fix") return runFixCommand(argv, positional, configPath);
+  if (command === "suggest") return runSuggestCommand(flags, configPath);
   if (command === "init") {
     const root = process.cwd();
     const withDemo = flags.has("--demo") || !flags.has("--no-demo");
-    const configFile = resolve13(root, configPath ?? "doc-bridge.config.json");
-    const docsIndex = resolve13(root, "docs/for-agents/INDEX.md");
-    const exampleDoc = resolve13(root, "docs/for-agents/packages/example.md");
-    const agentsMd = resolve13(root, "AGENTS.md");
+    const configFile = resolve18(root, configPath ?? "doc-bridge.config.json");
+    const docsIndex = resolve18(root, "docs/for-agents/INDEX.md");
+    const exampleDoc = resolve18(root, "docs/for-agents/packages/example.md");
+    const agentsMd = resolve18(root, "AGENTS.md");
     const configWritten = writeIfMissing(configFile, initConfigContents(configFile, withDemo));
     const indexWritten = writeIfMissing(
       docsIndex,
@@ -5008,7 +7194,7 @@ var runCli = (argv) => {
     );
     const exampleWritten = withDemo ? writeIfMissing(exampleDoc, exampleAgentDoc) : false;
     const agentsWritten = writeIfMissing(agentsMd, agentsMdSnippet);
-    if (withDemo) writeIfMissing(resolve13(root, "src/.gitkeep"), "");
+    if (withDemo) writeIfMissing(resolve18(root, "src/.gitkeep"), "");
     const scaffold = flags.has("--scaffold-workspaces") ? scaffoldWorkspaceDocs(root, loadProject(configFile).config) : void 0;
     writeJson2({
       ok: true,
@@ -5187,6 +7373,7 @@ var runCli = (argv) => {
       return 1;
     }
   }
+  if (command === "rules") return runRulesCommand(argv, flags, positional, configPath);
   if (command === "conformance") {
     const action = positional[1];
     const profile = positional[2];
@@ -5251,9 +7438,9 @@ var runCli = (argv) => {
       const { config, root } = loadProject(configPath);
       const report = runDoctor(root, config);
       if (flags.has("--write-badge")) {
-        const badgePath = resolve13(root, ".doc-bridge", "coverage-badge.json");
-        mkdirSync5(dirname8(badgePath), { recursive: true });
-        writeFileSync4(badgePath, `${formatDoctorBadgeJson(report.badge)}
+        const badgePath = resolve18(root, ".doc-bridge", "coverage-badge.json");
+        mkdirSync8(dirname10(badgePath), { recursive: true });
+        writeFileSync8(badgePath, `${formatDoctorBadgeJson(report.badge)}
 `, "utf8");
       }
       if (flags.has("--badge")) {