/**
 * Commander program definition.
 * Wires all CLI commands with lazy imports for fast --help.
 *
 * @module src/cli/program
 */

import { Command, Option } from "commander";
// node:fs sync unlink — Bun has no equivalent; used only in the detached-
// child signal handler where we need a synchronous cleanup on the signal
// path.
import { unlinkSync } from "node:fs";

import {
  CLI_NAME,
  DOCS_URL,
  ISSUES_URL,
  PRODUCT_NAME,
  VERSION,
} from "../app/constants";
import { INDEX_NAME_REQUIREMENTS, isValidIndexName } from "../app/index-name";
import { resolveDepthPolicy } from "../core/depth-policy";
import {
  findingsRunStatePathForIndex,
  formatFindingsRunStatusLine,
  readFindingsRunStatus,
} from "../core/findings-run-state";
import { parseAndValidateTagFilter } from "../core/tags";
import {
  formatWriteLeaseBusyJson,
  formatWriteLeaseBusyMessage,
  isWriteLeaseBusyResult,
  parseLockWaitMs,
  withCliWriteLease,
  type WriteLeaseBusyFailure,
} from "../core/write-lease";
import { type McpToolProfile, parseMcpToolProfile } from "../mcp/tool-profile";
import { setColorsEnabled } from "./colors";
import {
  applyGlobalOptions,
  type GlobalOptions,
  parseGlobalOptions,
} from "./context";
import { DETACHED_CHILD_FLAG } from "./detach";
import { CliError } from "./errors";
import {
  assertFormatSupported,
  CMD,
  collectRepeatableValue,
  getDefaultLimit,
  parseCliProjectAffinityOptions,
  parseCliMetadataFilter,
  parseOptionalFloat,
  parsePositiveInt,
} from "./options";
import { resolveCliQueryText } from "./query-text";

// ─────────────────────────────────────────────────────────────────────────────
// Global State (set by preAction hook)
// ─────────────────────────────────────────────────────────────────────────────

// Using object wrapper to allow mutation while satisfying linter
const globalState: { current: GlobalOptions | null } = { current: null };

/**
 * Get resolved global options. Must be called after command parsing.
 * Throws if called before preAction hook runs.
 */
export function getGlobals(): GlobalOptions {
  if (!globalState.current) {
    throw new Error("Global options not resolved - called before preAction?");
  }
  return globalState.current;
}

/**
 * Reset global state (for testing).
 * Resets both option state and color state to avoid test pollution.
 */
export function resetGlobals(): void {
  globalState.current = null;
  // Reset colors to default (true) - will be set by applyGlobalOptions on next run
  setColorsEnabled(true);
}

/**
 * Resolve the user-facing argv slice (everything after `[execPath, scriptPath]`)
 * from a Commander Command instance. Walks up to the root via `.parent` so we
 * get the original argv passed to `parseAsync()` regardless of which
 * sub-command's action handler invoked us.
 *
 * Exported for tests. Production callers (runDaemonDetach / runServeDetach)
 * call this with `cmd` from their action handler.
 */
export function resolveCliArgv(cmd: Command): string[] {
  let root: Command = cmd;
  while (root.parent) {
    root = root.parent;
  }
  // Commander's Command.rawArgs is the full argv passed into parseAsync()
  // (including [execPath, scriptPath]). Drop the first two so the slice
  // matches what we'd build from `process.argv.slice(2)` in the legacy
  // path — that's what the detach child re-exec wants.
  //
  // Note: rawArgs is documented in Commander's source
  // (`node_modules/commander/lib/command.js:1028` — `this.rawArgs =
  // argv.slice()`) but is not on its public TypeScript type, hence the
  // narrow cast.
  const rawArgs = (root as unknown as { rawArgs: string[] }).rawArgs;
  return rawArgs.slice(2);
}

/**
 * Select output format with explicit precedence.
 * Precedence: local non-json format > local --json > global --json > terminal
 */
function getFormat(
  cmdOpts: Record<string, unknown>
): "terminal" | "json" | "files" | "csv" | "md" | "xml" {
  const globals = getGlobals();

  const local = {
    json: Boolean(cmdOpts.json),
    files: Boolean(cmdOpts.files),
    csv: Boolean(cmdOpts.csv),
    md: Boolean(cmdOpts.md),
    xml: Boolean(cmdOpts.xml),
  };

  // Count local format flags
  const localFormats = Object.entries(local).filter(([_, v]) => v);
  if (localFormats.length > 1) {
    throw new CliError(
      "VALIDATION",
      `Conflicting output formats: ${localFormats.map(([k]) => k).join(", ")}. Choose one.`
    );
  }

  // Local non-json format wins (--md, --csv, --files, --xml)
  if (local.files) {
    return "files";
  }
  if (local.csv) {
    return "csv";
  }
  if (local.md) {
    return "md";
  }
  if (local.xml) {
    return "xml";
  }

  // Local --json wins over global
  if (local.json) {
    return "json";
  }

  // Global --json as fallback
  if (globals.json) {
    return "json";
  }

  return "terminal";
}

/**
 * Write output with optional paging for terminal format.
 * Paging only applies to terminal format with list-like output.
 */
async function writeOutput(
  content: string,
  format: "terminal" | "json" | "files" | "csv" | "md" | "xml"
): Promise<void> {
  const globals = getGlobals();

  // Only page terminal output when paging enabled
  if (format === "terminal" && !globals.noPager && process.stdout.isTTY) {
    const { pageContent } = await import("./pager.js");
    await pageContent(content);
  } else {
    process.stdout.write(content + "\n");
  }
}

/** Emit opt-in trace identity without changing command stdout payloads. */
export function writeRetrievalTraceReceipt(
  metadata: { traceId: string } | undefined
): void {
  if (metadata) {
    process.stderr.write(`Trace: ${metadata.traceId}\n`);
  }
}

async function resolveTerminalLinkPolicy(
  format: "terminal" | "json" | "files" | "csv" | "md" | "xml"
): Promise<
  | {
      isTTY: boolean;
      editorUriTemplate?: string | null;
    }
  | undefined
> {
  if (format !== "terminal") {
    return undefined;
  }

  const globals = getGlobals();
  const envTemplate = process.env.GNO_EDITOR_URI_TEMPLATE?.trim();
  if (envTemplate) {
    return {
      isTTY: process.stdout.isTTY ?? false,
      editorUriTemplate: envTemplate,
    };
  }

  const { loadConfig } = await import("../config");
  const configResult = await loadConfig(globals.config);
  const configTemplate = configResult.ok
    ? configResult.value.editorUriTemplate?.trim()
    : undefined;

  return {
    isTTY: process.stdout.isTTY ?? false,
    editorUriTemplate:
      configTemplate && configTemplate.length > 0 ? configTemplate : null,
  };
}

function parseCsvValues(raw: unknown): string[] | undefined {
  if (typeof raw !== "string") {
    return undefined;
  }
  const values = raw
    .split(",")
    .map((v) => v.trim().toLowerCase())
    .filter((v) => v.length > 0);
  return values.length > 0 ? values : undefined;
}

function addWriteLeaseFlags(command: Command): Command {
  return command
    .option(
      "--lock-wait <duration>",
      "how long to wait for the index write lease (default: 120s)",
      "120s"
    )
    .option("--no-wait", "fail immediately if the index write lease is held");
}

function parseWriteLeaseFlags(cmdOpts: Record<string, unknown>): {
  lockWaitMs: number;
  noWait: boolean;
} {
  const parsed = parseLockWaitMs(cmdOpts.lockWait);
  if (parsed === null) {
    throw new CliError(
      "VALIDATION",
      `Invalid --lock-wait duration: ${String(cmdOpts.lockWait)}. Use seconds ("120"), "120s", or "2m".`
    );
  }
  return {
    lockWaitMs: parsed,
    noWait: cmdOpts.wait === false,
  };
}

function throwIfWriteLeaseBusy<
  T extends { success: boolean; error?: string; contention?: unknown },
>(result: T | WriteLeaseBusyFailure, json: boolean): asserts result is T {
  if (!isWriteLeaseBusyResult(result)) {
    return;
  }
  if (json) {
    process.stdout.write(
      `${JSON.stringify(formatWriteLeaseBusyJson(result.contention))}\n`
    );
  } else {
    process.stderr.write(`${formatWriteLeaseBusyMessage(result.contention)}\n`);
  }
  throw new CliError("BUSY", result.error, { silent: true });
}

function parseContextInteger(
  name: string,
  value: unknown,
  allowZero = false
): number {
  const raw = typeof value === "string" ? value : String(value);
  if (!/^\d+$/.test(raw)) {
    throw new CliError("VALIDATION", `--${name} must be an integer`, {
      details: { contextCode: "invalid_budget" },
    });
  }
  const parsed = Number(raw);
  if (!Number.isSafeInteger(parsed) || (allowZero ? parsed < 0 : parsed < 1)) {
    throw new CliError(
      "VALIDATION",
      `--${name} must be ${allowZero ? "non-negative" : "positive"}`,
      { details: { contextCode: "invalid_budget" } }
    );
  }
  return parsed;
}

function validateContextOutputPath(value: unknown): string | undefined {
  if (value === undefined) return undefined;
  if (typeof value !== "string" || !value.trim() || value === "-") {
    throw new CliError(
      "VALIDATION",
      "--output requires an explicit file path",
      {
        details: { contextCode: "invalid_filter" },
      }
    );
  }
  return value;
}

// ─────────────────────────────────────────────────────────────────────────────
// Program Factory
// ─────────────────────────────────────────────────────────────────────────────

export function createProgram(): Command {
  const program = new Command();

  program
    .name(CLI_NAME)
    .description(`${PRODUCT_NAME} - Local Knowledge Index and Retrieval`)
    .version(VERSION, "-V, --version", "show version")
    .exitOverride() // Prevent Commander from calling process.exit()
    .showSuggestionAfterError(true)
    .showHelpAfterError("(Use --help for available options)");

  // Global flags - resolved via preAction hook
  program
    .option("--index <name>", "index name", "default")
    .option("--config <path>", "config file path")
    .option("--no-color", "disable colors")
    .option("--verbose", "verbose logging")
    .option("--yes", "non-interactive mode")
    .option("-q, --quiet", "suppress non-essential output")
    .option("--json", "JSON output (for errors and supported commands)")
    .option("--offline", "offline mode (use cached models only)")
    .option("--no-pager", "disable automatic paging of long output");

  // Resolve globals ONCE before any command runs (ensures consistency)
  program.hook("preAction", (thisCommand) => {
    const rootOpts = thisCommand.optsWithGlobals();
    const globals = parseGlobalOptions(rootOpts);
    if (!isValidIndexName(globals.index)) {
      throw new CliError(
        "VALIDATION",
        `Invalid index name: ${INDEX_NAME_REQUIREMENTS}.`
      );
    }
    applyGlobalOptions(globals);
    globalState.current = globals;
  });

  // Wire command groups
  wireSearchCommands(program);
  wireOnboardingCommands(program);
  wireCaptureCommand(program);
  wireMemoryCommands(program);
  wireManagementCommands(program);
  wireTraceCommands(program);
  wirePublishCommand(program);
  wireVecCommands(program);
  wireRetrievalCommands(program);
  wireTagsCommands(program);
  wireLinksCommands(program);
  wireGraphCommand(program);
  wireKnowledgeDeltaCommands(program);
  wireMcpCommand(program);
  wireSkillCommands(program);
  wireAgentsCommands(program);
  wireDaemonCommand(program);
  wireServeCommand(program);
  wireCompletionCommand(program);

  // Add docs/support links to help footer
  program.addHelpText(
    "after",
    `
Documentation: ${DOCS_URL}
Report issues: ${ISSUES_URL}`
  );

  return program;
}

function wireTraceCommands(program: Command): void {
  const traceCmd = program
    .command("trace")
    .description("Inspect and manage private local retrieval traces");

  const outputFormat = (options: Record<string, unknown>): "json" | "md" =>
    getFormat(options) === "json" ? "json" : "md";

  traceCmd
    .command("list")
    .description("List bounded, redacted retrieval trace summaries")
    .option("-n, --limit <num>", "maximum traces", "50")
    .option("--cursor <cursor>", "continue from a previous list receipt")
    .option("--json", "JSON output")
    .option("--md", "Markdown output")
    .action(async (cmdOpts: Record<string, unknown>) => {
      const globals = getGlobals();
      const { traceList } = await import("./commands/trace");
      const output = await traceList(
        {
          limit: parsePositiveInt("limit", cmdOpts.limit),
          cursor: cmdOpts.cursor as string | undefined,
        },
        {
          configPath: globals.config,
          indexName: globals.index,
          format: outputFormat(cmdOpts),
        }
      );
      process.stdout.write(output);
    });

  traceCmd
    .command("show <trace-id>")
    .description("Inspect one bounded retrieval trace receipt")
    .option("--detail-limit <num>", "maximum records per detail section", "500")
    .option("--json", "JSON output")
    .option("--md", "Markdown output")
    .action(async (traceId: string, cmdOpts: Record<string, unknown>) => {
      const globals = getGlobals();
      const { traceShow } = await import("./commands/trace");
      const output = await traceShow(
        traceId,
        {
          detailLimit: parsePositiveInt("detail-limit", cmdOpts.detailLimit),
        },
        {
          configPath: globals.config,
          indexName: globals.index,
          format: outputFormat(cmdOpts),
        }
      );
      process.stdout.write(output);
    });

  traceCmd
    .command("label <trace-id>")
    .description("Append an explicit retrieval relevance judgment")
    .requiredOption(
      "--label <label>",
      "relevant, irrelevant, or missing-expected"
    )
    .requiredOption("--target <ref>", "evidence or expected-document reference")
    .option("--target-kind <kind>", "document, chunk, or span")
    .option("--from-line <num>", "exact evidence start line")
    .option("--to-line <num>", "exact evidence end line")
    .option("--source-hash <sha256>", "expected immutable source hash")
    .option("--docid <docid>", "expected document ID")
    .option("--idempotency-key <key>", "caller retry key")
    .option("--json", "JSON output")
    .option("--md", "Markdown output")
    .action(async (traceId: string, cmdOpts: Record<string, unknown>) => {
      const globals = getGlobals();
      const rawLabel = String(cmdOpts.label).replace("-", "_");
      if (!["relevant", "irrelevant", "missing_expected"].includes(rawLabel)) {
        throw new CliError(
          "VALIDATION",
          "--label must be relevant, irrelevant, or missing-expected"
        );
      }
      const rawTargetKind = cmdOpts.targetKind;
      if (
        rawTargetKind !== undefined &&
        (typeof rawTargetKind !== "string" ||
          !["document", "chunk", "span"].includes(rawTargetKind))
      ) {
        throw new CliError(
          "VALIDATION",
          "--target-kind must be document, chunk, or span"
        );
      }
      const { traceLabel } = await import("./commands/trace");
      const output = await traceLabel(
        {
          traceId,
          label: rawLabel as "relevant" | "irrelevant" | "missing_expected",
          targetRef: String(cmdOpts.target),
          targetKind: rawTargetKind as
            | "document"
            | "chunk"
            | "span"
            | undefined,
          startLine:
            cmdOpts.fromLine === undefined
              ? undefined
              : parsePositiveInt("from-line", cmdOpts.fromLine),
          endLine:
            cmdOpts.toLine === undefined
              ? undefined
              : parsePositiveInt("to-line", cmdOpts.toLine),
          sourceHash: cmdOpts.sourceHash as string | undefined,
          docid: cmdOpts.docid as string | undefined,
          idempotencyKey: cmdOpts.idempotencyKey as string | undefined,
        },
        {
          configPath: globals.config,
          indexName: globals.index,
          format: outputFormat(cmdOpts),
        }
      );
      process.stdout.write(output);
    });

  traceCmd
    .command("export <trace-ids...>")
    .description("Export immutable terminal traces as one local receipt")
    .option("--format <format>", "agentic-receipt or qrels", "agentic-receipt")
    .option("--output <path>", "write canonical artifact atomically")
    .option("--json", "JSON output")
    .action(async (traceIds: string[], cmdOpts: Record<string, unknown>) => {
      const globals = getGlobals();
      const exportFormat = String(cmdOpts.format);
      if (!["agentic-receipt", "qrels"].includes(exportFormat)) {
        throw new CliError(
          "VALIDATION",
          "--format must be agentic-receipt or qrels"
        );
      }
      const { traceExport } = await import("./commands/trace");
      process.stdout.write(
        await traceExport(traceIds, {
          configPath: globals.config,
          indexName: globals.index,
          format: "json",
          output: cmdOpts.output as string | undefined,
          exportFormat: exportFormat as "agentic-receipt" | "qrels",
        })
      );
    });

  traceCmd
    .command("replay <export-id>")
    .description("Compare one immutable qrels baseline with a candidate")
    .requiredOption("--candidate <type>", "bm25, vector, or hybrid")
    .option("-n, --limit <num>", "result cutoff")
    .option("--candidate-limit <num>", "candidate pool size")
    .option("--no-expand", "disable query expansion")
    .option("--no-rerank", "disable reranking")
    .option("--json", "JSON output")
    .option("--md", "Markdown output")
    .action(async (exportId: string, cmdOpts: Record<string, unknown>) => {
      const globals = getGlobals();
      const candidateType = String(cmdOpts.candidate);
      if (!["bm25", "vector", "hybrid"].includes(candidateType)) {
        throw new CliError(
          "VALIDATION",
          "--candidate must be bm25, vector, or hybrid"
        );
      }
      const { traceReplay } = await import("./commands/replay");
      process.stdout.write(
        await traceReplay(
          exportId,
          {
            id: `cli-${candidateType}`,
            type: candidateType as "bm25" | "vector" | "hybrid",
            limit:
              cmdOpts.limit === undefined
                ? undefined
                : parsePositiveInt("limit", cmdOpts.limit),
            candidateLimit:
              cmdOpts.candidateLimit === undefined
                ? undefined
                : parsePositiveInt("candidate-limit", cmdOpts.candidateLimit),
            noExpand: cmdOpts.expand === false,
            noRerank: cmdOpts.rerank === false,
          },
          {
            configPath: globals.config,
            indexName: globals.index,
            format: outputFormat(cmdOpts),
            offline: globals.offline,
          }
        )
      );
    });

  traceCmd
    .command("delete <trace-id>")
    .description("Delete one trace and every owned local record")
    .option("--json", "JSON output")
    .option("--md", "Markdown output")
    .action(async (traceId: string, cmdOpts: Record<string, unknown>) => {
      const globals = getGlobals();
      const { traceDelete } = await import("./commands/trace");
      process.stdout.write(
        await traceDelete(traceId, {
          configPath: globals.config,
          indexName: globals.index,
          format: outputFormat(cmdOpts),
        })
      );
    });

  traceCmd
    .command("purge")
    .description("Delete every local retrieval trace receipt")
    .option("--json", "JSON output")
    .option("--md", "Markdown output")
    .action(async (cmdOpts: Record<string, unknown>) => {
      const globals = getGlobals();
      if (!globals.yes) {
        throw new CliError(
          "VALIDATION",
          "Trace purge requires the global --yes confirmation"
        );
      }
      const { tracePurge } = await import("./commands/trace");
      process.stdout.write(
        await tracePurge({
          configPath: globals.config,
          indexName: globals.index,
          format: outputFormat(cmdOpts),
        })
      );
    });
}

// ─────────────────────────────────────────────────────────────────────────────
// Search Commands (search, vsearch, query, ask)
// ─────────────────────────────────────────────────────────────────────────────

function wireSearchCommands(program: Command): void {
  // search - BM25 keyword search
  program
    .command("search [query]")
    .description("BM25 keyword search")
    .option(
      "--query-file <path>",
      "read query from file; use - for stdin (keeps the query off argv)"
    )
    .option("-n, --limit <num>", "max results")
    .option("--min-score <num>", "minimum score threshold")
    .option("-c, --collection <name>", "filter by collection")
    .option("--lang <code>", "language filter/hint (BCP-47)")
    .option(
      "--since <date>",
      "modified-at lower bound (ISO date/time or token)"
    )
    .option(
      "--until <date>",
      "modified-at upper bound (ISO date/time or token)"
    )
    .option("--category <values>", "require category match (comma-separated)")
    .option("--filter <json>", "typed custom metadata predicate (JSON)")
    .option("--author <text>", "filter by author (case-insensitive contains)")
    .option("--intent <text>", "disambiguating context for ambiguous queries")
    .option(
      "--exclude <values>",
      "exclude docs containing any term (comma-separated)"
    )
    .option("--tags-all <tags>", "require ALL tags (comma-separated)")
    .option("--tags-any <tags>", "require ANY tag (comma-separated)")
    .option(
      "--project-root <path>",
      "trusted project root (repeatable; replaces cwd affinity)",
      collectRepeatableValue,
      []
    )
    .option("--no-project-affinity", "disable project-aware ranking")
    .option("--full", "include full content")
    .option("--line-numbers", "include line numbers in output")
    .option("--json", "JSON output")
    .option("--md", "Markdown output")
    .option("--csv", "CSV output")
    .option("--xml", "XML output")
    .option("--files", "file paths only")
    .action(
      async (
        queryText: string | undefined,
        cmdOpts: Record<string, unknown>
      ) => {
        const format = getFormat(cmdOpts);
        assertFormatSupported(CMD.search, format);
        const globals = getGlobals();
        queryText = await resolveCliQueryText(queryText, cmdOpts.queryFile);

        // Validate empty query
        if (!queryText.trim()) {
          throw new CliError("VALIDATION", "Query cannot be empty");
        }

        // Validate minScore range
        const minScore = parseOptionalFloat("min-score", cmdOpts.minScore);
        if (minScore !== undefined && (minScore < 0 || minScore > 1)) {
          throw new CliError(
            "VALIDATION",
            "--min-score must be between 0 and 1"
          );
        }

        // Parse and validate tag filters
        let tagsAll: string[] | undefined;
        let tagsAny: string[] | undefined;
        try {
          tagsAll = cmdOpts.tagsAll
            ? parseAndValidateTagFilter(cmdOpts.tagsAll as string)
            : undefined;
          tagsAny = cmdOpts.tagsAny
            ? parseAndValidateTagFilter(cmdOpts.tagsAny as string)
            : undefined;
        } catch (error) {
          throw new CliError(
            "VALIDATION",
            error instanceof Error ? error.message : "Invalid tag filter"
          );
        }

        const limit = cmdOpts.limit
          ? parsePositiveInt("limit", cmdOpts.limit)
          : cmdOpts.verify
            ? 5
            : getDefaultLimit(format);
        const categories = parseCsvValues(cmdOpts.category);
        const exclude = parseCsvValues(cmdOpts.exclude);
        const projectAffinity = parseCliProjectAffinityOptions(cmdOpts);

        const { search, formatSearch } = await import("./commands/search");
        const result = await search(queryText, {
          configPath: globals.config,
          indexName: globals.index,
          limit,
          minScore,
          collection: cmdOpts.collection as string | undefined,
          lang: cmdOpts.lang as string | undefined,
          since: cmdOpts.since as string | undefined,
          until: cmdOpts.until as string | undefined,
          categories,
          author: cmdOpts.author as string | undefined,
          filter: parseCliMetadataFilter(cmdOpts.filter),
          intent: cmdOpts.intent as string | undefined,
          exclude,
          tagsAll,
          tagsAny,
          ...projectAffinity,
          full: Boolean(cmdOpts.full),
          lineNumbers: Boolean(cmdOpts.lineNumbers),
          json: format === "json",
          md: format === "md",
          csv: format === "csv",
          xml: format === "xml",
          files: format === "files",
        });

        // Check success before printing - stdout is for successful outputs only
        if (!result.success) {
          // Map validation errors to exit code 1
          throw new CliError(
            result.isValidation ? "VALIDATION" : "RUNTIME",
            result.error
          );
        }
        const output = formatSearch(result, {
          json: format === "json",
          md: format === "md",
          csv: format === "csv",
          xml: format === "xml",
          files: format === "files",
          full: Boolean(cmdOpts.full),
          lineNumbers: Boolean(cmdOpts.lineNumbers),
          terminalLinks: await resolveTerminalLinkPolicy(format),
        });
        await writeOutput(output, format);
        writeRetrievalTraceReceipt(result.metadata);
      }
    );

  // vsearch - Vector similarity search
  program
    .command("vsearch <query>")
    .description("Vector similarity search")
    .option("-n, --limit <num>", "max results")
    .option("--min-score <num>", "minimum score threshold")
    .option("-c, --collection <name>", "filter by collection")
    .option("--lang <code>", "language filter/hint (BCP-47)")
    .option(
      "--since <date>",
      "modified-at lower bound (ISO date/time or token)"
    )
    .option(
      "--until <date>",
      "modified-at upper bound (ISO date/time or token)"
    )
    .option("--category <values>", "require category match (comma-separated)")
    .option("--filter <json>", "typed custom metadata predicate (JSON)")
    .option("--author <text>", "filter by author (case-insensitive contains)")
    .option("--intent <text>", "disambiguating context for ambiguous queries")
    .option(
      "--exclude <values>",
      "exclude docs containing any term (comma-separated)"
    )
    .option("--tags-all <tags>", "require ALL tags (comma-separated)")
    .option("--tags-any <tags>", "require ANY tag (comma-separated)")
    .option(
      "--project-root <path>",
      "trusted project root (repeatable; replaces cwd affinity)",
      collectRepeatableValue,
      []
    )
    .option("--no-project-affinity", "disable project-aware ranking")
    .option("--full", "include full content")
    .option("--line-numbers", "include line numbers in output")
    .option("--json", "JSON output")
    .option("--md", "Markdown output")
    .option("--csv", "CSV output")
    .option("--xml", "XML output")
    .option("--files", "file paths only")
    .action(async (queryText: string, cmdOpts: Record<string, unknown>) => {
      const format = getFormat(cmdOpts);
      assertFormatSupported(CMD.vsearch, format);
      const globals = getGlobals();

      // Validate empty query
      if (!queryText.trim()) {
        throw new CliError("VALIDATION", "Query cannot be empty");
      }

      // Validate minScore range
      const minScore = parseOptionalFloat("min-score", cmdOpts.minScore);
      if (minScore !== undefined && (minScore < 0 || minScore > 1)) {
        throw new CliError("VALIDATION", "--min-score must be between 0 and 1");
      }

      // Parse and validate tag filters
      let tagsAll: string[] | undefined;
      let tagsAny: string[] | undefined;
      try {
        tagsAll = cmdOpts.tagsAll
          ? parseAndValidateTagFilter(cmdOpts.tagsAll as string)
          : undefined;
        tagsAny = cmdOpts.tagsAny
          ? parseAndValidateTagFilter(cmdOpts.tagsAny as string)
          : undefined;
      } catch (error) {
        throw new CliError(
          "VALIDATION",
          error instanceof Error ? error.message : "Invalid tag filter"
        );
      }

      const limit = cmdOpts.limit
        ? parsePositiveInt("limit", cmdOpts.limit)
        : getDefaultLimit(format);
      const categories = parseCsvValues(cmdOpts.category);
      const exclude = parseCsvValues(cmdOpts.exclude);
      const projectAffinity = parseCliProjectAffinityOptions(cmdOpts);

      const { vsearch, formatVsearch } = await import("./commands/vsearch");
      const result = await vsearch(queryText, {
        configPath: globals.config,
        indexName: globals.index,
        limit,
        minScore,
        collection: cmdOpts.collection as string | undefined,
        lang: cmdOpts.lang as string | undefined,
        since: cmdOpts.since as string | undefined,
        until: cmdOpts.until as string | undefined,
        categories,
        author: cmdOpts.author as string | undefined,
        filter: parseCliMetadataFilter(cmdOpts.filter),
        intent: cmdOpts.intent as string | undefined,
        exclude,
        tagsAll,
        tagsAny,
        ...projectAffinity,
        full: Boolean(cmdOpts.full),
        lineNumbers: Boolean(cmdOpts.lineNumbers),
        json: format === "json",
        md: format === "md",
        csv: format === "csv",
        xml: format === "xml",
        files: format === "files",
      });

      if (!result.success) {
        throw new CliError("RUNTIME", result.error);
      }
      const output = formatVsearch(result, {
        json: format === "json",
        md: format === "md",
        csv: format === "csv",
        xml: format === "xml",
        files: format === "files",
        full: Boolean(cmdOpts.full),
        lineNumbers: Boolean(cmdOpts.lineNumbers),
        terminalLinks: await resolveTerminalLinkPolicy(format),
      });
      await writeOutput(output, format);
      writeRetrievalTraceReceipt(result.metadata);
    });

  // query - Hybrid search with expansion and reranking
  program
    .command("query [query...]")
    .description("Hybrid search with expansion and reranking")
    .option(
      "--query-file <path>",
      "read query from file; use - for stdin (keeps the query off argv)"
    )
    .option("-n, --limit <num>", "max results")
    .option("--min-score <num>", "minimum score threshold")
    .option("-c, --collection <name>", "filter by collection")
    .option("--lang <code>", "language hint (BCP-47)")
    .option(
      "--since <date>",
      "modified-at lower bound (ISO date/time or token)"
    )
    .option(
      "--until <date>",
      "modified-at upper bound (ISO date/time or token)"
    )
    .option("--category <values>", "require category match (comma-separated)")
    .option("--filter <json>", "typed custom metadata predicate (JSON)")
    .option("--author <text>", "filter by author (case-insensitive contains)")
    .option("--intent <text>", "disambiguating context for ambiguous queries")
    .option(
      "--exclude <values>",
      "exclude docs containing any term (comma-separated)"
    )
    .option("--tags-all <tags>", "require ALL tags (comma-separated)")
    .option("--tags-any <tags>", "require ANY tag (comma-separated)")
    .option(
      "--project-root <path>",
      "trusted project root (repeatable; replaces cwd affinity)",
      collectRepeatableValue,
      []
    )
    .option("--no-project-affinity", "disable project-aware ranking")
    .option("--full", "include full content")
    .option("--line-numbers", "include line numbers in output")
    .option("--fast", "skip query expansion, graph expansion, and reranking")
    .option(
      "--thorough",
      "use expansion with a wider rerank pool (slowest, best recall)"
    )
    .option("--no-expand", "disable query expansion")
    .option("--no-rerank", "disable reranking")
    .option("--graph", "enable graph neighbor expansion (default)")
    .option("--no-graph", "disable graph neighbor expansion")
    .option("--target <doc>", "diagnose target document ref")
    .option(
      "--query-mode <mode:text>",
      "structured mode entry (repeatable): term:<text>, intent:<text>, or hyde:<text>",
      (value: string, previous: string[] = []) => [...previous, value],
      []
    )
    .option("-C, --candidate-limit <num>", "max candidates passed to reranking")
    .option("--explain", "include scoring explanation")
    .option("--json", "JSON output")
    .option("--md", "Markdown output")
    .option("--csv", "CSV output")
    .option("--xml", "XML output")
    .option("--files", "file paths only")
    .action(
      async (
        queryParts: string[] | undefined,
        cmdOpts: Record<string, unknown>
      ) => {
        const parts = queryParts ?? [];
        const format = getFormat(cmdOpts);
        const isDiagnose = parts[0] === "diagnose" && Boolean(cmdOpts.target);
        assertFormatSupported(
          isDiagnose ? CMD.queryDiagnose : CMD.query,
          format
        );
        const diagnoseFormat = format === "json" ? "json" : "terminal";
        const globals = getGlobals();
        if (isDiagnose && cmdOpts.queryFile) {
          throw new CliError(
            "VALIDATION",
            "query diagnose does not accept --query-file"
          );
        }
        let queryText = isDiagnose
          ? parts.slice(1).join(" ")
          : await resolveCliQueryText(parts.join(" "), cmdOpts.queryFile);

        // Validate empty query
        if (!queryText.trim()) {
          throw new CliError("VALIDATION", "Query cannot be empty");
        }

        // Validate minScore range
        const minScore = parseOptionalFloat("min-score", cmdOpts.minScore);
        if (minScore !== undefined && (minScore < 0 || minScore > 1)) {
          throw new CliError(
            "VALIDATION",
            "--min-score must be between 0 and 1"
          );
        }

        // Parse optional structured query modes
        let queryModes:
          | import("../pipeline/types").QueryModeInput[]
          | undefined;
        if (Array.isArray(cmdOpts.queryMode) && cmdOpts.queryMode.length > 0) {
          const { parseQueryModeSpecs } =
            await import("../pipeline/query-modes");
          const parsed = parseQueryModeSpecs(cmdOpts.queryMode as string[]);
          if (!parsed.ok) {
            throw new CliError("VALIDATION", parsed.error.message);
          }
          queryModes = parsed.value;
        }

        const { normalizeStructuredQueryInput } =
          await import("../core/structured-query");
        const normalizedInput = normalizeStructuredQueryInput(
          queryText,
          queryModes ?? []
        );
        if (!normalizedInput.ok) {
          throw new CliError("VALIDATION", normalizedInput.error.message);
        }
        queryText = normalizedInput.value.query;
        queryModes =
          normalizedInput.value.queryModes.length > 0
            ? normalizedInput.value.queryModes
            : undefined;

        // Parse and validate tag filters
        let tagsAll: string[] | undefined;
        let tagsAny: string[] | undefined;
        try {
          tagsAll = cmdOpts.tagsAll
            ? parseAndValidateTagFilter(cmdOpts.tagsAll as string)
            : undefined;
          tagsAny = cmdOpts.tagsAny
            ? parseAndValidateTagFilter(cmdOpts.tagsAny as string)
            : undefined;
        } catch (error) {
          throw new CliError(
            "VALIDATION",
            error instanceof Error ? error.message : "Invalid tag filter"
          );
        }

        const limit = cmdOpts.limit
          ? parsePositiveInt("limit", cmdOpts.limit)
          : getDefaultLimit(format);
        const { loadConfig } = await import("../config");
        const { getActivePreset } = await import("../llm/registry");
        const configResult = await loadConfig(globals.config);
        const activePresetId = configResult.ok
          ? getActivePreset(configResult.value).id
          : "slim-tuned";
        const candidateLimit = cmdOpts.candidateLimit
          ? parsePositiveInt("candidate-limit", cmdOpts.candidateLimit)
          : undefined;
        const categories = parseCsvValues(cmdOpts.category);
        const exclude = parseCsvValues(cmdOpts.exclude);
        const projectAffinity = parseCliProjectAffinityOptions(cmdOpts);

        const depthPolicy = resolveDepthPolicy({
          presetId: activePresetId,
          fast: Boolean(cmdOpts.fast),
          thorough: Boolean(cmdOpts.thorough),
          expand: cmdOpts.expand === false ? false : undefined,
          rerank: cmdOpts.rerank === false ? false : undefined,
          candidateLimit,
        });

        if (isDiagnose) {
          const { queryDiagnose, formatQueryDiagnose } =
            await import("./commands/query");
          const result = await queryDiagnose(queryText, {
            configPath: globals.config,
            indexName: globals.index,
            target: cmdOpts.target as string,
            limit,
            minScore,
            collection: cmdOpts.collection as string | undefined,
            lang: cmdOpts.lang as string | undefined,
            since: cmdOpts.since as string | undefined,
            until: cmdOpts.until as string | undefined,
            categories,
            author: cmdOpts.author as string | undefined,
            filter: parseCliMetadataFilter(cmdOpts.filter),
            intent: cmdOpts.intent as string | undefined,
            exclude,
            tagsAll,
            tagsAny,
            ...projectAffinity,
            noExpand: depthPolicy.noExpand,
            noRerank: depthPolicy.noRerank,
            graph: cmdOpts.graph !== false,
            noGraph: Boolean(cmdOpts.fast) || cmdOpts.graph === false,
            candidateLimit: depthPolicy.candidateLimit,
            queryModes,
            json: diagnoseFormat === "json",
          });

          if (!result.success) {
            throw new CliError("RUNTIME", result.error);
          }
          await writeOutput(
            formatQueryDiagnose(result, { format: diagnoseFormat }),
            diagnoseFormat
          );
          return;
        }

        const { query, formatQuery } = await import("./commands/query");
        const result = await query(queryText, {
          configPath: globals.config,
          indexName: globals.index,
          limit,
          minScore,
          collection: cmdOpts.collection as string | undefined,
          lang: cmdOpts.lang as string | undefined,
          since: cmdOpts.since as string | undefined,
          until: cmdOpts.until as string | undefined,
          categories,
          author: cmdOpts.author as string | undefined,
          filter: parseCliMetadataFilter(cmdOpts.filter),
          intent: cmdOpts.intent as string | undefined,
          exclude,
          tagsAll,
          tagsAny,
          ...projectAffinity,
          full: Boolean(cmdOpts.full),
          lineNumbers: Boolean(cmdOpts.lineNumbers),
          noExpand: depthPolicy.noExpand,
          noRerank: depthPolicy.noRerank,
          graph: cmdOpts.graph !== false,
          noGraph: Boolean(cmdOpts.fast) || cmdOpts.graph === false,
          candidateLimit: depthPolicy.candidateLimit,
          queryModes,
          explain: Boolean(cmdOpts.explain),
          json: format === "json",
          md: format === "md",
          csv: format === "csv",
          xml: format === "xml",
          files: format === "files",
        });

        if (!result.success) {
          throw new CliError("RUNTIME", result.error);
        }
        const output = formatQuery(result, {
          format,
          full: Boolean(cmdOpts.full),
          lineNumbers: Boolean(cmdOpts.lineNumbers),
          terminalLinks: await resolveTerminalLinkPolicy(format),
        });
        await writeOutput(output, format);
        writeRetrievalTraceReceipt(result.metadata);
      }
    );

  // bench - Retrieval benchmark fixture runner
  program
    .command("bench <fixture>")
    .description("Run retrieval quality benchmarks from a fixture")
    .option("-c, --collection <name>", "override fixture collection")
    .option("-k, --top-k <num>", "override top-k metric cutoff")
    .option(
      "--mode <name>",
      "benchmark mode (repeatable): bm25, vector, hybrid, fast, no-rerank, thorough",
      (value: string, previous: string[] = []) => [...previous, value],
      []
    )
    .option("-C, --candidate-limit <num>", "max candidates passed to reranking")
    .option("--json", "JSON output")
    .action(async (fixture: string, cmdOpts: Record<string, unknown>) => {
      const format = getFormat(cmdOpts);
      assertFormatSupported(CMD.bench, format);
      const globals = getGlobals();
      const topK = cmdOpts.topK
        ? parsePositiveInt("top-k", cmdOpts.topK)
        : undefined;
      const candidateLimit = cmdOpts.candidateLimit
        ? parsePositiveInt("candidate-limit", cmdOpts.candidateLimit)
        : undefined;

      const { bench, formatBench } = await import("./commands/bench");
      const result = await bench(fixture, {
        configPath: globals.config,
        indexName: globals.index,
        collection: cmdOpts.collection as string | undefined,
        topK,
        candidateLimit,
        modes:
          Array.isArray(cmdOpts.mode) && cmdOpts.mode.length > 0
            ? (cmdOpts.mode as string[])
            : undefined,
        json: format === "json",
      });

      if (!result.success) {
        throw new CliError(
          result.isValidation ? "VALIDATION" : "RUNTIME",
          result.error
        );
      }

      await writeOutput(
        formatBench(result, { json: format === "json" }),
        format
      );
    });

  // ask - Human-friendly query with grounded answer
  program
    .command("ask <query>")
    .description("Human-friendly query with grounded answer")
    .option("-n, --limit <num>", "max source results")
    .option("-c, --collection <name>", "filter by collection")
    .option("--lang <code>", "language hint (BCP-47)")
    .option(
      "--since <date>",
      "modified-at lower bound (ISO date/time or token)"
    )
    .option(
      "--until <date>",
      "modified-at upper bound (ISO date/time or token)"
    )
    .option("--category <values>", "require category match (comma-separated)")
    .option("--filter <json>", "typed custom metadata predicate (JSON)")
    .option("--author <text>", "filter by author (case-insensitive contains)")
    .option("--intent <text>", "disambiguating context for ambiguous queries")
    .option(
      "--exclude <values>",
      "exclude docs containing any term (comma-separated)"
    )
    .option(
      "--query-mode <mode:text>",
      "structured mode entry (repeatable): term:<text>, intent:<text>, or hyde:<text>",
      (value: string, previous: string[] = []) => [...previous, value],
      []
    )
    .option("--fast", "skip query expansion, graph expansion, and reranking")
    .option(
      "--thorough",
      "use expansion with a wider rerank pool (slowest, best recall)"
    )
    .option("-C, --candidate-limit <num>", "max candidates passed to reranking")
    .option("--answer", "generate short grounded answer")
    .option(
      "--verify",
      "generate and verify every claim against a closed Context Capsule"
    )
    .option("--no-answer", "force retrieval-only output")
    .option("--max-answer-tokens <num>", "max answer tokens")
    .option("--context-budget-tokens <num>", "verified Context token budget")
    .option("--context-budget-bytes <num>", "verified Context byte budget")
    .option("--min-score <score>", "minimum retrieval score (0-1)")
    .option("--graph", "include bounded graph expansion (default)")
    .option("--no-graph", "disable graph neighbor expansion")
    .option("--explain", "include retrieval scoring explanation")
    .option(
      "--project-root <path>",
      "trusted project root (repeatable; replaces cwd affinity)",
      collectRepeatableValue,
      []
    )
    .option("--no-project-affinity", "disable project-aware ranking")
    .option("--show-sources", "show all retrieved sources (not just cited)")
    .option("--json", "JSON output")
    .option("--md", "Markdown output")
    .action(async (queryText: string, cmdOpts: Record<string, unknown>) => {
      const format = getFormat(cmdOpts);
      assertFormatSupported(CMD.ask, format);
      const globals = getGlobals();

      // Validate empty query
      if (!queryText.trim()) {
        throw new CliError("VALIDATION", "Query cannot be empty");
      }

      const limit = cmdOpts.limit
        ? parsePositiveInt("limit", cmdOpts.limit)
        : getDefaultLimit(format);
      const { loadConfig } = await import("../config");
      const { getActivePreset } = await import("../llm/registry");
      const configResult = await loadConfig(globals.config);
      const activePresetId = configResult.ok
        ? getActivePreset(configResult.value).id
        : "slim-tuned";
      const candidateLimit = cmdOpts.candidateLimit
        ? parsePositiveInt("candidate-limit", cmdOpts.candidateLimit)
        : undefined;

      // Parse max-answer-tokens (optional, defaults to 512 in command impl)
      const maxAnswerTokens = cmdOpts.maxAnswerTokens
        ? parsePositiveInt("max-answer-tokens", cmdOpts.maxAnswerTokens)
        : undefined;
      const contextBudgetTokens = cmdOpts.contextBudgetTokens
        ? parsePositiveInt("context-budget-tokens", cmdOpts.contextBudgetTokens)
        : undefined;
      const contextBudgetBytes = cmdOpts.contextBudgetBytes
        ? parsePositiveInt("context-budget-bytes", cmdOpts.contextBudgetBytes)
        : undefined;
      const minScore = parseOptionalFloat("min-score", cmdOpts.minScore);
      if (minScore !== undefined && (minScore < 0 || minScore > 1)) {
        throw new CliError("VALIDATION", "min-score must be between 0 and 1");
      }
      if (cmdOpts.verify && cmdOpts.noAnswer) {
        throw new CliError(
          "VALIDATION",
          "--verify cannot be combined with --no-answer"
        );
      }
      const categories = parseCsvValues(cmdOpts.category);
      const exclude = parseCsvValues(cmdOpts.exclude);
      const projectAffinity = parseCliProjectAffinityOptions(cmdOpts);

      let queryModes: import("../pipeline/types").QueryModeInput[] | undefined;
      if (Array.isArray(cmdOpts.queryMode) && cmdOpts.queryMode.length > 0) {
        const { parseQueryModeSpecs } = await import("../pipeline/query-modes");
        const parsed = parseQueryModeSpecs(cmdOpts.queryMode as string[]);
        if (!parsed.ok) {
          throw new CliError("VALIDATION", parsed.error.message);
        }
        queryModes = parsed.value;
      }

      const { normalizeStructuredQueryInput } =
        await import("../core/structured-query");
      const normalizedInput = normalizeStructuredQueryInput(
        queryText,
        queryModes ?? []
      );
      if (!normalizedInput.ok) {
        throw new CliError("VALIDATION", normalizedInput.error.message);
      }
      queryText = normalizedInput.value.query;
      queryModes =
        normalizedInput.value.queryModes.length > 0
          ? normalizedInput.value.queryModes
          : undefined;

      const depthPolicy = resolveDepthPolicy({
        presetId: activePresetId,
        fast: Boolean(cmdOpts.fast),
        thorough: Boolean(cmdOpts.thorough),
        candidateLimit,
        hasStructuredModes: Boolean(queryModes?.length),
      });

      const { ask, formatAsk } = await import("./commands/ask");
      const showSources = Boolean(cmdOpts.showSources);
      const result = await ask(queryText, {
        limit,
        collection: cmdOpts.collection as string | undefined,
        lang: cmdOpts.lang as string | undefined,
        since: cmdOpts.since as string | undefined,
        until: cmdOpts.until as string | undefined,
        categories,
        author: cmdOpts.author as string | undefined,
        filter: parseCliMetadataFilter(cmdOpts.filter),
        intent: cmdOpts.intent as string | undefined,
        exclude,
        minScore,
        graph: !cmdOpts.fast && cmdOpts.graph !== false,
        noGraph: Boolean(cmdOpts.fast) || cmdOpts.graph === false,
        queryModes,
        noExpand: depthPolicy.noExpand,
        noRerank: depthPolicy.noRerank,
        candidateLimit: depthPolicy.candidateLimit,
        explain: Boolean(cmdOpts.explain),
        // Per spec: --answer defaults to false, --no-answer forces retrieval-only
        // Commander creates separate cmdOpts.noAnswer for --no-answer flag
        answer: Boolean(cmdOpts.answer),
        noAnswer: Boolean(cmdOpts.noAnswer),
        verify: Boolean(cmdOpts.verify),
        maxAnswerTokens,
        contextBudgetTokens,
        contextBudgetBytes,
        ...projectAffinity,
        showSources,
        json: format === "json",
        md: format === "md",
      });

      if (!result.success) {
        throw new CliError("RUNTIME", result.error);
      }
      const output = formatAsk(result, {
        json: format === "json",
        md: format === "md",
        showSources,
      });
      await writeOutput(output, format);
      writeRetrievalTraceReceipt(result.metadata);
    });
}

// ─────────────────────────────────────────────────────────────────────────────
// Onboarding Commands (init, index, status, doctor)
// ─────────────────────────────────────────────────────────────────────────────

function wireOnboardingCommands(program: Command): void {
  const profileCmd = program
    .command("profile")
    .description("Inspect a project-local retrieval profile");

  const wireProfileRead = (
    command: "check" | "show" | "diff",
    description: string
  ): void => {
    profileCmd
      .command(`${command} [path]`)
      .description(description)
      .option("--json", "JSON output")
      .action(
        async (path: string | undefined, cmdOpts: Record<string, unknown>) => {
          const globals = getGlobals();
          const json = Boolean(cmdOpts.json) || globals.json;
          const { formatProjectProfileResult, runProjectProfileCommand } =
            await import("./commands/profile");
          const outcome = await runProjectProfileCommand({
            command,
            path,
            configPath: globals.config,
            offline: globals.offline,
          });
          process.stdout.write(
            `${formatProjectProfileResult(outcome.result, { json })}\n`
          );
          if (outcome.exitCode !== 0) {
            throw new CliError(
              outcome.exitCode === 1 ? "VALIDATION" : "RUNTIME",
              "Project profile inspection failed",
              { silent: true }
            );
          }
        }
      );
  };

  wireProfileRead("check", "Validate a project-local retrieval profile");
  wireProfileRead("show", "Show normalized project-local retrieval state");
  wireProfileRead("diff", "Compare a project profile with local config");
  profileCmd
    .command("apply [path]")
    .description("Apply a project profile without implicit deletion")
    .option("--json", "JSON output")
    .action(
      async (path: string | undefined, cmdOpts: Record<string, unknown>) => {
        const globals = getGlobals();
        const json = Boolean(cmdOpts.json) || globals.json;
        const {
          formatProjectProfileApplyResult,
          runProjectProfileApplyCommand,
        } = await import("./commands/profile-apply");
        const outcome = await runProjectProfileApplyCommand({
          path,
          configPath: globals.config,
          indexName: globals.index,
        });
        process.stdout.write(
          `${formatProjectProfileApplyResult(outcome.result, { json })}\n`
        );
        if (outcome.exitCode !== 0) {
          throw new CliError(
            outcome.exitCode === 1 ? "VALIDATION" : "RUNTIME",
            "Project profile apply failed",
            { silent: true }
          );
        }
      }
    );

  // init - Initialize GNO
  program
    .command("init [path]")
    .description("Initialize GNO configuration")
    .option("-n, --name <name>", "collection name")
    .option("--pattern <glob>", "file matching pattern")
    .option("--include <exts>", "extension allowlist (CSV)")
    .option("--exclude <patterns>", "exclude patterns (CSV)")
    .option("--update <cmd>", "shell command to run before indexing")
    .option("--tokenizer <type>", "FTS tokenizer (unicode61, porter, trigram)")
    .option("--language <code>", "language hint (BCP-47)")
    .action(
      async (path: string | undefined, cmdOpts: Record<string, unknown>) => {
        const globals = getGlobals();
        const { init } = await import("./commands/init");
        const result = await init({
          path,
          name: cmdOpts.name as string | undefined,
          pattern: cmdOpts.pattern as string | undefined,
          include: cmdOpts.include as string | undefined,
          exclude: cmdOpts.exclude as string | undefined,
          update: cmdOpts.update as string | undefined,
          tokenizer: cmdOpts.tokenizer as
            | "unicode61"
            | "porter"
            | "trigram"
            | undefined,
          language: cmdOpts.language as string | undefined,
          yes: globals.yes,
          configPath: globals.config,
        });

        if (!result.success) {
          throw new CliError("RUNTIME", result.error ?? "Init failed");
        }

        if (result.alreadyInitialized) {
          process.stdout.write("GNO already initialized.\n");
          if (result.collectionAdded) {
            process.stdout.write(
              `Collection "${result.collectionAdded}" added.\n`
            );
          }
        } else {
          process.stdout.write("GNO initialized successfully.\n");
          process.stdout.write(`Config: ${result.configPath}\n`);
          process.stdout.write(`Database: ${result.dbPath}\n`);
          if (result.collectionAdded) {
            process.stdout.write(
              `Collection "${result.collectionAdded}" added.\n`
            );
          }
        }
      }
    );

  // setup - Verify a folder is lexically retrievable, then hand off semantics
  program
    .command("setup <folder>")
    .description("Add and verify a folder with a real lexical retrieval")
    .option("-n, --name <name>", "collection name")
    .option(
      "--exclude <pattern>",
      "literal exclusion pattern (repeatable)",
      collectRepeatableValue,
      []
    )
    .option(
      "--authorize-secret-risk",
      "explicitly authorize indexing likely secret files"
    )
    .option(
      "--connector <id>",
      "install and verify one connector (repeatable)",
      collectRepeatableValue,
      []
    )
    .option(
      "--apply-profile",
      "apply a valid project profile before lexical setup"
    )
    .option("--no-semantic", "skip background semantic indexing")
    .option("--json", "JSON output")
    .action(async (folder: string, cmdOpts: Record<string, unknown>) => {
      const globals = getGlobals();
      const json = Boolean(cmdOpts.json) || globals.json;
      const {
        formatSetupOutputResult,
        formatSetupProfileAdvisory,
        setupWithActivation,
      } = await import("./commands/setup-activation");
      const exclusions = cmdOpts.exclude as string[];
      const outcome = await setupWithActivation({
        folder,
        name: cmdOpts.name as string | undefined,
        exclude: exclusions.length > 0 ? exclusions : undefined,
        authorizeSecretRisk: Boolean(cmdOpts.authorizeSecretRisk),
        connectorIds: cmdOpts.connector as string[],
        applyProfile: Boolean(cmdOpts.applyProfile),
        semantic: cmdOpts.semantic !== false,
        indexName: globals.index,
        configPath: globals.config,
        offline: globals.offline,
        yes: globals.yes,
        json,
        quiet: globals.quiet,
        progress: (stage) => {
          process.stderr.write(`setup: ${stage}\n`);
        },
        onProfileAdvisory: (profile) => {
          if (json || globals.quiet) return;
          const advisory = formatSetupProfileAdvisory(profile, {
            applyRequested: Boolean(cmdOpts.applyProfile),
          });
          if (advisory) process.stderr.write(`${advisory}\n`);
        },
        onProfileApply: (profile) => {
          if (json || globals.quiet) return;
          process.stderr.write(`setup: project profile ${profile.status}\n`);
        },
      });
      const output = formatSetupOutputResult(outcome.result, { json });
      if (json || outcome.exitCode === 0) {
        process.stdout.write(`${output}\n`);
      } else {
        process.stderr.write(`${output}\n`);
      }
      if (outcome.exitCode !== 0) {
        const setupResult =
          "setup" in outcome.result ? outcome.result.setup : outcome.result;
        throw new CliError(
          outcome.exitCode === 1 ? "VALIDATION" : "RUNTIME",
          setupResult.lexical.error?.message ?? "Setup failed",
          { silent: true }
        );
      }
    });

  // index - Index collections
  addWriteLeaseFlags(
    program
      .command("index [collection]")
      .description("Index files from collections")
      .option("--no-embed", "skip embedding after sync")
      .option("--git-pull", "run git pull in git repositories")
      .option("--models-pull", "download models if missing")
      .option("--json", "JSON output")
  ).action(
    async (
      collection: string | undefined,
      cmdOpts: Record<string, unknown>
    ) => {
      const globals = getGlobals();
      const { index, formatIndex } = await import("./commands/index-cmd");
      const lease = parseWriteLeaseFlags(cmdOpts);
      const opts = {
        configPath: globals.config,
        indexName: globals.index,
        collection,
        noEmbed: cmdOpts.embed === false,
        gitPull: Boolean(cmdOpts.gitPull),
        modelsPull: Boolean(cmdOpts.modelsPull),
        yes: globals.yes,
        verbose: globals.verbose,
        json: getFormat(cmdOpts) === "json",
        lockWaitMs: lease.lockWaitMs,
        noWait: lease.noWait,
      };
      const result = await index(opts);

      if (!result.success) {
        throwIfWriteLeaseBusy(result, opts.json);
        if (!result.stages) {
          throw new CliError("RUNTIME", result.error ?? "Index failed");
        }
        // A stage failed after the run started: emit the partial per-stage
        // receipt, then exit non-zero (fn-132 R4 - never exit 0 on a failed
        // embed stage).
        process.stdout.write(`${formatIndex(result, opts)}\n`);
        throw new CliError("RUNTIME", result.error, { silent: true });
      }
      process.stdout.write(`${formatIndex(result, opts)}\n`);
      if ((result.embedResult?.contentionErrors ?? 0) > 0) {
        throw new CliError(
          "BUSY",
          "Some chunks were deferred by index contention",
          { silent: true }
        );
      }
    }
  );

  // audit - Read-only workspace integrity report
  program
    .command("audit [category]")
    .description("Run read-only workspace integrity audits")
    .option(
      "-c, --collection <name>",
      "collection scope (repeatable)",
      collectRepeatableValue,
      []
    )
    .option(
      "--path <prefix>",
      "collection-relative path prefix (repeatable)",
      collectRepeatableValue,
      []
    )
    .option(
      "--tag <tag>",
      "require tag (repeatable, AND semantics)",
      collectRepeatableValue,
      []
    )
    .option("--max-findings <count>", "maximum returned findings", Number)
    .option("--max-age-days <days>", "explicit age review signal", Number)
    .option(
      "--orphan-root <uri>",
      "URI excluded from orphan findings (repeatable)",
      collectRepeatableValue,
      []
    )
    .option(
      "--orphan-ignore-prefix <prefix>",
      "path prefix excluded from orphan findings (repeatable)",
      collectRepeatableValue,
      []
    )
    .option("--output <path>", "also write the rendered report to a file")
    .option("--no-progress", "disable progress on stderr")
    .option("--json", "JSON output")
    .action(
      async (
        category: string | undefined,
        cmdOpts: Record<string, unknown>
      ) => {
        const { audit, formatAuditReport, writeAuditReport } =
          await import("./commands/audit");
        const globals = getGlobals();
        const json = getFormat(cmdOpts) === "json";
        const showProgress =
          cmdOpts.progress !== false &&
          !globals.quiet &&
          !json &&
          process.stderr.isTTY;
        const controller = new AbortController();
        const abort = (): void => controller.abort();
        process.once("SIGINT", abort);
        try {
          const result = await audit({
            category,
            configPath: globals.config,
            indexName: globals.index,
            collections: cmdOpts.collection as string[],
            paths: cmdOpts.path as string[],
            tags: cmdOpts.tag as string[],
            maxFindings: cmdOpts.maxFindings as number | undefined,
            maxAgeDays: cmdOpts.maxAgeDays as number | undefined,
            orphanRoots: cmdOpts.orphanRoot as string[],
            orphanIgnorePrefixes: cmdOpts.orphanIgnorePrefix as string[],
            signal: controller.signal,
            onProgress: showProgress
              ? ({ phase, completed, total }) => {
                  process.stderr.write(
                    `\rAudit ${phase}: ${completed}/${Math.max(total, 1)}`
                  );
                }
              : undefined,
          });
          if (!result.success) {
            throw new CliError(
              result.invalid ? "VALIDATION" : "RUNTIME",
              result.error
            );
          }
          const rendered = formatAuditReport(result.report, { json });
          process.stdout.write(`${rendered}\n`);
          if (cmdOpts.output) {
            await writeAuditReport(cmdOpts.output as string, result.report, {
              json,
            });
          }
          if (result.exitCode === 2) {
            throw new CliError("RUNTIME", "Audit runtime failure", {
              silent: true,
            });
          }
          if (result.exitCode === 4) {
            throw new CliError("AUDIT_FINDINGS", "Audit findings present", {
              silent: true,
            });
          }
          if (result.exitCode === 5) {
            throw new CliError("AUDIT_PARTIAL", "Audit evidence is partial", {
              silent: true,
            });
          }
        } finally {
          if (showProgress) process.stderr.write("\n");
          process.removeListener("SIGINT", abort);
        }
      }
    );

  // status - Show index status
  program
    .command("status")
    .description("Show index status")
    .option("--json", "JSON output")
    .action(async (cmdOpts: Record<string, unknown>) => {
      const format = getFormat(cmdOpts);
      assertFormatSupported(CMD.status, format);

      const { status, formatStatus } = await import("./commands/status");
      const globals = getGlobals();
      const result = await status({
        configPath: globals.config,
        indexName: globals.index,
        json: format === "json",
      });

      if (!result.success) {
        throw new CliError("RUNTIME", result.error ?? "Status failed");
      }
      process.stdout.write(
        `${formatStatus(result, { json: format === "json" })}\n`
      );
    });

  // peek - Cheap metadata snapshot for integrations
  program
    .command("peek")
    .description("Show a cheap index snapshot for integrations")
    .option("--json", "JSON output")
    .action(async (cmdOpts: Record<string, unknown>) => {
      const format = getFormat(cmdOpts);
      assertFormatSupported(CMD.peek, format);

      const { peek, formatPeek } = await import("./commands/peek");
      const globals = getGlobals();
      const snapshot = await peek({
        configPath: globals.config,
        indexName: globals.index,
      });
      process.stdout.write(
        `${formatPeek(snapshot, { json: format === "json" })}\n`
      );
    });

  // doctor - Diagnose configuration issues
  program
    .command("doctor")
    .description("Diagnose configuration issues")
    .option("--json", "JSON output")
    .action(async (cmdOpts: Record<string, unknown>) => {
      const format = getFormat(cmdOpts);
      const { doctor, formatDoctor, hasCriticalDoctorErrors } =
        await import("./commands/doctor");
      const globals = getGlobals();
      const result = await doctor({
        configPath: globals.config,
        indexName: globals.index,
        json: format === "json",
      });

      process.stdout.write(
        `${formatDoctor(result, { json: format === "json" })}\n`
      );
      if (hasCriticalDoctorErrors(result.checks)) {
        throw new CliError("RUNTIME", "Critical health checks failed", {
          silent: true,
        });
      }
    });
}

function wireCaptureCommand(program: Command): void {
  program
    .command("capture [content...]")
    .description("Capture a note with provenance")
    .option("--stdin", "read capture content from stdin")
    .option("--file <path>", "read capture content from a text/markdown file")
    .option("-c, --collection <name>", "target collection")
    .option("--title <title>", "capture title")
    .option("--path <relPath>", "explicit relative path inside collection")
    .option("--folder <relPath>", "folder path inside collection")
    .option("--preset <id>", "note preset scaffold")
    .option("--tags <tags>", "comma-separated tags")
    .option(
      "--collision-policy <policy>",
      "error, open_existing, or create_with_suffix"
    )
    .option(
      "--source-kind <kind>",
      "direct, web, email, meeting, chat, file, api, or unknown"
    )
    .option("--source-url <url>", "source URL")
    .option("--source-title <title>", "source title")
    .option("--source-author <author>", "source author")
    .option("--source-date <date>", "source observed date/time")
    .option("--source-id <id>", "source external id")
    .option("--json", "JSON output")
    .action(
      async (contentParts: string[], cmdOpts: Record<string, unknown>) => {
        const format = getFormat(cmdOpts);
        assertFormatSupported(CMD.capture, format);
        const globals = getGlobals();
        const { capture, formatCaptureReceipt } =
          await import("./commands/capture");
        const receipt = await capture({
          configPath: globals.config,
          indexName: globals.index,
          inlineContent:
            contentParts.length > 0 ? contentParts.join(" ") : undefined,
          stdin: Boolean(cmdOpts.stdin),
          file: cmdOpts.file as string | undefined,
          collection: cmdOpts.collection as string | undefined,
          title: cmdOpts.title as string | undefined,
          path: cmdOpts.path as string | undefined,
          folder: cmdOpts.folder as string | undefined,
          preset: cmdOpts.preset as never,
          tags: cmdOpts.tags as string | undefined,
          collisionPolicy: cmdOpts.collisionPolicy as never,
          sourceKind: cmdOpts.sourceKind as never,
          sourceUrl: cmdOpts.sourceUrl as string | undefined,
          sourceTitle: cmdOpts.sourceTitle as string | undefined,
          sourceAuthor: cmdOpts.sourceAuthor as string | undefined,
          sourceDate: cmdOpts.sourceDate as string | undefined,
          sourceId: cmdOpts.sourceId as string | undefined,
        });
        const output = formatCaptureReceipt(receipt, {
          json: format === "json",
          quiet: globals.quiet,
        });
        await writeOutput(output, format);
      }
    );
}

// ─────────────────────────────────────────────────────────────────────────────
// Memory Commands (remember, recall)
// ─────────────────────────────────────────────────────────────────────────────

function wireMemoryCommands(program: Command): void {
  program
    .command("remember <text>")
    .description("Store a fact in a memory-managed collection")
    .option("-c, --collection <name>", "memory-managed target collection")
    .option(
      "--scope <scope>",
      "explicit scope (repeatable, required; no implicit global scope)",
      collectRepeatableValue,
      []
    )
    .option("--decision <decision>", "add or supersede (omit for candidates)")
    .option("--add", "shorthand for --decision add")
    .option(
      "--supersede <uri>",
      "shorthand for --decision supersede --predecessor <uri>"
    )
    .option("--predecessor <uri>", "predecessor gno:// URI for supersede")
    .option(
      "--predecessor-hash <hash>",
      "predecessor contentHash from recall (required for supersede)"
    )
    .option(
      "--receipt <path>",
      "recall receipt JSON to fence against (recall --json output)"
    )
    .option(
      "--derived-from <uri>",
      "declared origin of the fact (repeatable; gno:// origins are fenced)",
      collectRepeatableValue,
      []
    )
    .option("--source <text>", "free-form source evidence")
    .option(
      "--caller <id>",
      "caller identity (default: $GNO_MEMORY_CALLER or cli:<user>)"
    )
    .option(
      "--session <id>",
      "session identity (default: $GNO_MEMORY_SESSION or ppid:<pid>)"
    )
    .option("--json", "JSON output")
    .action(async (text: string, cmdOpts: Record<string, unknown>) => {
      const format = getFormat(cmdOpts);
      const globals = getGlobals();
      const { formatRememberResult, remember } =
        await import("./commands/memory");
      const result = await remember({
        configPath: globals.config,
        indexName: globals.index,
        text,
        collection: cmdOpts.collection as string | undefined,
        scopes: cmdOpts.scope as string[],
        decision: cmdOpts.decision as string | undefined,
        add: Boolean(cmdOpts.add),
        supersede: cmdOpts.supersede as string | undefined,
        predecessor: cmdOpts.predecessor as string | undefined,
        predecessorHash: cmdOpts.predecessorHash as string | undefined,
        receipt: cmdOpts.receipt as string | undefined,
        derivedFrom: cmdOpts.derivedFrom as string[],
        source: cmdOpts.source as string | undefined,
        caller: cmdOpts.caller as string | undefined,
        session: cmdOpts.session as string | undefined,
      });
      await writeOutput(
        formatRememberResult(result, {
          json: format === "json",
          quiet: globals.quiet,
        }),
        format
      );
    });

  program
    .command("recall <query>")
    .description("Recall current facts from a memory-managed collection")
    .option("-c, --collection <name>", "memory-managed collection")
    .option(
      "--scope <scope>",
      "explicit scope (repeatable, required; no implicit global scope)",
      collectRepeatableValue,
      []
    )
    .option("--max-facts <n>", "budget override: max facts (default 8)")
    .option(
      "--max-tokens <n>",
      "budget override: max payload tokens (default 512)"
    )
    .option(
      "--caller <id>",
      "caller identity (default: $GNO_MEMORY_CALLER or cli:<user>)"
    )
    .option(
      "--session <id>",
      "session identity (default: $GNO_MEMORY_SESSION or ppid:<pid>)"
    )
    .option("--json", "JSON output")
    .action(async (query: string, cmdOpts: Record<string, unknown>) => {
      const format = getFormat(cmdOpts);
      const globals = getGlobals();
      const { formatRecallResult, recall } = await import("./commands/memory");
      const result = await recall({
        configPath: globals.config,
        indexName: globals.index,
        query,
        collection: cmdOpts.collection as string | undefined,
        scopes: cmdOpts.scope as string[],
        maxFacts: cmdOpts.maxFacts as number | undefined,
        maxTokens: cmdOpts.maxTokens as number | undefined,
        caller: cmdOpts.caller as string | undefined,
        session: cmdOpts.session as string | undefined,
      });
      await writeOutput(
        formatRecallResult(result, {
          json: format === "json",
          quiet: globals.quiet,
        }),
        format
      );
    });
}

// ─────────────────────────────────────────────────────────────────────────────
// Retrieval Commands (get, multi-get, ls)
// ─────────────────────────────────────────────────────────────────────────────

function wireRetrievalCommands(program: Command): void {
  // get - Retrieve document by URI or docid
  program
    .command("get <ref>")
    .description("Get document by URI or docid")
    .option(
      "--from <line>",
      "Start at line number",
      parsePositiveInt.bind(null, "from")
    )
    .option(
      "-l, --limit <lines>",
      "Limit to N lines",
      parsePositiveInt.bind(null, "limit")
    )
    .option("--line-numbers", "Prefix lines with numbers")
    .option("--trace-id <id>", "Continue an open retrieval trace")
    .option("--source", "Include source metadata")
    .option("--json", "JSON output")
    .option("--md", "Markdown output")
    .action(async (ref: string, cmdOpts: Record<string, unknown>) => {
      const format = getFormat(cmdOpts);
      assertFormatSupported(CMD.get, format);
      const globals = getGlobals();

      const { get, formatGet } = await import("./commands/get");
      const result = await get(ref, {
        configPath: globals.config,
        indexName: globals.index,
        from: cmdOpts.from as number | undefined,
        limit: cmdOpts.limit as number | undefined,
        lineNumbers: Boolean(cmdOpts.lineNumbers),
        source: Boolean(cmdOpts.source),
        json: format === "json",
        md: format === "md",
        traceId: cmdOpts.traceId as string | undefined,
      });

      if (!result.success) {
        throw new CliError(
          result.isValidation ? "VALIDATION" : "RUNTIME",
          result.error
        );
      }

      process.stdout.write(
        `${formatGet(result, {
          lineNumbers: Boolean(cmdOpts.lineNumbers),
          json: format === "json",
          md: format === "md",
        })}\n`
      );
      writeRetrievalTraceReceipt(result.metadata);
    });

  // multi-get - Retrieve multiple documents
  program
    .command("multi-get <refs...>")
    .description("Get multiple documents by URI or docid")
    .option(
      "--max-bytes <n>",
      "Max bytes per document",
      parsePositiveInt.bind(null, "max-bytes")
    )
    .option("--line-numbers", "Include line numbers")
    .option("--json", "JSON output")
    .option("--files", "File protocol output")
    .option("--md", "Markdown output")
    .action(async (refs: string[], cmdOpts: Record<string, unknown>) => {
      const format = getFormat(cmdOpts);
      assertFormatSupported(CMD.multiGet, format);
      const globals = getGlobals();

      const { multiGet, formatMultiGet } = await import("./commands/multi-get");
      const result = await multiGet(refs, {
        configPath: globals.config,
        indexName: globals.index,
        maxBytes: cmdOpts.maxBytes as number | undefined,
        lineNumbers: Boolean(cmdOpts.lineNumbers),
        json: format === "json",
        files: format === "files",
        md: format === "md",
      });

      if (!result.success) {
        throw new CliError(
          result.isValidation ? "VALIDATION" : "RUNTIME",
          result.error
        );
      }

      process.stdout.write(
        `${formatMultiGet(result, {
          lineNumbers: Boolean(cmdOpts.lineNumbers),
          json: format === "json",
          files: format === "files",
          md: format === "md",
        })}\n`
      );
    });

  // ls - List indexed documents
  program
    .command("ls [scope]")
    .description("List indexed documents")
    .option(
      "-n, --limit <num>",
      "Max results",
      parsePositiveInt.bind(null, "limit")
    )
    .option(
      "--offset <num>",
      "Skip first N results",
      parsePositiveInt.bind(null, "offset")
    )
    .option("--json", "JSON output")
    .option("--files", "File protocol output")
    .option("--md", "Markdown output")
    .action(
      async (scope: string | undefined, cmdOpts: Record<string, unknown>) => {
        const format = getFormat(cmdOpts);
        assertFormatSupported(CMD.ls, format);
        const globals = getGlobals();

        const { ls, formatLs } = await import("./commands/ls");
        const result = await ls(scope, {
          configPath: globals.config,
          limit: cmdOpts.limit as number | undefined,
          offset: cmdOpts.offset as number | undefined,
          json: format === "json",
          files: format === "files",
          md: format === "md",
        });

        if (!result.success) {
          throw new CliError(
            result.isValidation ? "VALIDATION" : "RUNTIME",
            result.error
          );
        }

        const output = formatLs(result, {
          json: format === "json",
          files: format === "files",
          md: format === "md",
        });
        await writeOutput(output, format);
      }
    );
}

// ─────────────────────────────────────────────────────────────────────────────
// MCP Commands
// ─────────────────────────────────────────────────────────────────────────────

function wireMcpCommand(program: Command): void {
  // mcp - Start MCP server (stdio transport) or manage MCP configuration
  const mcpCmd = program
    .command("mcp")
    .description("MCP server and configuration");

  // Default action: start MCP server
  mcpCmd
    .command("serve", { isDefault: true })
    .description("Start MCP server (stdio transport)")
    .option(
      "--enable-write",
      "Enable write operations (capture, add-collection, sync, remove-collection)"
    )
    .option(
      "--tool-profile <profile>",
      "advertised tool set: core (7 read tools + capture/remember with --enable-write) or full (default)"
    )
    .action(async (cmdOpts: Record<string, unknown>) => {
      const { mcpCommand } = await import("./commands/mcp.js");
      const globalOpts = program.opts();
      const globals = parseGlobalOptions(globalOpts);
      await mcpCommand(globals, {
        enableWrite: cmdOpts.enableWrite === true ? true : undefined,
        toolProfile: parseToolProfileOption(cmdOpts.toolProfile),
      });
    });

  // install - Install gno MCP server to client configs
  mcpCmd
    .command("install")
    .description("Install gno as MCP server in client configuration")
    .option(
      "-t, --target <target>",
      "target client (claude-desktop, cursor, zed, windsurf, opencode, amp, lmstudio, librechat, claude-code, codex)",
      "claude-desktop"
    )
    .option(
      "-s, --scope <scope>",
      "scope (user, project) - defaults to project for LibreChat and user otherwise"
    )
    .option("-f, --force", "overwrite existing configuration")
    .option("--dry-run", "show what would be done without making changes")
    .option(
      "--enable-write",
      "Enable write operations in installed MCP configuration"
    )
    .option(
      "--tool-profile <profile>",
      "advertised tool set the registration starts with: core (7 read tools + capture/remember with --enable-write) or full (default)"
    )
    .option("--json", "JSON output")
    .action(async (cmdOpts: Record<string, unknown>) => {
      const target = cmdOpts.target as string;
      const toolProfile = parseToolProfileOption(cmdOpts.toolProfile);
      const requestedScope = cmdOpts.scope;

      // Import MCP_TARGETS for validation
      const { getDefaultTargetScope, MCP_TARGETS } =
        await import("./commands/mcp/paths.js");

      // Validate target
      if (!(MCP_TARGETS as string[]).includes(target)) {
        throw new CliError(
          "VALIDATION",
          `Invalid target: ${target}. Must be one of: ${MCP_TARGETS.join(", ")}.`
        );
      }
      // Validate an explicit scope, then let the target choose its default.
      if (
        requestedScope !== undefined &&
        (typeof requestedScope !== "string" ||
          !["user", "project"].includes(requestedScope))
      ) {
        throw new CliError(
          "VALIDATION",
          `Invalid scope: ${JSON.stringify(requestedScope)}. Must be 'user' or 'project'.`
        );
      }
      const scope =
        typeof requestedScope === "string"
          ? requestedScope
          : getDefaultTargetScope(
              target as Parameters<typeof getDefaultTargetScope>[0]
            );

      const { installMcp } = await import("./commands/mcp/install.js");
      const globals = getGlobals();
      await installMcp({
        target: target as NonNullable<
          Parameters<typeof installMcp>[0]
        >["target"],
        scope: scope as "user" | "project",
        force: Boolean(cmdOpts.force),
        dryRun: Boolean(cmdOpts.dryRun),
        enableWrite: Boolean(cmdOpts.enableWrite),
        toolProfile,
        indexName: globals.index,
        configPath: globals.config,
        // Pass undefined if not set, so global --json can take effect
        json: cmdOpts.json === true ? true : undefined,
      });
    });

  // uninstall - Remove gno MCP server from client configs
  mcpCmd
    .command("uninstall")
    .description("Remove gno MCP server from client configuration")
    .option(
      "-t, --target <target>",
      "target client (claude-desktop, cursor, zed, windsurf, opencode, amp, lmstudio, librechat, claude-code, codex)",
      "claude-desktop"
    )
    .option(
      "-s, --scope <scope>",
      "scope (user, project) - defaults to project for LibreChat and user otherwise"
    )
    .option("--json", "JSON output")
    .action(async (cmdOpts: Record<string, unknown>) => {
      const target = cmdOpts.target as string;
      const requestedScope = cmdOpts.scope;

      // Import MCP_TARGETS for validation
      const { getDefaultTargetScope, MCP_TARGETS } =
        await import("./commands/mcp/paths.js");

      // Validate target
      if (!(MCP_TARGETS as string[]).includes(target)) {
        throw new CliError(
          "VALIDATION",
          `Invalid target: ${target}. Must be one of: ${MCP_TARGETS.join(", ")}.`
        );
      }
      // Validate an explicit scope, then let the target choose its default.
      if (
        requestedScope !== undefined &&
        (typeof requestedScope !== "string" ||
          !["user", "project"].includes(requestedScope))
      ) {
        throw new CliError(
          "VALIDATION",
          `Invalid scope: ${JSON.stringify(requestedScope)}. Must be 'user' or 'project'.`
        );
      }
      const scope =
        typeof requestedScope === "string"
          ? requestedScope
          : getDefaultTargetScope(
              target as Parameters<typeof getDefaultTargetScope>[0]
            );

      const { uninstallMcp } = await import("./commands/mcp/uninstall.js");
      await uninstallMcp({
        target: target as NonNullable<
          Parameters<typeof uninstallMcp>[0]
        >["target"],
        scope: scope as "user" | "project",
        // Pass undefined if not set, so global --json can take effect
        json: cmdOpts.json === true ? true : undefined,
      });
    });

  // status - Show MCP installation status
  mcpCmd
    .command("status")
    .description("Show MCP server installation status")
    .option(
      "-t, --target <target>",
      "filter by target (claude-desktop, cursor, zed, windsurf, opencode, amp, lmstudio, librechat, claude-code, codex, all)",
      "all"
    )
    .option(
      "-s, --scope <scope>",
      "filter by scope (user, project, all)",
      "all"
    )
    .option("--json", "JSON output")
    .action(async (cmdOpts: Record<string, unknown>) => {
      const target = cmdOpts.target as string;
      const scope = cmdOpts.scope as string;

      // Import MCP_TARGETS for validation
      const { getTargetDisplayName, getTargetScopes, MCP_TARGETS } =
        await import("./commands/mcp/paths.js");

      // Validate target
      if (target !== "all" && !(MCP_TARGETS as string[]).includes(target)) {
        throw new CliError(
          "VALIDATION",
          `Invalid target: ${target}. Must be one of: ${MCP_TARGETS.join(", ")}, all.`
        );
      }
      // Validate scope
      if (!["user", "project", "all"].includes(scope)) {
        throw new CliError(
          "VALIDATION",
          `Invalid scope: ${scope}. Must be 'user', 'project', or 'all'.`
        );
      }
      // Validate target/scope combination
      if (
        target !== "all" &&
        scope !== "all" &&
        !getTargetScopes(
          target as Parameters<typeof getTargetScopes>[0]
        ).includes(scope as "user" | "project")
      ) {
        throw new CliError(
          "VALIDATION",
          `${getTargetDisplayName(target as Parameters<typeof getTargetDisplayName>[0])} does not support ${scope} scope.`
        );
      }

      const { statusMcp } = await import("./commands/mcp/status.js");
      await statusMcp({
        target: target as NonNullable<
          Parameters<typeof statusMcp>[0]
        >["target"],
        scope: scope as "user" | "project" | "all",
        // Pass undefined if not set, so global --json can take effect
        json: cmdOpts.json === true ? true : undefined,
      });
    });
}

// ─────────────────────────────────────────────────────────────────────────────
// Management Commands (collection, context, models, update, embed, cleanup)
// ─────────────────────────────────────────────────────────────────────────────

function wireManagementCommands(program: Command): void {
  // collection subcommands
  const collectionCmd = program
    .command("collection")
    .description("Manage collections");

  collectionCmd
    .command("add <path>")
    .description("Add a collection")
    .requiredOption("-n, --name <name>", "collection name")
    .option("--pattern <glob>", "file matching pattern")
    .option("--include <exts>", "extension allowlist (CSV)")
    .option("--exclude <patterns>", "exclude patterns (CSV)")
    .option("--embed-model <uri>", "collection-specific embedding model URI")
    .option("--update <cmd>", "shell command to run before indexing")
    .action(async (path: string, cmdOpts: Record<string, unknown>) => {
      const { collectionAdd } = await import("./commands/collection");
      await collectionAdd(path, {
        embedModel: cmdOpts.embedModel as string | undefined,
        name: cmdOpts.name as string,
        pattern: cmdOpts.pattern as string | undefined,
        include: cmdOpts.include as string | undefined,
        exclude: cmdOpts.exclude as string | undefined,
        update: cmdOpts.update as string | undefined,
        configPath: getGlobals().config,
      });
    });

  collectionCmd
    .command("list")
    .description("List collections")
    .option("--json", "JSON output")
    .option("--md", "Markdown output")
    .action(async (cmdOpts: Record<string, unknown>) => {
      const format = getFormat(cmdOpts);
      assertFormatSupported(CMD.collectionList, format);

      const { collectionList } = await import("./commands/collection");
      await collectionList({
        json: format === "json",
        md: format === "md",
      });
    });

  collectionCmd
    .command("remove <name>")
    .description("Remove a collection")
    .action(async (name: string) => {
      const { collectionRemove } = await import("./commands/collection");
      await collectionRemove(name, { configPath: getGlobals().config });
    });

  collectionCmd
    .command("rename <old> <new>")
    .description("Rename a collection")
    .action(async (oldName: string, newName: string) => {
      const { collectionRename } = await import("./commands/collection");
      await collectionRename(oldName, newName, {
        configPath: getGlobals().config,
      });
    });

  addWriteLeaseFlags(
    collectionCmd
      .command("clear-embeddings <name>")
      .description("Clear stale or all embeddings for a collection")
      .option("--all", "remove all embeddings for the collection")
      .option("--json", "JSON output")
  ).action(async (name: string, cmdOpts: Record<string, unknown>) => {
    const { collectionClearEmbeddings } = await import("./commands/collection");
    const json = Boolean(cmdOpts.json);
    const lease = parseWriteLeaseFlags(cmdOpts);
    const result = await withCliWriteLease(
      {
        indexName: getGlobals().index,
        lockWaitMs: lease.lockWaitMs,
        noWait: lease.noWait,
      },
      async () => {
        await collectionClearEmbeddings(name, {
          all: Boolean(cmdOpts.all),
          indexName: getGlobals().index,
          json,
        });
        return { success: true as const };
      }
    );
    throwIfWriteLeaseBusy(result, json);
  });

  const collectionPolicyCmd = collectionCmd
    .command("policy")
    .description("Inspect and change collection egress policy");

  collectionPolicyCmd
    .command("get <name>")
    .description("Show effective policy, source, and confirmation revision")
    .action(async (name: string) => {
      const { collectionPolicyGet } = await import("./commands/collection");
      await collectionPolicyGet(name, { configPath: getGlobals().config });
    });

  collectionPolicyCmd
    .command("set <name> <policy>")
    .description("Set local_only, lan, or remote policy")
    .option(
      "--confirm-relaxation <current-revision>",
      "confirm relaxation against the current policy revision"
    )
    .action(
      async (
        name: string,
        policy: string,
        cmdOpts: Record<string, unknown>
      ) => {
        if (!["local_only", "lan", "remote"].includes(policy)) {
          throw new CliError(
            "VALIDATION",
            "Policy must be local_only, lan, or remote"
          );
        }
        const { collectionPolicySet } = await import("./commands/collection");
        await collectionPolicySet(
          name,
          policy as "local_only" | "lan" | "remote",
          {
            configPath: getGlobals().config,
            confirmRelaxation: cmdOpts.confirmRelaxation as string | undefined,
          }
        );
      }
    );

  collectionPolicyCmd
    .command("check")
    .description("Check or explain an exact egress decision without acting")
    .requiredOption("--action <action>", "egress action")
    .requiredOption(
      "--destination <zone>",
      "local_process, loopback, lan, remote"
    )
    .requiredOption("--content-class <class>", "content class")
    .option(
      "-c, --collection <name>",
      "collection scope (repeatable)",
      collectRepeatableValue,
      []
    )
    .option("--authenticated", "caller authentication succeeded")
    .option("--authorized", "operation authorization succeeded")
    .option("--partial", "explicitly permit partial collection results")
    .option(
      "--explain-egress",
      "return the same decision contract without performing an action"
    )
    .action(async (cmdOpts: Record<string, unknown>) => {
      const { collectionPolicyCheck } = await import("./commands/collection");
      await collectionPolicyCheck(
        {
          collections: cmdOpts.collection as string[],
          action: cmdOpts.action as Parameters<
            typeof collectionPolicyCheck
          >[0]["action"],
          destinationZone: cmdOpts.destination as Parameters<
            typeof collectionPolicyCheck
          >[0]["destinationZone"],
          contentClass: cmdOpts.contentClass as Parameters<
            typeof collectionPolicyCheck
          >[0]["contentClass"],
          authenticated: Boolean(cmdOpts.authenticated),
          authorized: Boolean(cmdOpts.authorized),
          partial: Boolean(cmdOpts.partial),
        },
        { configPath: getGlobals().config }
      );
    });

  const egressAuditCmd = program
    .command("egress-audit")
    .description("Manage local content-free egress audit receipts");
  egressAuditCmd
    .command("list")
    .option("--limit <count>", "page size", Number)
    .option("--cursor <cursor>", "opaque next-page cursor")
    .action(async (cmdOpts: Record<string, unknown>) => {
      const { egressAuditList } = await import("./commands/egress-audit");
      await egressAuditList(
        {
          limit: cmdOpts.limit as number | undefined,
          cursor: cmdOpts.cursor as string | undefined,
        },
        { configPath: getGlobals().config }
      );
    });
  egressAuditCmd.command("show <audit-id>").action(async (auditId: string) => {
    const { egressAuditShow } = await import("./commands/egress-audit");
    await egressAuditShow(auditId, { configPath: getGlobals().config });
  });
  egressAuditCmd.command("status").action(async () => {
    const { egressAuditStatus } = await import("./commands/egress-audit");
    await egressAuditStatus({ configPath: getGlobals().config });
  });
  egressAuditCmd
    .command("delete <audit-id>")
    .action(async (auditId: string) => {
      const { egressAuditDelete } = await import("./commands/egress-audit");
      await egressAuditDelete(auditId, { configPath: getGlobals().config });
    });
  egressAuditCmd.command("purge").action(async () => {
    const { egressAuditPurge } = await import("./commands/egress-audit");
    await egressAuditPurge({ configPath: getGlobals().config });
  });

  // context subcommands
  const contextCmd = program
    .command("context")
    .description("Manage context items");

  contextCmd
    .command("add <scope> <text>")
    .description("Add context metadata for a scope")
    .action(async (scope: string, text: string) => {
      const { contextAdd } = await import("./commands/context");
      const exitCode = await contextAdd(scope, text, {
        configPath: getGlobals().config,
      });
      if (exitCode !== 0) {
        throw new CliError("VALIDATION", "Failed to add context");
      }
    });

  contextCmd
    .command("list")
    .description("List context items")
    .option("--json", "JSON output")
    .option("--md", "Markdown output")
    .action(async (cmdOpts: Record<string, unknown>) => {
      const format = getFormat(cmdOpts);
      assertFormatSupported(CMD.contextList, format);

      const { contextList } = await import("./commands/context");
      await contextList(format as "terminal" | "json" | "md");
    });

  contextCmd
    .command("check")
    .description("Check context configuration")
    .option("--json", "JSON output")
    .option("--md", "Markdown output")
    .action(async (cmdOpts: Record<string, unknown>) => {
      const format = getFormat(cmdOpts);
      assertFormatSupported(CMD.contextCheck, format);

      const { contextCheck } = await import("./commands/context");
      await contextCheck(format as "terminal" | "json" | "md");
    });

  contextCmd
    .command("build <goal...>")
    .description("Build a deterministic evidence Capsule")
    .requiredOption("--budget <tokens>", "global token budget")
    .option("--bytes <bytes>", "global byte budget")
    .option("--query <query>", "retrieval query (defaults to goal)")
    .option(
      "--query-mode <mode:text>",
      "structured mode entry (repeatable): term:<text>, intent:<text>, or hyde:<text>",
      (value: string, previous: string[] = []) => [...previous, value],
      []
    )
    .option(
      "-c, --collection <name>",
      "collection filter (repeatable)",
      (value: string, previous: string[] = []) => [...previous, value],
      []
    )
    .option("--uri-prefix <uri>", "canonical GNO URI prefix")
    .option("--tags-all <tags>", "require ALL tags (comma-separated)")
    .option("--tags-any <tags>", "require ANY tag (comma-separated)")
    .option("--category <values>", "require category match (comma-separated)")
    .option("--filter <json>", "typed custom metadata predicate (JSON)")
    .option("--author <text>", "filter by author")
    .option("--lang <code>", "language hint (BCP-47)")
    .option("--since <date>", "modified-at lower bound")
    .option("--until <date>", "modified-at upper bound")
    .option("--graph", "enable graph neighbor expansion (default)")
    .option("--no-graph", "disable graph neighbor expansion")
    .option(
      "--project-root <path>",
      "trusted project root (repeatable; replaces cwd affinity)",
      collectRepeatableValue,
      []
    )
    .option("--no-project-affinity", "disable project-aware ranking")
    .option("--fast", "use lexical-first retrieval without graph or rerank")
    .option("--thorough", "use a wider retrieval pool")
    .option("-n, --limit <num>", "maximum retrieved results")
    .option("-C, --candidate-limit <num>", "maximum rerank candidates")
    .option("--safety-margin <tokens>", "reserved token margin", "0")
    .option("--safety-margin-bytes <bytes>", "reserved byte margin", "0")
    .option("--output <path>", "write only to this explicit file")
    .option("--json", "canonical JSON output")
    .option("--md", "readable Markdown output")
    .action(async (goalParts: string[], cmdOpts: Record<string, unknown>) => {
      const format = getFormat(cmdOpts);
      assertFormatSupported(CMD.contextBuild, format);
      const outputPath = validateContextOutputPath(cmdOpts.output);
      if (cmdOpts.fast && cmdOpts.thorough) {
        throw new CliError("VALIDATION", "Choose either --fast or --thorough");
      }
      const globals = getGlobals();
      const projectAffinity = parseCliProjectAffinityOptions(cmdOpts);
      const { contextBuild } = await import("./commands/context-build");
      let queryModes: import("../pipeline/types").QueryModeInput[] | undefined;
      if (Array.isArray(cmdOpts.queryMode) && cmdOpts.queryMode.length > 0) {
        const { parseQueryModeSpecs } = await import("../pipeline/query-modes");
        const parsed = parseQueryModeSpecs(cmdOpts.queryMode as string[]);
        if (!parsed.ok) {
          throw new CliError("VALIDATION", parsed.error.message, {
            details: { contextCode: "invalid_filter" },
          });
        }
        queryModes = parsed.value;
      }
      const output = await contextBuild(goalParts.join(" "), {
        configPath: globals.config,
        indexName: globals.index,
        budgetTokens: parseContextInteger("budget", cmdOpts.budget),
        budgetBytes:
          cmdOpts.bytes === undefined
            ? undefined
            : parseContextInteger("bytes", cmdOpts.bytes),
        safetyMarginTokens: parseContextInteger(
          "safety-margin",
          cmdOpts.safetyMargin ?? "0",
          true
        ),
        safetyMarginBytes: parseContextInteger(
          "safety-margin-bytes",
          cmdOpts.safetyMarginBytes ?? "0",
          true
        ),
        query: cmdOpts.query as string | undefined,
        ...projectAffinity,
        queryModes,
        collections: cmdOpts.collection as string[],
        uriPrefix: cmdOpts.uriPrefix as string | undefined,
        tagsAll: parseCsvValues(cmdOpts.tagsAll),
        tagsAny: parseCsvValues(cmdOpts.tagsAny),
        categories: parseCsvValues(cmdOpts.category),
        author: cmdOpts.author as string | undefined,
        filter: parseCliMetadataFilter(cmdOpts.filter),
        lang: cmdOpts.lang as string | undefined,
        since: cmdOpts.since as string | undefined,
        until: cmdOpts.until as string | undefined,
        graph: !cmdOpts.fast && cmdOpts.graph !== false,
        limit:
          cmdOpts.limit === undefined
            ? undefined
            : parseContextInteger("limit", cmdOpts.limit),
        candidateLimit:
          cmdOpts.candidateLimit === undefined
            ? undefined
            : parseContextInteger("candidate-limit", cmdOpts.candidateLimit),
        depthPolicy: cmdOpts.fast
          ? "fast"
          : cmdOpts.thorough
            ? "thorough"
            : "balanced",
        format: format === "json" ? "json" : "md",
      });
      if (outputPath !== undefined) {
        await Bun.write(outputPath, output);
        return;
      }
      await writeOutput(output, format === "json" ? "json" : "md");
    });

  contextCmd
    .command("verify <file>")
    .description("Verify a saved Context Capsule without rebuilding it")
    .option("--output <path>", "write only to this explicit file")
    .option("--json", "canonical JSON receipt")
    .option("--md", "readable Markdown receipt")
    .action(
      async (
        file: string,
        cmdOpts: Record<string, unknown>,
        command: Command
      ) => {
        const format = getFormat(cmdOpts);
        assertFormatSupported(CMD.contextVerify, format);
        const outputPath = validateContextOutputPath(cmdOpts.output);
        const globals = getGlobals();
        const explicitIndexName =
          command.getOptionValueSourceWithGlobals("index") === "cli"
            ? globals.index
            : undefined;
        const { contextVerify } = await import("./commands/context-verify");
        const output = await contextVerify(file, {
          configPath: globals.config,
          indexName: explicitIndexName,
          format: format === "json" ? "json" : "md",
        });
        if (outputPath !== undefined) {
          await Bun.write(outputPath, output);
          return;
        }
        await writeOutput(output, format === "json" ? "json" : "md");
      }
    );

  contextCmd
    .command("watch <file>")
    .description("Watch a saved Context Capsule for evidence changes")
    .option("--question <text>", "question associated with this Capsule")
    .option("--label <text>", "short local label")
    .option("--notify", "emit metadata-only local reverification events")
    .option("--json", "JSON output")
    .action(
      async (
        file: string,
        cmdOpts: Record<string, unknown>,
        command: Command
      ) => {
        const format = getFormat(cmdOpts);
        assertFormatSupported(CMD.contextSaved, format);
        const globals = getGlobals();
        const explicitIndexName =
          command.getOptionValueSourceWithGlobals("index") === "cli"
            ? globals.index
            : undefined;
        const { watchSavedCapsule } = await import("./commands/context-saved");
        await writeOutput(
          await watchSavedCapsule(file, {
            configPath: globals.config,
            indexName: globals.index,
            explicitIndexName,
            question: cmdOpts.question as string | undefined,
            label: cmdOpts.label as string | undefined,
            notify: Boolean(cmdOpts.notify),
            format: format === "json" ? "json" : "terminal",
          }),
          format === "json" ? "json" : "terminal"
        );
      }
    );

  contextCmd
    .command("watches")
    .description("List watched saved Context Capsules")
    .option("--json", "JSON output")
    .action(async (cmdOpts: Record<string, unknown>) => {
      const format = getFormat(cmdOpts);
      assertFormatSupported(CMD.contextSaved, format);
      const globals = getGlobals();
      const { listWatchedCapsules } = await import("./commands/context-saved");
      await writeOutput(
        await listWatchedCapsules({
          configPath: globals.config,
          indexName: globals.index,
          format: format === "json" ? "json" : "terminal",
        }),
        format === "json" ? "json" : "terminal"
      );
    });

  contextCmd
    .command("unwatch <registration>")
    .description("Stop watching a saved Context Capsule")
    .option("--json", "JSON output")
    .action(async (registration: string, cmdOpts: Record<string, unknown>) => {
      const format = getFormat(cmdOpts);
      assertFormatSupported(CMD.contextSaved, format);
      const globals = getGlobals();
      const { unwatchSavedCapsule } = await import("./commands/context-saved");
      await writeOutput(
        await unwatchSavedCapsule(registration, {
          configPath: globals.config,
          indexName: globals.index,
          format: format === "json" ? "json" : "terminal",
        }),
        format === "json" ? "json" : "terminal"
      );
    });

  contextCmd
    .command("reverify <registration>")
    .description("Reverify one watched saved Context Capsule")
    .option("--json", "JSON output")
    .action(async (registration: string, cmdOpts: Record<string, unknown>) => {
      const format = getFormat(cmdOpts);
      assertFormatSupported(CMD.contextSaved, format);
      const globals = getGlobals();
      const { reverifyWatchedCapsule } =
        await import("./commands/context-saved");
      const result = await reverifyWatchedCapsule(registration, {
        configPath: globals.config,
        indexName: globals.index,
        format: format === "json" ? "json" : "terminal",
      });
      await writeOutput(result.output, format === "json" ? "json" : "terminal");
      if (result.operationStatus === "failed") {
        throw new CliError(
          "RUNTIME",
          result.errorMessage ??
            "Saved Context Capsule verification operation failed",
          { operationStatus: "failed" }
        );
      }
    });

  contextCmd
    .command("rm <scope> [text]")
    .description("Remove context item")
    .action(async (scope: string, text?: string) => {
      const { contextRm } = await import("./commands/context");
      const exitCode = await contextRm(scope, text, {
        configPath: getGlobals().config,
      });
      if (exitCode !== 0) {
        throw new CliError("VALIDATION", "Failed to remove context");
      }
    });

  // models subcommands
  const modelsCmd = program.command("models").description("Manage LLM models");

  modelsCmd
    .command("list")
    .description("List available models")
    .option("--json", "JSON output")
    .action(async (cmdOpts: Record<string, unknown>) => {
      const format = getFormat(cmdOpts);
      assertFormatSupported(CMD.modelsList, format);

      const { modelsList, formatModelsList } =
        await import("./commands/models");
      const result = await modelsList({ json: format === "json" });
      process.stdout.write(
        `${formatModelsList(result, { json: format === "json" })}\n`
      );
    });

  modelsCmd
    .command("use")
    .description("Switch active model preset")
    .argument("<preset>", "preset ID (slim, balanced, quality)")
    .action(async (preset: string) => {
      const globals = getGlobals();
      const { modelsUse, formatModelsUse } =
        await import("./commands/models/use");
      const result = await modelsUse(preset, { configPath: globals.config });
      if (!result.success) {
        throw new CliError("VALIDATION", result.error);
      }
      process.stdout.write(`${formatModelsUse(result)}\n`);
    });

  modelsCmd
    .command("pull")
    .description("Download models")
    .option("--all", "download all configured models")
    .option("--embed", "download embedding model")
    .option("--rerank", "download reranker model")
    .option("--expand", "download expansion model")
    .option("--gen", "download answer generation model")
    .option("--force", "force re-download")
    .option("--no-progress", "disable download progress")
    .action(async (cmdOpts: Record<string, unknown>) => {
      const globals = getGlobals();
      const { modelsPull, formatModelsPull, createProgressRenderer } =
        await import("./commands/models");

      // Merge global quiet/json with local --no-progress
      const showProgress =
        (process.stderr.isTTY ?? false) &&
        !globals.quiet &&
        !globals.json &&
        cmdOpts.progress !== false;

      const result = await modelsPull({
        all: Boolean(cmdOpts.all),
        embed: Boolean(cmdOpts.embed),
        rerank: Boolean(cmdOpts.rerank),
        expand: Boolean(cmdOpts.expand),
        gen: Boolean(cmdOpts.gen),
        force: Boolean(cmdOpts.force),
        onProgress: showProgress ? createProgressRenderer() : undefined,
      });

      // For models pull, print result first, then check for failures
      // This allows partial success output before throwing
      process.stdout.write(`${formatModelsPull(result)}\n`);
      if (result.failed > 0) {
        throw new CliError("RUNTIME", `${result.failed} model(s) failed`);
      }
    });

  modelsCmd
    .command("clear")
    .description("Clear model cache")
    .action(async () => {
      const globals = getGlobals();
      const { modelsClear, formatModelsClear } =
        await import("./commands/models");
      const result = await modelsClear({ yes: globals.yes });
      process.stdout.write(`${formatModelsClear(result)}\n`);
    });

  modelsCmd
    .command("path")
    .description("Show model cache path")
    .option("--json", "JSON output")
    .action(async (cmdOpts: Record<string, unknown>) => {
      const format = getFormat(cmdOpts);
      const { modelsPath, formatModelsPath } =
        await import("./commands/models");
      const result = modelsPath();
      process.stdout.write(
        `${formatModelsPath(result, { json: format === "json" })}\n`
      );
    });

  // update - Sync files from disk
  addWriteLeaseFlags(
    program
      .command("update")
      .description("Sync files from disk into the index")
      .option("--git-pull", "run git pull in git repositories")
      .option("--json", "JSON output")
  ).action(async (cmdOpts: Record<string, unknown>) => {
    const globals = getGlobals();
    const { update, formatUpdate } = await import("./commands/update");
    const lease = parseWriteLeaseFlags(cmdOpts);
    const opts = {
      configPath: globals.config,
      indexName: globals.index,
      gitPull: Boolean(cmdOpts.gitPull),
      verbose: globals.verbose,
      json: getFormat(cmdOpts) === "json",
      lockWaitMs: lease.lockWaitMs,
      noWait: lease.noWait,
    };
    const result = await update(opts);

    if (!result.success) {
      throwIfWriteLeaseBusy(result, opts.json);
      throw new CliError("RUNTIME", result.error ?? "Update failed");
    }
    process.stdout.write(`${formatUpdate(result, opts)}\n`);
  });

  // embed - Generate embeddings
  addWriteLeaseFlags(
    program
      .command("embed [collection]")
      .description("Generate embeddings for indexed documents")
      .option("--collection <name>", "restrict to one collection")
      .option("--model <uri>", "embedding model URI")
      .option("--batch-size <num>", "batch size", "32")
      .option("--force", "regenerate all embeddings")
      .option("--dry-run", "show what would be done")
      .option("--json", "JSON output")
  ).action(
    async (
      collectionArg: string | undefined,
      cmdOpts: Record<string, unknown>
    ) => {
      const globals = getGlobals();
      const format = getFormat(cmdOpts);

      const { embed, formatEmbed } = await import("./commands/embed");
      const collection =
        collectionArg ?? (cmdOpts.collection as string | undefined);
      const lease = parseWriteLeaseFlags(cmdOpts);
      const opts = {
        configPath: globals.config,
        indexName: globals.index,
        collection,
        model: cmdOpts.model as string | undefined,
        batchSize: parsePositiveInt("batch-size", cmdOpts.batchSize),
        force: Boolean(cmdOpts.force),
        dryRun: Boolean(cmdOpts.dryRun),
        yes: globals.yes,
        json: format === "json",
        verbose: globals.verbose,
        offline: globals.offline,
        lockWaitMs: lease.lockWaitMs,
        noWait: lease.noWait,
      };
      const result = await embed(opts);

      if (!result.success) {
        throwIfWriteLeaseBusy(result, opts.json);
        throw new CliError("RUNTIME", result.error ?? "Embed failed");
      }
      process.stdout.write(`${formatEmbed(result, opts)}\n`);
      if (result.contentionErrors > 0) {
        throw new CliError(
          "BUSY",
          "Some chunks were deferred by index contention",
          { silent: true }
        );
      }
    }
  );

  // cleanup - Clean stale data
  addWriteLeaseFlags(
    program.command("cleanup").description("Clean orphaned data from index")
  ).action(async (cmdOpts: Record<string, unknown>) => {
    const { cleanup, formatCleanup } = await import("./commands/cleanup");
    const lease = parseWriteLeaseFlags(cmdOpts);
    const result = await withCliWriteLease(
      {
        indexName: getGlobals().index,
        lockWaitMs: lease.lockWaitMs,
        noWait: lease.noWait,
      },
      () => cleanup({ indexName: getGlobals().index })
    );
    throwIfWriteLeaseBusy(result, false);

    if (!result.success) {
      throw new CliError("RUNTIME", result.error ?? "Cleanup failed");
    }
    process.stdout.write(`${formatCleanup(result)}\n`);
  });

  // reset - Reset GNO to fresh state
  program
    .command("reset")
    .description("Delete all GNO data and start fresh")
    .option("--confirm", "confirm destructive operation")
    .option("--keep-config", "preserve config file")
    .option("--keep-cache", "preserve model cache")
    .action(async (cmdOpts: Record<string, unknown>) => {
      const { reset, formatReset } = await import("./commands/reset");
      const globals = getGlobals();
      const result = await reset({
        // Accept either --confirm or global --yes
        confirm: Boolean(cmdOpts.confirm) || globals.yes,
        keepConfig: Boolean(cmdOpts.keepConfig),
        keepCache: Boolean(cmdOpts.keepCache),
      });
      process.stdout.write(`${formatReset(result)}\n`);
    });
}

// ─────────────────────────────────────────────────────────────────────────────
// Vec Commands (sync, rebuild)
// ─────────────────────────────────────────────────────────────────────────────

function wireVecCommands(program: Command): void {
  const vecCmd = program.command("vec").description("Vector index maintenance");

  // vec sync
  addWriteLeaseFlags(
    vecCmd
      .command("sync")
      .description("Sync vec0 index with content_vectors")
      .option("--json", "JSON output")
  ).action(async (cmdOpts: Record<string, unknown>) => {
    const format = getFormat(cmdOpts);
    const globals = getGlobals();

    const { vecSync, formatVecSync } = await import("./commands/vec");
    const lease = parseWriteLeaseFlags(cmdOpts);
    const result = await withCliWriteLease(
      {
        indexName: globals.index,
        lockWaitMs: lease.lockWaitMs,
        noWait: lease.noWait,
      },
      () =>
        vecSync({
          configPath: globals.config,
          indexName: globals.index,
          json: format === "json",
        })
    );
    throwIfWriteLeaseBusy(result, format === "json");

    if (!result.success) {
      throw new CliError("RUNTIME", result.error);
    }

    process.stdout.write(
      `${formatVecSync(result, { json: format === "json" })}\n`
    );
  });

  // vec rebuild
  addWriteLeaseFlags(
    vecCmd
      .command("rebuild")
      .description("Rebuild vec0 index from content_vectors")
      .option("--json", "JSON output")
  ).action(async (cmdOpts: Record<string, unknown>) => {
    const format = getFormat(cmdOpts);
    const globals = getGlobals();

    const { vecRebuild, formatVecRebuild } = await import("./commands/vec");
    const lease = parseWriteLeaseFlags(cmdOpts);
    const result = await withCliWriteLease(
      {
        indexName: globals.index,
        lockWaitMs: lease.lockWaitMs,
        noWait: lease.noWait,
      },
      () =>
        vecRebuild({
          configPath: globals.config,
          indexName: globals.index,
          json: format === "json",
        })
    );
    throwIfWriteLeaseBusy(result, format === "json");

    if (!result.success) {
      throw new CliError("RUNTIME", result.error);
    }

    process.stdout.write(
      `${formatVecRebuild(result, { json: format === "json" })}\n`
    );
  });
}

function wirePublishCommand(program: Command): void {
  const visibilityValues = [
    "public",
    "secret-link",
    "invite-only",
    "encrypted",
  ] as const;
  const publishCmd = program
    .command("publish")
    .description("Export publish artifacts for gno.sh");

  publishCmd
    .command("export <target>")
    .description("Export a collection or document ref as a gno.sh artifact")
    .option("--out <path>", "output artifact path")
    .option(
      "--visibility <mode>",
      "visibility mode (public, secret-link, invite-only, encrypted)",
      "public"
    )
    .option(
      "--passphrase <value>",
      "required for encrypted export; encrypts locally before upload"
    )
    .option("--slug <slug>", "route slug override")
    .option("--title <title>", "space title override")
    .option("--summary <summary>", "space summary override")
    .option(
      "--preview",
      "print sanitized markdown + warnings instead of writing the artifact"
    )
    .option("--json", "JSON output")
    .action(async (target: string, cmdOpts: Record<string, unknown>) => {
      const format = getFormat(cmdOpts);
      assertFormatSupported(CMD.publishExport, format);
      const globals = getGlobals();

      const visibility = cmdOpts.visibility as string;
      const passphrase =
        typeof cmdOpts.passphrase === "string" ? cmdOpts.passphrase : undefined;
      if (
        !visibilityValues.includes(
          visibility as (typeof visibilityValues)[number]
        )
      ) {
        throw new CliError(
          "VALIDATION",
          `Invalid visibility: ${visibility}. Must be public, secret-link, invite-only, or encrypted.`
        );
      }
      if (visibility === "encrypted" && !passphrase?.trim()) {
        throw new CliError(
          "VALIDATION",
          "Encrypted publish export requires --passphrase."
        );
      }

      const { formatPublishExport, publishExport } =
        await import("./commands/publish");
      const result = await publishExport(target, {
        configPath: globals.config,
        json: format === "json",
        out: typeof cmdOpts.out === "string" ? cmdOpts.out : undefined,
        encryptionPassphrase: passphrase,
        preview: cmdOpts.preview === true,
        slug: cmdOpts.slug as string | undefined,
        summary: cmdOpts.summary as string | undefined,
        title: cmdOpts.title as string | undefined,
        visibility: visibility as
          | "encrypted"
          | "invite-only"
          | "public"
          | "secret-link",
      });

      if (!result.success) {
        throw new CliError(
          result.isValidation ? "VALIDATION" : "RUNTIME",
          result.error
        );
      }

      await writeOutput(
        formatPublishExport(result, { json: format === "json" }),
        format
      );
    });
}

// ─────────────────────────────────────────────────────────────────────────────
// Skill Commands (install, uninstall, show, paths)
// ─────────────────────────────────────────────────────────────────────────────

function wireSkillCommands(program: Command): void {
  const skillCmd = program
    .command("skill")
    .description("Manage GNO agent skill");

  skillCmd
    .command("install")
    .description("Install GNO skill to supported agents")
    .option(
      "-s, --scope <scope>",
      "installation scope (project, user)",
      "project"
    )
    .option(
      "-t, --target <target>",
      "target agent (claude, codex, opencode, openclaw, hermes, all)",
      "claude"
    )
    .option("-f, --force", "overwrite existing installation")
    .option("--json", "JSON output")
    .action(async (cmdOpts: Record<string, unknown>) => {
      const scope = cmdOpts.scope as string;
      const target = cmdOpts.target as string;

      // Validate scope
      if (!["project", "user"].includes(scope)) {
        throw new CliError(
          "VALIDATION",
          `Invalid scope: ${scope}. Must be 'project' or 'user'.`
        );
      }
      // Validate target
      if (
        !["claude", "codex", "opencode", "openclaw", "hermes", "all"].includes(
          target
        )
      ) {
        throw new CliError(
          "VALIDATION",
          `Invalid target: ${target}. Must be 'claude', 'codex', 'opencode', 'openclaw', 'hermes', or 'all'.`
        );
      }

      const { installSkill } = await import("./commands/skill/install.js");
      await installSkill({
        scope: scope as "project" | "user",
        target: target as
          | "claude"
          | "codex"
          | "opencode"
          | "openclaw"
          | "hermes"
          | "all",
        force: Boolean(cmdOpts.force),
        // The root program also defines a global --json and may consume the
        // flag; leave undefined here so the runner falls back to globals.
        json: cmdOpts.json === true ? true : undefined,
      });
    });

  skillCmd
    .command("uninstall")
    .description("Uninstall GNO skill")
    .option(
      "-s, --scope <scope>",
      "installation scope (project, user)",
      "project"
    )
    .option(
      "-t, --target <target>",
      "target agent (claude, codex, opencode, openclaw, hermes, all)",
      "claude"
    )
    .option("--json", "JSON output")
    .action(async (cmdOpts: Record<string, unknown>) => {
      const scope = cmdOpts.scope as string;
      const target = cmdOpts.target as string;

      // Validate scope
      if (!["project", "user"].includes(scope)) {
        throw new CliError(
          "VALIDATION",
          `Invalid scope: ${scope}. Must be 'project' or 'user'.`
        );
      }
      // Validate target
      if (
        !["claude", "codex", "opencode", "openclaw", "hermes", "all"].includes(
          target
        )
      ) {
        throw new CliError(
          "VALIDATION",
          `Invalid target: ${target}. Must be 'claude', 'codex', 'opencode', 'openclaw', 'hermes', or 'all'.`
        );
      }

      const { uninstallSkill } = await import("./commands/skill/uninstall.js");
      await uninstallSkill({
        scope: scope as "project" | "user",
        target: target as
          | "claude"
          | "codex"
          | "opencode"
          | "openclaw"
          | "hermes"
          | "all",
        json: cmdOpts.json === true ? true : undefined,
      });
    });

  skillCmd
    .command("show")
    .description("Preview skill files without installing")
    .option("--file <name>", "specific file to show")
    .option("--all", "show all skill files")
    .action(async (cmdOpts: Record<string, unknown>) => {
      const { showSkill } = await import("./commands/skill/show.js");
      await showSkill({
        file: cmdOpts.file as string | undefined,
        all: Boolean(cmdOpts.all),
      });
    });

  skillCmd
    .command("paths")
    .description("Show resolved skill installation paths")
    .option(
      "-s, --scope <scope>",
      "filter by scope (project, user, all)",
      "all"
    )
    .option(
      "-t, --target <target>",
      "filter by target (claude, codex, opencode, openclaw, hermes, all)",
      "all"
    )
    .option("--json", "JSON output")
    .action(async (cmdOpts: Record<string, unknown>) => {
      const scope = cmdOpts.scope as string;
      const target = cmdOpts.target as string;

      // Validate scope
      if (!["project", "user", "all"].includes(scope)) {
        throw new CliError(
          "VALIDATION",
          `Invalid scope: ${scope}. Must be 'project', 'user', or 'all'.`
        );
      }
      // Validate target
      if (
        !["claude", "codex", "opencode", "openclaw", "hermes", "all"].includes(
          target
        )
      ) {
        throw new CliError(
          "VALIDATION",
          `Invalid target: ${target}. Must be 'claude', 'codex', 'opencode', 'openclaw', 'hermes', or 'all'.`
        );
      }

      const { showPaths } = await import("./commands/skill/paths-cmd.js");
      await showPaths({
        scope: scope as "project" | "user" | "all",
        target: target as
          | "claude"
          | "codex"
          | "opencode"
          | "openclaw"
          | "hermes"
          | "all",
        json: cmdOpts.json === true ? true : undefined,
      });
    });
}

// ─────────────────────────────────────────────────────────────────────────────
// Agents Commands (install, update, verify, uninstall)
// ─────────────────────────────────────────────────────────────────────────────

function wireAgentsCommands(program: Command): void {
  const agentsCmd = program
    .command("agents")
    .description(
      "Manage the GNO protocol block in global harness instruction files"
    );

  const targetDescription =
    "target harness (claude, codex, cursor, opencode, grok, hermes, openclaw, all)";

  const collectExtraDir = (value: string, previous: string[]): string[] => [
    ...previous,
    value,
  ];

  const parseCommonOpts = async (cmdOpts: Record<string, unknown>) => {
    const { parseTargetOption } = await import("./commands/agents/commands.js");
    return {
      target: parseTargetOption((cmdOpts.target as string) ?? "all"),
      extraDirs: (cmdOpts.extraDir as string[] | undefined) ?? [],
      dryRun: Boolean(cmdOpts.dryRun),
      // The root program also defines a global --json and may consume the
      // flag; leave undefined here so the runner falls back to globals.
      json: cmdOpts.json ? true : undefined,
    };
  };

  agentsCmd
    .command("install")
    .description(
      "Install the GNO protocol block into detected harnesses' global instruction files"
    )
    .option("-t, --target <target>", targetDescription, "all")
    .option(
      "--extra-dir <path>",
      "additional instruction dir (repeatable, for nonstandard layouts)",
      collectExtraDir,
      [] as string[]
    )
    .option("--dry-run", "print the unified diff and write nothing")
    .option("--json", "JSON output")
    .action(async (cmdOpts: Record<string, unknown>) => {
      const { installAgents } = await import("./commands/agents/commands.js");
      await installAgents(await parseCommonOpts(cmdOpts), "install");
    });

  agentsCmd
    .command("update")
    .description("Refresh an installed GNO protocol block in place")
    .option("-t, --target <target>", targetDescription, "all")
    .option(
      "--extra-dir <path>",
      "additional instruction dir (repeatable, for nonstandard layouts)",
      collectExtraDir,
      [] as string[]
    )
    .option("--dry-run", "print the unified diff and write nothing")
    .option("--json", "JSON output")
    .action(async (cmdOpts: Record<string, unknown>) => {
      const { installAgents } = await import("./commands/agents/commands.js");
      await installAgents(await parseCommonOpts(cmdOpts), "update");
    });

  agentsCmd
    .command("verify")
    .description(
      "Verify installed GNO protocol blocks (one block, version + hash)"
    )
    .option("-t, --target <target>", targetDescription, "all")
    .option(
      "--extra-dir <path>",
      "additional instruction dir (repeatable, for nonstandard layouts)",
      collectExtraDir,
      [] as string[]
    )
    .option("--json", "JSON output")
    .action(async (cmdOpts: Record<string, unknown>) => {
      const { verifyAgents } = await import("./commands/agents/commands.js");
      await verifyAgents(await parseCommonOpts(cmdOpts));
    });

  agentsCmd
    .command("uninstall")
    .description("Remove the GNO protocol block and markers from harness files")
    .option("-t, --target <target>", targetDescription, "all")
    .option(
      "--extra-dir <path>",
      "additional instruction dir (repeatable, for nonstandard layouts)",
      collectExtraDir,
      [] as string[]
    )
    .option("--dry-run", "print the unified diff and write nothing")
    .option("--json", "JSON output")
    .action(async (cmdOpts: Record<string, unknown>) => {
      const { uninstallAgents } = await import("./commands/agents/commands.js");
      await uninstallAgents(await parseCommonOpts(cmdOpts));
    });
}

// ─────────────────────────────────────────────────────────────────────────────
// Tags Commands (list, add, rm)
// ─────────────────────────────────────────────────────────────────────────────

function wireTagsCommands(program: Command): void {
  const tagsCmd = program.command("tags").description("Manage document tags");

  // tags list
  tagsCmd
    .command("list", { isDefault: true })
    .description("List all tags with document counts")
    .option("-c, --collection <name>", "filter by collection")
    .option("--prefix <prefix>", "filter by tag prefix")
    .option("--json", "JSON output")
    .option("--md", "Markdown output")
    .action(async (cmdOpts: Record<string, unknown>) => {
      const format = getFormat(cmdOpts);
      assertFormatSupported(CMD.tagsList, format);
      const globals = getGlobals();

      const { tagsList, formatTagsList } = await import("./commands/tags");
      const result = await tagsList({
        configPath: globals.config,
        indexName: globals.index,
        collection: cmdOpts.collection as string | undefined,
        prefix: cmdOpts.prefix as string | undefined,
        json: format === "json",
        md: format === "md",
      });

      if (!result.success) {
        throw new CliError(
          result.isValidation ? "VALIDATION" : "RUNTIME",
          result.error
        );
      }

      const output = formatTagsList(result, {
        json: format === "json",
        md: format === "md",
      });
      await writeOutput(output, format);
    });

  // tags add <doc> <tag>
  addWriteLeaseFlags(
    tagsCmd
      .command("add <doc> <tag>")
      .description("Add a tag to a document")
      .option("--json", "JSON output")
  ).action(
    async (doc: string, tag: string, cmdOpts: Record<string, unknown>) => {
      const format = getFormat(cmdOpts);
      const globals = getGlobals();

      const { tagsAdd, formatTagsAdd } = await import("./commands/tags");
      const lease = parseWriteLeaseFlags(cmdOpts);
      const result = await withCliWriteLease(
        {
          indexName: globals.index,
          lockWaitMs: lease.lockWaitMs,
          noWait: lease.noWait,
        },
        () =>
          tagsAdd(doc, tag, {
            configPath: globals.config,
            indexName: globals.index,
            json: format === "json",
          })
      );
      throwIfWriteLeaseBusy(result, format === "json");

      if (!result.success) {
        throw new CliError(
          result.isValidation ? "VALIDATION" : "RUNTIME",
          result.error
        );
      }

      process.stdout.write(
        `${formatTagsAdd(result, { json: format === "json" })}\n`
      );
    }
  );

  // tags rm <doc> <tag>
  addWriteLeaseFlags(
    tagsCmd
      .command("rm <doc> <tag>")
      .description("Remove a tag from a document")
      .option("--json", "JSON output")
  ).action(
    async (doc: string, tag: string, cmdOpts: Record<string, unknown>) => {
      const format = getFormat(cmdOpts);
      const globals = getGlobals();

      const { tagsRm, formatTagsRm } = await import("./commands/tags");
      const lease = parseWriteLeaseFlags(cmdOpts);
      const result = await withCliWriteLease(
        {
          indexName: globals.index,
          lockWaitMs: lease.lockWaitMs,
          noWait: lease.noWait,
        },
        () =>
          tagsRm(doc, tag, {
            configPath: globals.config,
            indexName: globals.index,
            json: format === "json",
          })
      );
      throwIfWriteLeaseBusy(result, format === "json");

      if (!result.success) {
        throw new CliError(
          result.isValidation ? "VALIDATION" : "RUNTIME",
          result.error
        );
      }

      process.stdout.write(
        `${formatTagsRm(result, { json: format === "json" })}\n`
      );
    }
  );
}

// ─────────────────────────────────────────────────────────────────────────────
// Links Commands (links, backlinks, similar)
// ─────────────────────────────────────────────────────────────────────────────

function wireLinksCommands(program: Command): void {
  // links - List outgoing links from a document
  const linksCmd = program
    .command("links")
    .description("Document link commands");

  linksCmd
    .command("list <doc>", { isDefault: true })
    .description("List outgoing links from a document")
    .option("--type <type>", "filter by link type (wiki, markdown)")
    .option("--edge-type <type>", "filter by semantic edge type")
    .option("--relation <type>", "alias for --edge-type")
    .option("--json", "JSON output")
    .option("--md", "Markdown output")
    .action(async (doc: string, cmdOpts: Record<string, unknown>) => {
      const format = getFormat(cmdOpts);
      assertFormatSupported(CMD.linksList, format);
      const globals = getGlobals();

      // Validate type option
      const linkType = cmdOpts.type as string | undefined;
      if (linkType && !["wiki", "markdown"].includes(linkType)) {
        throw new CliError(
          "VALIDATION",
          `Invalid link type: ${linkType}. Must be 'wiki' or 'markdown'.`
        );
      }
      const edgeType = cmdOpts.edgeType as string | undefined;
      const relation = cmdOpts.relation as string | undefined;
      if (linkType && (edgeType || relation)) {
        throw new CliError(
          "VALIDATION",
          "--type cannot be combined with --edge-type or --relation"
        );
      }
      if (edgeType && relation && edgeType !== relation) {
        throw new CliError(
          "VALIDATION",
          "--edge-type and --relation are aliases and must match when both are provided"
        );
      }

      const { linksList, formatLinksList } = await import("./commands/links");
      const result = await linksList(doc, {
        configPath: globals.config,
        type: linkType as "wiki" | "markdown" | undefined,
        edgeType,
        relation,
        json: format === "json",
        md: format === "md",
      });

      if (!result.success) {
        throw new CliError(
          result.isValidation ? "VALIDATION" : "RUNTIME",
          result.error
        );
      }

      const output = formatLinksList(result, {
        json: format === "json",
        md: format === "md",
      });
      await writeOutput(output, format);
    });

  // backlinks - List documents linking TO this document
  program
    .command("backlinks <doc>")
    .description("List documents linking to this document")
    .option("-c, --collection <name>", "filter by collection")
    .option("--edge-type <type>", "filter by semantic edge type")
    .option("--relation <type>", "alias for --edge-type")
    .option("--json", "JSON output")
    .option("--md", "Markdown output")
    .action(async (doc: string, cmdOpts: Record<string, unknown>) => {
      const format = getFormat(cmdOpts);
      assertFormatSupported(CMD.backlinks, format);
      const globals = getGlobals();

      const { backlinks, formatBacklinks } = await import("./commands/links");
      const edgeType = cmdOpts.edgeType as string | undefined;
      const relation = cmdOpts.relation as string | undefined;
      if (edgeType && relation && edgeType !== relation) {
        throw new CliError(
          "VALIDATION",
          "--edge-type and --relation are aliases and must match when both are provided"
        );
      }
      const result = await backlinks(doc, {
        configPath: globals.config,
        collection: cmdOpts.collection as string | undefined,
        edgeType,
        relation,
        json: format === "json",
        md: format === "md",
      });

      if (!result.success) {
        throw new CliError(
          result.isValidation ? "VALIDATION" : "RUNTIME",
          result.error
        );
      }

      const output = formatBacklinks(result, {
        json: format === "json",
        md: format === "md",
      });
      await writeOutput(output, format);
    });

  // similar - Find semantically similar documents
  program
    .command("similar <doc>")
    .description("Find semantically similar documents")
    .option("-n, --limit <num>", "max results", "5")
    .option("--threshold <num>", "minimum similarity (0-1)", "0.7")
    .option("--cross-collection", "search across all collections")
    .option("--json", "JSON output")
    .option("--md", "Markdown output")
    .action(async (doc: string, cmdOpts: Record<string, unknown>) => {
      const format = getFormat(cmdOpts);
      assertFormatSupported(CMD.similar, format);
      const globals = getGlobals();

      const limit = cmdOpts.limit
        ? parsePositiveInt("limit", cmdOpts.limit)
        : 5;

      const threshold = parseOptionalFloat("threshold", cmdOpts.threshold);
      if (threshold !== undefined && (threshold < 0 || threshold > 1)) {
        throw new CliError("VALIDATION", "--threshold must be between 0 and 1");
      }

      const { similar, formatSimilar } = await import("./commands/links");
      const result = await similar(doc, {
        configPath: globals.config,
        limit,
        threshold,
        crossCollection: Boolean(cmdOpts.crossCollection),
        json: format === "json",
        md: format === "md",
      });

      if (!result.success) {
        throw new CliError(
          result.isValidation ? "VALIDATION" : "RUNTIME",
          result.error
        );
      }

      const output = formatSimilar(result, {
        json: format === "json",
        md: format === "md",
      });
      await writeOutput(output, format);
    });
}

// ─────────────────────────────────────────────────────────────────────────────
// Graph Command
// ─────────────────────────────────────────────────────────────────────────────

function wireGraphCommand(program: Command): void {
  const graphCmd = program
    .command("graph")
    .description("Output knowledge graph of document links")
    .option("-c, --collection <name>", "filter by collection")
    .option("--limit <n>", "max nodes (default 2000)")
    .option("--edge-limit <n>", "max edges (default 10000)")
    .option("--include-similar", "include similarity edges")
    .option("--threshold <n>", "similarity threshold (default 0.7)")
    .option("--include-isolated", "include nodes with no links")
    .option("--similar-top-k <n>", "similar docs per node (default 5)")
    .option("--neighbors <ref>", "show graph neighbors for document/node ref")
    .option("--direction <dir>", "neighbor direction: both, out, in")
    .option("--from <ref>", "path start document/node ref")
    .option("--to <ref>", "path target document/node ref")
    .option("--max-depth <n>", "max path hops (default 6)")
    .option("--json", "JSON output (default)")
    .option("--dot", "Graphviz DOT output")
    .option("--mermaid", "Mermaid diagram output")
    .action(async (cmdOpts: Record<string, unknown>) => {
      const globals = getGlobals();

      // Validate mutually exclusive format flags
      const formatFlags = [cmdOpts.json, cmdOpts.dot, cmdOpts.mermaid].filter(
        Boolean
      );
      if (formatFlags.length > 1) {
        throw new CliError(
          "VALIDATION",
          "Choose one format: --json, --dot, or --mermaid"
        );
      }

      const format: "json" | "dot" | "mermaid" = cmdOpts.dot
        ? "dot"
        : cmdOpts.mermaid
          ? "mermaid"
          : "json";

      const limitNodes = cmdOpts.limit
        ? parsePositiveInt("limit", cmdOpts.limit)
        : undefined;
      const limitEdges = cmdOpts.edgeLimit
        ? parsePositiveInt("edge-limit", cmdOpts.edgeLimit)
        : undefined;
      const threshold = parseOptionalFloat("threshold", cmdOpts.threshold);
      if (threshold !== undefined && (threshold < 0 || threshold > 1)) {
        throw new CliError("VALIDATION", "--threshold must be between 0 and 1");
      }
      const similarTopK = cmdOpts.similarTopK
        ? parsePositiveInt("similar-top-k", cmdOpts.similarTopK)
        : undefined;
      const maxDepth = cmdOpts.maxDepth
        ? parsePositiveInt("max-depth", cmdOpts.maxDepth)
        : undefined;
      const graphDirection = (cmdOpts.direction ?? "both") as string;
      if (
        graphDirection !== "both" &&
        graphDirection !== "out" &&
        graphDirection !== "in"
      ) {
        throw new CliError(
          "VALIDATION",
          "--direction must be one of: both, out, in"
        );
      }
      if (cmdOpts.neighbors && (cmdOpts.from || cmdOpts.to)) {
        throw new CliError(
          "VALIDATION",
          "--neighbors cannot be combined with --from/--to"
        );
      }

      const { graph, formatGraph } = await import("./commands/graph.js");
      const result = await graph({
        configPath: globals.config,
        indexName: globals.index,
        collection: cmdOpts.collection as string | undefined,
        limitNodes,
        limitEdges,
        includeSimilar: Boolean(cmdOpts.includeSimilar),
        threshold,
        includeIsolated: Boolean(cmdOpts.includeIsolated),
        similarTopK,
        format,
        neighbors: cmdOpts.neighbors as string | undefined,
        direction: graphDirection as "both" | "out" | "in",
        from: cmdOpts.from as string | undefined,
        to: cmdOpts.to as string | undefined,
        maxDepth,
      });

      if (!result.success) {
        throw new CliError(
          result.isValidation ? "VALIDATION" : "RUNTIME",
          result.error
        );
      }

      const output = formatGraph(result, { format });

      // Print truncation warning to stderr if applicable
      if (result.data.meta.truncated) {
        for (const warning of result.data.meta.warnings) {
          console.error(`Warning: ${warning}`);
        }
      }

      await writeOutput(output, format === "json" ? "json" : "terminal");
    });

  graphCmd
    .command("query <doc>")
    .description("Run bounded typed-edge traversal from a document")
    .option("--direction <dir>", "direction: both, out, in")
    .option("--edge-type <type>", "filter by typed edge type")
    .option("--max-depth <n>", "max traversal depth (default 2)")
    .option("--max-nodes <n>", "max returned nodes (default 100)")
    .option(
      "--frontier-limit <n>",
      "max frontier width per depth (default 100)"
    )
    .option(
      "--visited-limit <n>",
      "max visited rows during traversal (default 500)"
    )
    .option("--json", "JSON output")
    .action(
      async (
        doc: string,
        cmdOpts: Record<string, unknown>,
        command: Command
      ) => {
        const globals = getGlobals();
        const format = getFormat(cmdOpts);
        assertFormatSupported(CMD.graphQuery, format);
        if (format !== "terminal" && format !== "json") {
          throw new CliError(
            "VALIDATION",
            "gno graph query supports terminal and json output"
          );
        }
        const argv = resolveCliArgv(command);
        const directionFlagIndex = argv.lastIndexOf("--direction");
        const rawDirection =
          directionFlagIndex >= 0 ? argv[directionFlagIndex + 1] : undefined;
        const direction = (rawDirection ??
          cmdOpts.direction ??
          "both") as string;
        if (direction !== "both" && direction !== "out" && direction !== "in") {
          throw new CliError(
            "VALIDATION",
            "--direction must be one of: both, out, in"
          );
        }

        const maxDepth = cmdOpts.maxDepth
          ? parsePositiveInt("max-depth", cmdOpts.maxDepth)
          : undefined;
        const maxNodes = cmdOpts.maxNodes
          ? parsePositiveInt("max-nodes", cmdOpts.maxNodes)
          : undefined;
        const frontierLimit = cmdOpts.frontierLimit
          ? parsePositiveInt("frontier-limit", cmdOpts.frontierLimit)
          : undefined;
        const visitedLimit = cmdOpts.visitedLimit
          ? parsePositiveInt("visited-limit", cmdOpts.visitedLimit)
          : undefined;

        const { graphQuery, formatGraphQuery } =
          await import("./commands/graph.js");
        const result = await graphQuery(doc, {
          configPath: globals.config,
          indexName: globals.index,
          direction: direction as "both" | "out" | "in",
          edgeType: cmdOpts.edgeType as string | undefined,
          maxDepth,
          maxNodes,
          frontierLimit,
          visitedLimit,
          format,
        });

        if (!result.success) {
          throw new CliError(
            result.isValidation ? "VALIDATION" : "RUNTIME",
            result.error
          );
        }

        const output = formatGraphQuery(result, { format });
        if (result.data.meta.truncated) {
          for (const warning of result.data.meta.warnings) {
            console.error(`Warning: ${warning}`);
          }
        }

        await writeOutput(output, format);
      }
    );
}

/**
 * `gno changes --follow --jsonl`: the follow flags form one mode that
 * excludes the one-shot listing flags. The cursor-expiry record is the
 * stdout envelope, so its non-zero exit is silent on stderr.
 */
async function runChangesFollow(
  cmdOpts: Record<string, unknown>,
  format: string,
  globals: GlobalOptions
): Promise<void> {
  if (!cmdOpts.follow || !cmdOpts.jsonl) {
    throw new CliError(
      "VALIDATION",
      "--follow and --jsonl must be used together (--cursor requires both)"
    );
  }
  if (format === "json" || cmdOpts.since !== undefined) {
    throw new CliError(
      "VALIDATION",
      "--follow cannot be combined with --json or --since; use --cursor to resume"
    );
  }
  if (cmdOpts.limit !== undefined) {
    throw new CliError(
      "VALIDATION",
      "--follow cannot be combined with --limit"
    );
  }
  const { changesFollow } = await import("./commands/changes");
  const result = await changesFollow(
    {
      cursor: cmdOpts.cursor as string | undefined,
      collection: cmdOpts.collection as string | undefined,
    },
    { configPath: globals.config, indexName: globals.index }
  );
  if (result.status === "error") {
    throw new CliError(
      result.isValidation ? "VALIDATION" : "RUNTIME",
      result.error
    );
  }
  if (result.status === "expired") {
    throw new CliError(
      "RUNTIME",
      `Follow cursor expired; earliest retained cursor is ${result.earliestCursor}`,
      { silent: true }
    );
  }
}

function wireKnowledgeDeltaCommands(program: Command): void {
  program
    .command("changes")
    .description("List retained metadata-only document changes")
    .option("--since <time-or-cursor>", "ISO-8601 time or opaque cursor")
    .option("-c, --collection <name>", "filter by collection")
    .option("-n, --limit <num>", "maximum changes (default 100)")
    .option("--json", "JSON output")
    .option(
      "--follow",
      "stream new changes as they land (requires --jsonl; SIGINT exits 0)"
    )
    .option("--jsonl", "one JSON object per line (only with --follow)")
    .option(
      "--cursor <cursor>",
      "resume a --follow stream from a persisted postCursor"
    )
    .action(async (cmdOpts: Record<string, unknown>) => {
      const format = getFormat(cmdOpts);
      assertFormatSupported(CMD.changes, format);
      const deltaFormat = format === "json" ? "json" : "terminal";
      const globals = getGlobals();
      if (cmdOpts.follow || cmdOpts.jsonl || cmdOpts.cursor !== undefined) {
        await runChangesFollow(cmdOpts, format, globals);
        return;
      }
      const { changes, formatChanges } = await import("./commands/changes");
      const result = await changes(
        {
          since: cmdOpts.since as string | undefined,
          collection: cmdOpts.collection as string | undefined,
          limit: parsePositiveInt("limit", cmdOpts.limit ?? "100"),
        },
        { configPath: globals.config, indexName: globals.index }
      );
      if (!result.success) {
        throw new CliError(
          result.isValidation ? "VALIDATION" : "RUNTIME",
          result.error
        );
      }
      await writeOutput(formatChanges(result.data, deltaFormat), deltaFormat);
    });

  program
    .command("diff <doc>")
    .description("Show one retained metadata-only structural change")
    .option("--change <id>", "opaque change ID")
    .option("--json", "JSON output")
    .action(async (doc: string, cmdOpts: Record<string, unknown>) => {
      const format = getFormat(cmdOpts);
      assertFormatSupported(CMD.diff, format);
      const deltaFormat = format === "json" ? "json" : "terminal";
      const globals = getGlobals();
      const { diff, formatDiff } = await import("./commands/changes");
      const result = await diff(doc, cmdOpts.change as string | undefined, {
        configPath: globals.config,
        indexName: globals.index,
      });
      if (!result.success) {
        throw new CliError(
          result.isValidation ? "VALIDATION" : "RUNTIME",
          result.error
        );
      }
      await writeOutput(formatDiff(result.data, deltaFormat), deltaFormat);
    });

  program
    .command("impact <doc>")
    .description("Find bounded inbound knowledge dependencies")
    .option("--max-depth <n>", "maximum dependency depth", "3")
    .option("--max-nodes <n>", "maximum returned nodes", "100")
    .option("--max-edges <n>", "maximum traversed evidence edges", "250")
    .option("--frontier-limit <n>", "maximum frontier width", "100")
    .option("--visited-limit <n>", "maximum visited rows", "500")
    .option("--json", "JSON output")
    .action(async (doc: string, cmdOpts: Record<string, unknown>) => {
      const format = getFormat(cmdOpts);
      assertFormatSupported(CMD.impact, format);
      const deltaFormat = format === "json" ? "json" : "terminal";
      const globals = getGlobals();
      const { impact, formatImpact } = await import("./commands/changes");
      const result = await impact(
        doc,
        {
          maxDepth: parsePositiveInt("max-depth", cmdOpts.maxDepth),
          maxNodes: parsePositiveInt("max-nodes", cmdOpts.maxNodes),
          maxEdges: parsePositiveInt("max-edges", cmdOpts.maxEdges),
          frontierLimit: parsePositiveInt(
            "frontier-limit",
            cmdOpts.frontierLimit
          ),
          visitedLimit: parsePositiveInt("visited-limit", cmdOpts.visitedLimit),
        },
        { configPath: globals.config, indexName: globals.index }
      );
      if (!result.success) {
        throw new CliError(
          result.isValidation ? "VALIDATION" : "RUNTIME",
          result.error
        );
      }
      await writeOutput(formatImpact(result.data, deltaFormat), deltaFormat);
    });
}

// ─────────────────────────────────────────────────────────────────────────────
// Serve Command (web UI)
// ─────────────────────────────────────────────────────────────────────────────

function addGatewayOptions(
  command: Command,
  hostDescription = "HTTP listen address (default: 127.0.0.1)"
): Command {
  return command
    .option("--host <address>", hostDescription)
    .option("--mcp-token-file <path>", "restrictive bearer token file")
    .option(
      "--mcp-allowed-host <host>",
      "exact allowed Host header (repeatable)",
      (value: string, previous: string[] = []) => [...previous, value]
    )
    .option(
      "--mcp-allowed-origin <origin>",
      "exact allowed Origin (repeatable)",
      (value: string, previous: string[] = []) => [...previous, value]
    )
    .option(
      "--mcp-enable-write",
      "authorize HTTP MCP mutation tools (independent of authentication)"
    )
    .option(
      "--mcp-tool-profile <profile>",
      "advertised MCP tool set: core or full (overrides gateway.toolProfile; default full)"
    );
}

/** Validate a `--tool-profile` / `--mcp-tool-profile` value; undefined when absent. */
function parseToolProfileOption(value: unknown): McpToolProfile | undefined {
  try {
    return parseMcpToolProfile(value);
  } catch (error) {
    throw new CliError(
      "VALIDATION",
      error instanceof Error ? error.message : String(error)
    );
  }
}

function wireDaemonCommand(program: Command): void {
  const daemonCmd = addGatewayOptions(
    program
      .command("daemon")
      .description("Start headless continuous indexing")
      .option("-p, --port <num>", "MCP gateway port", "3000")
      .option(
        "--no-sync-on-start",
        "skip initial sync and only watch future file changes"
      )
      // Local `--json` so `gno daemon --status --json` parses cleanly in any
      // argv position. Mirrors the serve wiring: gated to --status only.
      .option(
        "--json",
        "JSON output (applies to --status; see process-status schema)"
      )
  );

  // --detach / --status / --stop are mutually exclusive. Use Commander's
  // Option API so the conflict error is the native "option '--status'
  // cannot be used with option '--detach'" surface.
  daemonCmd.addOption(
    new Option(
      "--detach",
      "run as a detached background process (macOS/Linux only)"
    ).conflicts(["status", "stop"])
  );
  daemonCmd.addOption(
    new Option(
      "--status",
      "show status of the detached daemon process (use --json for machine output)"
    ).conflicts(["detach", "stop"])
  );
  daemonCmd.addOption(
    new Option(
      "--stop",
      "stop the detached daemon process (SIGTERM then SIGKILL fallback)"
    ).conflicts(["detach", "status"])
  );
  daemonCmd.addOption(
    new Option("--pid-file <path>", "override pid-file path")
  );
  daemonCmd.addOption(
    new Option("--log-file <path>", "override log-file path (append-only)")
  );
  // Sentinel flag set by the parent when re-exec'ing the detached child.
  // Hidden from --help; Commander consumes it via addOption so it doesn't
  // leak into user-visible argv.
  daemonCmd.addOption(
    new Option(
      `${DETACHED_CHILD_FLAG}`,
      "internal detached-child marker"
    ).hideHelp()
  );

  daemonCmd.action(async (cmdOpts: Record<string, unknown>, cmd: Command) => {
    await handleDaemonAction(cmdOpts, cmd);
  });
}

// ─────────────────────────────────────────────────────────────────────────────
// Daemon lifecycle branching (detach / status / stop / detached-child / fg)
// ─────────────────────────────────────────────────────────────────────────────

/**
 * Route `gno daemon` through the detach helpers based on which mutex flag the
 * user set. The four early branches return without touching `daemon()`; only
 * the foreground + detached-child paths boot the runtime.
 *
 * Mirrors `handleServeAction` exactly — same helper imports, same JSON
 * gating, same detached-child verification + pid-file cleanup. Daemon's port
 * identifies its headless MCP gateway.
 */
async function handleDaemonAction(
  cmdOpts: Record<string, unknown>,
  cmd: Command
): Promise<void> {
  const globals = getGlobals();
  // Validate before any side effect (pid files, detach, runtime boot).
  const toolProfile = parseToolProfileOption(cmdOpts.mcpToolProfile);

  const {
    resolveProcessPaths,
    statusProcess,
    stopProcess,
    spawnDetached,
    inspectForeignLive,
    verifyPidFileMatchesSelf,
    DETACHED_CHILD_FLAG: childFlag,
  } = await import("./detach.js");

  const paths = resolveProcessPaths("daemon", {
    pidFile: cmdOpts.pidFile as string | undefined,
    logFile: cmdOpts.logFile as string | undefined,
    cwd: process.cwd(),
  });

  // Per `spec/cli.md`, `--json` is only defined for `gno daemon --status`.
  // Silently accepting `--json` on --detach / --stop / foreground would let
  // users think they'll get structured output; fail fast instead. Mirrors
  // the serve wiring at handleServeAction.
  const jsonRequested = Boolean(cmdOpts.json) || globals.json;
  if (jsonRequested && !cmdOpts.status) {
    throw new CliError(
      "VALIDATION",
      "--json is only supported with `gno daemon --status`"
    );
  }

  if (cmdOpts.status) {
    const json = Boolean(cmdOpts.json) || globals.json;
    await runDaemonStatus({
      paths,
      json,
      indexName: globals.index,
      statusProcess,
      inspectForeignLive,
    });
    return;
  }

  if (cmdOpts.stop) {
    await runDaemonStop({ pidFile: paths.pidFile, stopProcess });
    return;
  }

  if (cmdOpts.detach) {
    const port = parsePositiveInt("port", cmdOpts.port);
    await runDaemonDetach({
      port,
      paths,
      spawnDetached,
      argv: resolveCliArgv(cmd),
    });
    return;
  }

  // Detached-child path: the parent spawned us with DETACHED_CHILD_FLAG.
  // Confirm the pid-file points at us before booting; if the parent never
  // registered us, exit cleanly rather than run unmanaged. On success,
  // install a shutdown hook that unlinks the pid-file. The daemon's own
  // `createSignalPromise` (in commands/daemon.ts) already drains SIGINT/
  // SIGTERM cleanly; `installPidFileCleanup` adds the unlink on top so the
  // pid-file disappears even if the runtime teardown misbehaves.
  const isDetachedChild = Boolean(
    (cmdOpts as Record<string, unknown>)[toCamelCase(childFlag)]
  );
  if (isDetachedChild) {
    const matched = await verifyPidFileMatchesSelf({ pidFile: paths.pidFile });
    if (!matched) {
      // Parent crashed before registering us, or another racer won.
      return;
    }
    installPidFileCleanup(paths.pidFile);
  }

  const port = parsePositiveInt("port", cmdOpts.port);

  const { daemon } = await import("./commands/daemon.js");
  const result = await daemon({
    configPath: globals.config,
    index: globals.index,
    offline: globals.offline,
    verbose: globals.verbose,
    quiet: globals.quiet,
    noSyncOnStart: cmdOpts.syncOnStart === false,
    port,
    host: cmdOpts.host as string | undefined,
    tokenFile: cmdOpts.mcpTokenFile as string | undefined,
    allowedHosts: cmdOpts.mcpAllowedHost as string[] | undefined,
    allowedOrigins: cmdOpts.mcpAllowedOrigin as string[] | undefined,
    enableWrite: cmdOpts.mcpEnableWrite === true ? true : undefined,
    toolProfile,
  });
  if (!result.success) {
    throw new CliError("RUNTIME", result.error);
  }
}

interface DaemonStatusDeps {
  paths: { pidFile: string; logFile: string };
  json: boolean;
  indexName?: string;
  statusProcess: typeof import("./detach.js").statusProcess;
  inspectForeignLive: typeof import("./detach.js").inspectForeignLive;
}

async function runDaemonStatus(deps: DaemonStatusDeps): Promise<void> {
  const status = await deps.statusProcess({
    kind: "daemon",
    pidFile: deps.paths.pidFile,
    logFile: deps.paths.logFile,
  });
  const foreign = await deps.inspectForeignLive({
    kind: "daemon",
    pidFile: deps.paths.pidFile,
  });
  // Persisted by the daemon after every scheduled findings attempt; absent
  // (null) when the pass is not configured. Read from disk, never live.
  const findings = await readFindingsRunStatus(
    findingsRunStatePathForIndex(deps.indexName)
  );

  if (deps.json) {
    process.stdout.write(
      `${JSON.stringify({ ...status, findings }, null, 2)}\n`
    );
    // In JSON mode, foreign-live metadata flows into the NOT_RUNNING
    // envelope's `details` payload below so stderr stays a single JSON
    // object that machine clients can parse deterministically.
  } else {
    process.stdout.write("gno daemon status\n");
    process.stdout.write(`${"─".repeat(50)}\n`);
    if (status.running) {
      process.stdout.write(
        `  running  yes (pid ${status.pid}, port ${status.port})\n`
      );
      if (status.version) {
        process.stdout.write(`  version  ${status.version}\n`);
      }
      if (status.started_at) {
        process.stdout.write(
          `  started  ${status.started_at} (uptime ${status.uptime_seconds ?? 0}s)\n`
        );
      }
    } else {
      process.stdout.write("  running  no\n");
    }
    process.stdout.write(`  pid-file ${status.pid_file}\n`);
    process.stdout.write(`  log-file ${status.log_file}`);
    if (status.log_size_bytes === null) {
      process.stdout.write(" (missing)\n");
    } else {
      process.stdout.write(` (${status.log_size_bytes} bytes)\n`);
    }
    if (findings) {
      process.stdout.write(
        `  findings ${formatFindingsRunStatusLine(findings)}\n`
      );
    }

    if (foreign) {
      // Terminal mode: emit the operator-facing warning on stderr. JSON
      // clients get the same data via the NOT_RUNNING envelope's details.
      process.stderr.write(
        `Warning: pid ${foreign.pid} is live but recorded gno version ${foreign.recordedVersion} differs from current ${foreign.currentVersion}; refusing to claim ownership.\n`
      );
    }
  }

  // Spec: `--status` exits 3 (NOT_RUNNING) when no live matching process is
  // found. The stdout payload stays schema-clean — we've already written it —
  // so throw a NOT_RUNNING *after* output so the envelope only hits stderr
  // and the exit code propagates through `runCli -> exitCodeFor`.
  if (!status.running) {
    throw new CliError(
      "NOT_RUNNING",
      `gno daemon is not running (pid-file ${status.pid_file}${foreign ? `; live-foreign pid ${foreign.pid}` : ""})`,
      {
        details: foreign
          ? {
              foreign_live: {
                pid: foreign.pid,
                recorded_version: foreign.recordedVersion,
                current_version: foreign.currentVersion,
              },
            }
          : undefined,
      }
    );
  }
}

interface DaemonStopDeps {
  pidFile: string;
  stopProcess: typeof import("./detach.js").stopProcess;
}

async function runDaemonStop(deps: DaemonStopDeps): Promise<void> {
  const outcome = await deps.stopProcess({
    kind: "daemon",
    pidFile: deps.pidFile,
  });

  switch (outcome.kind) {
    case "stopped":
      process.stdout.write(
        `Stopped gno daemon (pid ${outcome.pid}, ${outcome.signal})\n`
      );
      return;
    case "not-running":
      // Per spec/cli.md: `--stop` with no pid-file exits 3 silently (no
      // error envelope on either stream, no `--json` support).
      throw new CliError(
        "NOT_RUNNING",
        `gno daemon is not running (pid-file ${outcome.pidFile} missing or stale)`,
        { silent: true }
      );
    case "timeout":
      throw new CliError(
        "RUNTIME",
        `gno daemon (pid ${outcome.pid}) did not exit after SIGTERM + SIGKILL. Investigate manually.`
      );
    case "foreign-live":
      throw new CliError(
        "VALIDATION",
        `gno daemon (pid ${outcome.pid}) is live but was started by gno ${outcome.payload.version}; this binary is ${VERSION}. Refusing to signal pid ${outcome.pid}; terminate it manually and delete ${deps.pidFile}.`
      );
    default: {
      const exhaustive: never = outcome;
      throw new Error(`unreachable stop outcome: ${String(exhaustive)}`);
    }
  }
}

interface DaemonDetachDeps {
  port: number;
  paths: { pidFile: string; logFile: string };
  spawnDetached: typeof import("./detach.js").spawnDetached;
  /**
   * The user-facing argv slice (everything after `[execPath, scriptPath]`)
   * sourced from `Command.rawArgs` via `resolveCliArgv()`. Per-invocation,
   * not process-global, so back-to-back `runCli([...])` calls in the same
   * process don't taint each other.
   */
  argv: string[];
}

async function runDaemonDetach(deps: DaemonDetachDeps): Promise<void> {
  // Strip --detach from the re-exec argv so the child takes the foreground /
  // detached-child branch instead of re-spawning itself in an infinite loop.
  const childArgv = stripDetachFlag(deps.argv);
  const result = await deps.spawnDetached({
    kind: "daemon",
    argv: childArgv,
    pidFile: deps.paths.pidFile,
    logFile: deps.paths.logFile,
    port: deps.port,
  });
  // Daemon has no Web UI URL; its listener exists solely for MCP.
  process.stdout.write(`PID ${result.pid}\n`);
}

function wireServeCommand(program: Command): void {
  const serveCmd = addGatewayOptions(
    program
      .command("serve")
      .description("Start web UI server")
      .option("-p, --port <num>", "port to listen on", "3000")
      // Local `--json` so `gno serve --status --json` parses cleanly in any
      // argv position. Global `--json` already exists on the root program
      // (see line 208); resolution goes through `getFormat()` /
      // `getGlobals()` which precedence-merges local over global.
      .option(
        "--json",
        "JSON output (applies to --status; see process-status schema)"
      ),
    "loopback HTTP listen address (default: 127.0.0.1)"
  );

  // --detach / --status / --stop are mutually exclusive. Use Commander's
  // Option API so the conflict error is the native "option '--status'
  // cannot be used with option '--detach'" surface.
  serveCmd.addOption(
    new Option(
      "--detach",
      "run as a detached background process (macOS/Linux only)"
    ).conflicts(["status", "stop"])
  );
  serveCmd.addOption(
    new Option(
      "--status",
      "show status of the detached serve process (use --json for machine output)"
    ).conflicts(["detach", "stop"])
  );
  serveCmd.addOption(
    new Option(
      "--stop",
      "stop the detached serve process (SIGTERM then SIGKILL fallback)"
    ).conflicts(["detach", "status"])
  );
  serveCmd.addOption(new Option("--pid-file <path>", "override pid-file path"));
  serveCmd.addOption(
    new Option("--log-file <path>", "override log-file path (append-only)")
  );
  // Sentinel flag set by the parent when re-exec'ing the detached child.
  // Hidden from --help; Commander consumes it via addOption so it doesn't
  // leak into user-visible argv.
  serveCmd.addOption(
    new Option(
      `${DETACHED_CHILD_FLAG}`,
      "internal detached-child marker"
    ).hideHelp()
  );
  serveCmd.addOption(
    new Option(
      "--dev",
      "serve the development bundle with HMR (default: production)"
    )
  );

  serveCmd.action(async (cmdOpts: Record<string, unknown>, cmd: Command) => {
    await handleServeAction(cmdOpts, cmd);
  });
}

/** CLI serve bundle mode. Default `gno serve` is production unless `--dev`. */
export function resolveServeNodeEnv(
  dev: boolean
): "development" | "production" {
  return dev ? "development" : "production";
}

function applyServeBundleEnv(dev: boolean): void {
  process.env.NODE_ENV = resolveServeNodeEnv(dev);
}

// ─────────────────────────────────────────────────────────────────────────────
// Serve lifecycle branching (detach / status / stop / detached-child / fg)
// ─────────────────────────────────────────────────────────────────────────────

/**
 * Route `gno serve` through the detach helpers based on which mutex flag the
 * user set. The four early branches return without touching `startServer()`;
 * only the foreground + detached-child paths boot the runtime.
 */
async function handleServeAction(
  cmdOpts: Record<string, unknown>,
  cmd: Command
): Promise<void> {
  const globals = getGlobals();
  // Validate before any side effect (NODE_ENV, pid files, detach, runtime boot).
  const toolProfile = parseToolProfileOption(cmdOpts.mcpToolProfile);
  // NB: do NOT parse --port here. The status/stop branches don't need it
  // and rejecting `gno serve --status --port nope` on irrelevant input
  // would break management commands. parsePositiveInt is called inside
  // the foreground + detach paths where the port actually matters.

  const {
    resolveProcessPaths,
    statusProcess,
    stopProcess,
    spawnDetached,
    inspectForeignLive,
    verifyPidFileMatchesSelf,
    DETACHED_CHILD_FLAG: childFlag,
  } = await import("./detach.js");

  const paths = resolveProcessPaths("serve", {
    pidFile: cmdOpts.pidFile as string | undefined,
    logFile: cmdOpts.logFile as string | undefined,
    cwd: process.cwd(),
  });

  // Per `spec/cli.md`, `--json` is only defined for `gno serve --status`.
  // Silently accepting `--json` on --detach / --stop / foreground would let
  // users think they'll get structured output; fail fast instead. Commander
  // hoists `--json` to the root when both root and sub-command declare it
  // (verified against commander@14.0.2), so we consult the local flag first
  // and fall back to the global flag only if the user is mixing `serve`
  // with anything but `--status`.
  const jsonRequested = Boolean(cmdOpts.json) || globals.json;
  if (jsonRequested && !cmdOpts.status) {
    throw new CliError(
      "VALIDATION",
      "--json is only supported with `gno serve --status`"
    );
  }

  if (cmdOpts.status) {
    // Local --json wins over global so `gno serve --status --json` and
    // `gno --json serve --status` both produce the same result.
    const json = Boolean(cmdOpts.json) || globals.json;
    await runServeStatus({
      paths,
      json,
      statusProcess,
      inspectForeignLive,
    });
    return;
  }

  if (cmdOpts.stop) {
    await runServeStop({ pidFile: paths.pidFile, stopProcess });
    return;
  }

  const dev = cmdOpts.dev === true;
  applyServeBundleEnv(dev);

  if (cmdOpts.detach) {
    const port = parsePositiveInt("port", cmdOpts.port);
    await runServeDetach({
      port,
      paths,
      spawnDetached,
      argv: resolveCliArgv(cmd),
      nodeEnv: resolveServeNodeEnv(dev),
    });
    return;
  }

  // Detached-child path: the parent spawned us with DETACHED_CHILD_FLAG.
  // Confirm the pid-file points at us before booting; if the parent never
  // registered us, exit cleanly rather than run unmanaged. On success,
  // install a shutdown hook that unlinks the pid-file.
  const isDetachedChild = Boolean(
    (cmdOpts as Record<string, unknown>)[toCamelCase(childFlag)]
  );
  if (isDetachedChild) {
    const matched = await verifyPidFileMatchesSelf({ pidFile: paths.pidFile });
    if (!matched) {
      // Parent crashed before registering us, or another racer won.
      return;
    }
    installPidFileCleanup(paths.pidFile);
  }

  // Foreground + detached-child both need to actually bind a port; validate
  // here (after the management branches have returned) so a bad --port only
  // breaks invocations that would have used it.
  const port = parsePositiveInt("port", cmdOpts.port);

  const { serve } = await import("./commands/serve.js");
  const result = await serve({
    port,
    configPath: globals.config,
    index: globals.index,
    host: cmdOpts.host as string | undefined,
    tokenFile: cmdOpts.mcpTokenFile as string | undefined,
    allowedHosts: cmdOpts.mcpAllowedHost as string[] | undefined,
    allowedOrigins: cmdOpts.mcpAllowedOrigin as string[] | undefined,
    enableWrite: cmdOpts.mcpEnableWrite === true ? true : undefined,
    toolProfile,
  });

  if (!result.success) {
    throw new CliError("RUNTIME", result.error ?? "Server failed to start");
  }
  // Server runs until SIGINT/SIGTERM - no output needed here
}

interface ServeStatusDeps {
  paths: { pidFile: string; logFile: string };
  json: boolean;
  statusProcess: typeof import("./detach.js").statusProcess;
  inspectForeignLive: typeof import("./detach.js").inspectForeignLive;
}

async function runServeStatus(deps: ServeStatusDeps): Promise<void> {
  const status = await deps.statusProcess({
    kind: "serve",
    pidFile: deps.paths.pidFile,
    logFile: deps.paths.logFile,
  });
  const foreign = await deps.inspectForeignLive({
    kind: "serve",
    pidFile: deps.paths.pidFile,
  });

  if (deps.json) {
    process.stdout.write(`${JSON.stringify(status, null, 2)}\n`);
    // In JSON mode, foreign-live metadata flows into the NOT_RUNNING
    // envelope's `details` payload below so stderr stays a single JSON
    // object that machine clients can parse deterministically.
  } else {
    process.stdout.write("gno serve status\n");
    process.stdout.write(`${"─".repeat(50)}\n`);
    if (status.running) {
      const portText =
        status.port === null ? "(unknown port)" : `port ${status.port}`;
      process.stdout.write(`  running  yes (pid ${status.pid}, ${portText})\n`);
      if (status.version) {
        process.stdout.write(`  version  ${status.version}\n`);
      }
      if (status.started_at) {
        process.stdout.write(
          `  started  ${status.started_at} (uptime ${status.uptime_seconds ?? 0}s)\n`
        );
      }
    } else {
      process.stdout.write("  running  no\n");
    }
    process.stdout.write(`  pid-file ${status.pid_file}\n`);
    process.stdout.write(`  log-file ${status.log_file}`);
    if (status.log_size_bytes === null) {
      process.stdout.write(" (missing)\n");
    } else {
      process.stdout.write(` (${status.log_size_bytes} bytes)\n`);
    }

    if (foreign) {
      // Terminal mode: emit the operator-facing warning on stderr. JSON
      // clients get the same data via the NOT_RUNNING envelope's details.
      process.stderr.write(
        `Warning: pid ${foreign.pid} is live but recorded gno version ${foreign.recordedVersion} differs from current ${foreign.currentVersion}; refusing to claim ownership.\n`
      );
    }
  }

  // Spec: `--status` exits 3 (NOT_RUNNING) when no live matching process is
  // found. The stdout payload stays schema-clean — we've already written it —
  // so throw a NOT_RUNNING *after* output so the envelope only hits stderr
  // and the exit code propagates through `runCli -> exitCodeFor`. A
  // live-foreign pid is also "not ours", so we cannot claim running:true for
  // it; `statusProcess` already reports `running:false` in that case.
  if (!status.running) {
    throw new CliError(
      "NOT_RUNNING",
      `gno serve is not running (pid-file ${status.pid_file}${foreign ? `; live-foreign pid ${foreign.pid}` : ""})`,
      {
        details: foreign
          ? {
              foreign_live: {
                pid: foreign.pid,
                recorded_version: foreign.recordedVersion,
                current_version: foreign.currentVersion,
              },
            }
          : undefined,
      }
    );
  }
}

interface ServeStopDeps {
  pidFile: string;
  stopProcess: typeof import("./detach.js").stopProcess;
}

async function runServeStop(deps: ServeStopDeps): Promise<void> {
  const outcome = await deps.stopProcess({
    kind: "serve",
    pidFile: deps.pidFile,
  });

  switch (outcome.kind) {
    case "stopped":
      process.stdout.write(
        `Stopped gno serve (pid ${outcome.pid}, ${outcome.signal})\n`
      );
      return;
    case "not-running":
      // Per spec/cli.md: `--stop` with no pid-file exits 3 silently (no
      // error envelope on either stream, no `--json` support).
      throw new CliError(
        "NOT_RUNNING",
        `gno serve is not running (pid-file ${outcome.pidFile} missing or stale)`,
        { silent: true }
      );
    case "timeout":
      throw new CliError(
        "RUNTIME",
        `gno serve (pid ${outcome.pid}) did not exit after SIGTERM + SIGKILL. Investigate manually.`
      );
    case "foreign-live":
      throw new CliError(
        "VALIDATION",
        `gno serve (pid ${outcome.pid}) is live but was started by gno ${outcome.payload.version}; this binary is ${VERSION}. Refusing to signal pid ${outcome.pid}; terminate it manually and delete ${deps.pidFile}.`
      );
    default: {
      const exhaustive: never = outcome;
      throw new Error(`unreachable stop outcome: ${String(exhaustive)}`);
    }
  }
}

interface ServeDetachDeps {
  port: number;
  paths: { pidFile: string; logFile: string };
  spawnDetached: typeof import("./detach.js").spawnDetached;
  /**
   * The user-facing argv slice from `Command.rawArgs` via `resolveCliArgv()`.
   * Per-invocation so back-to-back `runCli([...])` calls in the same process
   * can't taint each other's child argv.
   */
  argv: string[];
  nodeEnv: "development" | "production";
}

async function runServeDetach(deps: ServeDetachDeps): Promise<void> {
  // Strip --detach from the re-exec argv so the child takes the foreground /
  // detached-child branch instead of re-spawning itself in an infinite loop.
  const childArgv = stripDetachFlag(deps.argv);
  const result = await deps.spawnDetached({
    kind: "serve",
    argv: childArgv,
    env: { NODE_ENV: deps.nodeEnv },
    pidFile: deps.paths.pidFile,
    logFile: deps.paths.logFile,
    port: deps.port,
  });
  process.stdout.write(
    `PID ${result.pid} listening on http://localhost:${deps.port}\n`
  );
}

/**
 * Remove `--detach` (and its short/long variants) from an argv slice while
 * preserving the order and value of every other argument. We only strip the
 * literal long form because that's the only form we register.
 */
function stripDetachFlag(argv: string[]): string[] {
  return argv.filter((a) => a !== "--detach");
}

/**
 * Install a one-shot SIGINT/SIGTERM handler that unlinks the pid-file before
 * the default signal handling (startServer's own shutdown) runs. Uses a sync
 * unlink so the pid-file is gone even if the subsequent async teardown
 * misbehaves.
 */
function installPidFileCleanup(pidFile: string): void {
  const cleanup = () => {
    try {
      unlinkSync(pidFile);
    } catch {
      // Already gone or permission-denied — nothing actionable here.
    }
  };
  process.once("SIGINT", cleanup);
  process.once("SIGTERM", cleanup);
  // Also run on a clean (`exit(0)`) path so crashes leave a stale pid-file
  // that `--status` can detect via liveness check, but orderly shutdown
  // (e.g. startServer returned) still cleans up.
  process.once("beforeExit", cleanup);
}

/**
 * Commander lowercases a long option name into camelCase for `cmdOpts`. The
 * sentinel flag `--__detached-child` maps to `__detachedChild` on the opts
 * bag; we derive that programmatically so the constant stays the single
 * source of truth.
 */
function toCamelCase(longFlag: string): string {
  return longFlag
    .replace(/^-+/, "")
    .replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
}

// ─────────────────────────────────────────────────────────────────────────────
// Completion Command (shell completions)
// ─────────────────────────────────────────────────────────────────────────────

function wireCompletionCommand(program: Command): void {
  const completionCmd = program
    .command("completion")
    .description("Shell completion scripts");

  // Output completion script
  completionCmd
    .command("output <shell>", { isDefault: true })
    .description("Output completion script for a shell (bash, zsh, fish)")
    .action(async (shell: string) => {
      const { completionOutput, SUPPORTED_SHELLS } =
        await import("./commands/completion/index.js");

      if (!SUPPORTED_SHELLS.includes(shell as "bash" | "zsh" | "fish")) {
        throw new CliError(
          "VALIDATION",
          `Unsupported shell: ${shell}. Supported: ${SUPPORTED_SHELLS.join(", ")}`
        );
      }

      const script = completionOutput({
        shell: shell as "bash" | "zsh" | "fish",
      });
      process.stdout.write(script);
    });

  // Install completion to user's shell config
  completionCmd
    .command("install")
    .description("Auto-install completion to shell config")
    .option(
      "-s, --shell <shell>",
      "shell to install for (bash, zsh, fish) - auto-detected if omitted"
    )
    .option("--json", "JSON output")
    .action(async (...args: unknown[]) => {
      // Last arg is the Command object - use optsWithGlobals for subcommands
      const cmd = args[args.length - 1] as Command;
      const cmdOpts = cmd.optsWithGlobals<{ shell?: string; json?: boolean }>();
      const { shell, json } = cmdOpts;

      const { completionInstall, SUPPORTED_SHELLS } =
        await import("./commands/completion/index.js");

      if (
        shell &&
        !SUPPORTED_SHELLS.includes(shell as "bash" | "zsh" | "fish")
      ) {
        throw new CliError(
          "VALIDATION",
          `Unsupported shell: ${shell}. Supported: ${SUPPORTED_SHELLS.join(", ")}`
        );
      }

      await completionInstall({
        shell: shell as "bash" | "zsh" | "fish" | undefined,
        json: Boolean(json),
      });
    });
}