@repolensai/cli 0.1.1

package/bin/repolens.mjs

@@ -0,0 +1,3518 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import {
+  buildCliKeychainDescriptor,
+  normalizeStoredCliAuthConfig,
+} from "../lib/auth-store.mjs";
+import {
+  buildDiagramRows,
+  buildEvidenceRows,
+  collectChangeBriefRelatedFiles,
+  collectExplainerRelatedFiles,
+  exportChangeBriefToMarkdown,
+  exportExplainerToMarkdown,
+} from "../lib/publish-shared.mjs";
+import {
+  buildHistoryReportMarkdown,
+  buildHistoryReportSummary,
+  buildHistoryReportTitle,
+  collectHistoryReportRelatedFiles,
+} from "../lib/history-report-shared.mjs";
+import {
+  buildHistoryReportMetadata as buildCompactHistoryMetadata,
+} from "../lib/history-metadata-shared.mjs";
+import {
+  buildLinuxDesktopEntry,
+  buildTerminalLaunchScript,
+  buildWindowsTerminalLaunchScript,
+  isSafeRepoLensCommand,
+  parseRepoLensProtocolUrl,
+} from "../lib/protocol-handler.mjs";
+import {
+  reportCliRuntimeEvent,
+} from "../lib/runtime-events.mjs";
+import {
+  collectEvolutionReport,
+  collectHotspotReport,
+  collectOwnershipReport,
+  collectStartHereReport,
+  collectTraceReport,
+} from "../lib/git-history.mjs";
+
+const AGENT_CANDIDATES = {
+  codex: ["codex"],
+  claude: ["claude", "claude-code"],
+};
+
+const KEY_COMPONENT_SCHEMA = {
+  type: "object",
+  required: ["name", "role", "files"],
+  properties: {
+    name: { type: "string" },
+    role: { type: "string" },
+    files: { type: "array", items: { type: "string" } },
+  },
+};
+
+const DIAGRAM_SCHEMA = {
+  type: "object",
+  required: ["type", "title", "mermaidSource", "relatedFiles"],
+  properties: {
+    type: { type: "string" },
+    title: { type: "string" },
+    mermaidSource: { type: "string" },
+    relatedFiles: { type: "array", items: { type: "string" } },
+  },
+};
+
+const EVIDENCE_SCHEMA = {
+  type: "object",
+  required: ["type", "reference", "description", "lineRange", "codeSnippet", "confidence"],
+  properties: {
+    type: { type: "string" },
+    reference: { type: "string" },
+    description: { type: "string" },
+    lineRange: {
+      type: ["array", "null"],
+      items: { type: "number" },
+      minItems: 2,
+      maxItems: 2,
+    },
+    codeSnippet: { type: ["string", "null"] },
+    confidence: { type: "string", enum: ["explicit", "strongly_inferred", "hypothesis"] },
+  },
+};
+
+const EXPLAINER_SCHEMA = {
+  type: "object",
+  required: [
+    "title",
+    "summary",
+    "valueProposition",
+    "userJourney",
+    "keyComponents",
+    "businessLogic",
+    "diagrams",
+    "risksAndQuestions",
+    "openQuestions",
+    "evidence",
+  ],
+  properties: {
+    title: { type: "string" },
+    summary: { type: "string" },
+    valueProposition: { type: "string" },
+    userJourney: { type: "string" },
+    keyComponents: { type: "array", items: KEY_COMPONENT_SCHEMA },
+    businessLogic: { type: "string" },
+    diagrams: { type: "array", items: DIAGRAM_SCHEMA },
+    risksAndQuestions: { type: "string" },
+    openQuestions: { type: "array", items: { type: "string" } },
+    evidence: { type: "array", items: EVIDENCE_SCHEMA },
+  },
+};
+
+const CHANGE_FEATURE_SCHEMA = {
+  type: "object",
+  required: ["feature", "impactType", "description", "confidence"],
+  properties: {
+    feature: { type: "string" },
+    impactType: { type: "string" },
+    description: { type: "string" },
+    confidence: { type: "string" },
+  },
+};
+
+const CHANGE_FILE_SCHEMA = {
+  type: "object",
+  required: ["path", "changeType", "role"],
+  properties: {
+    path: { type: "string" },
+    changeType: { type: "string" },
+    role: { type: "string" },
+  },
+};
+
+const CHANGE_BRIEF_SCHEMA = {
+  type: "object",
+  required: [
+    "summary",
+    "impactedFeatures",
+    "impactedFiles",
+    "impactedScreens",
+    "rolloutRisks",
+    "qaChecklist",
+    "communicationBrief",
+    "diagrams",
+    "evidence",
+  ],
+  properties: {
+    summary: { type: "string" },
+    impactedFeatures: { type: "array", items: CHANGE_FEATURE_SCHEMA },
+    impactedFiles: { type: "array", items: CHANGE_FILE_SCHEMA },
+    impactedScreens: { type: "array", items: { type: "string" } },
+    rolloutRisks: { type: "string" },
+    qaChecklist: { type: "array", items: { type: "string" } },
+    communicationBrief: { type: "string" },
+    diagrams: { type: "array", items: DIAGRAM_SCHEMA },
+    evidence: { type: "array", items: EVIDENCE_SCHEMA },
+  },
+};
+
+const RUN_MODE_PRESETS = {
+  review: {
+    description: "Structured code review findings ordered by severity.",
+    schema: {
+      type: "object",
+      required: ["summary", "overall_risk", "findings"],
+      properties: {
+        summary: { type: "string" },
+        overall_risk: { type: "string", enum: ["low", "medium", "high"] },
+        findings: {
+          type: "array",
+          items: {
+            type: "object",
+            required: ["severity", "title", "detail", "files", "recommendation"],
+            properties: {
+              severity: { type: "string", enum: ["low", "medium", "high"] },
+              title: { type: "string" },
+              detail: { type: "string" },
+              files: { type: "array", items: { type: "string" } },
+              recommendation: { type: "string" },
+            },
+          },
+        },
+      },
+    },
+  },
+  summary: {
+    description: "Structured high-level summary of the requested area or change.",
+    schema: {
+      type: "object",
+      required: ["summary", "key_points", "affected_files", "open_questions"],
+      properties: {
+        summary: { type: "string" },
+        key_points: { type: "array", items: { type: "string" } },
+        affected_files: { type: "array", items: { type: "string" } },
+        open_questions: { type: "array", items: { type: "string" } },
+      },
+    },
+  },
+  explainer: {
+    description: "App-compatible explainer payload that can be published into a board.",
+    publishKind: "feature",
+    schema: EXPLAINER_SCHEMA,
+  },
+  onboarding: {
+    description: "App-compatible onboarding pack payload that can be published into a board.",
+    publishKind: "onboarding",
+    schema: EXPLAINER_SCHEMA,
+  },
+  "change-brief": {
+    description: "App-compatible change brief payload that can be published into a board.",
+    publishKind: "change-brief",
+    schema: CHANGE_BRIEF_SCHEMA,
+  },
+};
+
+async function main() {
+  loadLocalEnv(process.cwd());
+  const rawArgs = process.argv.slice(2);
+  const args = rawArgs[0] === "--" ? rawArgs.slice(1) : rawArgs;
+  const command = args[0];
+
+  switch (command) {
+    case "doctor":
+      return handleDoctor(args.slice(1));
+    case "login":
+      return handleLogin(args.slice(1));
+    case "logout":
+      return handleLogout(args.slice(1));
+    case "whoami":
+      return handleWhoAmI(args.slice(1));
+    case "boards":
+      return handleBoards(args.slice(1));
+    case "link":
+      return handleLink(args.slice(1));
+    case "install-protocol":
+      return handleInstallProtocol(args.slice(1));
+    case "handle-url":
+      return handleHandleUrl(args.slice(1));
+    case "brief":
+      return handleBrief(args.slice(1));
+    case "evolution":
+      return handleEvolution(args.slice(1));
+    case "hotspots":
+      return handleHotspots(args.slice(1));
+    case "ownership":
+      return handleOwnership(args.slice(1));
+    case "start-here":
+      return handleStartHere(args.slice(1));
+    case "trace":
+      return handleTrace(args.slice(1));
+    case "run":
+      return handleRun(args.slice(1));
+    case "publish":
+      return handlePublish(args.slice(1));
+    case "delegate":
+      return handleDelegate(args.slice(1));
+    case "context":
+      return handleContext(args.slice(1));
+    case "help":
+    case "--help":
+    case "-h":
+    case undefined:
+      printHelp();
+      return;
+    default:
+      fail(`Unknown command "${command}". Run "repolens help" for usage.`);
+  }
+}
+
+function handleDoctor(args) {
+  const options = parseFlags(args, {
+    boolean: new Set(["json"]),
+  });
+
+  const repoRoot = findGitRoot(process.cwd());
+  const authConfig = loadCliAuthConfig();
+  const linkedBoard = loadRepoLink(process.cwd());
+  const publishReady = hasPublishEnv();
+  const protocolDescriptor = getProtocolInstallDescriptor();
+  const protocolInstalled = isProtocolHandlerInstalled();
+  const report = {
+    repoRoot,
+    auth: authConfig
+      ? {
+        connected: true,
+        appUrl: authConfig.appUrl,
+        user: authConfig.user ?? null,
+        tokenStore: authConfig.tokenStore?.type ?? (authConfig.token ? "file" : null),
+      }
+      : {
+          connected: false,
+      appUrl: null,
+      user: null,
+      tokenStore: null,
+    },
+    linkedBoard,
+    agents: Object.entries(AGENT_CANDIDATES).map(([agent, candidates]) => {
+      const resolved = resolveExecutable(candidates);
+      return {
+        agent,
+        available: Boolean(resolved),
+        executable: resolved ? resolved.name : null,
+        path: resolved ? resolved.path : null,
+      };
+    }),
+    publish: {
+      ready: publishReady,
+      supabaseUrlPresent: Boolean(process.env.NEXT_PUBLIC_SUPABASE_URL),
+      serviceRolePresent: Boolean(process.env.SUPABASE_SERVICE_ROLE_KEY),
+    },
+    protocol: {
+      installed: protocolInstalled,
+      platform: protocolDescriptor.platform,
+      installPath: protocolInstalled ? protocolDescriptor.installPath : null,
+    },
+  };
+
+  if (options.flags.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return;
+  }
+
+  process.stdout.write("RepoLens CLI doctor\n");
+  process.stdout.write(`Repo root: ${repoRoot ?? "Not inside a git repository"}\n`);
+  process.stdout.write(
+    `- auth: ${authConfig ? `connected to ${authConfig.appUrl}${authConfig.user?.email ? ` as ${authConfig.user.email}` : ""}` : "not connected"}\n`
+  );
+  if (authConfig) {
+    process.stdout.write(`- auth storage: ${authConfig.tokenStore?.type ?? (authConfig.token ? "file" : "unknown")}\n`);
+  }
+  process.stdout.write(
+    `- linked board: ${linkedBoard ? `${linkedBoard.boardId}${linkedBoard.boardName ? ` (${linkedBoard.boardName})` : ""}` : "none"}\n`
+  );
+  for (const agent of report.agents) {
+    process.stdout.write(
+      `- ${agent.agent}: ${agent.available ? `available via ${agent.executable} (${agent.path})` : "not found on PATH"}\n`
+    );
+  }
+  process.stdout.write(
+    `- publish: ${publishReady ? "ready" : "missing NEXT_PUBLIC_SUPABASE_URL or SUPABASE_SERVICE_ROLE_KEY"}\n`
+  );
+  process.stdout.write(
+    `- protocol launch: ${protocolInstalled ? `installed (${protocolDescriptor.installPath})` : protocolDescriptor.supported ? "not installed" : `unsupported on ${protocolDescriptor.platform}`}\n`
+  );
+}
+
+function getCliEventContext() {
+  const authConfig = loadCliAuthConfig();
+  if (!authConfig?.appUrl || !authConfig?.token) {
+    return null;
+  }
+
+  return authConfig;
+}
+
+async function reportCliEvent(event) {
+  const authConfig = getCliEventContext();
+  if (!authConfig) {
+    return false;
+  }
+
+  return await reportCliRuntimeEvent(authConfig, event);
+}
+
+async function handleLogin(args) {
+  const options = parseFlags(args, {
+    string: new Set(["app-url", "token", "label"]),
+    boolean: new Set(["json", "no-browser"]),
+  });
+
+  const appUrl = normalizeAppUrl(options.flags["app-url"]);
+  if (!appUrl) {
+    fail("Usage: repolens login --app-url URL [--token TOKEN] [--label LABEL] [--no-browser] [--json]");
+  }
+  const loginResult = options.flags.token
+    ? await verifyCliTokenLogin(appUrl, options.flags.token)
+    : await loginWithBrowserFlow(appUrl, {
+        label: options.flags.label ?? defaultCliLoginLabel(),
+        noBrowser: Boolean(options.flags["no-browser"]),
+        json: Boolean(options.flags.json),
+      });
+
+  const config = {
+    appUrl,
+    token: loginResult.token,
+    user: loginResult.user ?? null,
+    loggedInAt: new Date().toISOString(),
+  };
+  saveCliAuthConfig(config);
+  let protocolInstalled = false;
+  try {
+    protocolInstalled = ensureProtocolHandlerInstalled();
+    if (protocolInstalled) {
+      await reportCliEvent({
+        action: "cli_protocol.install_succeeded",
+        metadata: {
+          platform: process.platform,
+          installPath: getProtocolInstallDescriptor().installPath,
+          installedDuringLogin: true,
+        },
+      });
+    }
+  } catch (error) {
+    await reportCliEvent({
+      action: "cli_protocol.install_failed",
+      metadata: {
+        platform: process.platform,
+        installedDuringLogin: true,
+        error: error instanceof Error ? error.message : String(error),
+      },
+    });
+    throw error;
+  }
+
+  if (options.flags.json) {
+    process.stdout.write(`${JSON.stringify({ success: true, appUrl, user: loginResult.user, protocolInstalled }, null, 2)}\n`);
+    return;
+  }
+
+  process.stdout.write(`Connected RepoLens CLI to ${appUrl}\n`);
+  if (loginResult.user?.email) {
+    process.stdout.write(`Signed in as ${loginResult.user.email}\n`);
+  }
+  if (protocolInstalled) {
+    process.stdout.write("Installed RepoLens Launcher for one-click browser handoff.\n");
+  }
+}
+
+function handleLogout(args) {
+  const options = parseFlags(args, {
+    boolean: new Set(["json"]),
+  });
+
+  deleteCliAuthConfig();
+
+  if (options.flags.json) {
+    process.stdout.write(`${JSON.stringify({ success: true }, null, 2)}\n`);
+    return;
+  }
+
+  process.stdout.write("Removed local RepoLens CLI credentials.\n");
+}
+
+async function handleWhoAmI(args) {
+  const options = parseFlags(args, {
+    boolean: new Set(["json"]),
+  });
+
+  const config = requireCliAuthConfig();
+  const response = await callCliApi({
+    appUrl: config.appUrl,
+    token: config.token,
+    pathname: "/api/cli/me",
+    method: "GET",
+  });
+  const payload = await parseApiJson(response);
+  if (!response.ok) {
+    fail(payload.error ?? `Request failed with status ${response.status}.`);
+  }
+
+  if (options.flags.json) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    return;
+  }
+
+  process.stdout.write(`RepoLens account: ${payload.user?.email ?? "unknown"}\n`);
+  process.stdout.write(`App: ${config.appUrl}\n`);
+  process.stdout.write(`Boards: ${payload.user?.boardCount ?? 0}\n`);
+}
+
+async function handleBoards(args) {
+  const options = parseFlags(args, {
+    boolean: new Set(["json"]),
+  });
+
+  const config = requireCliAuthConfig();
+  const response = await callCliApi({
+    appUrl: config.appUrl,
+    token: config.token,
+    pathname: "/api/cli/boards",
+    method: "GET",
+  });
+  const payload = await parseApiJson(response);
+  if (!response.ok) {
+    fail(payload.error ?? `Request failed with status ${response.status}.`);
+  }
+
+  if (options.flags.json) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    return;
+  }
+
+  if (!Array.isArray(payload.boards) || payload.boards.length === 0) {
+    process.stdout.write("No RepoLens boards available.\n");
+    return;
+  }
+
+  process.stdout.write("RepoLens boards\n");
+  for (const board of payload.boards) {
+    process.stdout.write(`- ${board.id}  ${board.name} [${board.role}]${board.repoUrl ? `  ${board.repoUrl}` : ""}\n`);
+  }
+}
+
+async function handleLink(args) {
+  const options = parseFlags(args, {
+    string: new Set(["board-id"]),
+    boolean: new Set(["json"]),
+  });
+
+  const boardId = options.flags["board-id"];
+  if (!boardId) {
+    fail("Usage: repolens link --board-id UUID [--json]");
+  }
+
+  const repoRoot = findGitRoot(process.cwd());
+  if (!repoRoot) {
+    fail("Run `repolens link` from inside a git repository.");
+  }
+
+  const config = requireCliAuthConfig();
+  const response = await callCliApi({
+    appUrl: config.appUrl,
+    token: config.token,
+    pathname: "/api/cli/boards",
+    method: "GET",
+  });
+  const payload = await parseApiJson(response);
+  if (!response.ok) {
+    fail(payload.error ?? `Request failed with status ${response.status}.`);
+  }
+
+  const board = Array.isArray(payload.boards)
+    ? payload.boards.find((entry) => entry.id === boardId)
+    : null;
+  if (!board) {
+    fail(`Board ${boardId} is not accessible from the current RepoLens account.`);
+  }
+
+  const previousLink = loadRepoLink(repoRoot);
+  const link = {
+    boardId: board.id,
+    boardName: board.name,
+    appUrl: config.appUrl,
+    linkedAt: new Date().toISOString(),
+  };
+  saveRepoLink(repoRoot, link);
+  registerBoardLink(repoRoot, link, previousLink?.boardId ?? null);
+
+  if (options.flags.json) {
+    process.stdout.write(`${JSON.stringify({ success: true, repoRoot, link }, null, 2)}\n`);
+    return;
+  }
+
+  process.stdout.write(`Linked ${repoRoot} to board ${board.name} (${board.id})\n`);
+}
+
+async function handleInstallProtocol(args) {
+  const options = parseFlags(args, {
+    boolean: new Set(["json"]),
+  });
+
+  const descriptor = getProtocolInstallDescriptor();
+  if (!descriptor.supported) {
+    fail(`Protocol installation is not currently supported on ${descriptor.platform}.`);
+  }
+
+  try {
+    const installed = installProtocolHandler();
+    await reportCliEvent({
+      action: "cli_protocol.install_succeeded",
+      metadata: {
+        platform: process.platform,
+        installPath: installed.installPath,
+      },
+    });
+
+    if (options.flags.json) {
+      process.stdout.write(`${JSON.stringify({ success: true, install: installed }, null, 2)}\n`);
+      return;
+    }
+
+    process.stdout.write(`Installed RepoLens protocol handler for ${installed.platform} at ${installed.installPath}\n`);
+    process.stdout.write("Web pages can now attempt to open repolens-cli:// launch URLs on this machine.\n");
+  } catch (error) {
+    await reportCliEvent({
+      action: "cli_protocol.install_failed",
+      metadata: {
+        platform: process.platform,
+        error: error instanceof Error ? error.message : String(error),
+      },
+    });
+    fail(error instanceof Error ? error.message : String(error));
+  }
+}
+
+async function handleHandleUrl(args) {
+  const rawUrl = args[0];
+  if (!rawUrl) {
+    fail("Usage: repolens handle-url URL");
+  }
+
+  const protocolDescriptor = getProtocolInstallDescriptor();
+  if (!protocolDescriptor.supported) {
+    await reportCliEvent({
+      action: "cli_protocol.launch_unsupported_platform",
+      metadata: {
+        platform: protocolDescriptor.platform,
+      },
+    });
+    fail(`Protocol launch handling is not currently supported on ${protocolDescriptor.platform}.`);
+  }
+
+  let launch;
+  try {
+    launch = parseRepoLensProtocolUrl(rawUrl);
+  } catch (error) {
+    await reportCliEvent({
+      action: "cli_protocol.launch_invalid_url",
+      metadata: {
+        platform: process.platform,
+        error: error instanceof Error ? error.message : String(error),
+      },
+    });
+    throw error;
+  }
+
+  await reportCliEvent({
+    action: "cli_protocol.launch_received",
+    boardId: launch.boardId,
+    metadata: {
+      platform: process.platform,
+      source: launch.source,
+    },
+  });
+
+  if (!isSafeRepoLensCommand(launch.command)) {
+    await reportCliEvent({
+      action: "cli_protocol.launch_unsafe_command",
+      boardId: launch.boardId,
+      metadata: {
+        platform: process.platform,
+        source: launch.source,
+      },
+    });
+    fail("Refusing to launch an unsafe RepoLens command.");
+  }
+
+  const repoRoot = launch.boardId ? resolveLinkedRepoRootForBoard(launch.boardId) : null;
+  if (launch.boardId && !repoRoot) {
+    await reportCliEvent({
+      action: "cli_protocol.launch_missing_repo_link",
+      boardId: launch.boardId,
+      metadata: {
+        platform: process.platform,
+        source: launch.source,
+      },
+    });
+  }
+
+  try {
+    openTerminalForProtocolCommand({
+      command: launch.command,
+      repoRoot,
+      source: launch.source,
+    });
+    await reportCliEvent({
+      action: "cli_protocol.launch_opened",
+      boardId: launch.boardId,
+      metadata: {
+        platform: process.platform,
+        source: launch.source,
+        repoLinked: Boolean(repoRoot),
+      },
+    });
+  } catch (error) {
+    await reportCliEvent({
+      action: "cli_protocol.launch_terminal_failed",
+      boardId: launch.boardId,
+      metadata: {
+        platform: process.platform,
+        source: launch.source,
+        repoLinked: Boolean(repoRoot),
+        error: error instanceof Error ? error.message : String(error),
+      },
+    });
+    throw error;
+  }
+}
+
+function handleDelegate(args) {
+  if (args.length === 0) {
+    fail('Usage: repolens delegate <codex|claude> [--cwd PATH] [--dry-run] [--] <agent args...>');
+  }
+
+  const agent = args[0];
+  if (!Object.prototype.hasOwnProperty.call(AGENT_CANDIDATES, agent)) {
+    fail(`Unsupported agent "${agent}". Expected one of: ${Object.keys(AGENT_CANDIDATES).join(", ")}`);
+  }
+
+  const options = parseFlags(args.slice(1), {
+    string: new Set(["cwd"]),
+    boolean: new Set(["dry-run"]),
+  });
+
+  const resolved = resolveExecutable(AGENT_CANDIDATES[agent]);
+  if (!resolved) {
+    fail(`Could not find a local ${agent} CLI on PATH. Run "repolens doctor" to inspect availability.`);
+  }
+
+  const cwd = options.flags.cwd ? path.resolve(options.flags.cwd) : process.cwd();
+  if (!fs.existsSync(cwd) || !fs.statSync(cwd).isDirectory()) {
+    fail(`Invalid working directory: ${cwd}`);
+  }
+
+  if (options.flags["dry-run"]) {
+    process.stdout.write(`${resolved.name} ${options.positionals.join(" ")}\n`);
+    return;
+  }
+
+  const child = spawn(resolved.name, options.positionals, {
+    cwd,
+    stdio: "inherit",
+    env: process.env,
+  });
+
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+
+    process.exit(code ?? 1);
+  });
+
+  child.on("error", (error) => {
+    fail(`Failed to launch ${agent}: ${error.message}`);
+  });
+}
+
+function handleContext(args) {
+  const options = parseFlags(args, {
+    string: new Set(["cwd", "base", "head", "output"]),
+    boolean: new Set(["json"]),
+  });
+
+  const cwd = options.flags.cwd ? path.resolve(options.flags.cwd) : process.cwd();
+  const repoRoot = findGitRoot(cwd);
+  if (!repoRoot) {
+    fail(`No git repository found from ${cwd}`);
+  }
+
+  const branch = runCommand("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: repoRoot }).trim();
+  const recentCommits = lines(runCommand("git", ["log", "--oneline", "-n", "8"], { cwd: repoRoot }));
+  const statusLines = lines(runCommand("git", ["status", "--short"], { cwd: repoRoot }, { allowFailure: true }));
+  const trackedFiles = lines(runCommand("git", ["ls-files"], { cwd: repoRoot }, { allowFailure: true }));
+  const rankedFiles = rankPaths(trackedFiles).slice(0, 30);
+
+  let diffSummary = [];
+  let changedFiles = [];
+  const base = options.flags.base;
+  const head = options.flags.head;
+
+  if (base && head) {
+    diffSummary = lines(
+      runCommand("git", ["diff", "--stat", `${base}..${head}`], { cwd: repoRoot }, { allowFailure: true })
+    );
+    changedFiles = lines(
+      runCommand("git", ["diff", "--name-only", `${base}..${head}`], { cwd: repoRoot }, { allowFailure: true })
+    );
+  }
+
+  const payload = {
+    repoRoot,
+    branch,
+    generatedAt: new Date().toISOString(),
+    recentCommits,
+    status: statusLines,
+    topFiles: rankedFiles,
+    compare: base && head ? { base, head, diffSummary, changedFiles } : null,
+  };
+
+  if (options.flags.json) {
+    writeOutput(JSON.stringify(payload, null, 2), options.flags.output);
+    return;
+  }
+
+  writeOutput(buildContextMarkdown(payload), options.flags.output);
+}
+
+function handleBrief(args) {
+  const options = parseFlags(args, {
+    string: new Set(["cwd", "base", "head", "output"]),
+    boolean: new Set(["json"]),
+  });
+
+  if (!options.flags.base || !options.flags.head) {
+    fail("Usage: repolens brief --base <ref> --head <ref> [--cwd PATH] [--output FILE] [--json]");
+  }
+
+  const payload = collectRepoSnapshot({
+    cwd: options.flags.cwd ? path.resolve(options.flags.cwd) : process.cwd(),
+    base: options.flags.base,
+    head: options.flags.head,
+    includeRangeCommits: true,
+  });
+
+  if (options.flags.json) {
+    writeOutput(JSON.stringify(payload, null, 2), options.flags.output);
+    return;
+  }
+
+  writeOutput(buildBriefMarkdown(payload), options.flags.output);
+}
+
+async function handleEvolution(args) {
+  const options = parseFlags(args, {
+    string: new Set(["cwd", "path", "since", "limit", "output", "publish-board-id"]),
+    boolean: new Set(["json", "dry-run"]),
+  });
+
+  const targetPath = options.flags.path;
+  if (!targetPath) {
+    fail("Usage: repolens evolution --path PATH [--cwd PATH] [--since REF] [--limit N] [--output FILE] [--json] [--publish-board-id UUID] [--dry-run]");
+  }
+  if (options.flags.json && options.flags["publish-board-id"]) {
+    fail("Do not combine --json with --publish-board-id. Use --output if you need a local JSON file before publishing.");
+  }
+
+  const cwd = options.flags.cwd ? path.resolve(options.flags.cwd) : process.cwd();
+  const repoRoot = findGitRoot(cwd);
+  if (!repoRoot) {
+    fail(`No git repository found from ${cwd}`);
+  }
+
+  const limit = parsePositiveInteger(options.flags.limit, 20, "--limit");
+  const payload = {
+    repoRoot,
+    branch: runCommand("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: repoRoot }).trim(),
+    ...collectEvolutionReport({
+      cwd: repoRoot,
+      targetPath,
+      sinceRef: options.flags.since ?? null,
+      limit,
+      exec: (gitArgs, runtimeOptions = {}) => runCommand("git", gitArgs, { cwd: repoRoot }, runtimeOptions),
+    }),
+  };
+
+  if (options.flags.json) {
+    writeOutput(JSON.stringify(payload, null, 2), options.flags.output);
+  } else {
+    writeOutput(buildHistoryReportMarkdown("evolution", payload), options.flags.output);
+  }
+
+  if (options.flags["publish-board-id"]) {
+    await publishHistoryReport({
+      boardId: options.flags["publish-board-id"],
+      reportKind: "evolution",
+      payload,
+      dryRun: options.flags["dry-run"],
+    });
+  }
+}
+
+async function handleHotspots(args) {
+  const options = parseFlags(args, {
+    string: new Set(["cwd", "since", "limit", "output", "publish-board-id"]),
+    boolean: new Set(["json", "dry-run"]),
+  });
+  if (options.flags.json && options.flags["publish-board-id"]) {
+    fail("Do not combine --json with --publish-board-id. Use --output if you need a local JSON file before publishing.");
+  }
+
+  const cwd = options.flags.cwd ? path.resolve(options.flags.cwd) : process.cwd();
+  const repoRoot = findGitRoot(cwd);
+  if (!repoRoot) {
+    fail(`No git repository found from ${cwd}`);
+  }
+
+  const limit = parsePositiveInteger(options.flags.limit, 15, "--limit");
+  const payload = {
+    repoRoot,
+    branch: runCommand("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: repoRoot }).trim(),
+    ...collectHotspotReport({
+      sinceRef: options.flags.since ?? "HEAD~100",
+      limit,
+      exec: (gitArgs, runtimeOptions = {}) => runCommand("git", gitArgs, { cwd: repoRoot }, runtimeOptions),
+    }),
+  };
+
+  if (options.flags.json) {
+    writeOutput(JSON.stringify(payload, null, 2), options.flags.output);
+  } else {
+    writeOutput(buildHistoryReportMarkdown("hotspots", payload), options.flags.output);
+  }
+
+  if (options.flags["publish-board-id"]) {
+    await publishHistoryReport({
+      boardId: options.flags["publish-board-id"],
+      reportKind: "hotspots",
+      payload,
+      dryRun: options.flags["dry-run"],
+    });
+  }
+}
+
+async function handleOwnership(args) {
+  const options = parseFlags(args, {
+    string: new Set(["cwd", "path", "since", "limit", "output", "publish-board-id"]),
+    boolean: new Set(["json", "dry-run"]),
+  });
+
+  const targetPath = options.flags.path;
+  if (!targetPath) {
+    fail("Usage: repolens ownership --path PATH [--cwd PATH] [--since REF] [--limit N] [--output FILE] [--json] [--publish-board-id UUID] [--dry-run]");
+  }
+  if (options.flags.json && options.flags["publish-board-id"]) {
+    fail("Do not combine --json with --publish-board-id. Use --output if you need a local JSON file before publishing.");
+  }
+
+  const cwd = options.flags.cwd ? path.resolve(options.flags.cwd) : process.cwd();
+  const repoRoot = findGitRoot(cwd);
+  if (!repoRoot) {
+    fail(`No git repository found from ${cwd}`);
+  }
+
+  const limit = parsePositiveInteger(options.flags.limit, 10, "--limit");
+  const payload = {
+    repoRoot,
+    branch: runCommand("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: repoRoot }).trim(),
+    ...collectOwnershipReport({
+      cwd: repoRoot,
+      targetPath,
+      sinceRef: options.flags.since ?? null,
+      limit,
+      exec: (gitArgs, runtimeOptions = {}) => runCommand("git", gitArgs, { cwd: repoRoot }, runtimeOptions),
+    }),
+  };
+
+  if (options.flags.json) {
+    writeOutput(JSON.stringify(payload, null, 2), options.flags.output);
+  } else {
+    writeOutput(buildHistoryReportMarkdown("ownership", payload), options.flags.output);
+  }
+
+  if (options.flags["publish-board-id"]) {
+    await publishHistoryReport({
+      boardId: options.flags["publish-board-id"],
+      reportKind: "ownership",
+      payload,
+      dryRun: options.flags["dry-run"],
+    });
+  }
+}
+
+async function handleStartHere(args) {
+  const options = parseFlags(args, {
+    string: new Set(["cwd", "path", "since", "limit", "output", "publish-board-id"]),
+    boolean: new Set(["json", "dry-run"]),
+  });
+
+  const targetPath = options.flags.path;
+  if (!targetPath) {
+    fail("Usage: repolens start-here --path PATH [--cwd PATH] [--since REF] [--limit N] [--output FILE] [--json] [--publish-board-id UUID] [--dry-run]");
+  }
+  if (options.flags.json && options.flags["publish-board-id"]) {
+    fail("Do not combine --json with --publish-board-id. Use --output if you need a local JSON file before publishing.");
+  }
+
+  const cwd = options.flags.cwd ? path.resolve(options.flags.cwd) : process.cwd();
+  const repoRoot = findGitRoot(cwd);
+  if (!repoRoot) {
+    fail(`No git repository found from ${cwd}`);
+  }
+
+  const limit = parsePositiveInteger(options.flags.limit, 5, "--limit");
+  const payload = {
+    repoRoot,
+    branch: runCommand("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: repoRoot }).trim(),
+    ...collectStartHereReport({
+      cwd: repoRoot,
+      targetPath,
+      sinceRef: options.flags.since ?? null,
+      limit,
+      exec: (gitArgs, runtimeOptions = {}) => runCommand("git", gitArgs, { cwd: repoRoot }, runtimeOptions),
+    }),
+  };
+
+  if (options.flags.json) {
+    writeOutput(JSON.stringify(payload, null, 2), options.flags.output);
+  } else {
+    writeOutput(buildHistoryReportMarkdown("start-here", payload), options.flags.output);
+  }
+
+  if (options.flags["publish-board-id"]) {
+    await publishHistoryReport({
+      boardId: options.flags["publish-board-id"],
+      reportKind: "start-here",
+      payload,
+      dryRun: options.flags["dry-run"],
+    });
+  }
+}
+
+async function handleTrace(args) {
+  const options = parseFlags(args, {
+    string: new Set(["cwd", "query", "since", "limit", "output", "publish-board-id"]),
+    boolean: new Set(["json", "dry-run"]),
+  });
+
+  const query = options.flags.query;
+  if (!query) {
+    fail("Usage: repolens trace --query TEXT [--cwd PATH] [--since REF] [--limit N] [--output FILE] [--json] [--publish-board-id UUID] [--dry-run]");
+  }
+  if (options.flags.json && options.flags["publish-board-id"]) {
+    fail("Do not combine --json with --publish-board-id. Use --output if you need a local JSON file before publishing.");
+  }
+
+  const cwd = options.flags.cwd ? path.resolve(options.flags.cwd) : process.cwd();
+  const repoRoot = findGitRoot(cwd);
+  if (!repoRoot) {
+    fail(`No git repository found from ${cwd}`);
+  }
+
+  const limit = parsePositiveInteger(options.flags.limit, 5, "--limit");
+  const payload = {
+    repoRoot,
+    branch: runCommand("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: repoRoot }).trim(),
+    ...collectTraceReport({
+      cwd: repoRoot,
+      query,
+      sinceRef: options.flags.since ?? null,
+      limit,
+      exec: (gitArgs, runtimeOptions = {}) => runCommand("git", gitArgs, { cwd: repoRoot }, runtimeOptions),
+    }),
+  };
+
+  if (options.flags.json) {
+    writeOutput(JSON.stringify(payload, null, 2), options.flags.output);
+  } else {
+    writeOutput(buildHistoryReportMarkdown("trace", payload), options.flags.output);
+  }
+
+  if (options.flags["publish-board-id"]) {
+    await publishHistoryReport({
+      boardId: options.flags["publish-board-id"],
+      reportKind: "trace",
+      payload,
+      dryRun: options.flags["dry-run"],
+    });
+  }
+}
+
+async function handleRun(args) {
+  if (args.length === 0) {
+    fail(
+      "Usage: repolens run <codex|claude> --task <text> [--mode review|summary|explainer|onboarding|change-brief] [--base REF --head REF] [--audience VALUE] [--context-file FILE] [--save-packet FILE] [--output FILE] [--publish-board-id UUID] [--publish-as feature|onboarding|change-brief] [--user-id UUID] [--json] [--allow-edit] [--dry-run] [--] <extra agent args...>"
+    );
+  }
+
+  const agent = args[0];
+  if (!Object.prototype.hasOwnProperty.call(AGENT_CANDIDATES, agent)) {
+    fail(`Unsupported agent "${agent}". Expected one of: ${Object.keys(AGENT_CANDIDATES).join(", ")}`);
+  }
+
+  const options = parseFlags(args.slice(1), {
+    string: new Set([
+      "cwd",
+      "base",
+      "head",
+      "task",
+      "task-file",
+      "context-file",
+      "save-packet",
+      "output",
+      "model",
+      "mode",
+      "audience",
+      "publish-board-id",
+      "publish-as",
+      "user-id",
+    ]),
+    boolean: new Set(["json", "allow-edit", "dry-run"]),
+  });
+
+  const mode = options.flags.mode ?? null;
+  const modePreset = mode ? RUN_MODE_PRESETS[mode] ?? null : null;
+  if (mode && !modePreset) {
+    fail(`Unsupported run mode "${mode}". Expected one of: ${Object.keys(RUN_MODE_PRESETS).join(", ")}`);
+  }
+
+  if (modePreset && options.flags.json) {
+    fail("Do not combine --json with --mode. Structured modes already persist JSON results.");
+  }
+
+  const publishBoardId = options.flags["publish-board-id"] ?? null;
+  const requestedPublishTarget = options.flags["publish-as"] ?? null;
+  const shouldPublish = Boolean(publishBoardId || requestedPublishTarget);
+  const publishKind = shouldPublish
+    ? normalizePublishKind(requestedPublishTarget ?? defaultPublishKindForMode(mode))
+    : null;
+  if (requestedPublishTarget && !publishKind) {
+    fail('Unsupported publish target. Expected one of: "feature", "explainer", "onboarding", "change-brief".');
+  }
+  if (publishBoardId && !publishKind) {
+    fail("Publishing requires a publishable structured mode or an explicit --publish-as target.");
+  }
+
+  const task = resolveTask(options.flags.task, options.flags["task-file"]);
+  const cwd = options.flags.cwd ? path.resolve(options.flags.cwd) : process.cwd();
+  const repoRoot = findGitRoot(cwd);
+  if (!repoRoot) {
+    fail(`No git repository found from ${cwd}`);
+  }
+  const linkedBoard = loadRepoLink(repoRoot);
+  const resolvedPublishBoardId = publishBoardId ?? (shouldPublish ? linkedBoard?.boardId ?? null : null);
+  if (publishKind && !resolvedPublishBoardId) {
+    fail("Use --publish-board-id or run `repolens link --board-id <id>` before publishing from this repo.");
+  }
+
+  const audience = normalizeAudience(options.flags.audience, publishKind);
+  const snapshot = collectRepoSnapshot({
+    cwd: repoRoot,
+    base: options.flags.base,
+    head: options.flags.head,
+    includeRangeCommits: Boolean(options.flags.base && options.flags.head),
+  });
+  const historyAppendix = buildRunHistoryAppendix({
+    repoRoot,
+    snapshot,
+  });
+
+  const runStamp = buildRunStamp();
+  const packetOutputPath = options.flags["save-packet"]
+    ? path.resolve(options.flags["save-packet"])
+    : modePreset
+      ? path.resolve(repoRoot, ".repolens", "runs", `${runStamp}-${agent}-${mode}.packet.md`)
+      : null;
+  const structuredResultPath = modePreset
+    ? path.resolve(
+        options.flags.output
+          ? options.flags.output
+          : path.join(repoRoot, ".repolens", "runs", `${runStamp}-${agent}-${mode}.json`)
+      )
+    : options.flags.output
+      ? path.resolve(options.flags.output)
+      : null;
+  const schemaPath = modePreset
+    ? path.resolve(repoRoot, ".repolens", "runs", `${runStamp}-${agent}-${mode}.schema.json`)
+    : null;
+  const codexLastMessagePath = modePreset && agent === "codex"
+    ? path.resolve(repoRoot, ".repolens", "runs", `${runStamp}-${agent}-${mode}.raw.json`)
+    : null;
+
+  const contextAppendix = options.flags["context-file"]
+    ? fs.readFileSync(path.resolve(options.flags["context-file"]), "utf8")
+    : null;
+
+  const packet = buildRunPacket({
+    agent,
+    mode,
+    task,
+    snapshot,
+    historyAppendix,
+    allowEdit: Boolean(options.flags["allow-edit"]),
+    audience,
+    contextAppendix,
+  });
+
+  if (packetOutputPath) {
+    writeOutput(packet, packetOutputPath);
+  }
+
+  if (modePreset && schemaPath) {
+    writeOutput(JSON.stringify(modePreset.schema, null, 2), schemaPath);
+  }
+
+  const resolved = resolveExecutable(AGENT_CANDIDATES[agent]);
+  if (!resolved) {
+    fail(`Could not find a local ${agent} CLI on PATH. Run "repolens doctor" to inspect availability.`);
+  }
+
+  const runSpec = buildRunSpec({
+    agent,
+    cwd: repoRoot,
+    model: options.flags.model,
+    json: Boolean(options.flags.json),
+    allowEdit: Boolean(options.flags["allow-edit"]),
+    outputPath: structuredResultPath,
+    schemaPath,
+    codexLastMessagePath,
+    extraArgs: options.positionals,
+  });
+
+  if (options.flags["dry-run"]) {
+    process.stdout.write(`${resolved.name} ${runSpec.args.join(" ")}\n`);
+    if (resolvedPublishBoardId && publishKind) {
+      process.stdout.write(`Would publish structured result to board ${resolvedPublishBoardId} as ${publishKind}\n`);
+    }
+    return;
+  }
+
+  const rawOutput = await executeAgentRun({
+    command: resolved.name,
+    args: runSpec.args,
+    cwd: repoRoot,
+    prompt: packet,
+    outputPath: runSpec.outputPath,
+  });
+
+  if (!modePreset) {
+    return;
+  }
+
+  const rawContent = agent === "codex"
+    ? fs.readFileSync(codexLastMessagePath, "utf8")
+    : rawOutput;
+  const structured = parseStructuredJson(rawContent);
+  validateStructuredOutput(modePreset.schema, structured);
+
+  const envelope = {
+    type: "repolens-run",
+    version: 1,
+    mode,
+    agent,
+    audience,
+    generatedAt: snapshot.generatedAt,
+    repoRoot,
+    task,
+    packetPath: packetOutputPath,
+    schemaPath,
+    compare: snapshot.compare
+      ? {
+          base: snapshot.compare.base,
+          head: snapshot.compare.head,
+        }
+      : null,
+    result: structured,
+  };
+
+  writeOutput(JSON.stringify(envelope, null, 2), structuredResultPath);
+
+  if (resolvedPublishBoardId && publishKind) {
+    const publishResult = await publishEnvelope({
+      boardId: resolvedPublishBoardId,
+      publishKind,
+      audience,
+      userId: options.flags["user-id"] ?? null,
+      envelope,
+    });
+    process.stdout.write(`${JSON.stringify(publishResult, null, 2)}\n`);
+  }
+}
+
+async function handlePublish(args) {
+  const options = parseFlags(args, {
+    string: new Set(["input", "board-id", "publish-as", "audience", "user-id"]),
+    boolean: new Set(["dry-run", "json"]),
+  });
+
+  const inputPath = options.flags.input;
+  const linkedBoard = loadRepoLink(process.cwd());
+  const boardId = options.flags["board-id"] ?? linkedBoard?.boardId ?? null;
+  if (!inputPath || !boardId) {
+    fail(
+      "Usage: repolens publish --input FILE [--board-id UUID] [--publish-as feature|onboarding|change-brief] [--audience VALUE] [--user-id UUID] [--dry-run] [--json]"
+    );
+  }
+
+  const envelope = parseStructuredJson(fs.readFileSync(path.resolve(inputPath), "utf8"));
+  const publishKind = normalizePublishKind(options.flags["publish-as"] ?? defaultPublishKindForMode(envelope.mode ?? null));
+  if (!publishKind) {
+    fail(
+      "Could not infer a publish target from this run artifact. Use --publish-as feature, onboarding, or change-brief."
+    );
+  }
+
+  const audience = normalizeAudience(options.flags.audience ?? envelope.audience ?? null, publishKind);
+
+  if (options.flags["dry-run"]) {
+    const preview = buildPublishPreview({
+      boardId,
+      publishKind,
+      audience,
+      userId: options.flags["user-id"] ?? null,
+      envelope,
+    });
+    if (options.flags.json) {
+      process.stdout.write(`${JSON.stringify(preview, null, 2)}\n`);
+      return;
+    }
+
+    process.stdout.write(`Would publish ${publishKind} to board ${boardId}\n`);
+    process.stdout.write(`${JSON.stringify(preview, null, 2)}\n`);
+    return;
+  }
+
+  const result = await publishEnvelope({
+    boardId,
+    publishKind,
+    audience,
+    userId: options.flags["user-id"] ?? null,
+    envelope,
+  });
+
+  if (options.flags.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+
+  process.stdout.write(`Published ${publishKind} to board ${boardId}\n`);
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+function parseFlags(args, schema) {
+  const flags = {};
+  const positionals = [];
+  let index = 0;
+  let afterDoubleDash = false;
+
+  while (index < args.length) {
+    const token = args[index];
+
+    if (afterDoubleDash) {
+      positionals.push(token);
+      index += 1;
+      continue;
+    }
+
+    if (token === "--") {
+      afterDoubleDash = true;
+      index += 1;
+      continue;
+    }
+
+    if (token.startsWith("--")) {
+      const name = token.slice(2);
+      if (schema.boolean && schema.boolean.has(name)) {
+        flags[name] = true;
+        index += 1;
+        continue;
+      }
+
+      if (schema.string && schema.string.has(name)) {
+        const value = args[index + 1];
+        if (!value || value.startsWith("--")) {
+          fail(`Flag --${name} requires a value.`);
+        }
+        flags[name] = value;
+        index += 2;
+        continue;
+      }
+
+      fail(`Unknown flag "${token}"`);
+    }
+
+    positionals.push(token);
+    index += 1;
+  }
+
+  return { flags, positionals };
+}
+
+function loadLocalEnv(cwd) {
+  const repoRoot = findGitRoot(cwd) ?? cwd;
+  const candidates = [
+    path.join(repoRoot, ".env.local"),
+    path.join(repoRoot, ".env"),
+    path.join(repoRoot, "env"),
+  ];
+
+  for (const filePath of candidates) {
+    if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) {
+      continue;
+    }
+
+    const content = fs.readFileSync(filePath, "utf8");
+    for (const line of content.split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) {
+        continue;
+      }
+
+      const match = trimmed.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+      if (!match) {
+        continue;
+      }
+
+      const [, key, rawValue] = match;
+      if (Object.prototype.hasOwnProperty.call(process.env, key)) {
+        continue;
+      }
+
+      process.env[key] = parseEnvValue(rawValue);
+    }
+  }
+}
+
+function parseEnvValue(rawValue) {
+  let value = rawValue.trim();
+  if (!value) {
+    return "";
+  }
+
+  if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+    value = value.slice(1, -1);
+  } else {
+    const commentIndex = value.indexOf(" #");
+    if (commentIndex >= 0) {
+      value = value.slice(0, commentIndex).trimEnd();
+    }
+  }
+
+  return value.replaceAll("\\n", "\n");
+}
+
+function getCliConfigDir() {
+  const configured = process.env.REPOLENS_CONFIG_HOME;
+  if (configured) {
+    return path.resolve(configured);
+  }
+
+  return path.join(os.homedir(), ".repolens");
+}
+
+function getCliAuthConfigPath() {
+  return path.join(getCliConfigDir(), "auth.json");
+}
+
+function loadCliAuthConfig() {
+  const configPath = getCliAuthConfigPath();
+  if (!fs.existsSync(configPath)) {
+    return null;
+  }
+
+  try {
+    const parsed = normalizeStoredCliAuthConfig(JSON.parse(fs.readFileSync(configPath, "utf8")));
+    if (!parsed) {
+      return null;
+    }
+
+    if (parsed.tokenStore?.type === "keychain" && parsed.tokenStore.service && parsed.tokenStore.account) {
+      const keychainToken = loadTokenFromKeychain(parsed.tokenStore.service, parsed.tokenStore.account);
+      if (keychainToken) {
+        return {
+          ...parsed,
+          token: keychainToken,
+        };
+      }
+    }
+
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function requireCliAuthConfig() {
+  const config = loadCliAuthConfig();
+  if (!config?.appUrl || !config?.token) {
+    fail("RepoLens CLI is not connected. Create a CLI token in Settings, then run `repolens login --app-url <url>`.");
+  }
+
+  return config;
+}
+
+function saveCliAuthConfig(config) {
+  const configPath = getCliAuthConfigPath();
+  fs.mkdirSync(path.dirname(configPath), { recursive: true, mode: 0o700 });
+
+  const descriptor = shouldUseKeychainForCliAuth()
+    ? buildCliKeychainDescriptor(config.appUrl, config.user?.email ?? null)
+    : null;
+
+  if (descriptor && saveTokenToKeychain(descriptor.service, descriptor.account, config.token)) {
+    const metadata = {
+      ...config,
+      token: null,
+      tokenStore: {
+        type: "keychain",
+        service: descriptor.service,
+        account: descriptor.account,
+      },
+    };
+    fs.writeFileSync(configPath, `${JSON.stringify(metadata, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    return;
+  }
+
+  fs.writeFileSync(`${configPath}`, `${JSON.stringify({
+    ...config,
+    tokenStore: {
+      type: "file",
+    },
+  }, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+}
+
+function deleteCliAuthConfig() {
+  const configPath = getCliAuthConfigPath();
+  const config = loadCliAuthConfig();
+  if (config?.tokenStore?.type === "keychain" && config.tokenStore.service && config.tokenStore.account) {
+    deleteTokenFromKeychain(config.tokenStore.service, config.tokenStore.account);
+  }
+  if (fs.existsSync(configPath)) {
+    fs.unlinkSync(configPath);
+  }
+}
+
+function shouldUseKeychainForCliAuth() {
+  if (process.env.REPOLENS_DISABLE_KEYCHAIN === "1") {
+    return false;
+  }
+
+  return process.platform === "darwin" && Boolean(resolveSecurityExecutable());
+}
+
+function resolveSecurityExecutable() {
+  return fs.existsSync("/usr/bin/security") ? "/usr/bin/security" : null;
+}
+
+function loadTokenFromKeychain(service, account) {
+  const securityPath = resolveSecurityExecutable();
+  if (!securityPath) {
+    return null;
+  }
+
+  const result = spawnSync(securityPath, [
+    "find-generic-password",
+    "-a",
+    account,
+    "-s",
+    service,
+    "-w",
+  ], {
+    encoding: "utf8",
+  });
+
+  if (result.status !== 0) {
+    return null;
+  }
+
+  const token = result.stdout?.trim() ?? "";
+  return token || null;
+}
+
+function saveTokenToKeychain(service, account, token) {
+  const securityPath = resolveSecurityExecutable();
+  if (!securityPath || !token) {
+    return false;
+  }
+
+  const result = spawnSync(securityPath, [
+    "add-generic-password",
+    "-U",
+    "-a",
+    account,
+    "-s",
+    service,
+    "-w",
+    token,
+  ], {
+    encoding: "utf8",
+  });
+
+  return result.status === 0;
+}
+
+function deleteTokenFromKeychain(service, account) {
+  const securityPath = resolveSecurityExecutable();
+  if (!securityPath) {
+    return;
+  }
+
+  spawnSync(securityPath, [
+    "delete-generic-password",
+    "-a",
+    account,
+    "-s",
+    service,
+  ], {
+    encoding: "utf8",
+  });
+}
+
+function getBoardLinkIndexPath() {
+  return path.join(getCliConfigDir(), "linked-boards.json");
+}
+
+function loadBoardLinkIndex() {
+  const indexPath = getBoardLinkIndexPath();
+  if (!fs.existsSync(indexPath)) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(indexPath, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function saveBoardLinkIndex(index) {
+  const indexPath = getBoardLinkIndexPath();
+  fs.mkdirSync(path.dirname(indexPath), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(indexPath, `${JSON.stringify(index, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+}
+
+function registerBoardLink(repoRoot, link, previousBoardId = null) {
+  const index = loadBoardLinkIndex();
+
+  if (previousBoardId && index[previousBoardId]?.repoRoot === repoRoot) {
+    delete index[previousBoardId];
+  }
+
+  index[link.boardId] = {
+    repoRoot,
+    boardName: link.boardName ?? null,
+    appUrl: link.appUrl ?? null,
+    linkedAt: link.linkedAt ?? new Date().toISOString(),
+  };
+
+  saveBoardLinkIndex(index);
+}
+
+function resolveLinkedRepoRootForBoard(boardId) {
+  const index = loadBoardLinkIndex();
+  const entry = index[boardId];
+  if (!entry?.repoRoot) {
+    return null;
+  }
+
+  if (!fs.existsSync(entry.repoRoot) || !fs.statSync(entry.repoRoot).isDirectory()) {
+    delete index[boardId];
+    saveBoardLinkIndex(index);
+    return null;
+  }
+
+  return entry.repoRoot;
+}
+
+function getRepoLinkPath(cwd) {
+  const repoRoot = findGitRoot(cwd);
+  if (!repoRoot) {
+    return null;
+  }
+
+  return path.join(repoRoot, ".repolens", "link.json");
+}
+
+function loadRepoLink(cwd) {
+  const linkPath = getRepoLinkPath(cwd);
+  if (!linkPath || !fs.existsSync(linkPath)) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(linkPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function saveRepoLink(repoRoot, link) {
+  const linkPath = path.join(repoRoot, ".repolens", "link.json");
+  fs.mkdirSync(path.dirname(linkPath), { recursive: true });
+  fs.writeFileSync(linkPath, `${JSON.stringify(link, null, 2)}\n`, "utf8");
+}
+
+function getProtocolInstallDescriptor() {
+  if (process.platform === "darwin") {
+    const configured = process.env.REPOLENS_PROTOCOL_APP_PATH;
+    const appBundlePath = configured
+      ? path.resolve(configured)
+      : path.join(os.homedir(), "Applications", "RepoLens Launcher.app");
+
+    return {
+      supported: true,
+      platform: "darwin",
+      installPath: appBundlePath,
+      appBundlePath,
+    };
+  }
+
+  if (process.platform === "linux") {
+    const configured = process.env.REPOLENS_PROTOCOL_DESKTOP_PATH;
+    const desktopEntryPath = configured
+      ? path.resolve(configured)
+      : path.join(os.homedir(), ".local", "share", "applications", "repolens-launcher.desktop");
+    const launcherPath = path.join(getCliConfigDir(), "repolens-url-handler");
+
+    return {
+      supported: true,
+      platform: "linux",
+      installPath: desktopEntryPath,
+      desktopEntryPath,
+      launcherPath,
+    };
+  }
+
+  if (process.platform === "win32") {
+    const launcherPath = path.join(getCliConfigDir(), "repolens-url-handler.cmd");
+
+    return {
+      supported: true,
+      platform: "win32",
+      installPath: launcherPath,
+      launcherPath,
+      registryRoot: "HKCU\\Software\\Classes\\repolens-cli",
+    };
+  }
+
+  return {
+    supported: false,
+    platform: process.platform,
+    installPath: null,
+  };
+}
+
+function isProtocolHandlerInstalled() {
+  const descriptor = getProtocolInstallDescriptor();
+  if (!descriptor.supported) {
+    return false;
+  }
+
+  if (descriptor.platform === "darwin") {
+    return fs.existsSync(descriptor.appBundlePath);
+  }
+
+  if (descriptor.platform === "linux") {
+    return fs.existsSync(descriptor.desktopEntryPath) && fs.existsSync(descriptor.launcherPath);
+  }
+
+  if (descriptor.platform === "win32") {
+    return fs.existsSync(descriptor.launcherPath);
+  }
+
+  return false;
+}
+
+function ensureProtocolHandlerInstalled() {
+  if (process.env.REPOLENS_SKIP_PROTOCOL_INSTALL === "1") {
+    return false;
+  }
+
+  const descriptor = getProtocolInstallDescriptor();
+  if (!descriptor.supported || isProtocolHandlerInstalled()) {
+    return false;
+  }
+
+  installProtocolHandler();
+  return true;
+}
+
+function escapeDesktopExecValue(value) {
+  return String(value)
+    .replaceAll("\\", "\\\\")
+    .replaceAll(" ", "\\ ");
+}
+
+function installProtocolHandler() {
+  const cliEntrypoint = fs.realpathSync(process.argv[1]);
+  const nodePath = process.execPath;
+  const descriptor = getProtocolInstallDescriptor();
+
+  if (!descriptor.supported) {
+    throw new Error(`Protocol installation is not supported on ${process.platform}.`);
+  }
+
+  if (descriptor.platform === "darwin") {
+    const contentsPath = path.join(descriptor.appBundlePath, "Contents");
+    const macOsPath = path.join(contentsPath, "MacOS");
+    const executablePath = path.join(macOsPath, "repolens-url-handler");
+    const infoPlistPath = path.join(contentsPath, "Info.plist");
+
+    fs.mkdirSync(macOsPath, { recursive: true });
+
+    const infoPlist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleDisplayName</key>
+  <string>RepoLens Launcher</string>
+  <key>CFBundleExecutable</key>
+  <string>repolens-url-handler</string>
+  <key>CFBundleIdentifier</key>
+  <string>com.repolens.launcher</string>
+  <key>CFBundleName</key>
+  <string>RepoLens Launcher</string>
+  <key>CFBundlePackageType</key>
+  <string>APPL</string>
+  <key>CFBundleShortVersionString</key>
+  <string>0.1.1</string>
+  <key>CFBundleVersion</key>
+  <string>1</string>
+  <key>CFBundleURLTypes</key>
+  <array>
+    <dict>
+      <key>CFBundleURLName</key>
+      <string>RepoLens Launcher</string>
+      <key>CFBundleURLSchemes</key>
+      <array>
+        <string>repolens-cli</string>
+      </array>
+    </dict>
+  </array>
+  <key>LSUIElement</key>
+  <true/>
+</dict>
+</plist>
+`;
+
+    const launcherScript = `#!/bin/zsh
+exec ${shellEscape(nodePath)} ${shellEscape(cliEntrypoint)} handle-url "$1"
+`;
+
+    fs.writeFileSync(infoPlistPath, infoPlist, "utf8");
+    fs.writeFileSync(executablePath, launcherScript, { encoding: "utf8", mode: 0o755 });
+    fs.chmodSync(executablePath, 0o755);
+
+    const lsregister = "/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister";
+    if (fs.existsSync(lsregister)) {
+      spawnSync(lsregister, ["-f", descriptor.appBundlePath], { encoding: "utf8" });
+    }
+
+    return descriptor;
+  }
+
+  if (descriptor.platform === "linux") {
+    fs.mkdirSync(path.dirname(descriptor.launcherPath), { recursive: true, mode: 0o700 });
+    fs.mkdirSync(path.dirname(descriptor.desktopEntryPath), { recursive: true, mode: 0o755 });
+
+    const launcherScript = `#!/bin/sh
+exec ${shellEscape(nodePath)} ${shellEscape(cliEntrypoint)} handle-url "$1"
+`;
+
+    fs.writeFileSync(descriptor.launcherPath, launcherScript, { encoding: "utf8", mode: 0o755 });
+    fs.chmodSync(descriptor.launcherPath, 0o755);
+    fs.writeFileSync(
+      descriptor.desktopEntryPath,
+      buildLinuxDesktopEntry({
+        scriptPath: escapeDesktopExecValue(descriptor.launcherPath),
+      }),
+      "utf8"
+    );
+
+    const xdgMime = resolveOnPath("xdg-mime");
+    if (xdgMime) {
+      spawnSync(xdgMime.name, ["default", path.basename(descriptor.desktopEntryPath), "x-scheme-handler/repolens-cli"], {
+        encoding: "utf8",
+      });
+    }
+
+    return descriptor;
+  }
+
+  if (descriptor.platform === "win32") {
+    fs.mkdirSync(path.dirname(descriptor.launcherPath), { recursive: true, mode: 0o700 });
+    const launcherScript = `@echo off
+${JSON.stringify(nodePath)} ${JSON.stringify(cliEntrypoint)} handle-url %1
+`;
+
+    fs.writeFileSync(descriptor.launcherPath, launcherScript, { encoding: "utf8" });
+
+    const commandValue = `\\"${descriptor.launcherPath}\\" \\"%1\\"`;
+    const registryCommands = [
+      ["add", descriptor.registryRoot, "/ve", "/d", "URL:RepoLens CLI Protocol", "/f"],
+      ["add", descriptor.registryRoot, "/v", "URL Protocol", "/d", "", "/f"],
+      ["add", `${descriptor.registryRoot}\\shell\\open\\command`, "/ve", "/d", commandValue, "/f"],
+    ];
+
+    for (const args of registryCommands) {
+      const result = spawnSync("reg", args, { encoding: "utf8" });
+      if (result.status !== 0) {
+        const stderr = result.stderr?.trim() || result.stdout?.trim() || "Failed to update Windows protocol registry.";
+        throw new Error(stderr);
+      }
+    }
+
+    return descriptor;
+  }
+}
+
+function normalizeAppUrl(value) {
+  if (!value) {
+    return null;
+  }
+
+  try {
+    const url = new URL(value);
+    url.pathname = "";
+    url.search = "";
+    url.hash = "";
+    return url.toString().replace(/\/$/, "");
+  } catch {
+    return null;
+  }
+}
+
+async function callCliApi(params) {
+  const url = new URL(params.pathname, `${params.appUrl}/`);
+  const headers = {
+    authorization: `Bearer ${params.token}`,
+    connection: "close",
+    ...(params.body ? { "content-type": "application/json" } : {}),
+  };
+
+  return await fetch(url, {
+    method: params.method,
+    headers,
+    body: params.body ? JSON.stringify(params.body) : undefined,
+  });
+}
+
+async function verifyCliTokenLogin(appUrl, token) {
+  const response = await callCliApi({
+    appUrl,
+    token,
+    pathname: "/api/cli/me",
+    method: "GET",
+  });
+
+  const payload = await parseApiJson(response);
+  if (!response.ok) {
+    fail(payload.error ?? `Login failed with status ${response.status}.`);
+  }
+
+  return {
+    token,
+    user: payload.user ?? null,
+  };
+}
+
+async function loginWithBrowserFlow(appUrl, options) {
+  const response = await fetch(new URL("/api/cli/login/request", `${appUrl}/`), {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      Connection: "close",
+    },
+    body: JSON.stringify({
+      label: options.label,
+      appUrl,
+    }),
+  });
+
+  const payload = await parseApiJson(response);
+  if (!response.ok) {
+    fail(payload.error ?? `Browser login failed with status ${response.status}.`);
+  }
+
+  const verificationUrl = typeof payload.verificationUrl === "string" ? payload.verificationUrl : null;
+  const requestId = typeof payload.requestId === "string" ? payload.requestId : null;
+  const pollToken = typeof payload.pollToken === "string" ? payload.pollToken : null;
+  const intervalMs = typeof payload.intervalMs === "number" ? payload.intervalMs : 2000;
+  const expiresAt = typeof payload.expiresAt === "string" ? Date.parse(payload.expiresAt) : NaN;
+
+  if (!verificationUrl || !requestId || !pollToken) {
+    fail("CLI login request response was incomplete.");
+  }
+
+  if (!options.json) {
+    process.stdout.write("Approve RepoLens CLI login in your browser.\n");
+    process.stdout.write(`Verification code: ${payload.verificationCode}\n`);
+    process.stdout.write(`Open: ${verificationUrl}\n`);
+  }
+
+  if (!options.noBrowser) {
+    const browserOpened = openBrowser(verificationUrl);
+    if (!browserOpened) {
+      await reportCliEvent({
+        action: "cli_login.browser_open_failed",
+        metadata: {
+          platform: process.platform,
+          verificationUrl,
+        },
+      });
+      process.stderr.write("Could not open your browser automatically. Open the verification URL manually.\n");
+    }
+  }
+
+  while (true) {
+    if (!Number.isNaN(expiresAt) && Date.now() >= expiresAt) {
+      fail("CLI login request expired before approval completed.");
+    }
+
+    await sleep(intervalMs);
+
+    const pollResponse = await fetch(new URL("/api/cli/login/poll", `${appUrl}/`), {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        Connection: "close",
+      },
+      body: JSON.stringify({
+        requestId,
+        pollToken,
+      }),
+    });
+
+    const pollPayload = await parseApiJson(pollResponse);
+    if (!pollResponse.ok && pollResponse.status !== 410) {
+      fail(pollPayload.error ?? `CLI login poll failed with status ${pollResponse.status}.`);
+    }
+
+    if (pollPayload.status === "pending") {
+      continue;
+    }
+
+    if (pollPayload.status === "expired") {
+      fail("CLI login request expired before approval completed.");
+    }
+
+    if (pollPayload.status !== "approved" || typeof pollPayload.token !== "string") {
+      fail("CLI login did not complete successfully.");
+    }
+
+    return await verifyCliTokenLogin(appUrl, pollPayload.token);
+  }
+}
+
+async function parseApiJson(response) {
+  try {
+    return await response.json();
+  } catch {
+    return {};
+  }
+}
+
+function findGitRoot(cwd) {
+  const result = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+    cwd,
+    encoding: "utf8",
+  });
+
+  if (result.status !== 0) {
+    return null;
+  }
+
+  return result.stdout.trim() || null;
+}
+
+function defaultCliLoginLabel() {
+  return `${os.hostname()} terminal`;
+}
+
+function openBrowser(url) {
+  const commands = process.platform === "darwin"
+    ? [["open", [url]]]
+    : process.platform === "win32"
+      ? [["cmd.exe", ["/c", "start", "", url]]]
+      : [["xdg-open", [url]]];
+
+  for (const [command, args] of commands) {
+    const result = spawnSync(command, args, {
+      encoding: "utf8",
+    });
+
+    if (result.status === 0) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function resolveExecutable(candidates) {
+  for (const candidate of candidates) {
+    const result = resolveOnPath(candidate);
+    if (result) {
+      return result;
+    }
+  }
+
+  return null;
+}
+
+function resolveOnPath(command) {
+  const locator = process.platform === "win32" ? "where" : "which";
+  const result = spawnSync(locator, [command], {
+    encoding: "utf8",
+  });
+
+  if (result.status !== 0) {
+    return null;
+  }
+
+  const resolvedPath = lines(result.stdout)[0] ?? null;
+  if (!resolvedPath) {
+    return null;
+  }
+
+  return {
+    name: command,
+    path: resolvedPath,
+  };
+}
+
+function shellEscape(value) {
+  return `'${String(value).replaceAll("'", `'\"'\"'`)}'`;
+}
+
+function createTempProtocolLaunchScript(extension, content, mode = 0o700) {
+  const tempDir = path.join(os.tmpdir(), "repolens-launch");
+  fs.mkdirSync(tempDir, { recursive: true, mode: 0o700 });
+  const scriptPath = path.join(tempDir, `launch-${Date.now()}-${Math.random().toString(36).slice(2)}.${extension}`);
+  fs.writeFileSync(scriptPath, content, { encoding: "utf8", mode });
+  if (mode) {
+    fs.chmodSync(scriptPath, mode);
+  }
+  return scriptPath;
+}
+
+function openTerminalForProtocolCommand({ command, repoRoot, source }) {
+  const cliEntrypoint = fs.realpathSync(process.argv[1]);
+  if (process.platform === "darwin") {
+    const script = buildTerminalLaunchScript({
+      command,
+      cliEntrypoint,
+      nodePath: process.execPath,
+      repoRoot,
+      source,
+    });
+
+    const appleScript = [
+      'tell application "Terminal"',
+      "  activate",
+      `  do script ${JSON.stringify(`/bin/zsh -lc ${shellEscape(script)}`)}`,
+      "end tell",
+    ].join("\n");
+
+    const result = spawnSync("/usr/bin/osascript", ["-e", appleScript], {
+      encoding: "utf8",
+    });
+
+    if (result.status !== 0) {
+      const stderr = result.stderr ? result.stderr.trim() : "";
+      throw new Error(stderr || "Failed to open Terminal for RepoLens launch.");
+    }
+    return;
+  }
+
+  if (process.platform === "linux") {
+    const scriptPath = createTempProtocolLaunchScript("sh", `#!/bin/bash
+${buildTerminalLaunchScript({
+  command,
+  cliEntrypoint,
+  nodePath: process.execPath,
+  repoRoot,
+  source,
+})}
+`);
+    const terminalCandidates = [
+      ["x-terminal-emulator", ["-e", "/bin/bash", scriptPath]],
+      ["gnome-terminal", ["--", "/bin/bash", scriptPath]],
+      ["konsole", ["-e", "/bin/bash", scriptPath]],
+      ["xterm", ["-e", "/bin/bash", scriptPath]],
+    ];
+
+    for (const [binary, args] of terminalCandidates) {
+      const resolved = resolveOnPath(binary);
+      if (!resolved) {
+        continue;
+      }
+
+      const result = spawnSync(resolved.name, args, {
+        encoding: "utf8",
+      });
+
+      if (result.status === 0) {
+        return;
+      }
+    }
+
+    throw new Error("Failed to open a Linux terminal for RepoLens launch. Install a supported terminal emulator or copy the command manually.");
+  }
+
+  if (process.platform === "win32") {
+    const scriptPath = createTempProtocolLaunchScript("cmd", buildWindowsTerminalLaunchScript({
+      command,
+      cliEntrypoint,
+      nodePath: process.execPath,
+      repoRoot,
+      source,
+    }), 0o600);
+    const result = spawnSync("cmd.exe", ["/c", "start", "", "cmd.exe", "/k", scriptPath], {
+      encoding: "utf8",
+    });
+
+    if (result.status !== 0) {
+      const stderr = result.stderr ? result.stderr.trim() : "";
+      throw new Error(stderr || "Failed to open Windows Terminal for RepoLens launch.");
+    }
+    return;
+  }
+
+  throw new Error(`Protocol launch is not supported on ${process.platform}.`);
+}
+
+function runCommand(command, args, spawnOptions, runtimeOptions = {}) {
+  const result = spawnSync(command, args, {
+    ...spawnOptions,
+    encoding: "utf8",
+  });
+
+  if (result.status !== 0 && !runtimeOptions.allowFailure) {
+    const stderr = result.stderr ? result.stderr.trim() : "";
+    fail(stderr || `Command failed: ${command} ${args.join(" ")}`);
+  }
+
+  return result.stdout ?? "";
+}
+
+function rankPaths(paths) {
+  return paths
+    .map((filePath) => ({
+      filePath,
+      score: scorePath(filePath),
+    }))
+    .sort((left, right) => {
+      if (right.score !== left.score) {
+        return right.score - left.score;
+      }
+      return left.filePath.localeCompare(right.filePath);
+    })
+    .map((entry) => entry.filePath);
+}
+
+function scorePath(filePath) {
+  const normalized = filePath.toLowerCase();
+  let score = 0;
+
+  if (normalized === "package.json" || normalized.endsWith("/package.json")) score += 400;
+  if (normalized === "readme.md" || normalized.endsWith("/readme.md")) score += 320;
+  if (/(^|\/)(app|pages)\/.+(page|layout|route)\.(t|j)sx?$/.test(normalized)) score += 280;
+  if (/(^|\/)(index|main|server|client)\.(t|j)sx?$/.test(normalized)) score += 260;
+  if (/(^|\/)(api|routes|controllers?)\//.test(normalized)) score += 220;
+  if (/(^|\/)(services?|use-cases?|usecases?|core|lib)\//.test(normalized)) score += 180;
+  if (/(^|\/)(models?|entities?|schema|schemas|prisma|db)\//.test(normalized)) score += 170;
+  if (/(^|\/)(components?|views?|screens?)\//.test(normalized)) score += 140;
+  if (normalized.startsWith("src/")) score += 80;
+  if (/\.(ts|tsx|js|jsx|py|go|rs|java|rb|php|cs|swift)$/.test(normalized)) score += 40;
+  if (/(^|\/)(tests?|specs?|__tests__|stories|fixtures|mocks?)\//.test(normalized)) score -= 120;
+  if (/(^|\/)(docs|examples?)\//.test(normalized)) score -= 80;
+  score -= Math.floor(filePath.length / 10);
+
+  return score;
+}
+
+function buildContextMarkdown(payload) {
+  const sections = [
+    "# RepoLens Context Pack",
+    "",
+    `- Repo root: \`${payload.repoRoot}\``,
+    `- Branch: \`${payload.branch}\``,
+    `- Generated at: ${payload.generatedAt}`,
+    "",
+    "## Recent Commits",
+    payload.recentCommits.length > 0
+      ? payload.recentCommits.map((line) => `- ${line}`).join("\n")
+      : "- No commits found.",
+    "",
+    "## Working Tree",
+    payload.status.length > 0
+      ? payload.status.map((line) => `- \`${line}\``).join("\n")
+      : "- Clean working tree.",
+    "",
+    "## Top Files",
+    payload.topFiles.length > 0
+      ? payload.topFiles.map((line) => `- \`${line}\``).join("\n")
+      : "- No tracked files found.",
+  ];
+
+  if (payload.compare) {
+    sections.push(
+      "",
+      `## Compare ${payload.compare.base}..${payload.compare.head}`,
+      payload.compare.diffSummary.length > 0
+        ? payload.compare.diffSummary.map((line) => `- ${line}`).join("\n")
+        : "- No diff summary available.",
+      "",
+      "### Changed Files",
+      payload.compare.changedFiles.length > 0
+        ? payload.compare.changedFiles.map((line) => `- \`${line}\``).join("\n")
+        : "- No changed files found."
+    );
+  }
+
+  sections.push(
+    "",
+    "## Suggested Agent Handoff",
+    "- Use this pack as a local briefing artifact for `codex` or `claude`.",
+    "- Re-run with `repolens context --base <ref> --head <ref>` before change-brief style tasks.",
+    "- Use `repolens delegate <agent> -- --help` to inspect the local agent CLI contract."
+  );
+
+  return `${sections.join("\n")}\n`;
+}
+
+function buildBriefMarkdown(payload) {
+  const compare = payload.compare;
+  const sections = [
+    "# RepoLens Change Brief Pack",
+    "",
+    `- Repo root: \`${payload.repoRoot}\``,
+    `- Branch: \`${payload.branch}\``,
+    `- Generated at: ${payload.generatedAt}`,
+    compare ? `- Compare: \`${compare.base}..${compare.head}\`` : null,
+    "",
+    "## Commit Range",
+    compare && compare.rangeCommits.length > 0
+      ? compare.rangeCommits.map((line) => `- ${line}`).join("\n")
+      : "- No commit range summary available.",
+    "",
+    "## Diff Summary",
+    compare && compare.diffSummary.length > 0
+      ? compare.diffSummary.map((line) => `- ${line}`).join("\n")
+      : "- No diff summary available.",
+    "",
+    "## Changed Files",
+    compare && compare.changedFiles.length > 0
+      ? compare.changedFiles.map((line) => `- \`${line}\``).join("\n")
+      : "- No changed files found.",
+    "",
+    "## Architectural Context",
+    payload.topFiles.length > 0
+      ? payload.topFiles.slice(0, 20).map((line) => `- \`${line}\``).join("\n")
+      : "- No ranked files found.",
+    "",
+    "## Working Tree",
+    payload.status.length > 0
+      ? payload.status.map((line) => `- \`${line}\``).join("\n")
+      : "- Clean working tree.",
+  ].filter(Boolean);
+
+  return `${sections.join("\n")}\n`;
+}
+
+function buildRunPacket(params) {
+  const compare = params.snapshot.compare;
+  const modePreset = params.mode ? RUN_MODE_PRESETS[params.mode] : null;
+  const sections = [
+    "# RepoLens Agent Task Packet",
+    "",
+    `Agent target: ${params.agent}`,
+    params.mode ? `Structured mode: ${params.mode}` : null,
+    modePreset ? `Mode intent: ${modePreset.description}` : null,
+    params.audience ? `Requested audience: ${params.audience}` : null,
+    `Repo root: ${params.snapshot.repoRoot}`,
+    `Current branch: ${params.snapshot.branch}`,
+    `Generated at: ${params.snapshot.generatedAt}`,
+    "",
+    "## Task",
+    params.task.trim(),
+    "",
+    "## Execution Mode",
+    params.allowEdit
+      ? "- You may modify files if the task requires it. Prefer minimal, well-scoped changes."
+      : "- Analyze only. Do not modify files. Focus on findings, plan, and exact recommendations.",
+    "",
+    "## Recent Commits",
+    params.snapshot.recentCommits.length > 0
+      ? params.snapshot.recentCommits.map((line) => `- ${line}`).join("\n")
+      : "- No recent commits found.",
+    "",
+    "## Working Tree",
+    params.snapshot.status.length > 0
+      ? params.snapshot.status.map((line) => `- \`${line}\``).join("\n")
+      : "- Clean working tree.",
+    "",
+    "## Top Files",
+    params.snapshot.topFiles.length > 0
+      ? params.snapshot.topFiles.slice(0, 25).map((line) => `- \`${line}\``).join("\n")
+      : "- No ranked files found.",
+  ];
+
+  if (compare) {
+    sections.push(
+      "",
+      `## Compare ${compare.base}..${compare.head}`,
+      compare.rangeCommits.length > 0
+        ? compare.rangeCommits.map((line) => `- ${line}`).join("\n")
+        : "- No commit range summary available.",
+      "",
+      "### Diff Summary",
+      compare.diffSummary.length > 0
+        ? compare.diffSummary.map((line) => `- ${line}`).join("\n")
+        : "- No diff summary available.",
+      "",
+      "### Changed Files",
+      compare.changedFiles.length > 0
+        ? compare.changedFiles.map((line) => `- \`${line}\``).join("\n")
+        : "- No changed files found."
+    );
+  }
+
+  if (params.historyAppendix) {
+    sections.push("", "## History Context", params.historyAppendix.trim());
+  }
+
+  if (params.contextAppendix) {
+    sections.push("", "## Additional Context", params.contextAppendix.trim());
+  }
+
+  sections.push(
+    "",
+    "## Response Requirements",
+    params.allowEdit
+      ? "- Describe intended changes briefly, then execute them."
+      : "- Return analysis only.",
+    modePreset
+      ? `- Respond with JSON only. Match the ${params.mode} schema exactly.`
+      : "- Use a compact structure that is easy to scan.",
+    "- Ground claims in specific files, commits, or diff evidence where possible.",
+    "- Call out uncertainty instead of inferring silently."
+  );
+
+  if (modePreset) {
+    sections.push("", "## Structured Output Shape", "```json", JSON.stringify(modePreset.schema, null, 2), "```");
+  }
+
+  return `${sections.filter(Boolean).join("\n")}\n`;
+}
+
+function writeOutput(content, outputPath) {
+  if (!outputPath) {
+    process.stdout.write(content.endsWith("\n") ? content : `${content}\n`);
+    return;
+  }
+
+  const absolutePath = path.resolve(outputPath);
+  fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+  fs.writeFileSync(absolutePath, content.endsWith(os.EOL) ? content : `${content}${os.EOL}`, "utf8");
+  process.stdout.write(`Wrote ${absolutePath}\n`);
+}
+
+function lines(value) {
+  return value
+    .split(/\r?\n/)
+    .map((line) => line.trimEnd())
+    .filter(Boolean);
+}
+
+function printHelp() {
+  process.stdout.write(`RepoLens CLI
+
+Usage:
+  repolens doctor [--json]
+  repolens login --app-url URL [--label LABEL] [--no-browser] [--token TOKEN] [--json]
+  repolens logout [--json]
+  repolens whoami [--json]
+  repolens boards [--json]
+  repolens link --board-id UUID [--json]
+  repolens install-protocol [--json]
+  repolens handle-url URL
+  repolens brief --base REF --head REF [--cwd PATH] [--output FILE] [--json]
+  repolens evolution --path PATH [--cwd PATH] [--since REF] [--limit N] [--output FILE] [--json] [--publish-board-id UUID] [--dry-run]
+  repolens hotspots [--cwd PATH] [--since REF] [--limit N] [--output FILE] [--json] [--publish-board-id UUID] [--dry-run]
+  repolens ownership --path PATH [--cwd PATH] [--since REF] [--limit N] [--output FILE] [--json] [--publish-board-id UUID] [--dry-run]
+  repolens start-here --path PATH [--cwd PATH] [--since REF] [--limit N] [--output FILE] [--json] [--publish-board-id UUID] [--dry-run]
+  repolens trace --query TEXT [--cwd PATH] [--since REF] [--limit N] [--output FILE] [--json] [--publish-board-id UUID] [--dry-run]
+  repolens context [--cwd PATH] [--base REF --head REF] [--output FILE] [--json]
+  repolens run <codex|claude> --task TEXT [--mode review|summary|explainer|onboarding|change-brief] [--base REF --head REF] [--audience VALUE] [--context-file FILE] [--save-packet FILE] [--output FILE] [--publish-board-id UUID] [--publish-as feature|onboarding|change-brief] [--user-id UUID] [--json] [--allow-edit] [--dry-run] [--] <extra agent args...>
+  repolens publish --input FILE [--board-id UUID] [--publish-as feature|onboarding|change-brief] [--audience VALUE] [--user-id UUID] [--dry-run] [--json]
+  repolens delegate <codex|claude> [--cwd PATH] [--dry-run] [--] <agent args...>
+
+Examples:
+  repolens doctor
+  repolens login --app-url https://repolens.ai
+  repolens login --app-url https://repolens.ai --no-browser
+  repolens whoami
+  repolens boards
+  repolens link --board-id <board-id>
+  repolens install-protocol
+  repolens brief --base origin/main --head HEAD --output .repolens/brief.md
+  repolens evolution --path src/lib/auth.ts --since origin/main --output .repolens/evolution.md
+  repolens hotspots --since origin/main --output .repolens/hotspots.md
+  repolens ownership --path src/lib/auth.ts --since origin/main --output .repolens/ownership.md
+  repolens start-here --path src/features/billing --since origin/main --output .repolens/start-here.md
+  repolens trace --query auth --since origin/main --output .repolens/trace.md
+  repolens trace --query BillingService --since origin/main --publish-board-id <board-id> --dry-run
+  repolens context --base origin/main --head HEAD --output .repolens/context.md
+  repolens run codex --task "Review this change" --mode review --base origin/main --head HEAD --dry-run
+  repolens run codex --task "Explain the auth flow" --mode explainer --audience engineer --base origin/main --head HEAD --dry-run
+  repolens run claude --task "Build a release brief" --mode change-brief --audience qa --base origin/main --head HEAD --publish-board-id <board-id>
+  repolens publish --input .repolens/runs/latest.json --board-id <board-id> --publish-as feature --dry-run
+  repolens delegate codex -- --help
+`);
+}
+
+function fail(message) {
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+}
+
+main().catch((error) => {
+  fail(error instanceof Error ? error.message : String(error));
+});
+
+function collectRepoSnapshot({ cwd, base, head, includeRangeCommits = false }) {
+  const repoRoot = findGitRoot(cwd);
+  if (!repoRoot) {
+    fail(`No git repository found from ${cwd}`);
+  }
+
+  const branch = runCommand("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: repoRoot }).trim();
+  const recentCommits = lines(runCommand("git", ["log", "--oneline", "-n", "8"], { cwd: repoRoot }));
+  const status = lines(runCommand("git", ["status", "--short"], { cwd: repoRoot }, { allowFailure: true }));
+  const trackedFiles = lines(runCommand("git", ["ls-files"], { cwd: repoRoot }, { allowFailure: true }));
+  const topFiles = rankPaths(trackedFiles).slice(0, 30);
+
+  let compare = null;
+  if (base && head) {
+    compare = {
+      base,
+      head,
+      diffSummary: lines(
+        runCommand("git", ["diff", "--stat", `${base}..${head}`], { cwd: repoRoot }, { allowFailure: true })
+      ),
+      changedFiles: lines(
+        runCommand("git", ["diff", "--name-only", `${base}..${head}`], { cwd: repoRoot }, { allowFailure: true })
+      ),
+      rangeCommits: includeRangeCommits
+        ? lines(
+            runCommand("git", ["log", "--oneline", "--no-merges", `${base}..${head}`], { cwd: repoRoot }, { allowFailure: true })
+          )
+        : [],
+    };
+  }
+
+  return {
+    repoRoot,
+    branch,
+    generatedAt: new Date().toISOString(),
+    recentCommits,
+    status,
+    topFiles,
+    compare,
+  };
+}
+
+function buildRunHistoryAppendix({ repoRoot, snapshot }) {
+  const sections = [];
+  const sinceRef = snapshot.compare?.base ?? "HEAD~50";
+  const execGit = (gitArgs, runtimeOptions = {}) => runCommand("git", gitArgs, { cwd: repoRoot }, runtimeOptions);
+  const hotspotReport = collectHotspotReport({
+    sinceRef,
+    limit: 5,
+    exec: execGit,
+  });
+
+  if (hotspotReport.files.length > 0) {
+    sections.push(
+      "### Recent Hotspots",
+      hotspotReport.files
+        .slice(0, 5)
+        .map((file) => `- \`${file.filePath}\` — score ${file.score}, ${file.touchedCommits} commits, +${file.additions}/-${file.deletions}`)
+        .join("\n")
+    );
+  }
+
+  const scopePath = inferRunScopePath(snapshot.compare?.changedFiles ?? snapshot.topFiles.slice(0, 6));
+  if (scopePath) {
+    const startHere = collectStartHereReport({
+      cwd: repoRoot,
+      targetPath: scopePath,
+      sinceRef: snapshot.compare?.base ?? null,
+      limit: 4,
+      exec: execGit,
+    });
+
+    sections.push(
+      "### Start Here",
+      `- Scope: \`${startHere.targetPath}\` (${startHere.pathKind})`,
+      `- Why: ${startHere.summary}`,
+      `- Change drivers: ${startHere.whyChanged}`,
+      startHere.commitThemes.length > 0
+        ? `- Themes: ${startHere.commitThemes.slice(0, 3).map((theme) => `${theme.label} (${theme.commits})`).join(", ")}`
+        : "- Themes: no recurring commit themes found.",
+      startHere.readingOrder.length > 0
+        ? `- Reading order: ${startHere.readingOrder.slice(0, 3).map((entry) => `\`${entry.path}\``).join(" -> ")}`
+        : "- Reading order: no guided reading order derived."
+    );
+  }
+
+  const interestingPaths = snapshot.compare?.changedFiles?.slice(0, 3) ?? snapshot.topFiles.slice(0, 2);
+  if (interestingPaths.length > 0) {
+    const evolutionSections = interestingPaths.map((targetPath) => {
+      const evolution = collectEvolutionReport({
+        cwd: repoRoot,
+        targetPath,
+        sinceRef: snapshot.compare?.base ?? null,
+        limit: 3,
+        exec: execGit,
+      });
+
+      if (evolution.commits.length === 0) {
+        return `- \`${targetPath}\`: no recent history found.`;
+      }
+
+      const recent = evolution.commits
+        .slice(0, 3)
+        .map((commit) => `${commit.date} ${commit.sha.slice(0, 7)} ${commit.subject}`)
+        .join("; ");
+
+      const movement = evolution.renameHistory[0]
+        ? ` moved from \`${evolution.renameHistory[0].fromPath}\``
+        : "";
+      const themes = evolution.commitThemes.length > 0
+        ? ` themes: ${evolution.commitThemes.slice(0, 2).map((theme) => theme.label).join(", ")}`
+        : "";
+
+      return `- \`${targetPath}\`: ${recent}${movement}.${themes} ${evolution.whyChanged}`.trim();
+    });
+
+    sections.push("### Recent Evolution", evolutionSections.join("\n"));
+  }
+
+  if (interestingPaths.length > 0) {
+    const ownershipSections = interestingPaths.map((targetPath) => {
+      const ownership = collectOwnershipReport({
+        cwd: repoRoot,
+        targetPath,
+        sinceRef: snapshot.compare?.base ?? null,
+        limit: 2,
+        exec: execGit,
+      });
+
+      if (ownership.owners.length === 0) {
+        return `- \`${targetPath}\`: no ownership history found.`;
+      }
+
+      const leaders = ownership.owners
+        .slice(0, 2)
+        .map((owner) => `${owner.author} (${owner.commits} commits)`)
+        .join(", ");
+
+      return `- \`${targetPath}\`: ${leaders}`;
+    });
+
+    sections.push("### Ownership Signals", ownershipSections.join("\n"));
+  }
+
+  return sections.join("\n\n");
+}
+
+function inferRunScopePath(paths) {
+  const normalized = paths
+    .map((filePath) => normalizeScopePath(filePath))
+    .filter(Boolean);
+
+  if (normalized.length === 0) {
+    return null;
+  }
+
+  const prefixes = new Map();
+  for (const filePath of normalized) {
+    const segments = filePath.split("/");
+    for (let index = 1; index < segments.length; index += 1) {
+      const prefix = segments.slice(0, index).join("/");
+      const current = prefixes.get(prefix) ?? { count: 0, depth: index };
+      current.count += 1;
+      prefixes.set(prefix, current);
+    }
+  }
+
+  const rankedPrefix = Array.from(prefixes.entries())
+    .filter(([, entry]) => entry.count >= 2)
+    .sort((left, right) => (right[1].count * right[1].depth) - (left[1].count * left[1].depth) || right[1].depth - left[1].depth)[0];
+
+  if (rankedPrefix) {
+    return rankedPrefix[0];
+  }
+
+  return normalized[0];
+}
+
+function normalizeScopePath(value) {
+  return value.replace(/\\/g, "/").replace(/^\.\/+/, "").replace(/\/+$/, "");
+}
+
+function resolveTask(task, taskFile) {
+  if (task && taskFile) {
+    fail("Use either --task or --task-file, not both.");
+  }
+
+  if (taskFile) {
+    return fs.readFileSync(path.resolve(taskFile), "utf8");
+  }
+
+  if (task) {
+    return task;
+  }
+
+  fail("A task is required. Provide --task <text> or --task-file <file>.");
+}
+
+function parsePositiveInteger(value, fallback, flagName) {
+  if (!value) {
+    return fallback;
+  }
+
+  const parsed = Number.parseInt(value, 10);
+  if (Number.isNaN(parsed) || parsed <= 0) {
+    fail(`${flagName} must be a positive integer.`);
+  }
+
+  return parsed;
+}
+
+function buildRunSpec(params) {
+  const outputPath = params.outputPath;
+
+  if (params.agent === "codex") {
+    const args = [
+      "exec",
+      "-C",
+      params.cwd,
+      "--sandbox",
+      params.allowEdit ? "workspace-write" : "read-only",
+    ];
+
+    if (params.model) {
+      args.push("--model", params.model);
+    }
+
+    if (params.json) {
+      args.push("--json");
+    }
+
+    if (params.schemaPath) {
+      args.push("--output-schema", params.schemaPath);
+    }
+
+    if (params.codexLastMessagePath) {
+      args.push("-o", params.codexLastMessagePath);
+    } else if (outputPath && !params.json) {
+      args.push("-o", outputPath);
+    }
+
+    args.push(...params.extraArgs, "-");
+    return { args, outputPath: params.json ? outputPath : null };
+  }
+
+  const args = ["-p"];
+  if (params.model) {
+    args.push("--model", params.model);
+  }
+
+  if (params.schemaPath) {
+    args.push("--output-format", "json", "--json-schema", fs.readFileSync(params.schemaPath, "utf8"));
+  } else if (params.json) {
+    args.push("--output-format", "json");
+  }
+
+  if (params.allowEdit) {
+    args.push("--permission-mode", "acceptEdits");
+  } else {
+    args.push("--permission-mode", "plan");
+  }
+
+  args.push(...params.extraArgs);
+  return { args, outputPath };
+}
+
+async function executeAgentRun(params) {
+  return await new Promise((resolve, reject) => {
+    const child = spawn(params.command, params.args, {
+      cwd: params.cwd,
+      stdio: ["pipe", "pipe", "pipe"],
+      env: process.env,
+    });
+
+    let stdoutBuffer = "";
+    let stderrBuffer = "";
+
+    child.stdout.on("data", (chunk) => {
+      const text = chunk.toString();
+      stdoutBuffer += text;
+      process.stdout.write(text);
+    });
+
+    child.stderr.on("data", (chunk) => {
+      const text = chunk.toString();
+      stderrBuffer += text;
+      process.stderr.write(text);
+    });
+
+    child.on("error", (error) => reject(error));
+
+    child.on("close", (code) => {
+      if (params.outputPath) {
+        fs.mkdirSync(path.dirname(params.outputPath), { recursive: true });
+        fs.writeFileSync(params.outputPath, stdoutBuffer, "utf8");
+      }
+
+      if (code === 0) {
+        resolve(stdoutBuffer);
+        return;
+      }
+
+      const errorMessage = stderrBuffer.trim() || `Agent exited with code ${code ?? 1}`;
+      reject(new Error(errorMessage));
+    });
+
+    child.stdin.write(params.prompt);
+    child.stdin.end();
+  });
+}
+
+function parseStructuredJson(value) {
+  try {
+    return JSON.parse(value);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown JSON parse error";
+    fail(`Structured agent output was not valid JSON: ${message}`);
+  }
+}
+
+function validateStructuredOutput(schema, value, currentPath = "$") {
+  const error = getValidationError(schema, value, currentPath);
+  if (error) {
+    fail(error);
+  }
+}
+
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function getValidationError(schema, value, currentPath) {
+  const schemaType = schema.type;
+  if (Array.isArray(schemaType)) {
+    const errors = schemaType
+      .map((candidate) => getValidationError({ ...schema, type: candidate }, value, currentPath))
+      .filter(Boolean);
+    return errors.length === schemaType.length ? errors[0] : null;
+  }
+
+  if (schema.enum && !schema.enum.includes(value)) {
+    return `Structured output validation failed at ${currentPath}: expected one of ${schema.enum.join(", ")}.`;
+  }
+
+  if (schema.type === "object") {
+    if (!isPlainObject(value)) {
+      return `Structured output validation failed at ${currentPath}: expected object.`;
+    }
+
+    for (const key of schema.required ?? []) {
+      if (!(key in value)) {
+        return `Structured output validation failed at ${currentPath}: missing required key "${key}".`;
+      }
+    }
+
+    for (const [key, propertySchema] of Object.entries(schema.properties ?? {})) {
+      if (key in value) {
+        const nestedError = getValidationError(propertySchema, value[key], `${currentPath}.${key}`);
+        if (nestedError) {
+          return nestedError;
+        }
+      }
+    }
+
+    return null;
+  }
+
+  if (schema.type === "array") {
+    if (!Array.isArray(value)) {
+      return `Structured output validation failed at ${currentPath}: expected array.`;
+    }
+
+    if (typeof schema.minItems === "number" && value.length < schema.minItems) {
+      return `Structured output validation failed at ${currentPath}: expected at least ${schema.minItems} items.`;
+    }
+
+    if (typeof schema.maxItems === "number" && value.length > schema.maxItems) {
+      return `Structured output validation failed at ${currentPath}: expected at most ${schema.maxItems} items.`;
+    }
+
+    for (const [index, item] of value.entries()) {
+      const nestedError = getValidationError(schema.items, item, `${currentPath}[${index}]`);
+      if (nestedError) {
+        return nestedError;
+      }
+    }
+
+    return null;
+  }
+
+  if (schema.type === "string") {
+    return typeof value === "string"
+      ? null
+      : `Structured output validation failed at ${currentPath}: expected string.`;
+  }
+
+  if (schema.type === "number") {
+    return typeof value === "number" && !Number.isNaN(value)
+      ? null
+      : `Structured output validation failed at ${currentPath}: expected number.`;
+  }
+
+  if (schema.type === "boolean") {
+    return typeof value === "boolean"
+      ? null
+      : `Structured output validation failed at ${currentPath}: expected boolean.`;
+  }
+
+  if (schema.type === "null") {
+    return value === null
+      ? null
+      : `Structured output validation failed at ${currentPath}: expected null.`;
+  }
+
+  return null;
+}
+
+function buildRunStamp() {
+  return new Date().toISOString().replaceAll(":", "-").replaceAll(".", "-");
+}
+
+function normalizePublishKind(value) {
+  if (!value) {
+    return null;
+  }
+
+  switch (value) {
+    case "explainer":
+    case "feature":
+      return "feature";
+    case "onboarding":
+      return "onboarding";
+    case "change-brief":
+    case "change_brief":
+      return "change-brief";
+    default:
+      return null;
+  }
+}
+
+function defaultPublishKindForMode(mode) {
+  if (!mode) {
+    return null;
+  }
+
+  const preset = RUN_MODE_PRESETS[mode];
+  return preset?.publishKind ?? null;
+}
+
+function normalizeAudience(value, publishKind) {
+  if (!value) {
+    return publishKind === "change-brief" ? "pm" : "pm";
+  }
+
+  if (publishKind === "change-brief") {
+    if (value === "pm" || value === "engineer" || value === "qa") {
+      return value;
+    }
+    fail('Change brief audience must be one of: "pm", "engineer", "qa".');
+  }
+
+  if (value === "pm" || value === "engineer" || value === "technical_deep_dive") {
+    return value;
+  }
+
+  if (value === "qa") {
+    return value;
+  }
+
+  fail('Audience must be one of: "pm", "engineer", "technical_deep_dive", "qa".');
+}
+
+function hasPublishEnv() {
+  return Boolean(process.env.NEXT_PUBLIC_SUPABASE_URL && process.env.SUPABASE_SERVICE_ROLE_KEY);
+}
+
+function buildPublishPreview(params) {
+  const result = params.envelope?.result ?? {};
+  return {
+    boardId: params.boardId,
+    publishKind: params.publishKind,
+    audience: params.audience,
+    userId: params.userId,
+    mode: params.envelope?.mode ?? null,
+    title: readPublishTitle(params.publishKind, result),
+    summary: readPublishSummary(params.publishKind, result),
+    diagramCount: Array.isArray(result.diagrams) ? result.diagrams.length : 0,
+    evidenceCount: Array.isArray(result.evidence) ? result.evidence.length : 0,
+    compare: params.envelope?.compare ?? null,
+  };
+}
+
+function buildHistoryPublishPreview(params) {
+  return {
+    boardId: params.boardId,
+    reportKind: params.reportKind,
+    title: buildHistoryReportTitle(params.reportKind, params.payload),
+    summary: buildHistoryReportSummary(params.reportKind, params.payload),
+    relatedFiles: collectHistoryReportRelatedFiles(params.reportKind, params.payload).length,
+  };
+}
+
+async function publishHistoryReport(params) {
+  if (params.dryRun) {
+    process.stdout.write(`${JSON.stringify(buildHistoryPublishPreview(params), null, 2)}\n`);
+    return;
+  }
+
+  const authConfig = loadCliAuthConfig();
+  if (authConfig?.appUrl && authConfig?.token) {
+    const response = await callCliApi({
+      appUrl: authConfig.appUrl,
+      token: authConfig.token,
+      pathname: "/api/cli/history-reports",
+      method: "POST",
+      body: {
+        boardId: params.boardId,
+        reportKind: params.reportKind,
+        payload: params.payload,
+      },
+    });
+    const payload = await parseApiJson(response);
+    if (!response.ok) {
+      fail(payload.error ?? `History report publish failed with status ${response.status}.`);
+    }
+    process.stdout.write(`Published ${params.reportKind} history report to board ${params.boardId}\n`);
+    return payload;
+  }
+
+  return await publishHistoryReportLocally(params);
+}
+
+async function publishEnvelope(params) {
+  const authConfig = loadCliAuthConfig();
+  if (authConfig?.appUrl && authConfig?.token) {
+    const response = await callCliApi({
+      appUrl: authConfig.appUrl,
+      token: authConfig.token,
+      pathname: "/api/cli/publish",
+      method: "POST",
+      body: {
+        boardId: params.boardId,
+        publishAs: params.publishKind,
+        audience: params.audience,
+        envelope: params.envelope,
+      },
+    });
+    const payload = await parseApiJson(response);
+    if (!response.ok) {
+      fail(payload.error ?? `Publish failed with status ${response.status}.`);
+    }
+    return payload;
+  }
+
+  return await publishStructuredRun(params);
+}
+
+async function publishHistoryReportLocally(params) {
+  if (!hasPublishEnv()) {
+    fail("History report publishing requires repolens login or NEXT_PUBLIC_SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY.");
+  }
+
+  const Supabase = await import("@supabase/supabase-js");
+  const supabase = Supabase.createClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL,
+    process.env.SUPABASE_SERVICE_ROLE_KEY,
+    {
+      auth: {
+        autoRefreshToken: false,
+        persistSession: false,
+      },
+    }
+  );
+
+  const { data: board, error: boardError } = await supabase
+    .from("boards")
+    .select("id, owner_id")
+    .eq("id", params.boardId)
+    .maybeSingle();
+
+  if (boardError || !board) {
+    throw new Error(boardError?.message ?? `Board not found: ${params.boardId}`);
+  }
+
+  const now = new Date().toISOString();
+  const analysisMetadata = extractLocalHistoryAnalysisMetadata(params.reportKind, params.payload);
+  const historyReportMeta = buildCompactHistoryMetadata(params.reportKind, params.payload);
+  const { data: analysis, error: analysisError } = await supabase
+    .from("analyses")
+    .insert({
+      board_id: params.boardId,
+      triggered_by: board.owner_id,
+      status: "complete",
+      trigger_type: "manual",
+      commit_sha: null,
+      base_ref: analysisMetadata.baseRef,
+      head_ref: analysisMetadata.headRef,
+      stage_1_result: null,
+      stage_2_config: {
+        source: "repolens_cli",
+        mode: params.reportKind,
+        repo_root: params.payload.repoRoot ?? null,
+        task: analysisMetadata.task,
+        history_report_kind: params.reportKind,
+        history_report_meta: historyReportMeta,
+        generated_at: params.payload.generatedAt ?? null,
+      },
+      completed_at: now,
+    })
+    .select("id")
+    .single();
+
+  if (analysisError || !analysis) {
+    throw new Error(analysisError?.message ?? "Failed to create history report analysis.");
+  }
+
+  const { data: artifact, error: artifactError } = await supabase
+    .from("artifacts")
+    .insert({
+      analysis_id: analysis.id,
+      board_id: params.boardId,
+      type: "history_report",
+      perspective: params.reportKind,
+      audience: "engineer",
+      title: buildHistoryReportTitle(params.reportKind, params.payload),
+      content: buildHistoryReportMarkdown(params.reportKind, params.payload),
+      content_format: "markdown",
+      confidence_score: 0.86,
+      confidence_reason: "local_git_history_analysis",
+      is_inferred: false,
+      related_files: collectHistoryReportRelatedFiles(params.reportKind, params.payload),
+    })
+    .select("id")
+    .single();
+
+  if (artifactError || !artifact) {
+    throw new Error(artifactError?.message ?? "Failed to persist history report artifact.");
+  }
+
+  await supabase
+    .from("boards")
+    .update({ last_analyzed_at: now })
+    .eq("id", params.boardId);
+
+  await supabase.from("audit_logs").insert({
+    board_id: params.boardId,
+    user_id: board.owner_id,
+    action: "history_report.published_from_cli",
+    target_type: "history_report",
+    target_id: artifact.id,
+    metadata: {
+      kind: params.reportKind,
+      summary: buildHistoryReportSummary(params.reportKind, params.payload),
+      analysisId: analysis.id,
+    },
+  });
+
+  process.stdout.write(`Published ${params.reportKind} history report to board ${params.boardId}\n`);
+  return {
+    type: "history_report",
+    reportKind: params.reportKind,
+    analysisId: analysis.id,
+    artifactId: artifact.id,
+    href: `/report/${artifact.id}`,
+  };
+}
+
+async function publishStructuredRun(params) {
+  if (!hasPublishEnv()) {
+    fail("Publishing requires NEXT_PUBLIC_SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY.");
+  }
+
+  const envelope = params.envelope;
+  if (!isPlainObject(envelope) || envelope.type !== "repolens-run") {
+    fail("Publish input must be a RepoLens structured run envelope.");
+  }
+
+  if (!isPlainObject(envelope.result)) {
+    fail("Publish input is missing a structured result payload.");
+  }
+
+  const publishSchema = params.publishKind === "change-brief" ? CHANGE_BRIEF_SCHEMA : EXPLAINER_SCHEMA;
+  validateStructuredOutput(publishSchema, envelope.result);
+
+  const Supabase = await import("@supabase/supabase-js");
+  const supabase = Supabase.createClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL,
+    process.env.SUPABASE_SERVICE_ROLE_KEY,
+    {
+      auth: {
+        autoRefreshToken: false,
+        persistSession: false,
+      },
+    }
+  );
+
+  const { data: board, error: boardError } = await supabase
+    .from("boards")
+    .select("id, owner_id, repo_url, repo_branch")
+    .eq("id", params.boardId)
+    .maybeSingle();
+
+  if (boardError || !board) {
+    throw new Error(boardError?.message ?? `Board not found: ${params.boardId}`);
+  }
+
+  const triggeredBy = params.userId ?? board.owner_id;
+  if (!triggeredBy) {
+    throw new Error("Could not determine which user should own the published artifact.");
+  }
+
+  const compare = isPlainObject(envelope.compare) ? envelope.compare : null;
+  const now = new Date().toISOString();
+  const analysisInsert = {
+    board_id: params.boardId,
+    triggered_by: triggeredBy,
+    status: "complete",
+    trigger_type: "manual",
+    commit_sha: typeof compare?.head === "string" ? compare.head : null,
+    base_ref: typeof compare?.base === "string" ? compare.base : null,
+    head_ref: typeof compare?.head === "string" ? compare.head : board.repo_branch ?? null,
+    stage_1_result: null,
+    stage_2_config: {
+      source: "repolens_cli",
+      mode: envelope.mode ?? null,
+      agent: envelope.agent ?? null,
+      repo_root: envelope.repoRoot ?? null,
+      task: envelope.task ?? null,
+      packet_path: envelope.packetPath ?? null,
+      generated_at: envelope.generatedAt ?? null,
+    },
+    file_count: null,
+    loc_count: null,
+    duration_ms: null,
+    cost_usd: null,
+    completed_at: now,
+  };
+
+  const { data: analysis, error: analysisError } = await supabase
+    .from("analyses")
+    .insert(analysisInsert)
+    .select("id")
+    .single();
+
+  if (analysisError || !analysis) {
+    throw new Error(analysisError?.message ?? "Failed to create analysis row for published artifact.");
+  }
+
+  const result = envelope.result;
+  const evidenceRows = buildEvidenceRows(params.boardId, result.evidence, compare?.head ?? null);
+  let evidenceIds = [];
+  if (evidenceRows.length > 0) {
+    const { data: insertedEvidence, error: evidenceError } = await supabase
+      .from("evidence_cards")
+      .insert(evidenceRows)
+      .select("id");
+
+    if (evidenceError) {
+      throw new Error(evidenceError.message);
+    }
+
+    evidenceIds = (insertedEvidence ?? []).map((item) => item.id);
+  }
+
+  const diagramRows = buildDiagramRows({
+    analysisId: analysis.id,
+    boardId: params.boardId,
+    audience: params.audience,
+    diagrams: Array.isArray(result.diagrams) ? result.diagrams : [],
+    publishKind: params.publishKind,
+  });
+
+  let diagramIds = [];
+  if (diagramRows.length > 0) {
+    const { data: insertedDiagrams, error: diagramError } = await supabase
+      .from("artifacts")
+      .insert(diagramRows)
+      .select("id");
+
+    if (diagramError) {
+      throw new Error(diagramError.message);
+    }
+
+    diagramIds = (insertedDiagrams ?? []).map((item) => item.id);
+  }
+
+  if (params.publishKind === "change-brief") {
+    const artifactContent = exportChangeBriefToMarkdown(result);
+    const { data: mainArtifact, error: mainArtifactError } = await supabase
+      .from("artifacts")
+      .insert({
+        analysis_id: analysis.id,
+        board_id: params.boardId,
+        type: "change_brief",
+        perspective: "change_brief",
+        audience: params.audience,
+        title: "Change Brief",
+        content: artifactContent,
+        content_format: "markdown",
+        confidence_score: 0.72,
+        confidence_reason: "local_agent_structured_output",
+        is_inferred: true,
+        related_files: collectChangeBriefRelatedFiles(result),
+      })
+      .select("id")
+      .single();
+
+    if (mainArtifactError || !mainArtifact) {
+      throw new Error(mainArtifactError?.message ?? "Failed to persist change brief artifact.");
+    }
+
+    const { data: brief, error: briefError } = await supabase
+      .from("change_briefs")
+      .insert({
+        board_id: params.boardId,
+        analysis_id: analysis.id,
+        base_ref: typeof compare?.base === "string" ? compare.base : "local",
+        head_ref: typeof compare?.head === "string" ? compare.head : board.repo_branch ?? "HEAD",
+        audience: params.audience,
+        summary: stringOrFallback(result.summary, "Generated change brief"),
+        impacted_features: Array.isArray(result.impactedFeatures) ? result.impactedFeatures : [],
+        impacted_files: Array.isArray(result.impactedFiles) ? result.impactedFiles : [],
+        impacted_screens: Array.isArray(result.impactedScreens) ? result.impactedScreens : [],
+        rollout_risks: nullableString(result.rolloutRisks),
+        qa_checklist: Array.isArray(result.qaChecklist) ? result.qaChecklist.join("\n") : null,
+        communication_brief: nullableString(result.communicationBrief),
+        diagram_ids: diagramIds,
+        evidence_ids: evidenceIds,
+        confidence_level: "medium",
+      })
+      .select("id")
+      .single();
+
+    if (briefError || !brief) {
+      throw new Error(briefError?.message ?? "Failed to persist change brief.");
+    }
+
+    await finalizePublish({
+      supabase,
+      boardId: params.boardId,
+      userId: triggeredBy,
+      action: "change_brief.published_from_cli",
+      targetType: "change_brief",
+      targetId: brief.id,
+      metadata: {
+        mode: envelope.mode ?? null,
+        agent: envelope.agent ?? null,
+        mainArtifactId: mainArtifact.id,
+      },
+    });
+
+    return {
+      type: "change-brief",
+      boardId: params.boardId,
+      analysisId: analysis.id,
+      briefId: brief.id,
+      artifactId: mainArtifact.id,
+      href: `/brief/${brief.id}`,
+    };
+  }
+
+  const explainerType = params.publishKind === "onboarding" ? "onboarding" : "feature";
+  const artifactContent = exportExplainerToMarkdown(result);
+  const { data: mainArtifact, error: mainArtifactError } = await supabase
+    .from("artifacts")
+    .insert({
+      analysis_id: analysis.id,
+      board_id: params.boardId,
+      type: "explainer",
+      perspective: explainerType,
+      audience: params.audience,
+      title: stringOrFallback(result.title, "Generated Explainer"),
+      content: artifactContent,
+      content_format: "markdown",
+      confidence_score: 0.72,
+      confidence_reason: "local_agent_structured_output",
+      is_inferred: true,
+      related_files: collectExplainerRelatedFiles(result),
+    })
+    .select("id")
+    .single();
+
+  if (mainArtifactError || !mainArtifact) {
+    throw new Error(mainArtifactError?.message ?? "Failed to persist explainer artifact.");
+  }
+
+  const { data: explainer, error: explainerError } = await supabase
+    .from("explainers")
+    .insert({
+      board_id: params.boardId,
+      analysis_id: analysis.id,
+      type: explainerType,
+      audience: params.audience,
+      title: stringOrFallback(result.title, "Generated Explainer"),
+      summary: stringOrFallback(result.summary, "Generated by RepoLens CLI"),
+      value_proposition: nullableString(result.valueProposition),
+      user_journey: nullableString(result.userJourney),
+      key_components: Array.isArray(result.keyComponents) ? result.keyComponents : [],
+      business_logic: nullableString(result.businessLogic),
+      agent_logic: null,
+      risks_and_questions: joinSections([
+        nullableString(result.risksAndQuestions),
+        ...readStringArray(result.openQuestions),
+      ]),
+      diagram_ids: diagramIds,
+      evidence_ids: evidenceIds,
+      confidence_level: "medium",
+    })
+    .select("id")
+    .single();
+
+  if (explainerError || !explainer) {
+    throw new Error(explainerError?.message ?? "Failed to persist explainer.");
+  }
+
+  await finalizePublish({
+    supabase,
+    boardId: params.boardId,
+    userId: triggeredBy,
+    action: explainerType === "onboarding" ? "onboarding.published_from_cli" : "explainer.published_from_cli",
+    targetType: explainerType,
+    targetId: explainer.id,
+    metadata: {
+      mode: envelope.mode ?? null,
+      agent: envelope.agent ?? null,
+      mainArtifactId: mainArtifact.id,
+    },
+  });
+
+  return {
+    type: explainerType,
+    boardId: params.boardId,
+    analysisId: analysis.id,
+    explainerId: explainer.id,
+    artifactId: mainArtifact.id,
+    href: explainerType === "onboarding" ? `/onboarding/${explainer.id}` : `/explainer/${explainer.id}`,
+  };
+}
+
+async function finalizePublish(params) {
+  await params.supabase
+    .from("boards")
+    .update({ last_analyzed_at: new Date().toISOString() })
+    .eq("id", params.boardId);
+
+  await params.supabase.from("audit_logs").insert({
+    board_id: params.boardId,
+    user_id: params.userId,
+    action: params.action,
+    target_type: params.targetType,
+    target_id: params.targetId,
+    metadata: params.metadata,
+  });
+}
+
+function readPublishTitle(kind, result) {
+  if (kind === "change-brief") {
+    return stringOrFallback(result.summary, "Change Brief");
+  }
+  return stringOrFallback(result.title, "Generated Explainer");
+}
+
+function extractLocalHistoryAnalysisMetadata(reportKind, payload) {
+  switch (reportKind) {
+    case "evolution":
+    case "ownership":
+    case "start-here":
+      return {
+        baseRef: typeof payload.sinceRef === "string" ? payload.sinceRef : null,
+        headRef: typeof payload.branch === "string" ? payload.branch : null,
+        task: `${reportKind}:${typeof payload.targetPath === "string" ? payload.targetPath : "unknown"}`,
+      };
+    case "hotspots":
+      return {
+        baseRef: typeof payload.sinceRef === "string" ? payload.sinceRef : null,
+        headRef: typeof payload.branch === "string" ? payload.branch : null,
+        task: "hotspots",
+      };
+    case "trace":
+      return {
+        baseRef: typeof payload.sinceRef === "string" ? payload.sinceRef : null,
+        headRef: typeof payload.branch === "string" ? payload.branch : null,
+        task: `trace:${typeof payload.query === "string" ? payload.query : "unknown"}`,
+      };
+    default:
+      return { baseRef: null, headRef: null, task: "history-report" };
+  }
+}
+
+function readPublishSummary(kind, result) {
+  if (kind === "change-brief") {
+    return stringOrFallback(result.summary, "");
+  }
+  return stringOrFallback(result.summary, "");
+}
+
+function joinSections(sections) {
+  return sections.map(nullableString).filter(Boolean).join("\n\n");
+}
+
+function readStringArray(value) {
+  return Array.isArray(value) ? value.map(String).filter(Boolean) : [];
+}
+
+function stringOrFallback(value, fallback) {
+  return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+
+function nullableString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : null;
+}