docbridge 0.4.0 → 0.5.0

package/dist/index.js

@@ -168755,12 +168755,12 @@ Additional information: BADCLIENT: Bad error code, ${badCode} not found in range
 });
 
 // src/cli/index.ts
-import { readFileSync as readFileSync3, statSync } from "fs";
-import { resolve as resolve3 } from "path";
+import { readFileSync as readFileSync5, statSync as statSync4 } from "fs";
+import { resolve as resolve4 } from "path";
 // package.json
 var package_default = {
   name: "docbridge",
-  version: "0.4.0",
+  version: "0.5.0",
   description: "A Bun CLI that links Markdown specifications and code declarations.",
   license: "MIT",
   type: "module",
@@ -171886,6 +171886,861 @@ function fullChangeText(changes) {
   return typeof last.text === "string" ? last.text : undefined;
 }
 
+// src/cli/init.ts
+import {
+  cpSync,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync4,
+  statSync as statSync3,
+  writeFileSync
+} from "fs";
+import { join as join7, resolve as resolve3 } from "path";
+
+// src/core/init-discovery.ts
+import { existsSync as existsSync2, readdirSync as readdirSync2, statSync } from "fs";
+import { basename, dirname as dirname2, join as join5 } from "path";
+var HIGH_CONFIDENCE_DIR_NAMES = new Set([
+  "docs/specs",
+  "specs",
+  "spec",
+  "requirements",
+  "design",
+  "architecture",
+  "adr",
+  "decisions"
+]);
+var MEDIUM_CONFIDENCE_DIR_NAMES = new Set(["docs", "documentation", "doc"]);
+var EXCLUDED_PROSE_BASENAMES = new Set([
+  "readme.md",
+  "changelog.md",
+  "contributing.md",
+  "license.md",
+  "code_of_conduct.md",
+  "security.md"
+]);
+var EXCLUDED_DIR_SEGMENTS = new Set([
+  "runbook",
+  "runbooks",
+  "release",
+  "releases",
+  "changelog",
+  "changelogs",
+  "contributing"
+]);
+var IGNORED_WALK_SEGMENTS = new Set(["node_modules", ".git", "dist", "build"]);
+var TYPESCRIPT_PATTERNS = [
+  "src/**/*.ts",
+  "lib/**/*.ts",
+  "packages/*/src/**/*.ts",
+  "apps/*/src/**/*.ts"
+];
+var SWIFT_PATTERNS = ["Sources/**/*.swift", "*/Sources/**/*.swift"];
+var DART_PATTERNS = ["lib/**/*.dart"];
+var LANGUAGE_PATTERNS = {
+  typescript: TYPESCRIPT_PATTERNS,
+  swift: SWIFT_PATTERNS,
+  dart: DART_PATTERNS
+};
+function discoverRepository(projectRoot) {
+  return {
+    docs: discoverDocsScope(projectRoot),
+    code: discoverCodeScope(projectRoot),
+    agent: discoverAgentTarget(projectRoot)
+  };
+}
+function discoverDocsScope(projectRoot) {
+  const markdownFiles = collectMarkdownFiles(projectRoot);
+  const eligible = markdownFiles.filter((filePath) => isEligibleDocsFile(filePath));
+  if (eligible.length === 0) {
+    return {
+      candidates: [],
+      recommended: undefined,
+      ambiguous: true,
+      message: "No specification-like Markdown files were found. Confirm docs scope before creating docbridge.config.json."
+    };
+  }
+  const grouped = new Map;
+  for (const filePath of eligible) {
+    const directory = dirname2(filePath);
+    const existing = grouped.get(directory) ?? [];
+    existing.push(filePath);
+    grouped.set(directory, existing);
+  }
+  const candidates = [...grouped.entries()].map(([directory, files]) => ({
+    directory,
+    pattern: `${directory}/**/*.md`,
+    score: scoreDocsDirectory(directory),
+    fileCount: files.length
+  })).sort((left, right) => right.score !== left.score ? right.score - left.score : left.directory.localeCompare(right.directory));
+  const topScore = candidates[0]?.score ?? 0;
+  if (topScore === 0) {
+    return {
+      candidates,
+      recommended: undefined,
+      ambiguous: true,
+      message: "Markdown files were found, but no likely specification directory was detected. Confirm docs scope before creating docbridge.config.json."
+    };
+  }
+  const topCandidates = candidates.filter((candidate) => candidate.score === topScore);
+  if (topCandidates.length !== 1) {
+    return {
+      candidates,
+      recommended: undefined,
+      ambiguous: true,
+      message: "Multiple likely docs directories were detected. Confirm docs scope before creating docbridge.config.json."
+    };
+  }
+  return {
+    candidates,
+    recommended: topCandidates[0],
+    ambiguous: false,
+    message: undefined
+  };
+}
+function discoverCodeScope(projectRoot) {
+  const languages = [];
+  for (const language of ["typescript", "swift", "dart"]) {
+    const patterns = activeCodePatterns(projectRoot, language);
+    if (patterns.length > 0) {
+      languages.push({
+        language,
+        patterns,
+        fileCount: countCodeFiles(projectRoot, patterns, language)
+      });
+    }
+  }
+  if (languages.length === 0) {
+    return {
+      languages: [],
+      ambiguous: true,
+      message: "No supported code files were detected. Confirm code scope before creating docbridge.config.json."
+    };
+  }
+  return {
+    languages,
+    ambiguous: false,
+    message: undefined
+  };
+}
+function discoverAgentTarget(projectRoot) {
+  const hasAgentsDir = existsSync2(join5(projectRoot, ".agents"));
+  const hasClaudeDir = existsSync2(join5(projectRoot, ".claude"));
+  let defaultTarget = "none";
+  let recommendedTarget = "none";
+  let message;
+  if (hasAgentsDir && hasClaudeDir) {
+    defaultTarget = "both";
+    recommendedTarget = "both";
+  } else if (hasAgentsDir) {
+    defaultTarget = "codex";
+    recommendedTarget = "codex";
+  } else if (hasClaudeDir) {
+    defaultTarget = "claude";
+    recommendedTarget = "claude";
+  } else {
+    defaultTarget = "none";
+    recommendedTarget = "codex";
+    message = "No agent directory was detected. Interactive setup recommends Codex (.agents/skills/) after confirmation.";
+  }
+  return {
+    hasAgentsDir,
+    hasClaudeDir,
+    defaultTarget,
+    recommendedTarget,
+    message
+  };
+}
+function collectMarkdownFiles(projectRoot, currentDir = ".") {
+  const absoluteDir = join5(projectRoot, currentDir);
+  let entries;
+  try {
+    entries = readdirSync2(absoluteDir);
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const entry of entries) {
+    const relPath = currentDir === "." ? entry : `${currentDir}/${entry}`;
+    const segments = relPath.split("/");
+    if (segments.some((segment) => IGNORED_WALK_SEGMENTS.has(segment) || segment.startsWith("."))) {
+      continue;
+    }
+    const absolutePath = join5(projectRoot, relPath);
+    let stats;
+    try {
+      stats = statSync(absolutePath);
+    } catch {
+      continue;
+    }
+    if (stats.isDirectory()) {
+      files.push(...collectMarkdownFiles(projectRoot, relPath));
+      continue;
+    }
+    if (stats.isFile() && relPath.endsWith(".md")) {
+      files.push(relPath);
+    }
+  }
+  return files.sort();
+}
+function isEligibleDocsFile(filePath) {
+  if (EXCLUDED_PROSE_BASENAMES.has(basename(filePath).toLowerCase())) {
+    return false;
+  }
+  const segments = filePath.split("/").map((segment) => segment.toLowerCase());
+  return !segments.some((segment) => EXCLUDED_DIR_SEGMENTS.has(segment));
+}
+function scoreDocsDirectory(directory) {
+  const normalized = directory.replace(/^\.\/?/, "");
+  if (normalized === ".") {
+    return 0;
+  }
+  const segments = normalized.split("/");
+  let score = 0;
+  for (let index = 0;index < segments.length; index += 1) {
+    const tail = segments.slice(index).join("/");
+    if (HIGH_CONFIDENCE_DIR_NAMES.has(tail) || HIGH_CONFIDENCE_DIR_NAMES.has(segments[index] ?? "")) {
+      score = Math.max(score, 2);
+    } else if (MEDIUM_CONFIDENCE_DIR_NAMES.has(tail) || MEDIUM_CONFIDENCE_DIR_NAMES.has(segments[index] ?? "")) {
+      score = Math.max(score, 1);
+    }
+  }
+  return score;
+}
+function activeCodePatterns(projectRoot, language) {
+  return LANGUAGE_PATTERNS[language].filter((pattern) => countCodeFiles(projectRoot, [pattern], language) > 0);
+}
+function countCodeFiles(projectRoot, patterns, language) {
+  const seen = new Set;
+  for (const pattern of patterns) {
+    for (const filePath of collectFiles(projectRoot, [pattern])) {
+      if (!isExcludedCodeFile(filePath, language)) {
+        seen.add(filePath);
+      }
+    }
+  }
+  return seen.size;
+}
+function isExcludedCodeFile(filePath, language) {
+  const lower = filePath.toLowerCase();
+  const segments = filePath.split("/");
+  if (language === "typescript") {
+    if (lower.endsWith(".d.ts")) {
+      return true;
+    }
+    if (lower.endsWith(".test.ts") || lower.endsWith(".spec.ts") || segments.includes("__tests__") || segments.includes("tests") || segments.includes("test")) {
+      return true;
+    }
+  }
+  if (language === "swift") {
+    if (lower.endsWith("tests.swift") || segments.includes("Tests") || segments.includes("tests")) {
+      return true;
+    }
+  }
+  if (language === "dart") {
+    if (lower.endsWith("_test.dart") || segments.includes("test")) {
+      return true;
+    }
+  }
+  if (segments.some((segment) => ["generated", "gen", ".dart_tool", "build"].includes(segment.toLowerCase()))) {
+    return true;
+  }
+  return lower.includes(".generated.");
+}
+
+// src/core/init-plan.ts
+import {
+  existsSync as existsSync3,
+  readdirSync as readdirSync3,
+  readFileSync as readFileSync3,
+  realpathSync as realpathSync2,
+  statSync as statSync2
+} from "fs";
+import { dirname as dirname3, join as join6, relative as relative4 } from "path";
+import { fileURLToPath as fileURLToPath4 } from "url";
+var CONFIG_FILE_NAME2 = "docbridge.config.json";
+var INIT_SKILL_NAMES = [
+  "docbridge-adopt",
+  "docbridge-annotate",
+  "docbridge-link",
+  "docbridge-review",
+  "docbridge-sync"
+];
+var INIT_WITH_AGENT_SKILL_NAMES = ["docbridge-adopt"];
+function planInitCommand(input) {
+  const packageRoot = input.packageRoot ?? resolvePackageRoot();
+  const existingConfig = readExistingConfig(input.projectRoot);
+  const messages = [];
+  const nextSteps = [];
+  let exitCode = 0;
+  const agentResolution = input.command === "init" ? resolveInitAgentTarget(input.discovery, input.options) : resolveInitWithAgentTarget(input.discovery, input.options);
+  if (agentResolution.error !== undefined) {
+    return {
+      command: input.command,
+      configOps: [],
+      skillOps: [],
+      messages: [agentResolution.error],
+      nextSteps: [],
+      agentGuidance: [],
+      exitCode: 1
+    };
+  }
+  const agentTarget = agentResolution.target ?? "none";
+  const configOps = input.command === "init" ? planConfigOperations({
+    projectRoot: input.projectRoot,
+    options: input.options,
+    discovery: input.discovery,
+    confirmedScope: input.confirmedScope,
+    existingConfig,
+    messages
+  }) : [];
+  if (configOps.some((operation) => operation.action === "create" || operation.action === "would-create")) {
+    nextSteps.push("Review docbridge.config.json and adjust include.docs or include.code if needed.");
+    nextSteps.push("Add @doc and @code annotations to link code and documentation.");
+    nextSteps.push("Run docbridge check when links exist.");
+  } else if (existingConfig.ok) {
+    messages.push("Existing docbridge.config.json was left unchanged.");
+    summarizeExistingConfig(existingConfig.config, messages);
+  } else if (existingConfig.rawText !== undefined) {
+    messages.push("Existing docbridge.config.json is invalid and was not modified.");
+    for (const diagnostic of existingConfig.diagnostics) {
+      messages.push(diagnostic.message);
+    }
+    messages.push("Repair the config manually or delete it before re-running init.");
+    exitCode = 1;
+  }
+  const skillOps = planSkillOperations({
+    command: input.command,
+    projectRoot: input.projectRoot,
+    packageRoot,
+    agentTarget,
+    options: input.options
+  });
+  const agentGuidance = input.command === "init-with-agent" && agentTarget !== "none" ? buildAgentGuidance(input.projectRoot, agentTarget) : [];
+  if (input.command === "init-with-agent") {
+    nextSteps.push("Run the printed one-shot command or fallback prompt in your agent.");
+    nextSteps.push("Let docbridge-adopt confirm scope and create or improve docbridge.config.json.");
+  }
+  if (input.options.yes && input.command === "init" && configOps.length === 0 && existingConfig.rawText === undefined && (input.discovery.docs.ambiguous || input.discovery.code.ambiguous)) {
+    exitCode = 1;
+  }
+  return {
+    command: input.command,
+    configOps,
+    skillOps,
+    messages,
+    nextSteps,
+    agentGuidance,
+    exitCode
+  };
+}
+function buildConfigFromScope(scope) {
+  const code = {};
+  for (const language of scope.languages) {
+    code[language.language] = { patterns: [...language.patterns] };
+  }
+  return {
+    include: {
+      code,
+      docs: [scope.docsPattern]
+    }
+  };
+}
+function resolvePackageRoot(moduleUrl = import.meta.url) {
+  const modulePath = fileURLToPath4(moduleUrl);
+  let resolved;
+  try {
+    resolved = realpathSync2(modulePath);
+  } catch {
+    resolved = modulePath;
+  }
+  let dir = dirname3(resolved);
+  for (;; ) {
+    if (existsSync3(join6(dir, "templates", "skills"))) {
+      return dir;
+    }
+    const parent = dirname3(dir);
+    if (parent === dir) {
+      return dir;
+    }
+    dir = parent;
+  }
+}
+function listDistributableSkills(packageRoot) {
+  const skillsRoot = join6(packageRoot, "templates", "skills");
+  let entries;
+  try {
+    entries = readdirSync3(skillsRoot);
+  } catch {
+    return [];
+  }
+  return entries.filter((entry) => entry.startsWith("docbridge-")).filter((entry) => existsSync3(join6(skillsRoot, entry, "SKILL.md"))).sort();
+}
+function formatInitPlan(plan) {
+  const lines = [];
+  for (const message of plan.messages) {
+    lines.push(message);
+  }
+  if (plan.configOps.length > 0) {
+    lines.push("");
+    lines.push("Config:");
+    for (const operation of plan.configOps) {
+      lines.push(formatFileOp(operation));
+      if (operation.content !== undefined) {
+        lines.push(operation.content);
+      }
+    }
+  }
+  if (plan.skillOps.length > 0) {
+    lines.push("");
+    lines.push("Skills:");
+    for (const operation of plan.skillOps) {
+      lines.push(formatFileOp(operation));
+    }
+  }
+  if (plan.agentGuidance.length > 0) {
+    lines.push("");
+    lines.push("Agent setup:");
+    for (const guidance of plan.agentGuidance) {
+      lines.push("");
+      lines.push(`${capitalize(guidance.agent)} destination: ${guidance.destination}`);
+      lines.push(`One-shot command: ${guidance.oneShotCommand}`);
+      lines.push("Fallback prompt:");
+      lines.push(guidance.fallbackPrompt);
+    }
+  }
+  if (plan.nextSteps.length > 0) {
+    lines.push("");
+    lines.push("Next steps:");
+    for (const step of plan.nextSteps) {
+      lines.push(`- ${step}`);
+    }
+  }
+  return `${lines.join(`
+`)}
+`;
+}
+function planConfigOperations(input) {
+  if (input.existingConfig.rawText !== undefined) {
+    return [];
+  }
+  const scope = input.confirmedScope ?? inferConfirmedScope(input.discovery, input.options);
+  if (scope === undefined) {
+    if (input.discovery.docs.message !== undefined) {
+      input.messages.push(input.discovery.docs.message);
+    }
+    if (input.discovery.code.message !== undefined) {
+      input.messages.push(input.discovery.code.message);
+    }
+    if (input.options.yes) {
+      input.messages.push("Automatic setup stopped because docs or code scope is ambiguous. Re-run interactively or confirm scope explicitly.");
+    }
+    return [];
+  }
+  const config = buildConfigFromScope(scope);
+  const content = `${JSON.stringify({ $schema: "./schemas/docbridge.schema.json", ...config }, null, 2)}
+`;
+  const action = input.options.dryRun ? "would-create" : "create";
+  input.messages.push(`Docs scope: ${scope.docsPattern}`);
+  input.messages.push(`Code scope: ${scope.languages.map((language) => `${language.language} (${language.patterns.join(", ")})`).join("; ")}`);
+  return [
+    {
+      action,
+      path: CONFIG_FILE_NAME2,
+      content,
+      reason: "Create docbridge.config.json from discovered scope."
+    }
+  ];
+}
+function inferConfirmedScope(discovery, options) {
+  if (discovery.docs.ambiguous || discovery.code.ambiguous) {
+    return;
+  }
+  if (discovery.docs.recommended === undefined || discovery.code.languages.length === 0) {
+    return;
+  }
+  if (!options.yes) {
+    return;
+  }
+  return {
+    docsPattern: discovery.docs.recommended.pattern,
+    languages: discovery.code.languages
+  };
+}
+function planSkillOperations(input) {
+  if (input.agentTarget === "none") {
+    return [];
+  }
+  const skillNames = input.command === "init" ? [...INIT_SKILL_NAMES] : [...INIT_WITH_AGENT_SKILL_NAMES];
+  const destinations = agentDestinations(input.agentTarget);
+  const availableSkills = new Set(listDistributableSkills(input.packageRoot));
+  const operations = [];
+  for (const destination of destinations) {
+    for (const skillName of skillNames) {
+      if (!availableSkills.has(skillName)) {
+        continue;
+      }
+      const destinationDir = join6(input.projectRoot, destination, skillName);
+      const exists = existsSync3(destinationDir);
+      let action;
+      let reason;
+      if (exists && input.options.force) {
+        action = input.options.dryRun ? "would-overwrite" : "overwrite";
+        reason = "Overwrite existing skill directory.";
+      } else if (exists) {
+        action = "skip";
+        reason = "Skill directory already exists.";
+      } else {
+        action = input.options.dryRun ? "would-create" : "create";
+        reason = "Install distributable skill template.";
+      }
+      operations.push({
+        action,
+        path: relative4(input.projectRoot, destinationDir),
+        reason
+      });
+    }
+  }
+  return operations;
+}
+function buildAgentGuidance(projectRoot, agentTarget) {
+  const guidance = [];
+  if (agentTarget === "codex" || agentTarget === "both") {
+    guidance.push({
+      agent: "codex",
+      destination: ".agents/skills/docbridge-adopt/",
+      oneShotCommand: `cd ${projectRoot} && $docbridge_adopt_prompt`,
+      fallbackPrompt: buildFallbackPrompt(projectRoot, "codex")
+    });
+  }
+  if (agentTarget === "claude" || agentTarget === "both") {
+    guidance.push({
+      agent: "claude",
+      destination: ".claude/skills/docbridge-adopt/",
+      oneShotCommand: `cd ${projectRoot} && /docbridge-adopt`,
+      fallbackPrompt: buildFallbackPrompt(projectRoot, "claude")
+    });
+  }
+  for (const entry of guidance) {
+    entry.oneShotCommand = entry.oneShotCommand.replace("$docbridge_adopt_prompt", 'codex --prompt "Use the docbridge-adopt skill to adopt DocBridge in this repository."');
+  }
+  return guidance;
+}
+function buildFallbackPrompt(projectRoot, agent) {
+  const invocation = agent === "claude" ? "Use the docbridge-adopt skill" : "Use the docbridge-adopt skill from .agents/skills/docbridge-adopt";
+  return `${invocation} to adopt DocBridge in ${projectRoot}. Confirm docs and code scope, create or improve docbridge.config.json, install the companion DocBridge skills, and suggest the next linking steps.`;
+}
+function resolveInitAgentTarget(discovery, options) {
+  if (options.agentTarget !== undefined) {
+    return { target: options.agentTarget, error: undefined };
+  }
+  if (options.yes) {
+    return { target: discovery.agent.defaultTarget, error: undefined };
+  }
+  return { target: discovery.agent.recommendedTarget, error: undefined };
+}
+function resolveInitWithAgentTarget(discovery, options) {
+  if (options.agentTarget !== undefined) {
+    if (options.agentTarget === "none") {
+      return {
+        target: undefined,
+        error: "init-with-agent requires an agent target other than none."
+      };
+    }
+    return { target: options.agentTarget, error: undefined };
+  }
+  if (discovery.agent.defaultTarget === "none") {
+    if (options.yes) {
+      return {
+        target: undefined,
+        error: "init-with-agent --yes requires an explicit agent target when no .agents/ or .claude/ directory exists. Pass --agent-target codex, claude, or both."
+      };
+    }
+    return { target: discovery.agent.recommendedTarget, error: undefined };
+  }
+  return { target: discovery.agent.defaultTarget, error: undefined };
+}
+function readExistingConfig(projectRoot) {
+  const configPath = join6(projectRoot, CONFIG_FILE_NAME2);
+  let rawText;
+  try {
+    rawText = readFileSync3(configPath, "utf8");
+  } catch {
+    rawText = undefined;
+  }
+  const resolved = resolveConfig(rawText);
+  return {
+    rawText,
+    ok: resolved.ok,
+    config: resolved.config,
+    diagnostics: resolved.diagnostics
+  };
+}
+function summarizeExistingConfig(config, messages) {
+  messages.push(`Docs scope: ${config.include.docs.join(", ")}`);
+  const codeSummary = Object.entries(config.include.code).map(([language, entry]) => `${language}: ${entry?.patterns.join(", ") ?? ""}`).join("; ");
+  messages.push(`Code scope: ${codeSummary}`);
+}
+function agentDestinations(agentTarget) {
+  switch (agentTarget) {
+    case "codex":
+      return [".agents/skills"];
+    case "claude":
+      return [".claude/skills"];
+    case "both":
+      return [".agents/skills", ".claude/skills"];
+    default:
+      return [];
+  }
+}
+function formatFileOp(operation) {
+  const label = operation.action === "would-create" ? "would create" : operation.action === "would-overwrite" ? "would overwrite" : operation.action;
+  const reason = operation.reason ? ` (${operation.reason})` : "";
+  return `- ${label} ${operation.path}${reason}`;
+}
+function capitalize(value) {
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}
+
+// src/cli/init.ts
+class InitCliError extends Error {
+}
+var AGENT_TARGETS = new Set(["codex", "claude", "both", "none"]);
+function parseInitOptions(args, command) {
+  const options = {
+    root: ".",
+    yes: false,
+    dryRun: false,
+    force: false,
+    agentTarget: undefined
+  };
+  for (let index = 0;index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === undefined) {
+      continue;
+    }
+    if (arg === "--yes") {
+      options.yes = true;
+      continue;
+    }
+    if (arg === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+    if (arg === "--force") {
+      options.force = true;
+      continue;
+    }
+    if (arg === "--root") {
+      const root = args[index + 1];
+      if (root === undefined) {
+        throw new InitCliError("--root requires a path.");
+      }
+      options.root = root;
+      index += 1;
+      continue;
+    }
+    if (arg === "--agent-target") {
+      const target = args[index + 1];
+      if (target === undefined) {
+        throw new InitCliError("--agent-target requires a value.");
+      }
+      if (!AGENT_TARGETS.has(target)) {
+        throw new InitCliError(`Unknown agent target: ${target}. Supported values: codex, claude, both${command === "init" ? ", none" : ""}.`);
+      }
+      if (command === "init-with-agent" && target === "none") {
+        throw new InitCliError("init-with-agent requires an agent target other than none.");
+      }
+      options.agentTarget = target;
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      throw new InitCliError(`Unknown option: ${arg}`);
+    }
+    throw new InitCliError(`Unexpected argument: ${arg}`);
+  }
+  return options;
+}
+function createDefaultPrompts(isInteractive = process.stdin.isTTY) {
+  return {
+    isInteractive,
+    confirm(message, defaultValue = true) {
+      if (!isInteractive) {
+        return defaultValue;
+      }
+      process.stdout.write(`${message} ${defaultValue ? "[Y/n]" : "[y/N]"} `);
+      const answer = readFileSync4(0, "utf8").trim().toLowerCase();
+      if (answer.length === 0) {
+        return defaultValue;
+      }
+      return answer === "y" || answer === "yes";
+    },
+    select(message, choices, defaultChoice) {
+      if (!isInteractive) {
+        return defaultChoice;
+      }
+      process.stdout.write(`${message}
+`);
+      for (const [index, choice] of choices.entries()) {
+        process.stdout.write(`  ${index + 1}. ${choice}
+`);
+      }
+      process.stdout.write(`Choice [${defaultChoice}]: `);
+      const answer = readFileSync4(0, "utf8").trim();
+      if (answer.length === 0) {
+        return defaultChoice;
+      }
+      const numeric = Number.parseInt(answer, 10);
+      if (!Number.isNaN(numeric) && numeric >= 1 && numeric <= choices.length) {
+        return choices[numeric - 1] ?? defaultChoice;
+      }
+      if (choices.includes(answer)) {
+        return answer;
+      }
+      return defaultChoice;
+    }
+  };
+}
+function runInit(options, io, runtime = { prompts: createDefaultPrompts(false) }) {
+  return runInitCommand("init", options, io, runtime);
+}
+function runInitWithAgent(options, io, runtime = { prompts: createDefaultPrompts(false) }) {
+  return runInitCommand("init-with-agent", options, io, runtime);
+}
+function runInitCommand(command, options, io, runtime) {
+  const projectRoot = resolveProjectRoot(options.root);
+  const discovery = discoverRepository(projectRoot);
+  const confirmedScope = command === "init" ? resolveConfirmedScope({
+    command,
+    discovery,
+    options,
+    prompts: runtime.prompts
+  }) : undefined;
+  const plan = planInitCommand({
+    command,
+    projectRoot,
+    options,
+    discovery,
+    ...confirmedScope !== undefined ? { confirmedScope } : {},
+    ...runtime.packageRoot !== undefined ? { packageRoot: runtime.packageRoot } : {}
+  });
+  if (!options.dryRun) {
+    executePlan(projectRoot, plan, runtime.packageRoot ?? resolvePackageRoot());
+  }
+  io.stdout(formatInitPlan(plan));
+  return plan.exitCode;
+}
+function resolveConfirmedScope(input) {
+  if (input.options.yes) {
+    if (input.discovery.docs.ambiguous || input.discovery.code.ambiguous) {
+      return;
+    }
+    if (input.discovery.docs.recommended === undefined) {
+      return;
+    }
+    return {
+      docsPattern: input.discovery.docs.recommended.pattern,
+      languages: input.discovery.code.languages
+    };
+  }
+  if (!input.prompts.isInteractive) {
+    throw new InitCliError("Interactive setup requires a TTY. Re-run with --yes for non-interactive mode.");
+  }
+  if (input.discovery.docs.ambiguous) {
+    const choices = input.discovery.docs.candidates.map((candidate) => candidate.pattern);
+    if (choices.length === 0) {
+      throw new InitCliError("Docs scope is ambiguous and no candidates were detected. Create docbridge.config.json manually.");
+    }
+    const docsPattern2 = input.prompts.select("Choose docs scope:", choices, choices[0] ?? "");
+    const languages2 = selectLanguages(input.discovery.code.languages, input.prompts);
+    return { docsPattern: docsPattern2, languages: languages2 };
+  }
+  if (input.discovery.docs.recommended === undefined) {
+    throw new InitCliError("Docs scope could not be determined.");
+  }
+  let docsPattern = input.discovery.docs.recommended.pattern;
+  if (!input.prompts.confirm(`Use docs scope ${docsPattern}?`, true)) {
+    const choices = input.discovery.docs.candidates.map((candidate) => candidate.pattern);
+    docsPattern = input.prompts.select("Choose docs scope:", choices, docsPattern);
+  }
+  const languages = selectLanguages(input.discovery.code.languages, input.prompts);
+  if (input.command === "init") {
+    const recommendedTarget = input.discovery.agent.recommendedTarget;
+    if (input.options.agentTarget === undefined && input.discovery.agent.defaultTarget === "none" && !input.prompts.confirm(`Install Codex skills under .agents/skills/?`, recommendedTarget === "codex")) {
+      input.options.agentTarget = "none";
+    }
+  }
+  return {
+    docsPattern,
+    languages
+  };
+}
+function selectLanguages(languages, prompts) {
+  if (languages.length <= 1) {
+    return languages;
+  }
+  const selected = [...languages];
+  for (const language of languages) {
+    const keep = prompts.confirm(`Include ${language.language} code scope (${language.patterns.join(", ")})?`, true);
+    if (!keep) {
+      const index = selected.findIndex((entry) => entry.language === language.language);
+      if (index >= 0) {
+        selected.splice(index, 1);
+      }
+    }
+  }
+  if (selected.length === 0) {
+    throw new InitCliError("At least one supported code language must remain in scope.");
+  }
+  return selected;
+}
+function executePlan(projectRoot, plan, packageRoot) {
+  for (const operation of plan.configOps) {
+    executeFileOperation(projectRoot, operation);
+  }
+  for (const operation of plan.skillOps) {
+    if (operation.action === "skip") {
+      continue;
+    }
+    executeSkillOperation(projectRoot, packageRoot, operation);
+  }
+}
+function executeFileOperation(projectRoot, operation) {
+  const absolutePath = join7(projectRoot, operation.path);
+  if (operation.action === "create" && operation.content !== undefined) {
+    writeFileSync(absolutePath, operation.content, "utf8");
+  }
+  if (operation.action === "overwrite" && operation.content !== undefined) {
+    writeFileSync(absolutePath, operation.content, "utf8");
+  }
+}
+function executeSkillOperation(projectRoot, packageRoot, operation) {
+  if (operation.action !== "create" && operation.action !== "overwrite") {
+    return;
+  }
+  const skillName = operation.path.split("/").at(-1);
+  if (skillName === undefined) {
+    return;
+  }
+  const sourceDir = join7(packageRoot, "templates", "skills", skillName);
+  const destinationDir = join7(projectRoot, operation.path);
+  mkdirSync2(destinationDir, { recursive: true });
+  cpSync(sourceDir, destinationDir, { recursive: true, force: true });
+}
+function resolveProjectRoot(root) {
+  const projectRoot = resolve3(root);
+  let stats;
+  try {
+    stats = statSync3(projectRoot);
+  } catch {
+    throw new InitCliError(`Root path does not exist: ${root}`);
+  }
+  if (!stats.isDirectory()) {
+    throw new InitCliError(`Root path is not a directory: ${root}`);
+  }
+  return projectRoot;
+}
+
 // src/cli/index.ts
 var VERSION = package_default.version;
 
@@ -171899,6 +172754,8 @@ Usage:
   docbridge related [--root <path>] [--json] [--stdin] [--gate] [files...]
   docbridge context [--root <path>] [--json] [--stdin] [files...]
   docbridge graph [--root <path>] [--json] [--include-content] [--stdin] [files...]
+  docbridge init [--root <path>] [--yes] [--dry-run] [--force] [--agent-target <target>]
+  docbridge init-with-agent [--root <path>] [--yes] [--dry-run] [--force] [--agent-target <target>]
   docbridge lsp
 
 Commands:
@@ -171906,6 +172763,8 @@ Commands:
   related  List the linked counterparts of the given changed files.
   context  Print the content of the counterparts linked from the given files.
   graph    Print the resolved link graph.
+  init     Set up docbridge.config.json and install DocBridge agent skills.
+  init-with-agent  Install docbridge-adopt and print agent setup commands.
   lsp      Run the Language Server over stdio.
 
 Global options:
@@ -171933,6 +172792,13 @@ Graph options:
   --json              Emit machine-readable JSON.
   --include-content   Include lightweight node content. Requires --json.
   --stdin             Read newline-separated file paths from stdin.
+
+Init options:
+  --root <path>           Project root to set up. Defaults to current directory.
+  --yes                   Accept safe defaults without prompting.
+  --dry-run               Print planned file operations without writing files.
+  --force                 Overwrite existing installed skills.
+  --agent-target <target> Agent target: codex, claude, both, or none (init only).
 `;
 function parseCheckOptions(args) {
   const options = {
@@ -172084,11 +172950,11 @@ function parseGraphOptions(args) {
   }
   return options;
 }
-function resolveProjectRoot(root) {
-  const projectRoot = resolve3(root);
+function resolveProjectRoot2(root) {
+  const projectRoot = resolve4(root);
   let stats;
   try {
-    stats = statSync(projectRoot);
+    stats = statSync4(projectRoot);
   } catch {
     throw new CliError(`Root path does not exist: ${root}`);
   }
@@ -172098,7 +172964,7 @@ function resolveProjectRoot(root) {
   return projectRoot;
 }
 function runCheck(options, io) {
-  const projectRoot = resolveProjectRoot(options.root);
+  const projectRoot = resolveProjectRoot2(options.root);
   const result = check({ projectRoot, audit: options.audit });
   if (options.json) {
     io.stdout(`${JSON.stringify(result, null, 2)}
@@ -172118,10 +172984,10 @@ function runRelated(options, io) {
   if (!options.stdin && options.files.length === 0) {
     throw new CliError("Provide file paths as arguments or use --stdin.");
   }
-  const projectRoot = resolveProjectRoot(options.root);
+  const projectRoot = resolveProjectRoot2(options.root);
   const changedFiles = [...options.files];
   if (options.stdin) {
-    const readStdin = io.stdin ?? (() => readFileSync3(0, "utf8"));
+    const readStdin = io.stdin ?? (() => readFileSync5(0, "utf8"));
     changedFiles.push(...readStdin().split(`
 `));
   }
@@ -172161,10 +173027,10 @@ function runContext(options, io) {
   if (!options.stdin && options.files.length === 0) {
     throw new CliError("Provide file paths as arguments or use --stdin.");
   }
-  const projectRoot = resolveProjectRoot(options.root);
+  const projectRoot = resolveProjectRoot2(options.root);
   const inputFiles = [...options.files];
   if (options.stdin) {
-    const readStdin = io.stdin ?? (() => readFileSync3(0, "utf8"));
+    const readStdin = io.stdin ?? (() => readFileSync5(0, "utf8"));
     inputFiles.push(...readStdin().split(`
 `));
   }
@@ -172188,10 +173054,10 @@ function runContext(options, io) {
   return 0;
 }
 function runGraph(options, io) {
-  const projectRoot = resolveProjectRoot(options.root);
+  const projectRoot = resolveProjectRoot2(options.root);
   const inputFiles = [...options.files];
   if (options.stdin) {
-    const readStdin = io.stdin ?? (() => readFileSync3(0, "utf8"));
+    const readStdin = io.stdin ?? (() => readFileSync5(0, "utf8"));
     inputFiles.push(...readStdin().split(`
 `));
   }
@@ -172222,7 +173088,7 @@ function runGraph(options, io) {
 function run(argv, io = {
   stdout: (text) => process.stdout.write(text),
   stderr: (text) => process.stderr.write(text)
-}) {
+}, initRuntime = { prompts: createDefaultPrompts() }) {
   try {
     const [command, ...rest] = argv;
     if (command === undefined || command === "--help" || command === "-h") {
@@ -172253,8 +173119,19 @@ function run(argv, io = {
       runLspServer();
       return 0;
     }
+    if (command === "init") {
+      return runInit(parseInitOptions(rest, "init"), io, initRuntime);
+    }
+    if (command === "init-with-agent") {
+      return runInitWithAgent(parseInitOptions(rest, "init-with-agent"), io, initRuntime);
+    }
     throw new CliError(`Unknown command: ${command}`);
   } catch (error) {
+    if (error instanceof InitCliError || error instanceof CliError) {
+      io.stderr(`${error.message}
+`);
+      return 1;
+    }
     io.stderr(`${error instanceof Error ? error.message : String(error)}
 `);
     return 1;