@agentskit/doc-bridge 0.1.0-alpha.1

package/dist/cli/program.js

@@ -0,0 +1,3155 @@
+// src/cli/program.ts
+import { existsSync as existsSync9, mkdirSync as mkdirSync2, readFileSync as readFileSync14, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname4, resolve as resolve6 } from "path";
+import { createInterface } from "readline/promises";
+
+// src/config/load-config.ts
+import { existsSync, readFileSync } from "fs";
+import { basename, dirname, join, resolve } from "path";
+import vm from "vm";
+
+// src/config/defaults.ts
+var DEFAULT_AGENT_EXCLUDE = ["**/node_modules/**", "**/.git/**"];
+var applyConfigDefaults = (config) => {
+  const agentRoot = config.corpus.agent.root;
+  const agentIndex = config.corpus.agent.index ?? `${agentRoot}/INDEX.md`;
+  return {
+    ...config,
+    corpus: {
+      ...config.corpus,
+      agent: {
+        ...config.corpus.agent,
+        index: agentIndex,
+        include: config.corpus.agent.include ?? ["**/*.md"],
+        exclude: config.corpus.agent.exclude ?? [...DEFAULT_AGENT_EXCLUDE]
+      }
+    },
+    index: {
+      outFile: ".doc-bridge/index.json",
+      contentHash: "sha256-normalized-v1",
+      llmsTxt: {
+        enabled: true,
+        outFile: "llms.txt",
+        ...config.index?.llmsTxt
+      },
+      capabilities: {
+        enabled: true,
+        outFile: ".doc-bridge/capabilities.json",
+        ...config.index?.capabilities
+      },
+      ...config.index
+    },
+    gates: {
+      preset: "minimal",
+      ...config.gates
+    },
+    surfaces: {
+      cli: {
+        bin: "ak-docs",
+        defaultFormat: "json",
+        ...config.surfaces?.cli
+      },
+      mcp: {
+        enabled: true,
+        tools: ["handoff.resolve", "doc.search", "doc.get", "gate.status"],
+        transport: "stdio",
+        ...config.surfaces?.mcp
+      },
+      ...config.surfaces
+    },
+    intelligence: config.intelligence ? {
+      enabled: false,
+      ...config.intelligence,
+      chat: config.intelligence.chat ? { handoffFirst: true, ...config.intelligence.chat } : void 0
+    } : { enabled: false }
+  };
+};
+
+// src/config/schema.ts
+import { z } from "zod";
+var CONFIG_SCHEMA_VERSION = 1;
+var HumanCorpusPluginIdSchema = z.enum([
+  "plain-markdown",
+  "fumadocs",
+  "docusaurus",
+  "mkdocs",
+  "vitepress",
+  "custom"
+]);
+var AgentCorpusConfigSchema = z.object({
+  root: z.string().min(1).max(512),
+  index: z.string().min(1).max(512).optional(),
+  include: z.array(z.string().min(1).max(256)).max(64).optional(),
+  exclude: z.array(z.string().min(1).max(256)).max(64).optional(),
+  okf: z.object({
+    requireType: z.boolean().optional(),
+    allowedTypes: z.array(z.string().min(1).max(128)).max(64).optional()
+  }).strict().optional()
+}).strict();
+var HumanCorpusConfigSchema = z.object({
+  plugin: HumanCorpusPluginIdSchema,
+  options: z.record(z.string(), z.unknown()).optional()
+}).strict();
+var IndexConfigSchema = z.object({
+  outFile: z.string().min(1).max(512).optional(),
+  llmsTxt: z.object({
+    enabled: z.boolean().optional(),
+    outFile: z.string().min(1).max(512).optional(),
+    preamble: z.string().max(4e3).optional()
+  }).strict().optional(),
+  capabilities: z.object({
+    enabled: z.boolean().optional(),
+    outFile: z.string().min(1).max(512).optional()
+  }).strict().optional(),
+  contentHash: z.literal("sha256-normalized-v1").optional()
+}).strict();
+var OwnershipEntrySchema = z.object({
+  path: z.string().min(1).max(512),
+  group: z.string().min(1).max(128).optional(),
+  layer: z.string().min(1).max(32).optional(),
+  purpose: z.string().max(1024).optional(),
+  checks: z.array(z.string().min(1).max(256)).max(32).optional(),
+  agentDoc: z.string().min(1).max(512).optional(),
+  humanDoc: z.string().min(1).max(512).optional()
+}).strict();
+var RoutingConfigSchema = z.object({
+  plugin: z.enum(["pnpm-monorepo", "npm-workspaces", "yarn-workspaces", "custom"]).optional(),
+  options: z.object({
+    packages: z.array(z.string().min(1).max(256)).max(128).optional(),
+    ownership: z.record(z.string().min(1).max(256), OwnershipEntrySchema).optional(),
+    intents: z.array(
+      z.object({
+        id: z.string().min(1).max(128),
+        title: z.string().min(1).max(256),
+        paths: z.array(z.string().min(1).max(512)).max(32)
+      }).strict()
+    ).max(128).optional(),
+    changes: z.array(
+      z.object({
+        id: z.string().min(1).max(128),
+        title: z.string().min(1).max(256),
+        startHere: z.string().min(1).max(512),
+        relatedPackages: z.array(z.string().min(1).max(256)).max(32).optional()
+      }).strict()
+    ).max(128).optional()
+  }).strict().optional()
+}).strict();
+var GatesConfigSchema = z.object({
+  preset: z.enum(["minimal", "standard", "strict"]).optional(),
+  include: z.array(
+    z.enum([
+      "index-freshness",
+      "human-guide-links",
+      "link-rot",
+      "okf-type",
+      "docs-style",
+      "routing-currency",
+      "bootstrap-size"
+    ])
+  ).max(16).optional(),
+  exclude: z.array(
+    z.enum([
+      "index-freshness",
+      "human-guide-links",
+      "link-rot",
+      "okf-type",
+      "docs-style",
+      "routing-currency",
+      "bootstrap-size"
+    ])
+  ).max(16).optional(),
+  options: z.record(z.string(), z.unknown()).optional()
+}).strict();
+var SurfacesConfigSchema = z.object({
+  cli: z.object({
+    bin: z.string().min(1).max(64).optional(),
+    defaultFormat: z.enum(["json", "text"]).optional()
+  }).strict().optional(),
+  mcp: z.object({
+    enabled: z.boolean().optional(),
+    tools: z.array(
+      z.enum([
+        "handoff.resolve",
+        "doc.search",
+        "doc.get",
+        "gate.status",
+        "playbook.pattern.get",
+        "retriever.query",
+        "memory.classify",
+        "memory.promoteDraft",
+        "registry.topology"
+      ])
+    ).max(16).optional(),
+    transport: z.enum(["stdio", "http"]).optional(),
+    http: z.object({
+      port: z.number().int().min(1).max(65535).optional(),
+      path: z.string().min(1).max(256).optional()
+    }).strict().optional()
+  }).strict().optional()
+}).strict();
+var IntelligenceConfigSchema = z.object({
+  enabled: z.boolean().optional(),
+  adapter: z.object({
+    provider: z.enum(["openai", "anthropic", "ollama", "openrouter", "custom"]),
+    model: z.string().min(1).max(128).optional(),
+    apiKeyEnv: z.string().min(0).max(128).optional(),
+    baseUrl: z.string().url().optional(),
+    options: z.record(z.string(), z.unknown()).optional()
+  }).strict().optional(),
+  chat: z.object({
+    enabled: z.boolean().optional(),
+    sources: z.array(z.enum(["agent", "human", "federation"])).max(8).optional(),
+    handoffFirst: z.boolean().optional()
+  }).strict().optional(),
+  retriever: z.object({
+    enabled: z.boolean().optional(),
+    mode: z.enum(["local", "remote", "bm25", "agentskit-rag"]).optional(),
+    embedModel: z.string().min(1).max(128).optional(),
+    chunkSize: z.number().int().min(128).max(16384).optional(),
+    options: z.record(z.string(), z.unknown()).optional()
+  }).strict().optional(),
+  memory: z.object({
+    enabled: z.boolean().optional(),
+    adapters: z.array(z.enum(["playbook-memory", "cursor-rules", "session-export", "bootstrap-delta"])).max(8).optional(),
+    ingestDir: z.string().min(1).max(512).optional(),
+    classify: z.boolean().optional(),
+    promote: z.object({
+      enabled: z.boolean().optional(),
+      targets: z.array(z.enum(["agent", "human", "agents-md"])).max(8).optional(),
+      requireApproval: z.boolean().optional()
+    }).strict().optional()
+  }).strict().optional(),
+  runtime: z.enum(["agentskit", "custom"]).optional(),
+  runtimeModule: z.string().min(1).max(512).optional()
+}).strict();
+var FederationConfigSchema = z.object({
+  enabled: z.boolean().optional(),
+  sources: z.array(
+    z.object({
+      id: z.string().min(1).max(64),
+      llmsTxt: z.string().min(1).max(512).optional(),
+      rawBaseUrl: z.string().url().optional(),
+      includeInRetriever: z.boolean().optional(),
+      includeInChat: z.boolean().optional()
+    }).strict()
+  ).max(16).optional()
+}).strict();
+var DocBridgeConfigV1Schema = z.object({
+  schemaVersion: z.literal(CONFIG_SCHEMA_VERSION),
+  project: z.object({
+    name: z.string().min(1).max(128).optional(),
+    root: z.string().min(1).max(512).optional()
+  }).strict().optional(),
+  corpus: z.object({
+    agent: AgentCorpusConfigSchema,
+    human: z.union([HumanCorpusConfigSchema, z.array(HumanCorpusConfigSchema).max(8)]).optional()
+  }).strict(),
+  index: IndexConfigSchema.optional(),
+  routing: RoutingConfigSchema.optional(),
+  gates: GatesConfigSchema.optional(),
+  surfaces: SurfacesConfigSchema.optional(),
+  intelligence: IntelligenceConfigSchema.optional(),
+  federation: FederationConfigSchema.optional()
+}).strict();
+
+// src/config/load-config.ts
+var CONFIG_CANDIDATES = [
+  "doc-bridge.config.ts",
+  "doc-bridge.config.mts",
+  "doc-bridge.config.js",
+  "doc-bridge.config.mjs",
+  "doc-bridge.config.json",
+  "doc-bridge.config.yaml",
+  "doc-bridge.config.yml",
+  "package.json"
+];
+var ConfigNotFoundError = class extends Error {
+  constructor(cwd) {
+    super(
+      `No doc-bridge config found in ${cwd}. Run: ak-docs init \u2014 or pass --config <path>.`
+    );
+    this.cwd = cwd;
+    this.name = "ConfigNotFoundError";
+  }
+  cwd;
+};
+var findConfigPath = (cwd, explicitPath) => {
+  if (explicitPath) {
+    const abs = resolve(cwd, explicitPath);
+    return existsSync(abs) ? abs : null;
+  }
+  for (const name of CONFIG_CANDIDATES) {
+    const candidate = join(cwd, name);
+    if (!existsSync(candidate)) continue;
+    if (name !== "package.json") return candidate;
+    const pkg = parseJsonConfig(readFileSync(candidate, "utf8"), candidate);
+    if (pkg.docBridge) return candidate;
+  }
+  return null;
+};
+var parseJsonConfig = (raw, path) => {
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to parse JSON config at ${path}: ${message}`);
+  }
+};
+var parseCodeConfig = (raw, path) => {
+  const code = raw.replace(/import\s+type\s+[\s\S]*?;?\n/g, "").replace(/import\s+\{\s*defineConfig\s*\}\s+from\s+['"]@agentskit\/doc-bridge(?:\/config)?['"];?\n?/g, "").replace(/\s+satisfies\s+[A-Za-z0-9_.$<>{}\[\],\s]+(?=\s*(?:;|\)|$))/g, "").replace(/export\s+default/, "module.exports.default =");
+  if (/\bimport\b/.test(code)) {
+    throw new Error(`Unsupported import in ${path}. Static config only supports defineConfig imports.`);
+  }
+  const sandbox = {
+    module: { exports: {} },
+    exports: {},
+    defineConfig: (config) => config
+  };
+  try {
+    vm.runInNewContext(code, sandbox, { timeout: 250, filename: path });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to load config at ${path}: ${message}`);
+  }
+  return sandbox.module.exports.default;
+};
+var parseConfig = (input) => {
+  const result = DocBridgeConfigV1Schema.safeParse(input);
+  if (result.success) return result.data;
+  throw new Error(
+    `Invalid doc-bridge config:
+${result.error.issues.map(
+      (issue) => `  - ${issue.path.join(".") || "(root)"}: ${issue.message}`
+    ).join("\n")}`
+  );
+};
+var loadConfig = (opts = {}) => {
+  const cwd = resolve(opts.cwd ?? process.cwd());
+  const path = findConfigPath(cwd, opts.explicitPath);
+  if (!path) throw new ConfigNotFoundError(cwd);
+  const raw = readFileSync(path, "utf8");
+  const ext = path.split(".").pop()?.toLowerCase();
+  if (ext === "yaml" || ext === "yml") {
+    throw new Error(`YAML config is not supported yet (${path}). Use doc-bridge.config.json for now.`);
+  }
+  const parsed = basename(path) === "package.json" ? parseJsonConfig(raw, path).docBridge : ext === "ts" || ext === "mts" || ext === "js" || ext === "mjs" ? parseCodeConfig(raw, path) : parseJsonConfig(raw, path);
+  const config = applyConfigDefaults(parseConfig(parsed));
+  return { config, path };
+};
+var projectRootFromConfigPath = (configFilePath, projectRootField) => {
+  const configDir = dirname(resolve(configFilePath));
+  if (projectRootField) return resolve(configDir, projectRootField);
+  return configDir;
+};
+
+// src/index-builder/build-index.ts
+import { mkdirSync, readFileSync as readFileSync7, writeFileSync } from "fs";
+import { dirname as dirname3, join as join9 } from "path";
+
+// src/lib/paths.ts
+import { resolve as resolve2 } from "path";
+var toPosix = (value) => value.split("\\").join("/");
+
+// src/index-builder/scan-corpus.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { join as join3 } from "path";
+
+// src/lib/markdown.ts
+var parseFrontmatter = (markdown) => {
+  const normalized = markdown.replace(/^\uFEFF/, "");
+  if (!normalized.startsWith("---\n") && !normalized.startsWith("---\r\n")) {
+    return { data: {}, body: markdown };
+  }
+  const endMatch = /\r?\n---\r?\n/.exec(normalized.slice(3));
+  if (!endMatch || endMatch.index === void 0) {
+    return { data: {}, body: markdown };
+  }
+  const block = normalized.slice(4, 3 + endMatch.index);
+  const body = normalized.slice(3 + endMatch.index + endMatch[0].length);
+  const data = {};
+  for (const rawLine of block.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const m = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
+    if (!m?.[1]) continue;
+    const key = m[1];
+    const raw = (m[2] ?? "").trim();
+    if (raw === "true") data[key] = true;
+    else if (raw === "false") data[key] = false;
+    else if (raw.startsWith("[") && raw.endsWith("]")) {
+      data[key] = raw.slice(1, -1).split(",").map((part) => part.trim().replace(/^['"]|['"]$/g, "")).filter(Boolean);
+    } else {
+      data[key] = raw.replace(/^['"]|['"]$/g, "");
+    }
+  }
+  return { data, body };
+};
+var frontmatterString = (data, key) => {
+  const value = data[key];
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+};
+var frontmatterStringList = (data, key) => {
+  const value = data[key];
+  if (Array.isArray(value)) return value.filter((item) => typeof item === "string");
+  if (typeof value === "string" && value.length > 0) return [value];
+  return void 0;
+};
+var firstHeading = (markdown) => {
+  const { body } = parseFrontmatter(markdown);
+  for (const line of body.split("\n")) {
+    const m = /^#\s+(.+)$/.exec(line.trim());
+    if (m?.[1]) return m[1].trim();
+  }
+  return void 0;
+};
+var firstParagraph = (markdown) => {
+  const { body } = parseFrontmatter(markdown);
+  const lines = body.split("\n");
+  const buf = [];
+  for (const line of lines) {
+    const t = line.trim();
+    if (!t) {
+      if (buf.length) break;
+      continue;
+    }
+    if (t.startsWith("#")) continue;
+    if (t.startsWith("---")) continue;
+    buf.push(t);
+    if (buf.join(" ").length > 40) break;
+  }
+  const text = buf.join(" ").trim();
+  return text || void 0;
+};
+var slugFromPath = (relPath) => {
+  const base = relPath.replace(/\.mdx?$/, "");
+  const parts = base.split("/");
+  return parts[parts.length - 1] ?? base;
+};
+
+// src/lib/walk.ts
+import { readdirSync, statSync } from "fs";
+import { join as join2 } from "path";
+var DEFAULT_SKIP = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", "coverage", ".doc-bridge"]);
+var walkFiles = (root, opts) => {
+  const extensions = opts?.extensions ?? [".md"];
+  const skip = opts?.skipDirs ?? DEFAULT_SKIP;
+  const out = [];
+  const visit = (dir) => {
+    let entries = [];
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const name of entries) {
+      const abs = join2(dir, name);
+      let st;
+      try {
+        st = statSync(abs);
+      } catch {
+        continue;
+      }
+      if (st.isDirectory()) {
+        if (skip.has(name)) continue;
+        visit(abs);
+        continue;
+      }
+      if (!st.isFile()) continue;
+      if (extensions.some((ext) => name.endsWith(ext))) {
+        out.push(toPosix(abs));
+      }
+    }
+  };
+  visit(root);
+  return out.sort();
+};
+
+// src/index-builder/scan-corpus.ts
+var scanAgentCorpus = (root, config) => {
+  const agentRoot = join3(root, config.corpus.agent.root);
+  const files = walkFiles(agentRoot, { extensions: [".md", ".mdx"] });
+  const corpusRelRoot = toPosix(config.corpus.agent.root);
+  return files.map((abs) => {
+    const relToCorpus = toPosix(abs.replace(`${toPosix(agentRoot)}/`, ""));
+    const relPath = `${corpusRelRoot}/${relToCorpus}`;
+    const raw = readFileSync2(abs, "utf8");
+    const { data: frontmatter } = parseFrontmatter(raw);
+    const id = frontmatterString(frontmatter, "id") ?? frontmatterString(frontmatter, "package") ?? slugFromPath(relToCorpus);
+    const title = firstHeading(raw) ?? id;
+    const description = firstParagraph(raw);
+    return {
+      id,
+      type: "agent-doc",
+      title,
+      path: relPath,
+      absPath: abs,
+      relPath,
+      frontmatter,
+      ...description ? { description } : {}
+    };
+  });
+};
+var guessAgentDocForPackage = (corpus, packageId) => {
+  const exact = corpus.find(
+    (doc) => frontmatterString(doc.frontmatter, "package") === packageId || doc.relPath.endsWith(`/packages/${packageId}.md`) || doc.relPath.endsWith(`/${packageId}.md`) || doc.id === packageId
+  );
+  return exact?.path;
+};
+var ownershipFromFrontmatter = (corpus) => {
+  const out = [];
+  for (const doc of corpus) {
+    const id = frontmatterString(doc.frontmatter, "package") ?? (frontmatterString(doc.frontmatter, "type") === "package" ? frontmatterString(doc.frontmatter, "id") ?? doc.id : void 0);
+    const path = frontmatterString(doc.frontmatter, "editRoot") ?? frontmatterString(doc.frontmatter, "path");
+    if (!id || !path) continue;
+    const purpose = frontmatterString(doc.frontmatter, "purpose") ?? doc.description;
+    const checks = frontmatterStringList(doc.frontmatter, "checks");
+    const humanDoc = frontmatterString(doc.frontmatter, "humanDoc");
+    out.push({
+      id,
+      path,
+      agentDoc: doc.path,
+      ...purpose ? { purpose } : {},
+      ...checks ? { checks } : {},
+      ...humanDoc ? { humanDoc } : {}
+    });
+  }
+  return out;
+};
+
+// src/index-builder/build-handoffs.ts
+var defaultChecks = (config) => {
+  const preset = config.gates?.preset ?? "minimal";
+  if (preset === "strict" || preset === "standard") return ["npm test", "npm run lint"];
+  return ["npm test"];
+};
+var collectPackages = (config, discovered, corpus) => {
+  const byId = /* @__PURE__ */ new Map();
+  for (const [id, entry] of Object.entries(config.routing?.options?.ownership ?? {})) {
+    byId.set(id, { id, path: entry.path });
+  }
+  for (const pkg of discovered) {
+    const existing = byId.get(pkg.id);
+    if (!existing) {
+      byId.set(pkg.id, pkg);
+      continue;
+    }
+    byId.set(pkg.id, {
+      id: pkg.id,
+      path: existing.path || pkg.path,
+      ...pkg.name ? { name: pkg.name } : existing.name ? { name: existing.name } : {}
+    });
+  }
+  for (const seed of ownershipFromFrontmatter(corpus)) {
+    const existing = byId.get(seed.id);
+    if (!existing) {
+      byId.set(seed.id, { id: seed.id, path: seed.path });
+      continue;
+    }
+    if (!existing.path) {
+      byId.set(seed.id, { ...existing, path: seed.path });
+    }
+  }
+  return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
+};
+var buildLookup = (config, packages, corpus, indexOutFile, humanDocs = {}) => {
+  const ownership = {};
+  const handoffs = {};
+  const checks = defaultChecks(config);
+  const fmSeeds = new Map(ownershipFromFrontmatter(corpus).map((seed) => [seed.id, seed]));
+  for (const pkg of packages) {
+    const override = config.routing?.options?.ownership?.[pkg.id];
+    const fm = fmSeeds.get(pkg.id);
+    const agentDoc = override?.agentDoc ?? fm?.agentDoc ?? guessAgentDocForPackage(corpus, pkg.id) ?? config.corpus.agent.index;
+    const startHere = agentDoc ?? "";
+    const purpose = override?.purpose ?? fm?.purpose;
+    const humanDoc = override?.humanDoc ?? fm?.humanDoc ?? humanDocs[pkg.id];
+    const record = {
+      id: pkg.id,
+      path: override?.path ?? fm?.path ?? pkg.path,
+      checks: [...override?.checks ?? fm?.checks ?? checks],
+      ...override?.group ? { group: override.group } : {},
+      ...override?.layer ? { layer: override.layer } : {},
+      ...purpose ? { purpose } : {},
+      ...humanDoc ? { humanDoc } : {},
+      ...agentDoc ? { agentDoc } : {}
+    };
+    ownership[pkg.id] = record;
+    handoffs[pkg.id] = {
+      type: "agent-handoff",
+      schemaVersion: 1,
+      source: indexOutFile,
+      target: {
+        type: "package",
+        id: pkg.id,
+        path: record.path,
+        ...record.group ? { group: record.group } : {},
+        ...record.layer ? { layer: record.layer } : {}
+      },
+      startHere,
+      readBeforeEditing: [agentDoc, "AGENTS.md"].filter(
+        (v, i, a) => Boolean(v) && a.indexOf(v) === i
+      ),
+      editRoots: [record.path],
+      checks: [...record.checks],
+      ...record.humanDoc ? { humanDoc: record.humanDoc } : {},
+      notes: record.purpose ? [record.purpose] : []
+    };
+  }
+  const intents = {};
+  for (const intent of config.routing?.options?.intents ?? []) {
+    intents[intent.id] = { id: intent.id, title: intent.title, paths: intent.paths };
+  }
+  const changes = {};
+  for (const change of config.routing?.options?.changes ?? []) {
+    changes[change.id] = {
+      id: change.id,
+      title: change.title,
+      startHere: change.startHere,
+      ...change.relatedPackages ? { relatedPackages: change.relatedPackages } : {}
+    };
+  }
+  return {
+    lookup: {
+      packages: packages.map((p) => p.id),
+      ownership,
+      intents,
+      changes
+    },
+    handoffs
+  };
+};
+
+// src/version.ts
+var PACKAGE_VERSION = "0.1.0-alpha.1";
+
+// src/index-builder/capabilities.ts
+var renderCapabilitiesJson = (config, index, paths) => {
+  const payload = {
+    schemaVersion: 1,
+    type: "doc-bridge-capabilities",
+    package: "@agentskit/doc-bridge",
+    version: PACKAGE_VERSION,
+    project: index.project,
+    contentHash: index.contentHash,
+    artifacts: {
+      index: paths.index,
+      ...paths.llmsTxt ? { llmsTxt: paths.llmsTxt } : {}
+    },
+    capabilities: [
+      "index",
+      "query",
+      "search",
+      "agent-handoff",
+      "gates",
+      ...config.surfaces?.mcp?.enabled === false ? [] : ["mcp"],
+      ...config.corpus.human ? ["human-docs"] : []
+    ],
+    surfaces: {
+      cli: config.surfaces?.cli,
+      mcp: config.surfaces?.mcp
+    }
+  };
+  return `${JSON.stringify(payload, null, 2)}
+`;
+};
+
+// src/index-builder/content-hash.ts
+import { createHash } from "crypto";
+var sortValue = (value) => {
+  if (Array.isArray(value)) return value.map(sortValue);
+  if (value && typeof value === "object") {
+    const record = value;
+    return Object.fromEntries(
+      Object.keys(record).sort().map((key) => [key, sortValue(record[key])])
+    );
+  }
+  return value;
+};
+var sha256NormalizedV1 = (payload) => {
+  const normalized = JSON.stringify(sortValue(payload));
+  return createHash("sha256").update(normalized, "utf8").digest("hex");
+};
+
+// src/index-builder/llms-txt.ts
+var renderLlmsTxt = (config, knowledge, projectName2) => {
+  const preamble = config.index?.llmsTxt?.preamble ?? `# ${projectName2}
+
+> Agent-readable documentation index generated by ak-docs (@agentskit/doc-bridge).
+`;
+  const lines = knowledge.slice(0, 500).map((entry) => {
+    const desc = entry.description ? `: ${entry.description}` : "";
+    return `- [${entry.title}](${entry.path})${desc}`;
+  });
+  return `${preamble.trim()}
+
+## Knowledge
+
+${lines.join("\n")}
+`;
+};
+
+// src/index-builder/human-adapters/docusaurus.ts
+import { existsSync as existsSync2, readFileSync as readFileSync4 } from "fs";
+import { join as join5 } from "path";
+import vm2 from "vm";
+
+// src/index-builder/human-adapters/core.ts
+import { readFileSync as readFileSync3 } from "fs";
+import { join as join4 } from "path";
+var optionString = (options, keys) => {
+  for (const key of keys) {
+    const value = options?.[key];
+    if (typeof value === "string" && value) return value;
+  }
+  return void 0;
+};
+var parseFrontmatter2 = (raw) => {
+  if (!raw.startsWith("---\n")) return {};
+  const end = raw.indexOf("\n---", 4);
+  if (end === -1) return {};
+  const out = {};
+  for (const line of raw.slice(4, end).split("\n")) {
+    const match = /^([A-Za-z0-9_-]+):\s*(.+?)\s*$/.exec(line);
+    if (match?.[1] && match[2]) out[match[1]] = match[2].replace(/^['"]|['"]$/g, "");
+  }
+  return out;
+};
+var docId = (relToHumanRoot, raw) => {
+  const meta = parseFrontmatter2(raw);
+  return meta.package ?? meta.module ?? meta.id ?? slugFromPath(relToHumanRoot);
+};
+var routeSlug = (relToHumanRoot, opts) => relToHumanRoot.split("/").filter((part) => !opts?.stripGroups || !/^\(.+\)$/.test(part)).join("/").replace(/(?:^|\/)index\.mdx?$/, "").replace(/\.mdx?$/, "");
+var humanUrl = (slug, urlPrefix) => {
+  if (typeof urlPrefix !== "string" || !urlPrefix) return slug;
+  const prefix = urlPrefix.replace(/\/$/, "");
+  return slug ? `${prefix}/${slug.replace(/^\//, "")}` : prefix;
+};
+var scanMarkdownDocs = (root, humanRoot, options) => {
+  const out = [];
+  const absRoot = join4(root, humanRoot);
+  for (const abs of walkFiles(absRoot, { extensions: [".md", ".mdx"] })) {
+    const relToHumanRoot = toPosix(abs.replace(`${toPosix(absRoot)}/`, ""));
+    const raw = readFileSync3(abs, "utf8");
+    if (options?.includeRelPath && !options.includeRelPath(relToHumanRoot, raw)) continue;
+    out.push({
+      id: options?.idForDoc?.(relToHumanRoot, raw) ?? docId(relToHumanRoot, raw),
+      url: humanUrl(
+        options?.slugForDoc?.(relToHumanRoot, raw) ?? routeSlug(relToHumanRoot, options?.stripGroups ? { stripGroups: true } : void 0),
+        options?.urlPrefix
+      ),
+      path: abs
+    });
+  }
+  return out;
+};
+
+// src/index-builder/human-adapters/docusaurus.ts
+var docusaurusFileSlug = (relPath) => {
+  const parts = relPath.split("/");
+  const file = parts.at(-1) ?? "";
+  const base = file.replace(/\.mdx?$/, "");
+  const parent = parts.at(-2);
+  if (/^(index|readme)$/i.test(base) || base === parent) return parts.slice(0, -1).join("/");
+  return routeSlug(relPath);
+};
+var docusaurusSlug = (relPath, raw) => {
+  const slug = parseFrontmatter2(raw).slug;
+  if (!slug) return docusaurusFileSlug(relPath);
+  return slug.replace(/^\.\//, "").replace(/^\//, "").replace(/\/$/, "");
+};
+var docusaurusSidebarId = (relPath, raw) => {
+  const id = parseFrontmatter2(raw).id;
+  if (!id) return routeSlug(relPath);
+  const parts = relPath.split("/").slice(0, -1);
+  return [...parts, id].filter(Boolean).join("/");
+};
+var docusaurusRecordId = (relPath, raw) => {
+  const frontmatter = parseFrontmatter2(raw);
+  return frontmatter.package ?? frontmatter.module ?? docusaurusSidebarId(relPath, raw);
+};
+var sidebarsValue = (file) => {
+  if (!existsSync2(file)) return void 0;
+  const raw = readFileSync4(file, "utf8").replace(/import\s+type\s+[\s\S]*?;?\n/g, "").replace(/:\s*[A-Za-z0-9_.$<>{}\[\],\s]+(?=\s*=)/g, "").replace(/\s+satisfies\s+[A-Za-z0-9_.$<>{}\[\],\s]+(?=\s*(?:;|\n|$))/g, "").replace(/export\s+default/, "module.exports =");
+  const sandbox = { module: { exports: {} }, exports: {} };
+  vm2.runInNewContext(raw, sandbox, { timeout: 250 });
+  return sandbox.module.exports;
+};
+var visitSidebar = (value, filter) => {
+  if (typeof value === "string") {
+    filter.ids.add(value);
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item2 of value) visitSidebar(item2, filter);
+    return;
+  }
+  if (!value || typeof value !== "object") return;
+  const item = value;
+  if ((item.type === "doc" || item.type === "ref") && typeof item.id === "string") {
+    filter.ids.add(item.id);
+  }
+  if (item.type === "autogenerated" && typeof item.dirName === "string") {
+    filter.autogenDirs.push(item.dirName);
+  }
+  if (Array.isArray(item.items)) visitSidebar(item.items, filter);
+  if (item.link && typeof item.link === "object") visitSidebar(item.link, filter);
+  for (const child of Object.values(item)) {
+    if (Array.isArray(child)) visitSidebar(child, filter);
+  }
+};
+var readSidebars = (root, sidebarsFile) => {
+  if (!sidebarsFile) return { enabled: false, ids: /* @__PURE__ */ new Set(), autogenDirs: [] };
+  const value = sidebarsValue(join5(root, sidebarsFile));
+  const filter = { ids: /* @__PURE__ */ new Set(), autogenDirs: [] };
+  visitSidebar(value, filter);
+  return { enabled: true, ...filter };
+};
+var isIncludedBySidebar = (filter, id) => {
+  if (!filter.enabled) return true;
+  if (filter.ids.has(id)) return true;
+  return filter.autogenDirs.some((dir) => {
+    const prefix = dir === "." ? "" : dir.replace(/\/$/, "");
+    return prefix ? id === prefix || id.startsWith(`${prefix}/`) : true;
+  });
+};
+var docusaurusAdapter = {
+  plugin: "docusaurus",
+  scan: ({ root, config }) => {
+    const docsDir = optionString(config.options, ["docsDir", "root"]);
+    if (!docsDir) return [];
+    const sidebarFilter = readSidebars(root, optionString(config.options, ["sidebarsFile"]));
+    return scanMarkdownDocs(root, docsDir, {
+      includeRelPath: (relPath, raw) => isIncludedBySidebar(sidebarFilter, docusaurusSidebarId(relPath, raw)),
+      idForDoc: docusaurusRecordId,
+      slugForDoc: docusaurusSlug,
+      urlPrefix: config.options?.urlPrefix
+    });
+  }
+};
+
+// src/index-builder/human-adapters/fumadocs.ts
+import { existsSync as existsSync3, readFileSync as readFileSync5 } from "fs";
+import { join as join6 } from "path";
+var readMetaPages = (dir) => {
+  const file = join6(dir, "meta.json");
+  if (!existsSync3(file)) return void 0;
+  try {
+    const meta = JSON.parse(readFileSync5(file, "utf8"));
+    return Array.isArray(meta.pages) ? meta.pages.filter((page) => typeof page === "string") : void 0;
+  } catch {
+    return void 0;
+  }
+};
+var pageKey = (part) => part.replace(/\.mdx?$/, "");
+var isDotFile = (relPath) => {
+  const file = relPath.split("/").at(-1) ?? "";
+  return file.startsWith(".");
+};
+var isListedByMeta = (contentRoot, relPath) => {
+  if (isDotFile(relPath)) return false;
+  const parts = relPath.split("/");
+  for (let i = 0; i < parts.length; i += 1) {
+    const dir = join6(contentRoot, ...parts.slice(0, i));
+    const pages = readMetaPages(dir);
+    if (!pages?.length || pages.includes("...")) continue;
+    const key = pageKey(parts[i] ?? "");
+    if (!pages.includes(key) && !pages.includes(`./${key}`)) return false;
+  }
+  return true;
+};
+var fumadocsAdapter = {
+  plugin: "fumadocs",
+  scan: ({ root, config }) => {
+    const contentDir = optionString(config.options, ["contentDir", "root"]);
+    if (!contentDir) return [];
+    const contentRoot = join6(root, contentDir);
+    return scanMarkdownDocs(root, contentDir, {
+      includeRelPath: (relPath) => isListedByMeta(contentRoot, relPath),
+      urlPrefix: config.options?.urlPrefix,
+      stripGroups: true
+    });
+  }
+};
+
+// src/index-builder/human-adapters/plain-markdown.ts
+var plainMarkdownAdapter = {
+  plugin: "plain-markdown",
+  scan: ({ root, config }) => {
+    const humanRoot = optionString(config.options, ["root"]) ?? "docs";
+    return scanMarkdownDocs(root, humanRoot, { urlPrefix: config.options?.urlPrefix });
+  }
+};
+
+// src/index-builder/human-adapters/index.ts
+var ADAPTERS = [
+  plainMarkdownAdapter,
+  fumadocsAdapter,
+  docusaurusAdapter
+];
+var humanConfigs = (config) => {
+  const human = config.corpus.human;
+  if (!human) return [];
+  return Array.isArray(human) ? human : [human];
+};
+var scanHumanDocRecords = (root, config) => {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const human of humanConfigs(config)) {
+    const adapter = ADAPTERS.find((candidate) => candidate.plugin === human.plugin);
+    if (!adapter) continue;
+    for (const record of adapter.scan({ root, config: human })) {
+      if (seen.has(record.id)) continue;
+      seen.add(record.id);
+      out.push(record);
+    }
+  }
+  return out;
+};
+var scanHumanDocs = (root, config) => Object.fromEntries(scanHumanDocRecords(root, config).map((doc) => [doc.id, doc.url]));
+
+// src/index-builder/plugins/pnpm-monorepo.ts
+import { existsSync as existsSync5, readFileSync as readFileSync6 } from "fs";
+import { basename as basename2, join as join8 } from "path";
+
+// src/lib/glob-expand.ts
+import { existsSync as existsSync4, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
+import { join as join7 } from "path";
+var expandWorkspaceGlobs = (root, patterns) => {
+  const dirs = /* @__PURE__ */ new Set();
+  for (const pattern of patterns) {
+    const normalized = toPosix(pattern).replace(/\/$/, "");
+    if (!normalized.includes("*")) {
+      const abs = join7(root, normalized);
+      if (existsSync4(abs)) dirs.add(toPosix(abs));
+      continue;
+    }
+    const star = normalized.indexOf("*");
+    const base = join7(root, normalized.slice(0, star).replace(/\/$/, ""));
+    if (!existsSync4(base)) continue;
+    for (const name of readdirSync2(base)) {
+      const abs = join7(base, name);
+      try {
+        if (statSync2(abs).isDirectory()) dirs.add(toPosix(abs));
+      } catch {
+      }
+    }
+  }
+  return [...dirs].sort();
+};
+
+// src/index-builder/plugins/pnpm-monorepo.ts
+var parsePnpmWorkspace = (yaml) => {
+  const lines = yaml.split("\n");
+  const patterns = [];
+  let inPackages = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed === "packages:") {
+      inPackages = true;
+      continue;
+    }
+    if (inPackages) {
+      if (trimmed.startsWith("- ")) {
+        patterns.push(trimmed.slice(2).trim().replace(/^['"]|['"]$/g, ""));
+        continue;
+      }
+      if (trimmed && !trimmed.startsWith("#")) inPackages = false;
+    }
+  }
+  return patterns;
+};
+var readPackageJson = (dir) => {
+  const file = join8(dir, "package.json");
+  if (!existsSync5(file)) return null;
+  try {
+    return JSON.parse(readFileSync6(file, "utf8"));
+  } catch {
+    return null;
+  }
+};
+var discoverPnpmPackages = (root, config) => {
+  const explicit = config.routing?.options?.packages;
+  let patterns = explicit;
+  if (!patterns?.length) {
+    const workspaceFile = join8(root, "pnpm-workspace.yaml");
+    if (existsSync5(workspaceFile)) {
+      patterns = parsePnpmWorkspace(readFileSync6(workspaceFile, "utf8"));
+    }
+  }
+  if (!patterns?.length) return [];
+  const dirs = expandWorkspaceGlobs(root, patterns);
+  const out = [];
+  for (const abs of dirs) {
+    const pkg = readPackageJson(abs);
+    if (!pkg) continue;
+    const rel = toPosix(abs.replace(`${toPosix(root)}/`, ""));
+    const folderId = basename2(abs);
+    const id = pkg.name?.startsWith("@") ? pkg.name.split("/").pop() ?? folderId : pkg.name ?? folderId;
+    out.push({ id, path: rel, ...pkg.name ? { name: pkg.name } : {} });
+  }
+  return out.sort((a, b) => a.id.localeCompare(b.id));
+};
+
+// src/index-builder/build-index.ts
+var projectName = (root, config) => {
+  if (config.project?.name) return config.project.name;
+  try {
+    const pkg = JSON.parse(readFileSync7(join9(root, "package.json"), "utf8"));
+    if (pkg.name) return pkg.name;
+  } catch {
+  }
+  return toPosix(root.split("/").pop() ?? "project");
+};
+var existingGeneratedAt = (indexPath, contentHash) => {
+  try {
+    const index = JSON.parse(readFileSync7(indexPath, "utf8"));
+    return index.contentHash === contentHash && typeof index.generatedAt === "string" ? index.generatedAt : void 0;
+  } catch {
+    return void 0;
+  }
+};
+var buildDocBridgeIndex = (opts) => {
+  const root = opts.root ?? process.cwd();
+  const config = opts.config;
+  const write = opts.write ?? true;
+  const outFile = config.index?.outFile ?? ".doc-bridge/index.json";
+  const indexPath = join9(root, outFile);
+  const corpus = scanAgentCorpus(root, config);
+  const knowledge = corpus.map(({ absPath: _a, relPath: _r, frontmatter: _f, ...entry }) => entry);
+  const shouldDiscover = config.routing?.plugin === "pnpm-monorepo" || Boolean(config.routing?.options?.packages?.length) || config.routing?.plugin === "npm-workspaces" || config.routing?.plugin === "yarn-workspaces";
+  const discovered = shouldDiscover ? discoverPnpmPackages(root, config) : [];
+  const packages = collectPackages(config, discovered, corpus);
+  const humanDocs = scanHumanDocs(root, config);
+  const { lookup, handoffs } = buildLookup(config, packages, corpus, outFile, humanDocs);
+  const hashPayload = {
+    schemaVersion: 1,
+    knowledge,
+    handoffs,
+    lookup
+  };
+  const contentHash = sha256NormalizedV1(hashPayload);
+  const index = {
+    schemaVersion: 1,
+    contentHash,
+    contentHashAlgo: "sha256-normalized-v1",
+    generatedAt: existingGeneratedAt(indexPath, contentHash) ?? (/* @__PURE__ */ new Date()).toISOString(),
+    project: { name: projectName(root, config), root: "." },
+    knowledge,
+    handoffs,
+    lookup
+  };
+  if (write) {
+    mkdirSync(dirname3(indexPath), { recursive: true });
+    writeFileSync(indexPath, `${JSON.stringify(index, null, 2)}
+`, "utf8");
+  }
+  let llmsTxtPath;
+  let llmsTxtRelPath;
+  if (config.index?.llmsTxt?.enabled !== false) {
+    const llmsOut = config.index?.llmsTxt?.outFile ?? "llms.txt";
+    llmsTxtRelPath = toPosix(llmsOut);
+    llmsTxtPath = join9(root, llmsOut);
+    if (write) {
+      writeFileSync(
+        llmsTxtPath,
+        renderLlmsTxt(config, knowledge, index.project?.name ?? "project"),
+        "utf8"
+      );
+    }
+  }
+  let capabilitiesPath;
+  if (config.index?.capabilities?.enabled !== false) {
+    const capabilitiesOut = config.index?.capabilities?.outFile ?? ".doc-bridge/capabilities.json";
+    capabilitiesPath = join9(root, capabilitiesOut);
+    if (write) {
+      mkdirSync(dirname3(capabilitiesPath), { recursive: true });
+      writeFileSync(
+        capabilitiesPath,
+        renderCapabilitiesJson(config, index, {
+          index: toPosix(outFile),
+          ...llmsTxtRelPath ? { llmsTxt: llmsTxtRelPath } : {}
+        }),
+        "utf8"
+      );
+    }
+  }
+  return {
+    index,
+    indexPath: toPosix(indexPath),
+    ...llmsTxtPath ? { llmsTxtPath: toPosix(llmsTxtPath) } : {},
+    ...capabilitiesPath ? { capabilitiesPath: toPosix(capabilitiesPath) } : {}
+  };
+};
+
+// src/federation/llms.ts
+import { existsSync as existsSync6, readFileSync as readFileSync8 } from "fs";
+import { resolve as resolve3 } from "path";
+
+// src/query/search.ts
+var tokenize = (value) => value.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length >= 2);
+var searchIndex = (index, term, limit = 20) => {
+  const tokens = tokenize(term);
+  if (!tokens.length) return [];
+  const matches = [];
+  for (const entry of index.knowledge) {
+    const hay = `${entry.id} ${entry.title} ${entry.description ?? ""} ${entry.path}`.toLowerCase();
+    let score = 0;
+    for (const token of tokens) {
+      if (hay.includes(token)) score += token.length;
+    }
+    if (score > 0) {
+      matches.push({
+        type: "knowledge",
+        id: entry.id,
+        path: entry.path,
+        ...entry.description ? { summary: entry.description } : {},
+        score
+      });
+    }
+  }
+  for (const [id, owner] of Object.entries(index.lookup?.ownership ?? {})) {
+    const hay = `${id} ${owner.path} ${owner.purpose ?? ""} ${owner.group ?? ""}`.toLowerCase();
+    let score = 0;
+    for (const token of tokens) {
+      if (hay.includes(token)) score += token.length * 2;
+    }
+    if (score > 0) {
+      matches.push({
+        type: "ownership",
+        id,
+        path: owner.agentDoc ?? owner.path,
+        ...owner.purpose ? { summary: owner.purpose } : {},
+        score
+      });
+    }
+  }
+  return matches.sort((a, b) => b.score - a.score).slice(0, limit);
+};
+
+// src/retriever/doc-bridge-retriever.ts
+var chunkKey = (property, type, id) => `${property}:${type}:${id}`;
+var retrieveDocBridgeChunks = (index, query, options = {}) => {
+  const property = options.property ?? index.project?.name ?? "local";
+  const limit = options.limit ?? 8;
+  return searchIndex(index, query, limit).map((match) => {
+    const knowledge = index.knowledge.find((entry) => entry.id === match.id && entry.path === match.path);
+    const owner = index.lookup?.ownership?.[match.id];
+    const type = match.type === "ownership" ? "ownership" : knowledge?.type ?? match.type;
+    const summary = match.summary ?? owner?.purpose;
+    return {
+      chunkKey: chunkKey(property, type, match.id),
+      property,
+      type,
+      id: match.id,
+      path: match.path,
+      ...knowledge?.title ? { title: knowledge.title } : {},
+      ...summary ? { summary } : {},
+      score: match.score
+    };
+  });
+};
+
+// src/federation/llms.ts
+var tokenize2 = (value) => value.toLowerCase().split(/[^a-z0-9]+/).filter((token) => token.length >= 2);
+var scoreText = (query, text) => {
+  const hay = text.toLowerCase();
+  return tokenize2(query).reduce((score, token) => score + (hay.includes(token) ? token.length : 0), 0);
+};
+var defaultFetchText = async (url) => {
+  const signal = AbortSignal.timeout(5e3);
+  const res = await fetch(url, { signal });
+  if (!res.ok) throw new Error(`Failed to fetch ${url}: ${res.status}`);
+  return res.text();
+};
+var sourceText = async (root, source, fetchText) => {
+  if (/^https?:\/\//.test(source)) return fetchText(source);
+  const path = resolve3(root, source);
+  if (!existsSync6(path)) throw new Error(`Federation source not found: ${source}`);
+  return readFileSync8(path, "utf8");
+};
+var sameOrigin = (base, target) => {
+  if (!/^https?:\/\//.test(base) || !/^https?:\/\//.test(target)) return true;
+  return new URL(base).origin === new URL(target).origin;
+};
+var parseLlmsTxtLinks = (raw) => {
+  const links = [...raw.matchAll(/\[([^\]]+)\]\(([^)]+)\)(?::\s*([^\n]+))?/g)].map((match) => ({
+    title: match[1] ?? match[2] ?? "link",
+    url: match[2] ?? "",
+    ...match[3]?.trim() ? { description: match[3].trim() } : {}
+  })).filter((link) => link.url);
+  for (const match of raw.matchAll(/(?:^|\s)(?:Raw|llms\.txt|Full bundle|ZIP bundle)?:?\s*(https?:\/\/\S+)/gi)) {
+    const url = match[1]?.replace(/[),.;]+$/, "");
+    if (url && !links.some((link) => link.url === url)) links.push({ title: slugFromPath(url), url });
+  }
+  return links;
+};
+var chunksFromMarkdown = (property, raw, sourceUrl) => {
+  const searchable = raw.includes("\n==== ") ? raw : raw.replace(/^---\n[\s\S]*?\n---\n?/, "");
+  const sections = searchable.includes("\n==== ") ? searchable.split(/\n====\s+/).filter((section) => section.trim()) : searchable.split(/\n(?=##?\s+)/);
+  return sections.map((section, index) => {
+    const title = /^title:\s*(.+)$/m.exec(section)?.[1]?.trim() ?? /^https?:\/\/\S+\/([^/\s]+)$/m.exec(section)?.[1]?.trim() ?? /^#+\s+(.+)$/m.exec(section)?.[1]?.trim() ?? slugFromPath(sourceUrl);
+    const id = slugFromPath(title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "")) || `${index}`;
+    return {
+      chunkKey: `${property}:federated:${id}`,
+      property,
+      type: "federated",
+      id,
+      path: sourceUrl,
+      title,
+      summary: section.trim().slice(0, 500),
+      score: 0
+    };
+  });
+};
+var loadFederatedChunks = async (root, config, options = {}) => {
+  const fetchText = options.fetchText ?? defaultFetchText;
+  const chunks = [];
+  for (const source of config.federation?.sources ?? []) {
+    if (source.includeInRetriever === false || !source.llmsTxt) continue;
+    const llms = await sourceText(root, source.llmsTxt, fetchText);
+    chunks.push(...chunksFromMarkdown(source.id, llms, source.llmsTxt));
+    const links = parseLlmsTxtLinks(llms);
+    for (const link of links) {
+      const url = !/^https?:\/\//.test(link.url) && source.rawBaseUrl ? `${source.rawBaseUrl.replace(/\/$/, "")}/${link.url.replace(/^\//, "")}` : link.url;
+      if (!/\.(md|txt)(?:$|\?)/.test(url)) continue;
+      if (!sameOrigin(source.llmsTxt, url)) continue;
+      try {
+        const raw = await sourceText(root, url, fetchText);
+        chunks.push(...chunksFromMarkdown(source.id, raw, url));
+      } catch {
+      }
+    }
+  }
+  return chunks;
+};
+var retrieveHybridChunks = async (root, config, index, query, options = {}) => {
+  const limit = options.limit ?? 8;
+  const local = retrieveDocBridgeChunks(index, query, {
+    property: config.project?.name ?? index.project?.name ?? "local",
+    limit
+  });
+  const federated = (await loadFederatedChunks(root, config, options)).map((chunk) => ({
+    ...chunk,
+    score: scoreText(query, `${chunk.title ?? ""} ${chunk.summary ?? ""} ${chunk.path}`)
+  })).filter((chunk) => chunk.score > 0);
+  const byKey = /* @__PURE__ */ new Map();
+  for (const chunk of [...local, ...federated]) {
+    const existing = byKey.get(chunk.chunkKey);
+    if (!existing || chunk.score > existing.score) byKey.set(chunk.chunkKey, chunk);
+  }
+  return [...byKey.values()].sort((a, b) => b.score - a.score).slice(0, limit);
+};
+
+// src/gates/run-gates.ts
+import { readFileSync as readFileSync10 } from "fs";
+
+// src/query/load-index.ts
+import { existsSync as existsSync7, readFileSync as readFileSync9 } from "fs";
+import { join as join10, resolve as resolve4 } from "path";
+
+// src/schemas/agent-handoff.ts
+import { z as z2 } from "zod";
+var HANDOFF_SCHEMA_VERSION = 1;
+var HandoffTargetTypeSchema = z2.enum([
+  "package",
+  "module",
+  "app",
+  "screen",
+  "flow",
+  "component",
+  "intent",
+  "change",
+  "search"
+]);
+var HandoffTargetSchema = z2.object({
+  type: HandoffTargetTypeSchema,
+  id: z2.string().min(1).max(256),
+  path: z2.string().min(1).max(512).optional(),
+  group: z2.string().min(1).max(128).optional(),
+  layer: z2.string().min(1).max(32).optional()
+}).strict();
+var AgentHandoffV1Schema = z2.object({
+  type: z2.literal("agent-handoff"),
+  schemaVersion: z2.literal(HANDOFF_SCHEMA_VERSION).default(HANDOFF_SCHEMA_VERSION),
+  source: z2.string().min(1).max(512),
+  target: HandoffTargetSchema,
+  startHere: z2.string().min(1).max(512),
+  readBeforeEditing: z2.array(z2.string().min(1).max(512)).max(64),
+  editRoots: z2.array(z2.string().min(1).max(512)).max(32),
+  checks: z2.array(z2.string().min(1).max(256)).max(32),
+  humanDoc: z2.string().min(1).max(512).nullable().optional(),
+  playbookPatterns: z2.array(z2.string().url()).max(16).optional(),
+  notes: z2.array(z2.string().min(1).max(1024)).max(16)
+}).strict();
+var AgentHandoffLegacySchema = AgentHandoffV1Schema.omit({ schemaVersion: true }).extend({
+  schemaVersion: z2.literal(HANDOFF_SCHEMA_VERSION).optional()
+});
+var AgentSearchMatchSchema = z2.object({
+  type: z2.string().min(1).max(64),
+  id: z2.string().min(1).max(256),
+  path: z2.string().min(1).max(512),
+  summary: z2.string().max(2048).optional(),
+  score: z2.number().optional(),
+  refs: z2.number().int().nonnegative().optional()
+}).strict();
+var AgentSearchV1Schema = z2.object({
+  type: z2.literal("agent-search"),
+  schemaVersion: z2.literal(HANDOFF_SCHEMA_VERSION).default(HANDOFF_SCHEMA_VERSION),
+  source: z2.string().min(1).max(512),
+  term: z2.string().min(1).max(512),
+  count: z2.number().int().nonnegative(),
+  bestMatch: AgentSearchMatchSchema.nullable(),
+  matches: z2.array(AgentSearchMatchSchema).max(32),
+  nextCommands: z2.array(z2.string().min(1).max(512)).max(16)
+}).strict();
+var normalizeAgentHandoff = (input) => AgentHandoffV1Schema.parse(AgentHandoffLegacySchema.parse(input));
+
+// src/schemas/doc-bridge-index.ts
+import { z as z3 } from "zod";
+var INDEX_SCHEMA_VERSION = 1;
+var ContentHashAlgoSchema = z3.literal("sha256-normalized-v1");
+var EcosystemPropertySchema = z3.object({
+  id: z3.string().min(1).max(64),
+  name: z3.string().min(1).max(128),
+  url: z3.string().url().optional(),
+  llms: z3.string().url().optional()
+}).strict();
+var KnowledgeEntrySchema = z3.object({
+  id: z3.string().min(1).max(256),
+  type: z3.string().min(1).max(128),
+  title: z3.string().min(1).max(256),
+  path: z3.string().min(1).max(512),
+  description: z3.string().max(1024).optional(),
+  links: z3.array(z3.string().min(1).max(512)).max(64).optional(),
+  tags: z3.array(z3.string().min(1).max(64)).max(32).optional()
+}).strict();
+var CapabilityRefSchema = z3.object({
+  id: z3.string().min(1).max(256),
+  kind: z3.string().min(1).max(64),
+  description: z3.string().max(512).optional()
+}).strict();
+var OwnershipRecordSchema = z3.object({
+  id: z3.string().min(1).max(256),
+  path: z3.string().min(1).max(512),
+  group: z3.string().min(1).max(128).optional(),
+  layer: z3.string().min(1).max(32).optional(),
+  purpose: z3.string().max(1024).optional(),
+  checks: z3.array(z3.string().min(1).max(256)).max(32),
+  agentDoc: z3.string().min(1).max(512).optional(),
+  humanDoc: z3.string().min(1).max(512).optional(),
+  readme: z3.string().min(1).max(512).optional()
+}).strict();
+var IndexLookupSchema = z3.object({
+  packages: z3.array(z3.string().min(1).max(256)).max(2e3),
+  ownership: z3.record(z3.string().min(1).max(256), OwnershipRecordSchema).optional(),
+  intents: z3.record(
+    z3.string().min(1).max(128),
+    z3.object({
+      id: z3.string().min(1).max(128),
+      title: z3.string().min(1).max(256),
+      paths: z3.array(z3.string().min(1).max(512)).max(32)
+    }).strict()
+  ).optional(),
+  changes: z3.record(
+    z3.string().min(1).max(128),
+    z3.object({
+      id: z3.string().min(1).max(128),
+      title: z3.string().min(1).max(256),
+      startHere: z3.string().min(1).max(512),
+      relatedPackages: z3.array(z3.string().min(1).max(256)).max(32).optional()
+    }).strict()
+  ).optional()
+}).strict();
+var DocBridgeIndexV1Schema = z3.object({
+  schemaVersion: z3.literal(INDEX_SCHEMA_VERSION),
+  contentHash: z3.string().regex(/^[a-f0-9]{64}$/),
+  contentHashAlgo: ContentHashAlgoSchema,
+  generatedAt: z3.string().datetime().optional(),
+  project: z3.object({
+    name: z3.string().min(1).max(128),
+    root: z3.string().min(1).max(512).optional()
+  }).strict().optional(),
+  properties: z3.array(EcosystemPropertySchema).max(16).optional(),
+  knowledge: z3.array(KnowledgeEntrySchema).max(1e4),
+  capabilities: z3.array(CapabilityRefSchema).max(5e3).optional(),
+  handoffs: z3.record(z3.string().min(1).max(256), AgentHandoffLegacySchema).optional(),
+  lookup: IndexLookupSchema.optional()
+}).strict();
+
+// src/schemas/memory-candidate.ts
+import { z as z4 } from "zod";
+var MEMORY_CANDIDATE_SCHEMA_VERSION = 1;
+var MemorySourceSchema = z4.enum([
+  "cursor",
+  "claude",
+  "codex",
+  "copilot",
+  "agent-memory",
+  "manual"
+]);
+var MemorySuggestedTypeSchema = z4.enum([
+  "user",
+  "feedback",
+  "project",
+  "reference",
+  "unknown"
+]);
+var MemoryCandidateV1Schema = z4.object({
+  schemaVersion: z4.literal(MEMORY_CANDIDATE_SCHEMA_VERSION),
+  id: z4.string().min(1).max(256),
+  source: MemorySourceSchema,
+  rawPath: z4.string().min(1).max(512).optional(),
+  fact: z4.string().min(1).max(8e3),
+  why: z4.string().max(4e3).optional(),
+  howToApply: z4.string().max(4e3).optional(),
+  suggestedType: MemorySuggestedTypeSchema,
+  confidence: z4.number().min(0).max(1),
+  references: z4.array(z4.string().min(1).max(512)).max(64)
+}).strict();
+
+// src/validate.ts
+var zodIssues = (error) => error.issues.map((issue) => ({
+  path: issue.path.join(".") || "(root)",
+  message: issue.message
+}));
+var safeParseAgentHandoff = (input) => {
+  const legacy = AgentHandoffLegacySchema.safeParse(input);
+  if (!legacy.success) return { ok: false, issues: zodIssues(legacy.error) };
+  const normalized = AgentHandoffV1Schema.safeParse(normalizeAgentHandoff(legacy.data));
+  if (!normalized.success) return { ok: false, issues: zodIssues(normalized.error) };
+  return { ok: true, value: normalized.data };
+};
+var parseAgentHandoff = (input) => {
+  const result = safeParseAgentHandoff(input);
+  if (!result.ok) {
+    throw new Error(
+      `Invalid AgentHandoff:
+${result.issues.map((i) => `  - ${i.path}: ${i.message}`).join("\n")}`
+    );
+  }
+  return result.value;
+};
+var parseDocBridgeIndex = (input) => DocBridgeIndexV1Schema.parse(input);
+var parseDocBridgeConfig = (input) => {
+  const result = DocBridgeConfigV1Schema.safeParse(input);
+  if (!result.success) {
+    throw new Error(
+      `Invalid doc-bridge config:
+${zodIssues(result.error).map((i) => `  - ${i.path}: ${i.message}`).join("\n")}`
+    );
+  }
+  return result.data;
+};
+
+// src/query/load-index.ts
+var IndexNotFoundError = class extends Error {
+  constructor(path) {
+    super(`Missing index at ${path}. Run: ak-docs index`);
+    this.path = path;
+    this.name = "IndexNotFoundError";
+  }
+  path;
+};
+var indexFilePath = (root, config) => join10(root, config.index?.outFile ?? ".doc-bridge/index.json");
+var loadDocBridgeIndex = (root, config) => {
+  const path = indexFilePath(root, config);
+  if (!existsSync7(path)) throw new IndexNotFoundError(path);
+  const raw = JSON.parse(readFileSync9(path, "utf8"));
+  return parseDocBridgeIndex(raw);
+};
+
+// src/gates/run-gates.ts
+var SUPPORTED_GATES = ["index-freshness", "human-guide-links", "okf-type", "docs-style"];
+var runGate = (root, config, id) => {
+  if (id === "human-guide-links") return runHumanGuideLinksGate(root, config);
+  if (id === "okf-type") return runOkfTypeGate(root, config);
+  if (id === "docs-style") return runDocsStyleGate(root, config);
+  if (id !== "index-freshness") throw new Error(`Unsupported gate "${id}"`);
+  let current;
+  try {
+    current = loadDocBridgeIndex(root, config).contentHash;
+  } catch (error) {
+    if (error instanceof IndexNotFoundError) {
+      return { id, ok: false, message: error.message };
+    }
+    throw error;
+  }
+  const next = buildDocBridgeIndex({ root, config, write: false }).index.contentHash;
+  if (current !== next) {
+    return {
+      id,
+      ok: false,
+      message: "Index is stale. Run: ak-docs index",
+      expected: next,
+      actual: current
+    };
+  }
+  return { id, ok: true, message: "Index is fresh", expected: next, actual: current };
+};
+var runHumanGuideLinksGate = (root, config) => {
+  const urls = new Set(scanHumanDocRecords(root, config).map((doc) => doc.url));
+  const index = buildDocBridgeIndex({ root, config, write: false }).index;
+  const localHumanDocs = Object.values(index.handoffs ?? {}).map((handoff) => handoff.humanDoc).filter((url) => typeof url === "string" && url.length > 0).filter((url) => !/^https?:\/\//.test(url));
+  const missing = localHumanDocs.filter((url, i, all) => !urls.has(url) && all.indexOf(url) === i);
+  if (missing.length) {
+    return {
+      id: "human-guide-links",
+      ok: false,
+      message: `Broken humanDoc links: ${missing.join(", ")}`,
+      expected: "all local humanDoc links resolve",
+      actual: `${missing.length} broken`
+    };
+  }
+  return {
+    id: "human-guide-links",
+    ok: true,
+    message: `Resolved ${localHumanDocs.length} humanDoc link(s)`
+  };
+};
+var frontmatterType = (markdown) => {
+  const match = /^---\n([\s\S]*?)\n---/.exec(markdown);
+  return match?.[1]?.match(/^type:\s*['"]?([^'"\n#]+)['"]?/m)?.[1]?.trim();
+};
+var frontmatterField = (markdown, field) => {
+  const match = /^---\n([\s\S]*?)\n---/.exec(markdown);
+  return match?.[1]?.match(new RegExp(`^${field}:\\s*['"]?([^'"\\n#]+)['"]?`, "m"))?.[1]?.trim();
+};
+var runOkfTypeGate = (root, config) => {
+  const required = config.corpus.agent.okf?.requireType ?? config.gates?.preset === "strict";
+  if (!required) return { id: "okf-type", ok: true, message: "OKF type frontmatter not required" };
+  const allowed = config.corpus.agent.okf?.allowedTypes;
+  const bad = scanAgentCorpus(root, config).filter((doc) => doc.path !== config.corpus.agent.index).map((doc) => ({ path: doc.path, type: frontmatterType(readFileSync10(doc.absPath, "utf8")) })).filter((doc) => !doc.type || allowed && !allowed.includes(doc.type));
+  if (bad.length) {
+    return {
+      id: "okf-type",
+      ok: false,
+      message: `Missing or invalid OKF type frontmatter: ${bad.map((doc) => doc.path).join(", ")}`,
+      expected: allowed?.length ? `type: ${allowed.join(" | ")}` : "type frontmatter",
+      actual: `${bad.length} invalid`
+    };
+  }
+  return { id: "okf-type", ok: true, message: "All agent docs have OKF type frontmatter" };
+};
+var DOCS_STYLE_RULES = {
+  "google-dev-docs": [
+    "title",
+    "purpose",
+    "audience",
+    "task-orientation",
+    "examples",
+    "no-stale-wording"
+  ],
+  "playbook-okf": ["title", "purpose", "owner-source", "no-stale-wording"]
+};
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var docsStyleOptions = (config) => {
+  const raw = config.gates?.options?.["docs-style"];
+  if (!isRecord(raw)) return { profile: "playbook-okf", required: DOCS_STYLE_RULES["playbook-okf"] };
+  const profile = raw.profile === "google-dev-docs" || raw.profile === "playbook-okf" || raw.profile === "custom" ? raw.profile : "playbook-okf";
+  const customRequired = Array.isArray(raw.required) ? raw.required.filter(
+    (rule) => [
+      "title",
+      "purpose",
+      "audience",
+      "task-orientation",
+      "examples",
+      "owner-source",
+      "no-stale-wording"
+    ].includes(String(rule))
+  ) : [];
+  return {
+    profile,
+    required: profile === "custom" ? customRequired : DOCS_STYLE_RULES[profile]
+  };
+};
+var missingStyleRules = (markdown, rules) => {
+  const checks = {
+    title: /^#\s+\S+/m.test(markdown),
+    purpose: Boolean(frontmatterField(markdown, "purpose") || /^##\s+(Purpose|Goal)\b/im.test(markdown)),
+    audience: Boolean(frontmatterField(markdown, "audience") || /^##\s+Audience\b/im.test(markdown)),
+    "task-orientation": /^##\s+(How to|Usage|Workflow|Tasks?)\b/im.test(markdown),
+    examples: /^##\s+Examples?\b/im.test(markdown) || /```[\s\S]*?```/.test(markdown),
+    "owner-source": Boolean(
+      frontmatterField(markdown, "owner") || frontmatterField(markdown, "source") || /^(Owner|Source):\s+\S+/im.test(markdown)
+    ),
+    "no-stale-wording": !/\b(TODO|TBD|coming soon|eventually|placeholder)\b/i.test(markdown)
+  };
+  return rules.filter((rule) => !checks[rule]);
+};
+var runDocsStyleGate = (root, config) => {
+  const { profile, required } = docsStyleOptions(config);
+  if (!required.length) {
+    return { id: "docs-style", ok: true, message: "No docs-style rules configured" };
+  }
+  const bad = scanAgentCorpus(root, config).filter((doc) => doc.path !== config.corpus.agent.index).map((doc) => ({
+    path: doc.path,
+    missing: missingStyleRules(readFileSync10(doc.absPath, "utf8"), required)
+  })).filter((doc) => doc.missing.length > 0);
+  if (bad.length) {
+    return {
+      id: "docs-style",
+      ok: false,
+      message: `Docs style issues: ${bad.map((doc) => `${doc.path} (${doc.missing.join(", ")})`).join("; ")}`,
+      expected: `${profile}: ${required.join(", ")}`,
+      actual: `${bad.length} file(s) with style issues`
+    };
+  }
+  return {
+    id: "docs-style",
+    ok: true,
+    message: `All agent docs pass ${profile} docs-style rules`
+  };
+};
+var runGates = (root, config, ids) => {
+  const results = (ids ?? resolveGateIds(config)).map((id) => runGate(root, config, id));
+  return { ok: results.every((result) => result.ok), results };
+};
+var resolveGateIds = (config) => {
+  const preset = config.gates?.preset ?? "minimal";
+  const ids = new Set(
+    preset === "minimal" ? ["index-freshness"] : preset === "strict" ? ["index-freshness", "human-guide-links", "okf-type"] : ["index-freshness", "human-guide-links"]
+  );
+  for (const id of config.gates?.include ?? []) {
+    if (SUPPORTED_GATES.includes(id)) ids.add(id);
+  }
+  for (const id of config.gates?.exclude ?? []) {
+    if (SUPPORTED_GATES.includes(id)) ids.delete(id);
+  }
+  return [...ids];
+};
+
+// src/query/query.ts
+var handoffForPackage = (index, id, config) => {
+  const fromIndex = index.handoffs?.[id];
+  if (fromIndex) return normalizeAgentHandoff(fromIndex);
+  const owner = index.lookup?.ownership?.[id];
+  if (!owner) throw new Error(`Unknown package/ownership id "${id}". Try: ak-docs list packages`);
+  return normalizeAgentHandoff({
+    type: "agent-handoff",
+    source: config.index?.outFile ?? ".doc-bridge/index.json",
+    target: {
+      type: "package",
+      id,
+      path: owner.path,
+      ...owner.group ? { group: owner.group } : {},
+      ...owner.layer ? { layer: owner.layer } : {}
+    },
+    startHere: owner.agentDoc ?? config.corpus.agent.index ?? "",
+    readBeforeEditing: [owner.agentDoc, "AGENTS.md"].filter(Boolean),
+    editRoots: [owner.path],
+    checks: [...owner.checks],
+    ...owner.humanDoc ? { humanDoc: owner.humanDoc } : {},
+    notes: owner.purpose ? [owner.purpose] : []
+  });
+};
+var runQuery = (index, config, req) => {
+  if (req.kind === "search") {
+    const term = req.term ?? req.id ?? "";
+    const matches = searchIndex(index, term);
+    if (req.agent) {
+      const payload = {
+        type: "agent-search",
+        schemaVersion: 1,
+        source: config.index?.outFile ?? ".doc-bridge/index.json",
+        term,
+        count: matches.length,
+        bestMatch: matches[0] ? {
+          type: matches[0].type,
+          id: matches[0].id,
+          path: matches[0].path,
+          ...matches[0].summary ? { summary: matches[0].summary } : {},
+          score: matches[0].score
+        } : null,
+        matches: matches.slice(0, 8).map((m) => ({
+          type: m.type,
+          id: m.id,
+          path: m.path,
+          ...m.summary ? { summary: m.summary } : {},
+          score: m.score
+        })),
+        nextCommands: [...new Set(matches.slice(0, 5).map(
+          (m) => m.type === "ownership" || index.lookup?.ownership?.[m.id] ? `ak-docs query ownership ${m.id} --agent` : "ak-docs list knowledge --text"
+        ))]
+      };
+      return payload;
+    }
+    return { type: "search", data: { term, count: matches.length, matches } };
+  }
+  const id = req.id;
+  if (!id) throw new Error(`Missing id for query kind "${req.kind}"`);
+  if (req.kind === "package" || req.kind === "ownership") {
+    if (req.agent) return handoffForPackage(index, id, config);
+    const owner = index.lookup?.ownership?.[id];
+    return { type: req.kind, data: owner ?? index.handoffs?.[id] ?? null };
+  }
+  if (req.kind === "intent") {
+    const intent = index.lookup?.intents?.[id];
+    if (!intent) throw new Error(`Unknown intent "${id}"`);
+    if (req.agent) {
+      return normalizeAgentHandoff({
+        type: "agent-handoff",
+        source: config.index?.outFile ?? ".doc-bridge/index.json",
+        target: { type: "intent", id },
+        startHere: intent.paths[0] ?? "",
+        readBeforeEditing: [...intent.paths],
+        editRoots: [],
+        checks: [],
+        notes: [intent.title]
+      });
+    }
+    return { type: "intent", data: intent };
+  }
+  if (req.kind === "change") {
+    const change = index.lookup?.changes?.[id];
+    if (!change) throw new Error(`Unknown change route "${id}"`);
+    if (req.agent) {
+      return normalizeAgentHandoff({
+        type: "agent-handoff",
+        source: config.index?.outFile ?? ".doc-bridge/index.json",
+        target: { type: "change", id },
+        startHere: change.startHere,
+        readBeforeEditing: ["AGENTS.md", config.corpus.agent.index ?? ""].filter(Boolean),
+        editRoots: [change.startHere],
+        checks: [],
+        notes: [change.title]
+      });
+    }
+    return { type: "change", data: change };
+  }
+  throw new Error(`Unsupported query kind: ${req.kind}`);
+};
+
+// src/intelligence/adapter.ts
+import { join as join11 } from "path";
+
+// src/intelligence/peers.ts
+var PeerMissingError = class extends Error {
+  constructor(peer, installHint) {
+    super(
+      `Optional peer "${peer}" is not installed.
+Install Layer 1 intelligence peers:
+  ${installHint}`
+    );
+    this.peer = peer;
+    this.installHint = installHint;
+    this.name = "PeerMissingError";
+  }
+  peer;
+  installHint;
+};
+var LAYER1_INSTALL = "npm i -D @agentskit/rag @agentskit/ink @agentskit/adapters @agentskit/memory react";
+var isPeerResolutionFailure = (error) => {
+  const parts = [];
+  let cur = error;
+  for (let i = 0; i < 6 && cur; i += 1) {
+    if (cur instanceof Error) {
+      parts.push(cur.message, cur.name);
+      const code = cur.code;
+      if (code) parts.push(String(code));
+      cur = cur.cause;
+      continue;
+    }
+    parts.push(String(cur));
+    break;
+  }
+  const text = parts.join(" ").toLowerCase();
+  return text.includes("cannot find package") || text.includes("cannot find module") || text.includes("module not found") || text.includes("err_module_not_found") || text.includes("err_package_not_found") || text.includes("err_package_path_not_exported") || text.includes("failed to resolve module") || text.includes("failed to resolve") || // Node / network resolution edge cases for bare package imports
+  text.includes("fetch failed") || text.includes("enotfound") || text.includes("getaddrinfo");
+};
+var importPeer = async (name) => {
+  try {
+    return await import(name);
+  } catch (error) {
+    if (isPeerResolutionFailure(error)) {
+      throw new PeerMissingError(name, LAYER1_INSTALL);
+    }
+    throw error;
+  }
+};
+var layer1InstallHint = () => LAYER1_INSTALL;
+
+// src/intelligence/adapter.ts
+var readEnv = (name) => {
+  if (!name) return void 0;
+  const value = process.env[name];
+  return value && value.length > 0 ? value : void 0;
+};
+var resolveIntelligenceRuntime = async (config) => {
+  if (!config.intelligence?.enabled) {
+    throw new Error("Intelligence is disabled. Set intelligence.enabled: true in doc-bridge config.");
+  }
+  const adapterCfg = config.intelligence.adapter;
+  if (!adapterCfg) {
+    throw new Error("intelligence.adapter is required for chat/RAG (provider + optional model).");
+  }
+  const adapters = await importPeer("@agentskit/adapters");
+  const provider = adapterCfg.provider;
+  const model = adapterCfg.model;
+  const apiKey = readEnv(adapterCfg.apiKeyEnv) ?? readEnv("OPENAI_API_KEY") ?? readEnv("ANTHROPIC_API_KEY");
+  const baseUrl = adapterCfg.baseUrl;
+  let adapter;
+  let embed;
+  switch (provider) {
+    case "ollama": {
+      adapter = adapters.ollama({ model: model ?? "llama3.2", ...baseUrl ? { baseUrl } : {} });
+      embed = adapters.ollamaEmbedder({
+        model: typeof adapterCfg.options?.embedModel === "string" ? adapterCfg.options.embedModel : "nomic-embed-text",
+        ...baseUrl ? { baseUrl } : {}
+      });
+      break;
+    }
+    case "openai": {
+      if (!apiKey) throw new Error(`Missing API key env ${adapterCfg.apiKeyEnv ?? "OPENAI_API_KEY"}`);
+      adapter = adapters.openai({ apiKey, ...model ? { model } : {}, ...baseUrl ? { baseUrl } : {} });
+      embed = adapters.openaiEmbedder({ apiKey, model: "text-embedding-3-small" });
+      break;
+    }
+    case "anthropic": {
+      if (!apiKey) throw new Error(`Missing API key env ${adapterCfg.apiKeyEnv ?? "ANTHROPIC_API_KEY"}`);
+      adapter = adapters.anthropic({ apiKey, ...model ? { model } : {} });
+      const openaiKey = readEnv("OPENAI_API_KEY");
+      if (openaiKey) embed = adapters.openaiEmbedder({ apiKey: openaiKey });
+      else {
+        throw new Error(
+          "Anthropic chat requires an embedder for RAG. Set OPENAI_API_KEY for embeddings or use provider: ollama."
+        );
+      }
+      break;
+    }
+    case "openrouter": {
+      if (!apiKey) throw new Error(`Missing API key env ${adapterCfg.apiKeyEnv ?? "OPENROUTER_API_KEY"}`);
+      adapter = adapters.openrouter({ apiKey, ...model ? { model } : {} });
+      embed = adapters.openaiEmbedder({
+        apiKey,
+        model: "text-embedding-3-small"
+        // openrouter embeddings path may vary; adapters handle openai-compatible
+      });
+      break;
+    }
+    case "custom":
+      throw new Error(
+        "provider: custom requires a programmatic integration. Use ollama, openai, anthropic, or openrouter in v0.1."
+      );
+    default:
+      throw new Error(`Unsupported intelligence.adapter.provider: ${String(provider)}`);
+  }
+  return { adapter, embed, provider, ...model ? { model } : {} };
+};
+var defaultVectorStorePath = (root) => join11(root, ".doc-bridge", "vectors");
+
+// src/intelligence/rag.ts
+import { readFileSync as readFileSync11 } from "fs";
+import { join as join12 } 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 = join12(root, entry.path);
+      let content = "";
+      try {
+        content = readFileSync11(abs, "utf8");
+      } catch {
+        content = [entry.title, entry.description].filter(Boolean).join("\n\n");
+      }
+      docs.push({
+        id: entry.id,
+        content,
+        source: entry.path,
+        metadata: { type: entry.type, title: entry.title, path: entry.path }
+      });
+    }
+  }
+  return docs;
+};
+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" ? join12(root, config.intelligence.retriever.options.storePath) : defaultVectorStorePath(root);
+  const store = memoryMod.fileVectorMemory({ path: storePath });
+  const rag = ragMod.createRAG({
+    embed,
+    store,
+    topK: 6,
+    chunkSize: 900,
+    chunkOverlap: 120
+  });
+  const sources = config.intelligence?.chat?.sources ?? ["agent", "human"];
+  return {
+    storePath,
+    retriever: rag,
+    ingest: async () => {
+      const documents = loadDocuments(root, index, sources);
+      await rag.ingest(documents);
+      return { documentCount: documents.length, storePath };
+    },
+    search: async (query, topK = 6) => {
+      const hits = await rag.search(query, { topK });
+      return hits.map((hit) => ({
+        ...hit.id ? { id: hit.id } : {},
+        content: hit.content,
+        ...hit.score !== void 0 ? { score: hit.score } : {},
+        ...hit.source ? { source: hit.source } : {},
+        ...hit.metadata ? { metadata: hit.metadata } : {}
+      }));
+    }
+  };
+};
+
+// src/intelligence/chat.ts
+var wrapIntelligenceError = (error) => {
+  if (error instanceof PeerMissingError) return error;
+  if (isPeerResolutionFailure(error)) {
+    return new PeerMissingError("@agentskit/*", layer1InstallHint());
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  if (/fetch failed|econnrefused|enotfound|network|socket/i.test(message)) {
+    return new Error(
+      `Intelligence provider request failed (${message}).
+Check the model server (e.g. \`ollama serve\`) and Layer 1 peers:
+  ${layer1InstallHint()}`
+    );
+  }
+  return error instanceof Error ? error : new Error(message);
+};
+var handoffFirstHint = (index, config, question) => {
+  if (config.intelligence?.chat?.handoffFirst === false) return void 0;
+  const tokens = question.toLowerCase().split(/[^a-z0-9@/_-]+/).filter((t) => t.length >= 2);
+  const packages = index.lookup?.packages ?? [];
+  const hit = packages.find((id) => tokens.includes(id.toLowerCase()));
+  if (!hit) return void 0;
+  try {
+    const handoff = runQuery(index, config, { kind: "ownership", id: hit, agent: true });
+    return [
+      "## Deterministic AgentHandoff (prefer for edits)",
+      "```json",
+      JSON.stringify(handoff, null, 2),
+      "```",
+      "Use startHere / editRoots / checks before broad exploration."
+    ].join("\n");
+  } catch {
+    return void 0;
+  }
+};
+var systemPrompt = (index, config, provider, model, question) => {
+  const prefix = question ? handoffFirstHint(index, config, question) : void 0;
+  return [
+    "You are a documentation assistant for this repository (doc-bridge).",
+    "Prefer deterministic AgentHandoff fields for code edits.",
+    "Cite file paths from retrieved context.",
+    `Provider: ${provider}${model ? ` / ${model}` : ""}.`,
+    "If unsure, suggest: ak-docs query ownership <id> --agent or MCP handoff.resolve.",
+    prefix ?? ""
+  ].filter(Boolean).join("\n\n");
+};
+var runChatOnce = async (root, config, index, question) => {
+  try {
+    const { adapter, provider, model } = await resolveIntelligenceRuntime(config);
+    const core = await importPeer("@agentskit/core");
+    const rag = await createDocBridgeRag(root, config, index);
+    await rag.ingest();
+    const controller = core.createChatController({
+      adapter,
+      retriever: rag.retriever,
+      system: systemPrompt(index, config, provider, model, question)
+    });
+    const result = await controller.send(question);
+    const content = typeof result?.content === "string" ? result.content : JSON.stringify(result, null, 2);
+    return {
+      content,
+      handoffPrefixed: Boolean(handoffFirstHint(index, config, question))
+    };
+  } catch (error) {
+    throw wrapIntelligenceError(error);
+  }
+};
+var startInkChat = async (root, config, index) => {
+  try {
+    const { adapter, provider, model } = await resolveIntelligenceRuntime(config);
+    const rag = await createDocBridgeRag(root, config, index);
+    await rag.ingest();
+    const React = await importPeer("react");
+    const ink = await importPeer("ink");
+    const agentskitInk = await importPeer("@agentskit/ink");
+    const App = () => {
+      const chat = agentskitInk.useChat({
+        adapter,
+        retriever: rag.retriever,
+        system: systemPrompt(index, config, provider, model)
+      });
+      return React.createElement(
+        agentskitInk.ChatContainer,
+        null,
+        ...chat.messages.map(
+          (msg) => React.createElement(agentskitInk.Message, {
+            key: msg.id,
+            message: msg
+          })
+        ),
+        React.createElement(agentskitInk.InputBar, {
+          chat,
+          placeholder: "Ask about project docs (handoff-first RAG)\u2026"
+        })
+      );
+    };
+    const instance = ink.render(React.createElement(App));
+    await instance.waitUntilExit();
+  } catch (error) {
+    throw wrapIntelligenceError(error);
+  }
+};
+
+// src/memory/ingest.ts
+import { existsSync as existsSync8, readFileSync as readFileSync12 } from "fs";
+import { join as join13 } from "path";
+var memoryFact = (raw, id) => firstParagraph(raw) ?? firstHeading(raw) ?? id;
+var relativePath = (root, abs) => toPosix(abs).replace(`${toPosix(root)}/`, "");
+var ingestMarkdownDir = (root, dir, source, confidence) => {
+  if (!existsSync8(dir)) return [];
+  return walkFiles(dir, { extensions: [".md", ".mdc"] }).map((abs) => {
+    const rel = relativePath(root, abs);
+    const raw = readFileSync12(abs, "utf8");
+    const id = slugFromPath(rel);
+    return {
+      schemaVersion: 1,
+      id,
+      source,
+      rawPath: rel,
+      fact: memoryFact(raw, id),
+      suggestedType: "project",
+      confidence,
+      references: []
+    };
+  });
+};
+var ingestCursorRules = (root) => {
+  const dir = join13(root, ".cursor", "rules");
+  return ingestMarkdownDir(root, dir, "cursor", 0.6);
+};
+var ingestAgentMemory = (root) => ingestMarkdownDir(root, join13(root, ".agent-memory"), "agent-memory", 0.7);
+var ingestMemoryCandidates = (root) => [
+  ...ingestAgentMemory(root),
+  ...ingestCursorRules(root)
+];
+
+// src/memory/pipeline.ts
+var packageOwnership = /\b(?:package|module)\s+([a-z0-9._/-]+)\s+(?:owns|owner|responsible|routes?)\b/i;
+var secretPattern = /\b(?:api[_-]?key|token|secret|password)\s*[:=]\s*\S+/i;
+var privateEmailPattern = /\b[A-Z0-9._%+-]+@(?!example\.com\b)[A-Z0-9.-]+\.[A-Z]{2,}\b/i;
+var classifyRoute = (fact) => {
+  if (/\b(noise|scratch|ignore|discard)\b/i.test(fact)) {
+    return { route: "discard", reason: "marked as noise" };
+  }
+  if (/\b(playbook|pattern|principle|best practice)\b/i.test(fact)) {
+    return { route: "playbook", reason: "generalizable pattern" };
+  }
+  if (/\b(user-facing|human guide|docs site|tutorial|guide)\b/i.test(fact)) {
+    return { route: "human", reason: "user-facing documentation" };
+  }
+  return { route: "agent", reason: "project convention or ownership note" };
+};
+var classifyMemoryCandidates = (candidates, index) => candidates.map((candidate) => {
+  const duplicate = searchIndex(index, candidate.fact, 1)[0];
+  const targetMatch = packageOwnership.exec(candidate.fact);
+  const route = classifyRoute(candidate.fact);
+  return {
+    candidate,
+    ...route,
+    ...targetMatch?.[1] ? { target: targetMatch[1] } : {},
+    ...duplicate && duplicate.score >= 16 ? { duplicateOf: duplicate.path } : {}
+  };
+});
+var scanMemorySafety = (classifications) => classifications.flatMap(({ candidate }) => {
+  const findings = [];
+  if (secretPattern.test(candidate.fact)) {
+    findings.push({
+      candidateId: candidate.id,
+      kind: "secret",
+      message: "Potential secret-like value in memory fact"
+    });
+  }
+  if (privateEmailPattern.test(candidate.fact)) {
+    findings.push({
+      candidateId: candidate.id,
+      kind: "private-email",
+      message: "Potential private email in memory fact"
+    });
+  }
+  return findings;
+});
+var draftMemoryPromotion = (classifications) => {
+  const findings = scanMemorySafety(classifications);
+  const safe = findings.length === 0;
+  const lines = classifications.map(
+    ({ candidate, route, reason, target, duplicateOf }) => [
+      `- ${candidate.id}: ${route}`,
+      `reason=${reason}`,
+      target ? `target=${target}` : void 0,
+      duplicateOf ? `duplicateOf=${duplicateOf}` : void 0,
+      `fact=${candidate.fact}`
+    ].filter(Boolean).join(" | ")
+  );
+  return {
+    ok: safe,
+    title: "Draft doc-bridge memory promotion",
+    body: [
+      "# Draft doc-bridge memory promotion",
+      "",
+      safe ? "Safety scan: pass." : "Safety scan: blocked. Redact findings before PR.",
+      "",
+      "## Candidates",
+      "",
+      ...lines,
+      "",
+      "## Policy",
+      "",
+      "- Draft only; never auto-merge.",
+      "- Run doc-bridge gates before opening a PR."
+    ].join("\n"),
+    findings,
+    classifications: [...classifications]
+  };
+};
+
+// src/mcp/server.ts
+import { readFileSync as readFileSync13, realpathSync } from "fs";
+import { relative, resolve as resolve5 } from "path";
+import { z as z5, ZodError } from "zod";
+var MCP_TOOLS = [
+  {
+    name: "handoff.resolve",
+    description: "Resolve a package or ownership id to an AgentHandoff.",
+    inputSchema: {
+      type: "object",
+      properties: { id: { type: "string" }, kind: { type: "string", enum: ["package", "ownership"] } },
+      required: ["id"]
+    }
+  },
+  {
+    name: "doc.search",
+    description: "Search the deterministic doc-bridge index.",
+    inputSchema: {
+      type: "object",
+      properties: { term: { type: "string" }, limit: { type: "number" } },
+      required: ["term"]
+    }
+  },
+  {
+    name: "doc.get",
+    description: "Read an indexed agent documentation file by id or path.",
+    inputSchema: {
+      type: "object",
+      properties: { id: { type: "string" }, path: { type: "string" } }
+    }
+  },
+  {
+    name: "gate.status",
+    description: "Run the index-freshness gate.",
+    inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "retriever.query",
+    description: "Return local doc-bridge retriever chunks for a query.",
+    inputSchema: {
+      type: "object",
+      properties: { query: { type: "string" }, limit: { type: "number" } },
+      required: ["query"]
+    }
+  },
+  {
+    name: "memory.classify",
+    description: "Classify local memory candidates into agent/human/playbook/discard routes.",
+    inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "memory.promoteDraft",
+    description: "Build a safe draft promotion body for local memory candidates.",
+    inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "registry.topology",
+    description: "Return the doc-curator registry topology.",
+    inputSchema: { type: "object", properties: {} }
+  }
+];
+var asRecord = (value) => value && typeof value === "object" ? value : {};
+var HandoffResolveArgsSchema = z5.object({
+  id: z5.string().min(1),
+  kind: z5.enum(["package", "ownership"]).optional()
+});
+var DocSearchArgsSchema = z5.object({
+  term: z5.string().min(1),
+  limit: z5.number().int().positive().max(100).optional()
+});
+var RetrieverQueryArgsSchema = z5.object({
+  query: z5.string().min(1),
+  limit: z5.number().int().positive().max(100).optional()
+});
+var DocGetArgsSchema = z5.object({
+  id: z5.string().min(1).optional(),
+  path: z5.string().min(1).optional()
+}).refine((args) => args.id || args.path, "doc.get requires id or path");
+var parseToolArgs = (tool, schema, value) => {
+  try {
+    return schema.parse(value);
+  } catch (error) {
+    if (error instanceof ZodError) {
+      throw new Error(`${tool} invalid arguments: ${error.issues.map((issue) => issue.message).join(", ")}`);
+    }
+    throw error;
+  }
+};
+var textResult = (value) => ({
+  content: [
+    {
+      type: "text",
+      text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
+    }
+  ]
+});
+var findDocPath = (index, args) => {
+  if (args.path) {
+    const doc2 = index.knowledge.find((entry) => entry.path === args.path);
+    if (!doc2) throw new Error(`Unknown indexed doc path "${args.path}"`);
+    return doc2.path;
+  }
+  const id = args.id ?? "";
+  const doc = index.knowledge.find((entry) => entry.id === args.id);
+  if (!doc) throw new Error(`Unknown doc id "${id}"`);
+  return doc.path;
+};
+var resolveDocPath = (root, relPath) => {
+  const rootAbs = realpathSync.native(root);
+  const unresolved = resolve5(rootAbs, relPath);
+  const unresolvedRel = relative(rootAbs, unresolved);
+  if (unresolvedRel.startsWith("..")) throw new Error("doc.get path escapes project root");
+  const abs = realpathSync.native(unresolved);
+  const rel = relative(rootAbs, abs);
+  if (rel.startsWith("..")) throw new Error("doc.get path escapes project root");
+  return abs;
+};
+var handleMcpRequest = (ctx, request) => {
+  if (request.method === "initialize") {
+    return {
+      protocolVersion: "2024-11-05",
+      capabilities: { tools: {} },
+      serverInfo: { name: "ak-docs", version: "0.1.0-alpha.1" }
+    };
+  }
+  if (request.method === "tools/list") return { tools: MCP_TOOLS };
+  if (request.method === "tools/call") {
+    const params = asRecord(request.params);
+    const name = params.name;
+    const args = asRecord(params.arguments);
+    const index = () => ctx.loadIndex?.() ?? loadDocBridgeIndex(ctx.root, ctx.config);
+    if (name === "handoff.resolve") {
+      const parsed = parseToolArgs("handoff.resolve", HandoffResolveArgsSchema, args);
+      return textResult(
+        runQuery(index(), ctx.config, {
+          kind: parsed.kind === "package" ? "package" : "ownership",
+          id: parsed.id,
+          agent: true
+        })
+      );
+    }
+    if (name === "doc.search") {
+      const parsed = parseToolArgs("doc.search", DocSearchArgsSchema, args);
+      return textResult(searchIndex(index(), parsed.term, parsed.limit ?? 20));
+    }
+    if (name === "doc.get") {
+      const relPath = findDocPath(index(), parseToolArgs("doc.get", DocGetArgsSchema, args));
+      return textResult(readFileSync13(resolveDocPath(ctx.root, relPath), "utf8"));
+    }
+    if (name === "gate.status") return textResult(runGates(ctx.root, ctx.config));
+    if (name === "retriever.query") {
+      const parsed = parseToolArgs("retriever.query", RetrieverQueryArgsSchema, args);
+      return textResult(retrieveDocBridgeChunks(index(), parsed.query, parsed.limit ? { limit: parsed.limit } : {}));
+    }
+    if (name === "memory.classify") {
+      return textResult(classifyMemoryCandidates(ingestMemoryCandidates(ctx.root), index()));
+    }
+    if (name === "memory.promoteDraft") {
+      return textResult(draftMemoryPromotion(classifyMemoryCandidates(ingestMemoryCandidates(ctx.root), index())));
+    }
+    if (name === "registry.topology") {
+      return textResult({
+        id: "doc-curator",
+        delegates: ["docs-chat", "knowledge-promoter", "code-review"],
+        tools: ["handoff.resolve", "doc.search", "doc.get", "gate.status", "retriever.query"],
+        steps: ["classify", "draft", "verify", "review"],
+        mergePolicy: { autoMerge: false, requiresHuman: true }
+      });
+    }
+    throw new Error(`Unknown tool "${String(name)}"`);
+  }
+  if (request.method?.startsWith("notifications/")) return void 0;
+  throw new Error(`Unsupported MCP method "${request.method ?? ""}"`);
+};
+var writeFrame = (payload) => {
+  const body = JSON.stringify(payload);
+  process.stdout.write(`Content-Length: ${Buffer.byteLength(body)}\r
+\r
+${body}`);
+};
+var respond = (ctx, request) => {
+  if (request.id === void 0) {
+    try {
+      handleMcpRequest(ctx, request);
+    } catch {
+    }
+    return;
+  }
+  try {
+    const result = handleMcpRequest(ctx, request);
+    writeFrame({ jsonrpc: "2.0", id: request.id, result: result ?? {} });
+  } catch (error) {
+    writeFrame({
+      jsonrpc: "2.0",
+      id: request.id,
+      error: { code: -32e3, message: error instanceof Error ? error.message : String(error) }
+    });
+  }
+};
+var startMcpStdioServer = (ctx) => {
+  let buffer = Buffer.alloc(0);
+  process.stdin.on("data", (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    while (true) {
+      const headerEnd = buffer.indexOf("\r\n\r\n");
+      if (headerEnd === -1) return;
+      const header = buffer.subarray(0, headerEnd).toString("utf8");
+      const match = /content-length:\s*(\d+)/i.exec(header);
+      if (!match?.[1]) {
+        buffer = buffer.subarray(headerEnd + 4);
+        continue;
+      }
+      const length = Number(match[1]);
+      const bodyStart = headerEnd + 4;
+      const bodyEnd = bodyStart + length;
+      if (buffer.length < bodyEnd) return;
+      const raw = buffer.subarray(bodyStart, bodyEnd).toString("utf8");
+      buffer = buffer.subarray(bodyEnd);
+      respond(ctx, JSON.parse(raw));
+    }
+  });
+  process.stdin.resume();
+};
+
+// src/cli/program.ts
+var usage = `ak-docs \u2014 human\u2194agent documentation bridge (@agentskit/doc-bridge)
+
+Core (no API key):
+  ak-docs init [--demo] [--scaffold-workspaces]
+  ak-docs index
+  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 mcp
+  ak-docs memory ingest|classify|promote
+  ak-docs bootstrap agent-docs
+  ak-docs validate-config | validate-handoff <file>
+
+Intelligence (optional AgentsKit peers):
+  ak-docs rag ingest|search <query>
+  ak-docs chat                    terminal chat (Ink + RAG)
+  ak-docs ask <question> --chat   one-shot grounded answer
+
+Advanced / ecosystem:
+  ak-docs retrieve <query>
+  ak-docs registry topology
+  ak-docs playbook draft
+
+Global flags:
+  -h, --help   --version
+  --config <path>   (project root = config file directory)
+  --agent   --json   --text   --chat   --demo
+`;
+var QUERY_KINDS = /* @__PURE__ */ new Set(["package", "ownership", "intent", "change", "search"]);
+var LIST_KINDS = /* @__PURE__ */ new Set(["packages", "intents", "changes", "knowledge"]);
+var GATE_IDS = /* @__PURE__ */ new Set(["index-freshness", "human-guide-links", "okf-type", "docs-style"]);
+var parseArgs = (argv) => {
+  const flags = /* @__PURE__ */ new Set();
+  let configPath;
+  const positional = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg) continue;
+    if (arg === "--config") {
+      configPath = argv[i + 1];
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      flags.add(arg);
+      continue;
+    }
+    positional.push(arg);
+  }
+  let command = "help";
+  if (flags.has("--version") || flags.has("-V")) command = "version";
+  else if (flags.has("--help") || flags.has("-h")) command = "help";
+  else if (positional[0] === "validate-config") command = "validate-config";
+  else if (positional[0] === "validate-handoff") command = "validate-handoff";
+  else if (positional[0] === "init") command = "init";
+  else if (positional[0] === "bootstrap") command = "bootstrap";
+  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] === "index") command = "index";
+  else if (positional[0] === "gate") command = "gate";
+  else if (positional[0] === "mcp") command = "mcp";
+  else if (positional[0] === "query") command = "query";
+  else if (positional[0] === "search") command = "search";
+  else if (positional[0] === "retrieve") command = "retrieve";
+  else if (positional[0] === "ask") command = "ask";
+  else if (positional[0] === "chat") command = "chat";
+  else if (positional[0] === "rag") command = "rag";
+  else if (positional[0] === "list") command = "list";
+  return { command, flags, configPath, positional };
+};
+var writeJson = (payload) => {
+  process.stdout.write(`${JSON.stringify(payload, null, 2)}
+`);
+};
+var writeLines = (lines) => {
+  process.stdout.write(lines.length ? `${lines.join("\n")}
+` : "");
+};
+var textValue = (value) => {
+  if (value === null || value === void 0) return "Not found";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  return JSON.stringify(value, null, 2);
+};
+var writeTextQuery = (payload) => {
+  if (!payload || typeof payload !== "object" || !("data" in payload)) {
+    writeLines([textValue(payload)]);
+    return;
+  }
+  const result = payload;
+  if (result.type === "search") {
+    const data = result.data;
+    const matches = data.matches ?? [];
+    writeLines([
+      `Search: ${String(data.term ?? "")}`,
+      `Matches: ${String(data.count ?? matches.length)}`,
+      ...matches.map(
+        (match) => [match.type, match.id, match.path, match.summary].filter(Boolean).join("	")
+      )
+    ]);
+    return;
+  }
+  writeLines([textValue(result.data)]);
+};
+var writeTextSearch = (term, matches) => {
+  writeLines([
+    `Search: ${term}`,
+    `Matches: ${matches.length}`,
+    ...matches.map(
+      (match) => [match.type, match.id, match.path, match.summary].filter(Boolean).join("	")
+    )
+  ]);
+};
+var writeAsk = (question, matches, index) => {
+  const best = matches[0];
+  const owner = matches.find((match) => match.type === "ownership" || index.lookup?.ownership?.[match.id]);
+  const bestQuery = owner ? `ak-docs query ownership ${owner.id} --agent` : "ak-docs list knowledge --text";
+  writeLines([
+    `Question: ${question}`,
+    best ? `Best match: ${best.type} ${best.id} (${best.path})` : "Best match: none",
+    "",
+    "Matches:",
+    ...matches.length ? matches.slice(0, 5).map(
+      (match) => [match.type, match.id, match.path, match.summary].filter(Boolean).join("	")
+    ) : ["No local matches. Try: ak-docs search <term>"],
+    "",
+    "Next commands:",
+    ...best ? [
+      `ak-docs search "${question}" --agent`,
+      bestQuery
+    ] : ["ak-docs list knowledge --text"]
+  ]);
+};
+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 = resolve6(root, entry.path);
+  const rootAbs = resolve6(root);
+  if (abs !== rootAbs && !abs.startsWith(`${rootAbs}/`)) {
+    throw new Error(`Indexed doc escapes project root: ${entry.path}`);
+  }
+  return readFileSync14(abs, "utf8");
+};
+var runAskRepl = async (root, config) => {
+  const index = loadDocBridgeIndex(root, config);
+  const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+  try {
+    for (; ; ) {
+      const line = (await rl.question("ak-docs> ")).trim();
+      if (!line) continue;
+      if (line === "exit" || line === "quit") return 0;
+      const [command, ...rest] = line.split(/\s+/);
+      const value = rest.join(" ").trim();
+      try {
+        if (command === "search") {
+          writeTextSearch(value, searchIndex(index, value));
+        } else if (command === "read" || command === "open") {
+          process.stdout.write(`${readIndexedDoc(root, config, value).slice(0, 8e3)}
+`);
+        } else if (command === "resolve") {
+          writeJson(runQuery(index, config, { kind: "ownership", id: value, agent: true }));
+        } else if (command === "gate") {
+          const gateId = value || void 0;
+          writeJson(runGates(root, config, gateId ? [gateId] : void 0));
+        } else {
+          writeAsk(line, searchIndex(index, line, 8), index);
+        }
+      } catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+      }
+    }
+  } finally {
+    rl.close();
+  }
+};
+var wantsTextOutput = (flags, config) => !flags.has("--agent") && (flags.has("--text") || !flags.has("--json") && config.surfaces?.cli?.defaultFormat === "text");
+var loadProject = (configPath) => {
+  const loadOpts = configPath ? { explicitPath: configPath } : {};
+  const { config, path } = loadConfig(loadOpts);
+  parseDocBridgeConfig(config);
+  const root = projectRootFromConfigPath(path, config.project?.root);
+  return { config, configPath: path, root };
+};
+var indexDiagnostics = (config, result) => {
+  const diagnostics = [];
+  const onlyDoc = result.index.knowledge.length === 1 ? result.index.knowledge[0] : void 0;
+  if (onlyDoc?.path === config.corpus.agent.index) {
+    diagnostics.push(
+      `Only the starter ${config.corpus.agent.index} was indexed.`,
+      `Add agent docs under ${config.corpus.agent.root}/, then run ak-docs index again.`
+    );
+  }
+  const handoffCount = Object.keys(result.index.handoffs ?? {}).length;
+  if (handoffCount === 0) {
+    diagnostics.push(
+      "No ownership handoffs yet. Add routing.options.ownership, package frontmatter (package + editRoot), or a monorepo plugin."
+    );
+  }
+  return diagnostics;
+};
+var diagnosticNextCommands = (config, result) => {
+  const handoffIds = Object.keys(result.index.handoffs ?? {});
+  if (handoffIds[0]) {
+    return [
+      `ak-docs query package ${handoffIds[0]} --agent`,
+      `ak-docs list packages --text`,
+      "ak-docs mcp"
+    ];
+  }
+  return [
+    `mkdir -p ${config.corpus.agent.root}/packages`,
+    `edit ${config.corpus.agent.root}/packages/<module>.md  # frontmatter: package + editRoot`,
+    "ak-docs index"
+  ];
+};
+var writeIfMissing = (path, contents) => {
+  if (existsSync9(path)) return false;
+  mkdirSync2(dirname4(path), { recursive: true });
+  writeFileSync2(path, contents, "utf8");
+  return true;
+};
+var demoOwnership = {
+  example: {
+    path: "src",
+    purpose: "Starter ownership target \u2014 replace with your real modules",
+    checks: ["npm test"],
+    agentDoc: "docs/for-agents/packages/example.md"
+  }
+};
+var initConfigObject = (withDemo) => ({
+  schemaVersion: 1,
+  corpus: { agent: { root: "docs/for-agents" } },
+  ...withDemo ? {
+    routing: {
+      options: {
+        ownership: demoOwnership
+      }
+    }
+  } : {},
+  gates: { preset: "minimal" }
+});
+var initConfigContents = (path, withDemo) => {
+  if (path.endsWith(".ts") || path.endsWith(".mts")) {
+    return [
+      "import { defineConfig } from '@agentskit/doc-bridge/config'",
+      "",
+      "export default defineConfig({",
+      "  schemaVersion: 1,",
+      "  corpus: { agent: { root: 'docs/for-agents' } },",
+      ...withDemo ? [
+        "  routing: {",
+        "    options: {",
+        "      ownership: {",
+        "        example: { path: 'src', purpose: 'Starter ownership target', checks: ['npm test'], agentDoc: 'docs/for-agents/packages/example.md' },",
+        "      },",
+        "    },",
+        "  },"
+      ] : [],
+      "  gates: { preset: 'minimal' },",
+      "})",
+      ""
+    ].join("\n");
+  }
+  return `${JSON.stringify(initConfigObject(withDemo), null, 2)}
+`;
+};
+var exampleAgentDoc = `---
+type: package
+package: example
+editRoot: src
+checks: [npm test]
+---
+
+# example
+
+Starter agent doc generated by \`ak-docs init --demo\`.
+
+Describe ownership, boundaries, and how agents should change this module.
+
+## Checks
+
+- \`npm test\`
+`;
+var agentsMdSnippet = `# AGENTS.md
+
+## Documentation routing (doc-bridge)
+
+Before editing a package or module:
+
+1. Run \`ak-docs query ownership <id> --agent\` (or MCP tool \`handoff.resolve\`)
+2. Read \`startHere\` and respect \`editRoots\` + \`checks\`
+3. Prefer agent docs under \`docs/for-agents/\`; human site links appear as \`humanDoc\`
+
+Local consult without LLM: \`ak-docs ask "<question>"\`
+Optional grounded chat (AgentsKit peers): \`ak-docs chat\`
+`;
+var workspaceDocDraft = (id, path) => [
+  "---",
+  "type: package",
+  "draft: true",
+  `package: ${id}`,
+  `editRoot: ${path}`,
+  "---",
+  "",
+  `# ${id}`,
+  "",
+  "Draft generated by `ak-docs init --scaffold-workspaces`.",
+  "",
+  "## Ownership",
+  "",
+  `- Package: \`${path}\``,
+  "",
+  "## Notes",
+  "",
+  "- TODO: describe responsibility, boundaries, and checks.",
+  ""
+].join("\n");
+var scaffoldWorkspaceDocs = (root, config) => {
+  const created = [];
+  const skipped = [];
+  for (const pkg of discoverPnpmPackages(root, config)) {
+    const path = resolve6(root, config.corpus.agent.root, "packages", `${pkg.id}.md`);
+    if (writeIfMissing(path, workspaceDocDraft(pkg.id, pkg.path))) created.push(path);
+    else skipped.push(path);
+  }
+  return { created, skipped };
+};
+var bootstrapAgentDocs = (root, config) => {
+  const created = [];
+  const skipped = [];
+  for (const doc of scanHumanDocRecords(root, config)) {
+    const raw = readFileSync14(doc.path, "utf8");
+    const body = raw.replace(/^---\n[\s\S]*?\n---\n?/, "");
+    const title = firstHeading(body) ?? doc.id;
+    const description = firstParagraph(body);
+    const draftPath = resolve6(root, config.corpus.agent.root, "human", `${doc.id}.md`);
+    const draft = [
+      "---",
+      "type: knowledge",
+      "draft: true",
+      `id: ${doc.id}`,
+      `humanDoc: ${doc.url}`,
+      "---",
+      "",
+      `# ${title}`,
+      "",
+      "Draft generated by `ak-docs bootstrap agent-docs` from existing human docs.",
+      "",
+      ...description ? ["## Source summary", "", description, ""] : [],
+      "## Review checklist",
+      "",
+      "- TODO: confirm ownership, edit roots, and checks.",
+      "- TODO: move this draft to the right agent-doc location if needed.",
+      ""
+    ].join("\n");
+    if (writeIfMissing(draftPath, draft)) created.push(draftPath);
+    else skipped.push(draftPath);
+  }
+  return { created, skipped };
+};
+var registryTopology = () => ({
+  id: "doc-curator",
+  delegates: ["docs-chat", "knowledge-promoter", "code-review"],
+  tools: ["handoff.resolve", "doc.search", "doc.get", "gate.status", "retriever.query"],
+  steps: ["classify", "draft", "verify", "review"],
+  mergePolicy: { autoMerge: false, requiresHuman: true }
+});
+var runCli = (argv) => {
+  const { command, flags, configPath, positional } = parseArgs(argv);
+  if (command === "help") {
+    process.stdout.write(usage);
+    return 0;
+  }
+  if (command === "version") {
+    process.stdout.write(`ak-docs ${PACKAGE_VERSION} (@agentskit/doc-bridge)
+`);
+    return 0;
+  }
+  if (command === "validate-config") {
+    try {
+      const { config, path } = loadConfig(
+        configPath ? { explicitPath: configPath } : {}
+      );
+      parseDocBridgeConfig(config);
+      writeJson({ ok: true, path, schemaVersion: config.schemaVersion });
+      return 0;
+    } catch (error) {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+      return 1;
+    }
+  }
+  if (command === "validate-handoff") {
+    const file = positional[1];
+    if (!file) {
+      process.stderr.write("Missing handoff JSON file path.\n");
+      return 1;
+    }
+    try {
+      const abs = resolve6(file);
+      const raw = readFileSync14(abs, "utf8");
+      const handoff = parseAgentHandoff(JSON.parse(raw));
+      writeJson({ ok: true, handoff });
+      return 0;
+    } catch (error) {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+      return 1;
+    }
+  }
+  if (command === "init") {
+    const root = process.cwd();
+    const withDemo = flags.has("--demo") || !flags.has("--no-demo");
+    const configFile = resolve6(root, configPath ?? "doc-bridge.config.json");
+    const docsIndex = resolve6(root, "docs/for-agents/INDEX.md");
+    const exampleDoc = resolve6(root, "docs/for-agents/packages/example.md");
+    const agentsMd = resolve6(root, "AGENTS.md");
+    const configWritten = writeIfMissing(configFile, initConfigContents(configFile, withDemo));
+    const indexWritten = writeIfMissing(
+      docsIndex,
+      withDemo ? "# Agent docs index\n\n- [example](./packages/example.md) \u2014 starter ownership target\n" : "# Agent docs index\n\nStart here for ownership, architecture, and task handoffs.\n"
+    );
+    const exampleWritten = withDemo ? writeIfMissing(exampleDoc, exampleAgentDoc) : false;
+    const agentsWritten = writeIfMissing(agentsMd, agentsMdSnippet);
+    if (withDemo) writeIfMissing(resolve6(root, "src/.gitkeep"), "");
+    const scaffold = flags.has("--scaffold-workspaces") ? scaffoldWorkspaceDocs(root, loadProject(configFile).config) : void 0;
+    writeJson({
+      ok: true,
+      configPath: configFile,
+      demo: withDemo,
+      created: {
+        config: configWritten,
+        index: indexWritten,
+        ...withDemo ? { exampleDoc: exampleWritten, srcStub: true } : {},
+        agentsMd: agentsWritten,
+        ...scaffold ? { workspaceDocs: scaffold.created } : {}
+      },
+      ...scaffold ? { skipped: { workspaceDocs: scaffold.skipped } } : {},
+      nextCommands: withDemo ? ["ak-docs index", "ak-docs query package example --agent", "ak-docs list packages --text"] : ["ak-docs index", "ak-docs list knowledge --text"]
+    });
+    return 0;
+  }
+  if (command === "bootstrap") {
+    if (positional[1] !== "agent-docs") {
+      process.stderr.write("Usage: ak-docs bootstrap agent-docs [--config <path>]\n");
+      return 1;
+    }
+    try {
+      const { config, root } = loadProject(configPath);
+      const result = bootstrapAgentDocs(root, config);
+      writeJson({ ok: true, ...result });
+      return 0;
+    } catch (error) {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+      return 1;
+    }
+  }
+  if (command === "memory") {
+    if (!["ingest", "classify", "promote"].includes(positional[1] ?? "")) {
+      process.stderr.write("Usage: ak-docs memory <ingest|classify|promote> [--config <path>]\n");
+      return 1;
+    }
+    try {
+      const { config, root } = loadProject(configPath);
+      const candidates = ingestMemoryCandidates(root);
+      if (positional[1] === "ingest") {
+        writeJson({ ok: true, count: candidates.length, candidates });
+        return 0;
+      }
+      const index = loadDocBridgeIndex(root, config);
+      const classifications = classifyMemoryCandidates(candidates, index);
+      if (positional[1] === "classify") {
+        writeJson({ ok: true, count: classifications.length, classifications });
+        return 0;
+      }
+      const draft = draftMemoryPromotion(classifications);
+      writeJson(draft);
+      return draft.ok ? 0 : 1;
+    } catch (error) {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+      return 1;
+    }
+  }
+  if (command === "registry") {
+    if (positional[1] !== "topology") {
+      process.stderr.write("Usage: ak-docs registry topology\n");
+      return 1;
+    }
+    writeJson(registryTopology());
+    return 0;
+  }
+  if (command === "playbook") {
+    if (positional[1] !== "draft") {
+      process.stderr.write("Usage: ak-docs playbook draft [--config <path>]\n");
+      return 1;
+    }
+    try {
+      const { config, root } = loadProject(configPath);
+      const index = loadDocBridgeIndex(root, config);
+      const draft = draftMemoryPromotion(classifyMemoryCandidates(ingestMemoryCandidates(root), index));
+      writeJson({
+        ...draft,
+        title: "Draft Playbook feedback promotion",
+        pattern: "Doc Bridge Pattern"
+      });
+      return 0;
+    } catch (error) {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+      return 1;
+    }
+  }
+  if (command === "index") {
+    try {
+      const { config, root } = loadProject(configPath);
+      const result = buildDocBridgeIndex({ root, config });
+      const diagnostics = indexDiagnostics(config, result);
+      const handoffCount = Object.keys(result.index.handoffs ?? {}).length;
+      writeJson({
+        ok: true,
+        indexPath: result.indexPath,
+        ...result.llmsTxtPath ? { llmsTxtPath: result.llmsTxtPath } : {},
+        ...result.capabilitiesPath ? { capabilitiesPath: result.capabilitiesPath } : {},
+        contentHash: result.index.contentHash,
+        knowledgeCount: result.index.knowledge.length,
+        packageCount: result.index.lookup?.packages.length ?? 0,
+        handoffCount,
+        ...diagnostics.length ? { diagnostics } : {},
+        nextCommands: diagnosticNextCommands(config, result)
+      });
+      return 0;
+    } catch (error) {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+      return 1;
+    }
+  }
+  if (command === "gate") {
+    const action = positional[1];
+    const gateId = positional[2];
+    if (action !== "run") {
+      process.stderr.write("Usage: ak-docs gate run [index-freshness]\n");
+      return 1;
+    }
+    if (gateId && !GATE_IDS.has(gateId)) {
+      process.stderr.write(
+        `Unsupported gate "${gateId}". Supported gates: index-freshness, human-guide-links, okf-type, docs-style
+`
+      );
+      return 1;
+    }
+    try {
+      const { config, root } = loadProject(configPath);
+      const result = runGates(root, config, gateId ? [gateId] : void 0);
+      writeJson(result);
+      return result.ok ? 0 : 1;
+    } catch (error) {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+      return 1;
+    }
+  }
+  if (command === "mcp") {
+    try {
+      const { config, root } = loadProject(configPath);
+      startMcpStdioServer({ root, config });
+      return void 0;
+    } catch (error) {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+      return 1;
+    }
+  }
+  if (command === "query") {
+    const kind = positional[1];
+    const id = positional[2];
+    if (!kind || !QUERY_KINDS.has(kind) || kind === "search") {
+      process.stderr.write("Usage: ak-docs query <package|ownership|intent|change> <id> [--agent]\n");
+      return 1;
+    }
+    if (!id) {
+      process.stderr.write(`Missing id for query kind "${kind}".
+`);
+      return 1;
+    }
+    try {
+      const { config, root } = loadProject(configPath);
+      const index = loadDocBridgeIndex(root, config);
+      const result = runQuery(index, config, { kind, id, agent: flags.has("--agent") });
+      if (wantsTextOutput(flags, config)) writeTextQuery(result);
+      else writeJson(result);
+      return 0;
+    } catch (error) {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+      return 1;
+    }
+  }
+  if (command === "search") {
+    const term = positional.slice(1).join(" ").trim();
+    if (!term) {
+      process.stderr.write("Usage: ak-docs search <term> [--agent]\n");
+      return 1;
+    }
+    try {
+      const { config, root } = loadProject(configPath);
+      const index = loadDocBridgeIndex(root, config);
+      if (flags.has("--agent")) {
+        const result = runQuery(index, config, { kind: "search", term, agent: true });
+        writeJson(result);
+      } else {
+        const matches = searchIndex(index, term);
+        if (wantsTextOutput(flags, config)) writeTextSearch(term, matches);
+        else writeJson({ term, count: matches.length, matches });
+      }
+      return 0;
+    } catch (error) {
+      if (error instanceof IndexNotFoundError) {
+        process.stderr.write(`${error.message}
+`);
+        return 1;
+      }
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+      return 1;
+    }
+  }
+  if (command === "retrieve") {
+    const query = positional.slice(1).join(" ").trim();
+    if (!query) {
+      process.stderr.write("Usage: ak-docs retrieve <query> [--config <path>]\n");
+      return 1;
+    }
+    return (async () => {
+      try {
+        const { config, root } = loadProject(configPath);
+        const index = loadDocBridgeIndex(root, config);
+        writeJson({ query, chunks: await retrieveHybridChunks(root, config, index, query) });
+        return 0;
+      } catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+        return 1;
+      }
+    })();
+  }
+  if (command === "rag") {
+    const action = positional[1];
+    if (action !== "ingest" && action !== "search") {
+      process.stderr.write("Usage: ak-docs rag ingest | ak-docs rag search <query>\n");
+      return 1;
+    }
+    return (async () => {
+      try {
+        const { config, root } = loadProject(configPath);
+        const index = loadDocBridgeIndex(root, config);
+        const rag = await createDocBridgeRag(root, config, index);
+        if (action === "ingest") {
+          const result = await rag.ingest();
+          writeJson({ ok: true, ...result });
+          return 0;
+        }
+        const query = positional.slice(2).join(" ").trim();
+        if (!query) {
+          process.stderr.write("Usage: ak-docs rag search <query>\n");
+          return 1;
+        }
+        const hits = await rag.search(query);
+        writeJson({ query, count: hits.length, hits });
+        return 0;
+      } catch (error) {
+        if (error instanceof PeerMissingError) {
+          process.stderr.write(`${error.message}
+`);
+          return 1;
+        }
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+        return 1;
+      }
+    })();
+  }
+  if (command === "chat") {
+    return (async () => {
+      try {
+        const { config, root } = loadProject(configPath);
+        if (!config.intelligence?.enabled || !config.intelligence.adapter) {
+          process.stderr.write(
+            `Chat requires intelligence.enabled and intelligence.adapter in doc-bridge config.
+Layer 1 peers: ${layer1InstallHint()}
+`
+          );
+          return 1;
+        }
+        const index = loadDocBridgeIndex(root, config);
+        await startInkChat(root, config, index);
+        return 0;
+      } catch (error) {
+        if (error instanceof PeerMissingError) {
+          process.stderr.write(`${error.message}
+`);
+          return 1;
+        }
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+        return 1;
+      }
+    })();
+  }
+  if (command === "ask") {
+    const question = positional.slice(1).join(" ").trim();
+    try {
+      const { config, root } = loadProject(configPath);
+      if (flags.has("--chat")) {
+        if (!config.intelligence?.enabled || !config.intelligence.adapter) {
+          process.stderr.write(
+            `Chat mode requires intelligence.enabled and intelligence.adapter in doc-bridge config.
+Install peers: ${layer1InstallHint()}
+`
+          );
+          return 1;
+        }
+        if (!question) {
+          process.stderr.write("Usage: ak-docs ask <question> --chat\n");
+          return 1;
+        }
+        return (async () => {
+          try {
+            const index2 = loadDocBridgeIndex(root, config);
+            const result = await runChatOnce(root, config, index2, question);
+            writeLines([result.content]);
+            return 0;
+          } catch (error) {
+            if (error instanceof PeerMissingError) {
+              process.stderr.write(`${error.message}
+`);
+              return 1;
+            }
+            process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+            return 1;
+          }
+        })();
+      }
+      if (!question) {
+        if (process.stdin.isTTY) return runAskRepl(root, config);
+        process.stderr.write("Usage: ak-docs ask <question>, or run ak-docs ask in an interactive terminal.\n");
+        return 1;
+      }
+      const index = loadDocBridgeIndex(root, config);
+      writeAsk(question, searchIndex(index, question, 8), index);
+      return 0;
+    } catch (error) {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+      return 1;
+    }
+  }
+  if (command === "list") {
+    const kind = positional[1];
+    if (!kind || !LIST_KINDS.has(kind)) {
+      process.stderr.write("Usage: ak-docs list <packages|intents|changes|knowledge>\n");
+      return 1;
+    }
+    try {
+      const { config, root } = loadProject(configPath);
+      const index = loadDocBridgeIndex(root, config);
+      if (kind === "packages") {
+        const items2 = index.lookup?.packages ?? [];
+        if (wantsTextOutput(flags, config)) writeLines(items2);
+        else writeJson({ kind, items: items2 });
+        return 0;
+      }
+      if (kind === "intents") {
+        const items2 = Object.keys(index.lookup?.intents ?? {});
+        if (wantsTextOutput(flags, config)) writeLines(items2);
+        else writeJson({ kind, items: items2 });
+        return 0;
+      }
+      if (kind === "changes") {
+        const items2 = Object.keys(index.lookup?.changes ?? {});
+        if (wantsTextOutput(flags, config)) writeLines(items2);
+        else writeJson({ kind, items: items2 });
+        return 0;
+      }
+      const items = index.knowledge.map((entry) => ({
+        id: entry.id,
+        title: entry.title,
+        path: entry.path
+      }));
+      if (wantsTextOutput(flags, config)) {
+        writeLines(items.map((item) => [item.id, item.path, item.title].join("	")));
+      } else {
+        writeJson({ kind, items });
+      }
+      return 0;
+    } catch (error) {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+      return 1;
+    }
+  }
+  process.stdout.write(usage);
+  return 1;
+};
+export {
+  runCli
+};
+//# sourceMappingURL=program.js.map