@intentius/chant 0.124.12 → 0.124.14

package/dist/cli/main.js

@@ -0,0 +1,2540 @@
+#!/usr/bin/env tsx
+import { resolve } from "node:path";
+import { isEntryPoint } from "./is-entry-point.js";
+import { formatError } from "./format.js";
+import { resolveCommand } from "./registry.js";
+import { loadChantConfigUpward } from "../config.js";
+import { findProjectRoot, findWorkspaceRoot } from "../project-root.js";
+import { isNoLexiconDetected } from "../detectLexicon.js";
+import { CHANT_VERSION } from "./version.js";
+import { validateLexiconConfig, formatLexiconConfigProblems } from "../lexicon-config.js";
+import { armSandboxConfigEvaluation } from "../config-sandbox.js";
+import { armSandboxPolicyExecution } from "../lint/policy-import.js";
+import { ENV_VAR, unknownEnvError } from "../env.js";
+import { initRuntime } from "../runtime-adapter.js";
+import { installCompiledCli } from "../ts-loader.js";
+import { splitJoinedFlags, dispatchCommandGroup, collectCommandGroups, formatCommandGroupsHelp } from "./command-group.js";
+const handlerModules = new Map();
+function lazyHandler(load, pick) {
+    const handler = async (ctx) => pick(await load())(ctx);
+    handlerModules.set(handler, load);
+    return handler;
+}
+const buildHandlers = () => import("./handlers/build.js");
+const runBuild = lazyHandler(buildHandlers, (m) => m.runBuild);
+const lintHandlers = () => import("./handlers/lint.js");
+const runLint = lazyHandler(lintHandlers, (m) => m.runLint);
+const devHandlers = () => import("./handlers/dev.js");
+const runDevGenerate = lazyHandler(devHandlers, (m) => m.runDevGenerate);
+const runDevPublish = lazyHandler(devHandlers, (m) => m.runDevPublish);
+const runDevOnboard = lazyHandler(devHandlers, (m) => m.runDevOnboard);
+const runDevCheckLexicon = lazyHandler(devHandlers, (m) => m.runDevCheckLexicon);
+const runDevSurfaceDiff = lazyHandler(devHandlers, (m) => m.runDevSurfaceDiff);
+const runDevPinnedUpgrade = lazyHandler(devHandlers, (m) => m.runDevPinnedUpgrade);
+const runDevRollingUpgrade = lazyHandler(devHandlers, (m) => m.runDevRollingUpgrade);
+const runDevUnknown = lazyHandler(devHandlers, (m) => m.runDevUnknown);
+const serveHandlers = () => import("./handlers/serve.js");
+const runServeLsp = lazyHandler(serveHandlers, (m) => m.runServeLsp);
+const runServeMcp = lazyHandler(serveHandlers, (m) => m.runServeMcp);
+const runServeUnknown = lazyHandler(serveHandlers, (m) => m.runServeUnknown);
+const initHandlers = () => import("./handlers/init.js");
+const runInit = lazyHandler(initHandlers, (m) => m.runInit);
+const runInitLexicon = lazyHandler(initHandlers, (m) => m.runInitLexicon);
+const miscHandlers = () => import("./handlers/misc.js");
+const runList = lazyHandler(miscHandlers, (m) => m.runList);
+const runDescribe = lazyHandler(miscHandlers, (m) => m.runDescribe);
+const runImport = lazyHandler(miscHandlers, (m) => m.runImport);
+const runAudit = lazyHandler(miscHandlers, (m) => m.runAudit);
+const runUpdate = lazyHandler(miscHandlers, (m) => m.runUpdate);
+const runDoctor = lazyHandler(miscHandlers, (m) => m.runDoctor);
+const vendorHandlers = () => import("./handlers/vendor.js");
+const runVendor = lazyHandler(vendorHandlers, (m) => m.runVendor);
+const migrateHandlers = () => import("./handlers/migrate.js");
+const runMigrate = lazyHandler(migrateHandlers, (m) => m.runMigrate);
+const carveHandlers = () => import("./handlers/carve.js");
+const runCarveAdvise = lazyHandler(carveHandlers, (m) => m.runCarveAdvise);
+const runCarveUnknown = lazyHandler(carveHandlers, (m) => m.runCarveUnknown);
+const carveEmitHandlers = () => import("./handlers/carve-emit.js");
+const runCarveEmit = lazyHandler(carveEmitHandlers, (m) => m.runCarveEmit);
+const carveBridgeHandlers = () => import("./handlers/carve-bridge.js");
+const runCarveBridge = lazyHandler(carveBridgeHandlers, (m) => m.runCarveBridge);
+const carveApplyHandlers = () => import("./handlers/carve-apply.js");
+const runCarveApply = lazyHandler(carveApplyHandlers, (m) => m.runCarveApply);
+const carveStatusHandlers = () => import("./handlers/carve-status.js");
+const runCarveStatus = lazyHandler(carveStatusHandlers, (m) => m.runCarveStatus);
+const lifecycleHandlers = () => import("./handlers/lifecycle.js");
+const runLifecycleSnapshot = lazyHandler(lifecycleHandlers, (m) => m.runLifecycleSnapshot);
+const runLifecycleShow = lazyHandler(lifecycleHandlers, (m) => m.runLifecycleShow);
+const runLifecycleDiff = lazyHandler(lifecycleHandlers, (m) => m.runLifecycleDiff);
+const runLifecycleRollback = lazyHandler(lifecycleHandlers, (m) => m.runLifecycleRollback);
+const runLifecyclePlan = lazyHandler(lifecycleHandlers, (m) => m.runLifecyclePlan);
+const runLifecycleAffected = lazyHandler(lifecycleHandlers, (m) => m.runLifecycleAffected);
+const runLifecycleLog = lazyHandler(lifecycleHandlers, (m) => m.runLifecycleLog);
+const runLifecycleTeardown = lazyHandler(lifecycleHandlers, (m) => m.runLifecycleTeardown);
+const runLifecycleWhoami = lazyHandler(lifecycleHandlers, (m) => m.runLifecycleWhoami);
+const runLifecycleUnknown = lazyHandler(lifecycleHandlers, (m) => m.runLifecycleUnknown);
+const componentsHandlers = () => import("./handlers/components.js");
+const runComponentsStatus = lazyHandler(componentsHandlers, (m) => m.runComponentsStatus);
+const runComponentsReleaseRecord = lazyHandler(componentsHandlers, (m) => m.runComponentsReleaseRecord);
+const runComponentsExport = lazyHandler(componentsHandlers, (m) => m.runComponentsExport);
+const runComponentsUnknown = lazyHandler(componentsHandlers, (m) => m.runComponentsUnknown);
+const fanOutHandlers = () => import("./handlers/fan-out.js");
+const runComponentsFanOut = lazyHandler(fanOutHandlers, (m) => m.runComponentsFanOut);
+const promoteHandlers = () => import("./handlers/promote.js");
+const runComponentsPromote = lazyHandler(promoteHandlers, (m) => m.runComponentsPromote);
+const runComponentsRollback = lazyHandler(promoteHandlers, (m) => m.runComponentsRollback);
+const runComponentsRedeploy = lazyHandler(promoteHandlers, (m) => m.runComponentsRedeploy);
+const scenarioHandlers = () => import("./handlers/scenario.js");
+const runScenarioCheck = lazyHandler(scenarioHandlers, (m) => m.runScenarioCheck);
+const runScenarioUnknown = lazyHandler(scenarioHandlers, (m) => m.runScenarioUnknown);
+const graphHandlers = () => import("./handlers/graph.js");
+const runGraph = lazyHandler(graphHandlers, (m) => m.runGraph);
+const explainHandlers = () => import("./handlers/explain.js");
+const runExplain = lazyHandler(explainHandlers, (m) => m.runExplain);
+const searchHandlers = () => import("./handlers/search.js");
+const runSearch = lazyHandler(searchHandlers, (m) => m.runSearch);
+const runHandlers = () => import("./handlers/run.js");
+const runOp = lazyHandler(runHandlers, (m) => m.runOp);
+const runOpList = lazyHandler(runHandlers, (m) => m.runOpList);
+const runOpStatus = lazyHandler(runHandlers, (m) => m.runOpStatus);
+const runOpApprove = lazyHandler(runHandlers, (m) => m.runOpApprove);
+const runOpSignalRenamed = lazyHandler(runHandlers, (m) => m.runOpSignalRenamed);
+const runOpCancel = lazyHandler(runHandlers, (m) => m.runOpCancel);
+const runOpLog = lazyHandler(runHandlers, (m) => m.runOpLog);
+const runWaveHandlers = () => import("./handlers/run-wave.js");
+const runOpWaveCommand = lazyHandler(runWaveHandlers, (m) => m.runOpWaveCommand);
+const operatorHandlers = () => import("./handlers/operator.js");
+const runOperator = lazyHandler(operatorHandlers, (m) => m.runOperator);
+const runOperatorStatus = lazyHandler(operatorHandlers, (m) => m.runOperatorStatus);
+const runOperatorLog = lazyHandler(operatorHandlers, (m) => m.runOperatorLog);
+const runApprove = lazyHandler(operatorHandlers, (m) => m.runApprove);
+const emulatorHandlers = () => import("./handlers/emulator.js");
+const runEmulator = lazyHandler(emulatorHandlers, (m) => m.runEmulator);
+/** The lexicon plugin loader, which imports the lint, fold and build machinery: loaded when a command needs plugins (#3878). */
+const loadPlugins = async (...a) => (await import("./plugins.js")).loadPlugins(...a);
+const resolveProjectLexicons = async (...a) => (await import("./plugins.js")).resolveProjectLexicons(...a);
+/**
+ * Long-form flags that are pure booleans in {@link parseArgs} — their branch
+ * below sets a field to `true` and never consumes a following array element.
+ * Used only to reject a joined `--flag=value` form for these (chant #1127):
+ * a boolean has no value to assign, and silently reinterpreting the joined
+ * value as the next positional argument (path, component name, ...) would be
+ * exactly the kind of silent misparse this issue exists to close. `--report`
+ * is deliberately excluded — it's context-sensitive (bare boolean vs a SARIF
+ * path, decided by lookahead), so a joined value for it is legitimate and
+ * already handled correctly once split.
+ */
+const BOOLEAN_FLAGS = new Set([
+    "--help",
+    "--open",
+    "--version",
+    "--agents",
+    "--agent",
+    "--all-projects",
+    "--force",
+    "--fix",
+    "--watch",
+    "--verbose",
+    "--live",
+    "--overlay",
+    "--explain",
+    "--owned",
+    "--verbatim",
+    "--apply-rewrites",
+    "--write",
+    "--strict",
+    "--validate",
+    "--use-composites",
+    "--composites",
+    "--stacks",
+    "--components",
+    "--up",
+    "--down",
+    "--include-dependents",
+    "--local",
+    "--json",
+    "--progress-json",
+    "--update-snapshot",
+    "--update-baseline",
+    "--run-examples",
+    "--check",
+    "--bump",
+    "--no-release-record",
+    "--fold",
+    "--no-fold",
+    "--no-cache",
+    "--sandbox",
+    "--yes",
+    "--confirm-prod",
+    "--once",
+    "--expire",
+    "--check-live",
+    "--check-snapshot",
+    "--fail-on-drift",
+    "--durable-requests",
+    "--skip-mcp",
+    "--current",
+    "--uncommitted",
+    "--allow-code",
+    "--root-only",
+    "--generated",
+    "--decide",
+    "--record-plans",
+]);
+/**
+ * Parse command line arguments
+ */
+export function parseArgs(args) {
+    // Local mutable copy — chant #1127's joined-`--flag=value` splitting below
+    // rewrites the array in place (one token becomes two), so this must not
+    // mutate whatever array the caller passed in (e.g. `process.argv.slice(2)`
+    // is already a fresh copy, but callers shouldn't have to know that).
+    args = args.slice();
+    const result = {
+        command: "",
+        path: ".",
+        extraPositional: undefined,
+        extraPositional2: undefined,
+        output: undefined,
+        format: "",
+        force: undefined,
+        fix: false,
+        lexicon: undefined,
+        template: undefined,
+        watch: false,
+        verbose: false,
+        help: false,
+        param: undefined,
+        paramsFile: undefined,
+        report: undefined,
+        local: undefined,
+        profile: undefined,
+        json: undefined,
+        live: false,
+        migrateFrom: undefined,
+        migrateTo: undefined,
+        emit: undefined,
+        strict: false,
+        validate: false,
+        useComposites: false,
+        reportFile: undefined,
+        skill: undefined,
+        skipMcp: undefined,
+        src: undefined,
+        env: undefined,
+    };
+    // chant #1127 — generic joined `--flag=value` support, factored out to
+    // ./command-group.ts (chant #1078) so a lexicon's own mounted command can
+    // apply the identical splitting discipline to its own flag vocabulary.
+    // Every value-taking flag below is matched by an exact `arg === "--flag"`
+    // check and then consumes the *next* array element (`args[++i]`) as its
+    // value; a joined token like `--env=prod` never matches any of those,
+    // doesn't match the trailing positional branch either (it starts with
+    // `-`), and used to vanish with no error. Splitting the token at its FIRST
+    // `=` and re-dispatching as two array elements makes every flag below see
+    // the exact shape it already handles — including a flag like `--param`
+    // whose own value legitimately contains `=` (`--param=tier=production`
+    // splits to flag `--param`, value `tier=production`, not further split on
+    // the second `=`).
+    args = splitJoinedFlags(args, BOOLEAN_FLAGS);
+    let i = 0;
+    while (i < args.length) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h") {
+            result.help = true;
+        }
+        else if (arg === "--version" || arg === "-V") {
+            result.version = true;
+        }
+        else if (arg === "--output" || arg === "-o") {
+            result.output = args[++i];
+        }
+        else if (arg === "--format" || arg === "-f") {
+            result.format = args[++i];
+        }
+        else if (arg === "--lexicon" || arg === "-d") {
+            result.lexicon = args[++i];
+        }
+        else if (arg === "--template" || arg === "-t") {
+            result.template = args[++i];
+        }
+        else if (arg === "--force") {
+            result.force = true;
+        }
+        else if (arg === "--fix") {
+            result.fix = true;
+        }
+        else if (arg === "--watch" || arg === "-w") {
+            result.watch = true;
+        }
+        else if (arg === "--verbose" || arg === "-v") {
+            result.verbose = true;
+        }
+        else if (arg === "--profile" || arg === "-p") {
+            result.profile = args[++i];
+        }
+        else if (arg === "--report") {
+            // --report alone is the boolean (used by `run`); --report <path> is
+            // the migrate-command file path. Look ahead for a non-flag.
+            const next = args[i + 1];
+            if (next && !next.startsWith("-")) {
+                result.reportFile = next;
+                i++;
+            }
+            else {
+                result.report = true;
+            }
+        }
+        else if (arg === "--live") {
+            result.live = true;
+        }
+        else if (arg === "--overlay") {
+            result.overlay = true;
+        }
+        else if (arg === "--between") {
+            result.betweenA = args[++i];
+            result.betweenB = args[++i];
+            if (!result.betweenA || !result.betweenB)
+                throw new Error("--between needs two snapshot refs: --between <refA> <refB>");
+        }
+        else if (arg === "--traffic") {
+            const v = args[++i];
+            if (!v)
+                throw new Error('--traffic needs a level, passed to the engine verbatim: --traffic "100 rps, p50"');
+            result.traffic = v;
+        }
+        else if (arg === "--overlay-anchor") {
+            const v = args[++i];
+            if (v !== "source" && v !== "live")
+                throw new Error(`--overlay-anchor must be 'source' or 'live', got '${v}'`);
+            result.overlayAnchor = v;
+        }
+        else if (arg === "--from") {
+            // Shared by `migrate --from <lexicon>`, `import --from <env>`,
+            // `components promote --from <env>` and `init --from <repo>@<ref>`;
+            // the commands never run together, so one field carries all four.
+            result.migrateFrom = args[++i];
+        }
+        else if (arg === "--kustomize") {
+            // `chant import --kustomize <dir>` (#1548): render the overlay, import
+            // the output through the k8s template parser.
+            result.kustomize = args[++i];
+        }
+        else if (arg === "--parser-option") {
+            // `chant import --parser-option key[=value]` (#2994), repeatable: checked
+            // against the lexicon's parserOptions() by the import command.
+            const v = args[++i];
+            if (!v || v.startsWith("-"))
+                throw new Error("--parser-option needs key or key=value: --parser-option acceptLossyV1");
+            (result.parserOption ?? (result.parserOption = [])).push(v);
+        }
+        else if (arg === "--type") {
+            result.selectType = args[++i];
+        }
+        else if (arg === "--name") {
+            result.selectName = args[++i];
+        }
+        else if (arg === "--owned") {
+            result.owned = true;
+        }
+        else if (arg === "--namespace") {
+            // The live read's namespace default (#1629), not a kubectl `-n`: it fills
+            // in for entities that declare no namespace and leaves the ones that do
+            // alone. No `-n` short form — that spelling belongs to `chant kube`,
+            // where it means kubectl's scope selector.
+            result.namespace = args[++i];
+            if (!result.namespace || result.namespace.startsWith("-"))
+                throw new Error("--namespace needs a namespace: --namespace <ns>");
+        }
+        else if (arg === "--verbatim") {
+            result.verbatim = true;
+        }
+        else if (arg === "--state") {
+            result.statePath = args[++i];
+        }
+        else if (arg === "--select") {
+            result.selectAddress = args[++i];
+        }
+        else if (arg === "--live-name") {
+            result.liveName = args[++i];
+        }
+        else if (arg === "--apply-rewrites") {
+            result.applyRewrites = true;
+        }
+        else if (arg === "--stack") {
+            result.carveStack = args[++i];
+        }
+        else if (arg === "--write") {
+            result.write = true;
+        }
+        else if (arg === "--write-source") {
+            result.writeSource = true;
+        }
+        else if (arg === "--to") {
+            result.migrateTo = args[++i];
+        }
+        else if (arg === "--emit") {
+            result.emit = args[++i];
+        }
+        else if (arg === "--dry-run") {
+            result.dryRun = true;
+        }
+        else if (arg === "--yes") {
+            result.yes = true;
+        }
+        else if (arg === "--confirm-prod") {
+            result.confirmProd = true;
+        }
+        else if (arg === "--strict") {
+            result.strict = true;
+        }
+        else if (arg === "--validate") {
+            result.validate = true;
+        }
+        else if (arg === "--use-composites") {
+            result.useComposites = true;
+        }
+        else if (arg === "--skill") {
+            result.skill = args[++i];
+        }
+        else if (arg === "--skip-mcp") {
+            result.skipMcp = true;
+        }
+        else if (arg === "--src") {
+            result.src = args[++i];
+        }
+        else if (arg === "--env") {
+            result.env = args[++i];
+        }
+        else if (arg === "--port") {
+            const value = args[++i];
+            if (!value || value.startsWith("-"))
+                throw new Error("--port needs a port: --port <container-port>=<host-port>");
+            (result.port ?? (result.port = [])).push(value);
+        }
+        else if (arg === "--promote-to") {
+            result.promoteTo = args[++i];
+            if (!result.promoteTo || result.promoteTo.startsWith("-"))
+                throw new Error("--promote-to needs an environment: --promote-to <env>");
+        }
+        else if (arg === "--tier") {
+            result.tier = args[++i];
+        }
+        else if (arg === "--agents") {
+            result.agents = true;
+        }
+        else if (arg === "--scope") {
+            result.scope = args[++i];
+        }
+        else if (arg === "--all-projects") {
+            result.allProjects = true;
+        }
+        else if (arg === "--runtime") {
+            result.runtime = args[++i];
+        }
+        else if (arg === "--fail-on") {
+            result.failOn = args[++i];
+        }
+        else if (arg === "--max-files") {
+            // Validated by the audit handler, like `--limit` below.
+            result.maxFiles = Number(args[++i]);
+        }
+        else if (arg === "--theme") {
+            result.theme = args[++i];
+        }
+        else if (arg === "--stacks") {
+            result.stacks = true;
+        }
+        else if (arg === "--components") {
+            result.components = true;
+        }
+        else if (arg === "--generate") {
+            result.generate = args[++i];
+        }
+        else if (arg === "--spec") {
+            result.opsSpec = args[++i];
+        }
+        else if (arg === "--dump-outputs") {
+            result.dumpOutputs = args[++i];
+        }
+        else if (arg === "--digest-file") {
+            result.digestFile = args[++i];
+        }
+        else if (arg === "--seed-outputs") {
+            (result.seedOutputs ?? (result.seedOutputs = [])).push(args[++i]);
+        }
+        else if (arg === "--detail") {
+            result.detail = Number(args[++i]);
+        }
+        else if (arg === "--lens") {
+            result.lens = args[++i];
+        }
+        else if (arg === "--explain") {
+            result.explain = true;
+        }
+        else if (arg === "--show") {
+            result.show = args[++i];
+        }
+        else if (arg === "--up") {
+            result.up = true;
+        }
+        else if (arg === "--down") {
+            result.down = true;
+        }
+        else if (arg === "--node-sizes") {
+            result.nodeSizes = args[++i];
+        }
+        else if (arg === "--layout-engine") {
+            result.layoutEngine = args[++i];
+        }
+        else if (arg === "--base") {
+            result.base = args[++i];
+        }
+        else if (arg === "--head") {
+            result.head = args[++i];
+        }
+        else if (arg === "--include-dependents") {
+            result.includeDependents = true;
+        }
+        else if (arg === "--from-affected") {
+            result.fromAffected = args[++i];
+        }
+        else if (arg === "--gate") {
+            result.gate = args[++i];
+        }
+        else if (arg === "--wave-gate") {
+            result.waveGate = args[++i];
+            if (!result.waveGate || result.waveGate.startsWith("-"))
+                throw new Error("--wave-gate needs a gate name: --wave-gate <name>");
+        }
+        else if (arg === "--wave") {
+            const raw = args[++i];
+            const wave = Number(raw);
+            if (!Number.isInteger(wave) || wave < 1)
+                throw new Error(`--wave needs a wave number from 1: got "${raw ?? ""}"`);
+            result.wave = wave;
+        }
+        else if (arg === "--decide") {
+            result.decide = true;
+        }
+        else if (arg === "--record-plans") {
+            result.recordPlans = true;
+        }
+        else if (arg === "--share") {
+            const raw = args[++i];
+            const share = Number(raw);
+            if (!Number.isInteger(share) || share < 1)
+                throw new Error(`--share needs a share number from 1: got "${raw ?? ""}"`);
+            result.share = share;
+        }
+        else if (arg === "--canary") {
+            const raw = args[++i];
+            if (!raw || raw.startsWith("-"))
+                throw new Error("--canary needs a component name: --canary <name>[,<name>...]");
+            (result.canary ?? (result.canary = [])).push(...raw.split(",").map((n) => n.trim()).filter(Boolean));
+        }
+        else if (arg === "--pr") {
+            const raw = args[++i];
+            const pr = Number(raw);
+            if (!Number.isInteger(pr) || pr < 1)
+                throw new Error(`--pr needs a pull or merge request number: got "${raw ?? ""}"`);
+            result.pr = pr;
+        }
+        else if (arg === "--forge") {
+            result.forge = args[++i];
+            if (!result.forge || result.forge.startsWith("-"))
+                throw new Error("--forge needs a forge: --forge github|gitlab|forgejo");
+        }
+        else if (arg === "--require-review") {
+            result.requireReview = true;
+        }
+        else if (arg === "--pr-loop") {
+            result.prLoop = true;
+        }
+        else if (arg === "--resume") {
+            // `chant approve <op> <gate> --resume` (#3683) takes no value; the
+            // fan-out and pull-request apply take the attempt file they resume.
+            const next = args[i + 1];
+            if (next === undefined || next.startsWith("-"))
+                result.resumeRun = true;
+            else
+                result.resume = args[++i];
+        }
+        else if (arg === "--local") {
+            result.local = true;
+        }
+        else if (arg === "--json") {
+            result.json = true;
+        }
+        else if (arg === "--progress-json") {
+            result.progressJson = true;
+        }
+        else if (arg === "--gated-exit") {
+            // `chant run <op> --gated-exit <code>` (#2243) — remap only the gated
+            // outcome's exit code. Parsed as a number here and range-checked in the
+            // handler, where the refusal can name the flag alongside the run.
+            result.gatedExit = Number(args[++i]);
+        }
+        else if (arg === "--durable-requests") {
+            // `chant run approve ... --on <lexicon> --durable-requests` (#2126) —
+            // resolve the gate on the hosting runtime's own request path rather
+            // than by posting a follow-up prompt. Core only carries the flag; the
+            // runtime decides whether it has such a path.
+            result.durableRequests = true;
+        }
+        else if (arg === "--update-snapshot") {
+            result.updateSnapshot = true;
+        }
+        else if (arg === "--update-baseline") {
+            result.updateBaseline = true;
+        }
+        else if (arg === "--deep") {
+            result.deep = true;
+        }
+        else if (arg === "--at") {
+            result.at = args[++i];
+        }
+        else if (arg === "--kind") {
+            // `chant workspace records|graph|check --kind <kind file>` (#2546, #2549)
+            result.kind = args[++i];
+            if (!result.kind || result.kind.startsWith("-"))
+                throw new Error("--kind needs a kind file: --kind <path>");
+            // Repeatable for `workspace graph --intent` (#2651); the others read the last one.
+            (result.kinds ?? (result.kinds = [])).push(result.kind);
+        }
+        else if (arg === "--composites") {
+            // `chant workspace graph --composites` (#2662)
+            result.composites = true;
+        }
+        else if (arg === "--intent") {
+            // `chant workspace graph --intent <path[:start-end]|path#symbol>` (#2651), or `--intent --record <id>` with no region.
+            const value = args[i + 1];
+            if (value !== undefined && !value.startsWith("-"))
+                result.intent = args[++i];
+            else if (args.includes("--record"))
+                result.intent = "";
+            else
+                throw new Error("--intent needs a region: --intent <path[:start-end]|path#symbol>, or --intent --record <id>");
+        }
+        else if (arg === "--follow-squash") {
+            // `chant workspace graph --intent ... --follow-squash` and `chant workspace runs --follow-squash` (#3035)
+            result.followSquash = true;
+        }
+        else if (arg === "--record") {
+            // `chant workspace graph --intent --record <id>`
+            result.record = args[++i];
+            if (!result.record || result.record.startsWith("-"))
+                throw new Error("--record needs a record id: --record <id>");
+        }
+        else if (arg === "--path") {
+            // `chant workspace patch <range> --path <p>`, repeatable
+            const value = args[++i];
+            if (!value || value.startsWith("-"))
+                throw new Error("--path needs a path: --path <path>");
+            (result.paths ?? (result.paths = [])).push(value);
+        }
+        else if (arg === "--worktree") {
+            // `chant workspace patch [<commit>] --worktree`
+            result.worktree = true;
+        }
+        else if (arg === "--max-bytes") {
+            // `chant workspace patch <range> --max-bytes <n>`
+            const value = Number(args[++i]);
+            if (!Number.isInteger(value) || value < 1)
+                throw new Error("--max-bytes needs a whole number of bytes above 0");
+            result.maxBytes = value;
+        }
+        else if (arg === "--changes") {
+            // `chant workspace check --changes <base>..<head>` (#2773)
+            result.changes = args[++i];
+            if (!result.changes || result.changes.startsWith("-"))
+                throw new Error("--changes needs a range: --changes <base>..<head>");
+        }
+        else if (arg === "--severity") {
+            // `chant workspace check --changes <range> --severity off|warn|fail` (#2773)
+            result.severity = args[++i];
+            if (!result.severity || result.severity.startsWith("-"))
+                throw new Error("--severity needs off, warn or fail");
+        }
+        else if (arg === "--current") {
+            result.current = true;
+        }
+        else if (arg === "--uncommitted") {
+            // `chant workspace records --uncommitted` (#3160)
+            result.uncommitted = true;
+        }
+        else if (arg === "--set") {
+            // `chant workspace records amend <id> --set <file|->` (#2670)
+            result.set = args[++i];
+            if (!result.set || (result.set.startsWith("-") && result.set !== "-"))
+                throw new Error("--set needs a JSON file, or - for standard input: --set <file|->");
+        }
+        else if (arg === "--cover") {
+            // `chant workspace box listing set <member> --cover <image>` (#3308)
+            result.cover = args[++i];
+            if (!result.cover || result.cover.startsWith("-"))
+                throw new Error("--cover needs a PNG, JPEG or WebP file: --cover <image>");
+        }
+        else if (arg === "--cover-path") {
+            // `chant workspace box listing set <member> --cover <image> --cover-path <path>` (#3308)
+            result.coverPath = args[++i];
+            if (!result.coverPath || result.coverPath.startsWith("-"))
+                throw new Error("--cover-path needs a path from the workspace root: --cover-path <path>");
+        }
+        else if (arg === "--records") {
+            // `chant workspace box publish <member> --records` (#3165): the records kept uncommitted, not a work item.
+            result.records = true;
+        }
+        else if (arg === "--expect") {
+            // `chant workspace records amend|review|close <id> --expect <digest>` (#3173): the record's digest the caller last read.
+            result.expect = args[++i];
+            if (!result.expect || result.expect.startsWith("-"))
+                throw new Error("--expect needs the record's digest, as records --json prints it: --expect <digest>");
+        }
+        else if (arg === "--label") {
+            // `chant workspace wip save --label <text>` (#3172)
+            result.label = args[++i];
+            if (!result.label || result.label.startsWith("-"))
+                throw new Error("--label needs the snapshot's name, such as a turn id: --label <text>");
+        }
+        else if (arg === "--branch") {
+            // `chant workspace wip --branch <branch>` (#3172)
+            result.branch = args[++i];
+            if (!result.branch || result.branch.startsWith("-"))
+                throw new Error("--branch needs a branch name: --branch <branch>");
+        }
+        else if (arg === "--workflow") {
+            // `chant ci workflow --workflow <name>`, repeatable (#3573)
+            const name = args[++i];
+            if (!name || name.startsWith("-"))
+                throw new Error("--workflow needs a workflow's name: --workflow <name>");
+            result.ciWorkflows = [...(result.ciWorkflows ?? []), name];
+        }
+        else if (arg === "--chant") {
+            // `chant ci workflow --chant <command>` (#3573): what the tick step runs chant with.
+            result.ciChant = args[++i];
+            if (!result.ciChant || result.ciChant.startsWith("-"))
+                throw new Error("--chant needs the command that runs chant, such as \"npx tsx packages/core/src/cli/main.ts\": --chant <command>");
+        }
+        else if (arg === "--install") {
+            // `chant ci workflow --install <command>` (#3573): a step before the tick that installs what --chant runs.
+            result.ciInstall = args[++i];
+            if (!result.ciInstall || result.ciInstall.startsWith("-"))
+                throw new Error("--install needs the install command, such as \"npm install\": --install <command>");
+        }
+        else if (arg === "--token-secret") {
+            // `chant ci workflow --token-secret <NAME>` (#3573): the secret the tick's tag push authenticates with.
+            result.ciTokenSecret = args[++i];
+            if (!result.ciTokenSecret || result.ciTokenSecret.startsWith("-"))
+                throw new Error("--token-secret needs a repository secret's name, such as CI_GREEN_TOKEN: --token-secret <NAME>");
+        }
+        else if (arg === "--app-id-var") {
+            // `chant ci workflow --app-id-var <VAR> --app-key-secret <NAME>` (#3573): a GitHub App token pushes the tags.
+            result.ciAppIdVar = args[++i];
+            if (!result.ciAppIdVar || result.ciAppIdVar.startsWith("-"))
+                throw new Error("--app-id-var needs the Actions variable holding the App's id: --app-id-var <VAR>");
+        }
+        else if (arg === "--app-key-secret") {
+            result.ciAppKeySecret = args[++i];
+            if (!result.ciAppKeySecret || result.ciAppKeySecret.startsWith("-"))
+                throw new Error("--app-key-secret needs the secret holding the App's private key: --app-key-secret <NAME>");
+        }
+        else if (arg === "--verdict") {
+            // `chant workspace records review <id> --verdict agree|dissent|abstain` (#2670)
+            result.verdict = args[++i];
+            if (!result.verdict || result.verdict.startsWith("-"))
+                throw new Error("--verdict needs agree, dissent or abstain");
+        }
+        else if (arg === "--by") {
+            // `chant workspace records review <id> --by <principal>` (#2670): whoever the caller says.
+            result.by = args[++i];
+            if (!result.by || result.by.startsWith("-"))
+                throw new Error("--by needs the reviewer: --by <principal>");
+            // Repeatable for `workspace points answer` (#2739): each person who answered.
+            (result.bys ?? (result.bys = [])).push(result.by);
+        }
+        else if (arg === "--open") {
+            // `chant workspace points --open` (#2739): only the questions still open.
+            result.open = true;
+        }
+        else if (arg === "--inputs") {
+            // `chant workspace points ask <point> --inputs <file|-|json>` (#2739; JSON itself, #3403)
+            result.inputs = args[++i];
+            if (!result.inputs || (result.inputs.startsWith("-") && result.inputs !== "-"))
+                throw new Error("--inputs needs a JSON file, - for standard input, or the JSON itself: --inputs <file|-|json>");
+        }
+        else if (arg === "--candidates") {
+            // `chant workspace points ask <point> --candidates <file|-|json>` (#3403): an ad-hoc point's question and candidates.
+            result.candidates = args[++i];
+            if (!result.candidates || (result.candidates.startsWith("-") && result.candidates !== "-"))
+                throw new Error("--candidates needs a JSON file, - for standard input, or the JSON itself: --candidates <file|-|json>");
+        }
+        else if (arg === "--response") {
+            // `chant workspace points ask <point> --response <file>` (#2739): a POST /v1/systemone response the caller got.
+            result.response = args[++i];
+            if (!result.response || result.response.startsWith("-"))
+                throw new Error("--response needs a JSON file: --response <file>");
+        }
+        else if (arg === "--subject") {
+            // `chant workspace points ask <point> --subject <id>` (#2739): what the question is about.
+            result.subject = args[++i];
+            if (!result.subject || result.subject.startsWith("-"))
+                throw new Error("--subject needs what the question is about, such as a work item id: --subject <id>");
+        }
+        else if (arg === "--store") {
+            // `chant workspace points ask <point> --store ledger` (#3815): where a new question goes.
+            const store = args[++i];
+            if (store !== "tree" && store !== "ledger")
+                throw new Error("--store is tree (the answer kind's directory in the working tree) or ledger (chant/lifecycle): --store <tree|ledger>");
+            result.store = store;
+        }
+        else if (arg === "--answer") {
+            // `chant workspace points answer <id> --answer <value>` (#2739)
+            result.answer = args[++i];
+            if (result.answer === undefined || result.answer === "")
+                throw new Error("--answer needs one of the question's candidates: --answer <value>");
+        }
+        else if (arg === "--sign") {
+            // `chant workspace records review <id> --sign [<key file>]` (#2687): seal the verdict.
+            // `records new` and `records amend` take it too, to seal the record's author (#2688).
+            // `chant approve <op> <gate> --sign [<key file>]` seals a gate approval (#3163).
+            // With no key file, git's user.signingkey, as `git commit -S` reads it.
+            const next = args[i + 1];
+            result.sign = next !== undefined && !next.startsWith("-") ? args[++i] : true;
+        }
+        else if (arg === "--session") {
+            // `chant workspace records review <id> --session <id>` (#2670)
+            result.session = args[++i];
+            if (!result.session || result.session.startsWith("-"))
+                throw new Error("--session needs a session id: --session <id>");
+        }
+        else if (arg === "--prefix") {
+            // `chant workspace records new <kind> --prefix <prefix>` (#2670): the id prefix to allocate under.
+            result.prefix = args[++i];
+            if (!result.prefix || result.prefix.startsWith("-"))
+                throw new Error("--prefix needs an id prefix: --prefix <prefix>");
+        }
+        else if (arg === "--key" || arg === "--check-id" || arg === "--claim" || arg === "--environment" || arg === "--envelope" || arg === "--threshold") {
+            // `chant workspace evidence sign|verify` and `chant workspace signers` (#2553)
+            const value = args[++i];
+            if (value === undefined || value.startsWith("-"))
+                throw new Error(`${arg} needs a value`);
+            const field = { "--key": "key", "--check-id": "checkId", "--claim": "claim", "--environment": "environment", "--envelope": "envelope", "--threshold": "threshold" }[arg];
+            result[field] = value;
+        }
+        else if (arg === "--require") {
+            // `chant workspace records|verify --require attested` (#2547)
+            result.require = args[++i];
+            if (!result.require || result.require.startsWith("-"))
+                throw new Error("--require needs a provenance level: --require attested");
+        }
+        else if (arg === "--ambient") {
+            result.ambient = true;
+        }
+        else if (arg === "--check-live") {
+            result.checkLive = true;
+        }
+        else if (arg === "--check-snapshot") {
+            result.checkSnapshot = true;
+        }
+        else if (arg === "--fail-on-drift") {
+            result.failOnDrift = true;
+        }
+        else if (arg === "--run-examples") {
+            result.runExamples = true;
+        }
+        else if (arg === "--pinned-digest") {
+            result.pinnedDigest = args[++i];
+        }
+        else if (arg === "--check") {
+            result.check = true;
+        }
+        else if (arg === "--bump") {
+            result.bump = true;
+        }
+        else if (arg === "--component") {
+            result.component = args[++i];
+        }
+        else if (arg === "--digest") {
+            result.digest = args[++i];
+            if (result.digest !== undefined)
+                (result.digests ?? (result.digests = [])).push(result.digest);
+        }
+        else if (arg === "--release-plan") {
+            result.releasePlanFile = args[++i];
+        }
+        else if (arg === "--git-sha") {
+            result.gitSha = args[++i];
+        }
+        else if (arg === "--run-id") {
+            result.runId = args[++i];
+        }
+        else if (arg === "--actor") {
+            result.actor = args[++i];
+        }
+        else if (arg === "--approver") {
+            result.approver = args[++i];
+        }
+        else if (arg === "--relayed-by") {
+            // `chant approve <op> <gate> --relayed-by <principal>` and `workspace points answer <id> --relayed-by <principal>` (#3402):
+            // who carried the approval or answer to chant for the person it names.
+            result.relayedBy = args[++i];
+            if (!result.relayedBy || result.relayedBy.startsWith("-"))
+                throw new Error("--relayed-by needs the principal that relayed it: --relayed-by <principal>");
+        }
+        else if (arg === "--on") {
+            // `chant run ... --on <lexicon>` (#2121) — which runtime hosts the run.
+            result.on = args[++i];
+            if (!result.on || result.on.startsWith("-"))
+                throw new Error("--on needs a runtime name: --on <lexicon>");
+        }
+        else if (arg === "--compare-to") {
+            result.compareTo = args[++i];
+        }
+        else if (arg === "--no-release-record") {
+            result.noReleaseRecord = true;
+        }
+        else if (arg === "--fold") {
+            result.fold = true;
+        }
+        else if (arg === "--no-cache") {
+            // `chant workspace graph --no-cache` (#2876): read every member.
+            result.noCache = true;
+        }
+        else if (arg === "--no-fold") {
+            // chant #1134 — fold is the default build path; this is the explicit
+            // opt-out, and like --fold it beats chant.config.ts's build.fold.
+            result.fold = false;
+        }
+        else if (arg === "--sandbox") {
+            result.sandbox = true;
+        }
+        else if (arg === "--fold-rank") {
+            // chant #1083 — same context-sensitive shape as --report above:
+            // `--fold-rank` alone prints the ranked-blocker report; `--fold-rank
+            // <path>` ALSO writes the Brendan Gregg collapsed-format export there.
+            const next = args[i + 1];
+            if (next && !next.startsWith("-")) {
+                result.foldRankCollapsedFile = next;
+                i++;
+            }
+            else {
+                result.foldRank = true;
+            }
+        }
+        else if (arg === "--param") {
+            // chant #1118/#1127 — `--param name=value` (space-separated) and
+            // `--param=name=value` (joined, split above at its first `=` into flag
+            // `--param` + value `name=value`) both land here and behave
+            // identically; there is no separate joined-form error anymore (the
+            // #1118 hard error this superseded only existed because the parser
+            // didn't support joined forms at all — now that it does, the joined
+            // form is just as valid as the space-separated one).
+            (result.param ?? (result.param = [])).push(args[++i]);
+        }
+        else if (arg === "--lexicon-output") {
+            // `--lexicon-output <lexicon>=<path>` (repeatable); the joined form
+            // `--lexicon-output=otel=a.yml` arrives here already split at the first `=`.
+            (result.lexiconOutput ?? (result.lexiconOutput = [])).push(args[++i]);
+        }
+        else if (arg === "--params-file") {
+            result.paramsFile = args[++i];
+        }
+        else if (arg === "--projection") {
+            result.projection = args[++i];
+        }
+        else if (arg === "--interval") {
+            result.interval = args[++i];
+        }
+        else if (arg === "--lease-ttl") {
+            result.leaseTtl = args[++i];
+        }
+        else if (arg === "--steward") {
+            // #2731 — the name is optional: a project with one steward runs it
+            // with a bare `--steward`.
+            const next = args[i + 1];
+            if (next !== undefined && !next.startsWith("-")) {
+                result.steward = next;
+                i++;
+            }
+            else {
+                result.steward = "";
+            }
+        }
+        else if (arg === "--once") {
+            result.once = true;
+        }
+        else if (arg === "--work") {
+            // `chant run <op> --work <id>` (#2748)
+            const value = args[++i];
+            if (!value || value.startsWith("-"))
+                throw new Error("--work needs a work item id: --work <id>");
+            result.work = value;
+        }
+        else if (arg === "--holder" || arg === "--ttl" || arg === "--token" || arg === "--outcome") {
+            // `chant workspace work claim|renew|release <id>` (#2732)
+            const value = args[++i];
+            if (!value || value.startsWith("-"))
+                throw new Error(`${arg} needs a value: ${arg} <${arg.slice(2)}>`);
+            result[arg.slice(2)] = value;
+        }
+        else if (arg === "--signer") {
+            // `chant workspace runs statement <id> --signer <principal>` (#3192): the runner principal that will sign.
+            const value = args[++i];
+            if (!value || value.startsWith("-"))
+                throw new Error("--signer needs a principal: --signer <principal>");
+            result.signer = value;
+        }
+        else if (arg === "--unit" || arg === "--decision") {
+            // `chant workspace runs --unit <id> | --decision <id>` (#3033): the runs on one work item, or for one decision.
+            const value = args[++i];
+            if (!value || value.startsWith("-"))
+                throw new Error(`${arg} needs an id: ${arg} <id>`);
+            result[arg.slice(2)] = value;
+        }
+        else if (arg === "--note") {
+            result.note = args[++i];
+        }
+        else if (arg === "--reason") {
+            // `chant approve policy-override <subject> --reason <text>` (#3760): why the denied plan goes out anyway.
+            result.reason = args[++i];
+            if (result.reason === undefined || result.reason.startsWith("-"))
+                throw new Error("--reason needs the text of the reason: --reason <text>");
+        }
+        else if (arg === "--rule") {
+            // `chant approve policy-override <subject> --rule <id>` (#3760), once per rule that denied the plan.
+            const value = args[++i];
+            if (!value || value.startsWith("-"))
+                throw new Error("--rule needs a rule id: --rule <id>");
+            (result.rules ?? (result.rules = [])).push(value);
+        }
+        else if (arg === "--expire") {
+            result.expire = true;
+        }
+        else if (arg === "--role") {
+            // #2508 — a role the approver holds, for a gate whose quorum names
+            // roles. Repeatable, and a comma list works too.
+            const value = args[++i] ?? "";
+            result.roles = [...(result.roles ?? []), ...value.split(",").map((r) => r.trim()).filter(Boolean)];
+        }
+        else if (arg === "--agent") {
+            // #2508 — record the approval as an agent's rather than a person's.
+            result.agent = true;
+        }
+        else if (arg === "--allow-code") {
+            // #2550 — `chant workspace upgrade` runs a template's code migrations
+            // only when asked to.
+            result.allowCode = true;
+        }
+        else if (arg === "--source") {
+            // #2551 — `chant workspace upgrade --source <repo>[#<member>]`.
+            result.source = args[++i];
+            if (!result.source || result.source.startsWith("-"))
+                throw new Error("--source needs a template: --source <repo>[#<member>]");
+        }
+        else if (arg === "--tags") {
+            // #2551 — `chant workspace adopt-lineage --tags <glob>`, also hash-index and versions.
+            result.tags = args[++i];
+            if (!result.tags || result.tags.startsWith("-"))
+                throw new Error("--tags needs a tag glob: --tags 'v*'");
+        }
+        else if (arg === "--index") {
+            // #2551 — `chant workspace adopt-lineage --index <file>`.
+            result.index = args[++i];
+            if (!result.index || result.index.startsWith("-"))
+                throw new Error("--index needs a hash index file: --index <file>");
+        }
+        else if (arg === "--remove") {
+            // #2552 — `chant workspace import --remove` removes the export member instead of writing it again.
+            result.remove = true;
+        }
+        else if (arg === "--available") {
+            // #2551 — `chant workspace versions --available` lists the template's version tags.
+            result.available = true;
+        }
+        else if (arg === "--root-only") {
+            // #2537 — `chant build` and `chant lint` at a declared workspace root
+            // run on the root project alone instead of refusing with WSP000.
+            result.rootOnly = true;
+        }
+        else if (arg === "--generated") {
+            // #2641 — `chant workspace check --generated` runs each declared
+            // generator and compares its output with the file in the tree.
+            result.generated = true;
+        }
+        else if (arg === "--member") {
+            // #2537 — `chant workspace build|lint|audit|graph --member <name>`.
+            // Repeatable, and a comma list works too.
+            const value = args[++i];
+            if (!value || value.startsWith("-"))
+                throw new Error("--member needs a member or group name: --member <name>");
+            result.members = [...(result.members ?? []), ...value.split(",").map((m) => m.trim()).filter(Boolean)];
+        }
+        else if (arg === "--allow-same-origin") {
+            // chant#2384 — record a resolution the same-origin rule would refuse,
+            // deliberately. Flagged on the record, not just accepted quietly.
+            result.allowSameOrigin = true;
+        }
+        else if (arg === "--plan") {
+            result.plan = args[++i];
+        }
+        else if (arg === "--url") {
+            result.url = args[++i];
+        }
+        else if (arg === "--op") {
+            result.op = args[++i];
+        }
+        else if (arg === "--since") {
+            result.since = args[++i];
+        }
+        else if (arg === "--limit") {
+            // Parsed here, validated by the handler — `parseArgs` reports shape, not
+            // policy, the same split every other value flag here uses.
+            result.limit = Number(args[++i]);
+        }
+        else if (arg.startsWith("--")) {
+            // chant #1127 — every recognized flag is matched above; anything left
+            // starting with `--` is unrecognized, whether it arrived bare
+            // (`--bogus`) or joined (`--bogus=value`, already split into
+            // `--bogus` + `value` above). This used to fall through silently (the
+            // "ignores unknown flags" case) — a typo'd or misremembered flag would
+            // vanish with no diagnostic, exactly like the silent-drop this issue
+            // closes for joined values. Point at --help rather than enumerating
+            // every flag here: this parser's flag set is one flat list shared by
+            // every command, not scoped per-command, so "the command's known
+            // flags" isn't something this loop can name in isolation.
+            throw new Error(`Unknown flag: ${arg}\nRun "chant --help" to see supported flags.`);
+        }
+        else if (!arg.startsWith("-")) {
+            if (result.command)
+                (result.positionals ?? (result.positionals = [])).push(arg);
+            if (!result.command) {
+                result.command = arg;
+            }
+            else if (result.path === ".") {
+                result.path = arg;
+            }
+            else if (!result.extraPositional) {
+                result.extraPositional = arg;
+            }
+            else {
+                result.extraPositional2 = arg;
+            }
+        }
+        i++;
+    }
+    // #2603 — `--promote-to` (#2575) adds a job to the pipeline that generate
+    // mode synthesizes; no other command or mode reads it. Checked here, once
+    // the whole command line is known, rather than in the build handler, so
+    // `chant build --promote-to prod` and `chant run --promote-to prod` both
+    // fail instead of running as if the flag were absent. A lexicon-mounted
+    // command that takes its own `--promote-to` still gets it: `main` tries the
+    // plugin commands before rethrowing a parse error.
+    if (result.promoteTo && !(result.command === "build" && result.components && result.generate)) {
+        throw new Error("--promote-to needs build --components --generate <lexicon>: it adds a promote job to the generated CI pipeline, and only generate mode emits one.");
+    }
+    return result;
+}
+/**
+ * Print help message. `groups` — lexicon-contributed command groups
+ * (chant #1078), best-effort loaded from the current project; composed in
+ * below the static command list so `--help` lists every mounted verb group
+ * alongside core's own commands.
+ */
+function printHelp(groups = []) {
+    console.log(`
+chant - Declarative infrastructure specification toolkit
+
+Usage:
+  chant <command> [options] [path]
+
+Commands:
+  init                  Initialize a new chant project
+                        (--from <repo>@<ref>[#<member>] copies a template
+                        repository and records its lineage, and --from
+                        <dir>[#<member>] copies a template directory on
+                        disk; --param
+                        <name>=<value> sets a parameter the template's
+                        chant.template.json declares, repeatable)
+  init lexicon <name>   Scaffold a new lexicon plugin project
+  build                 Build infrastructure from specification files
+                        (--components --generate github|gitlab|forgejo:
+                         generate mode (#563), which synthesizes a thin CI
+                         pipeline that triggers each discovered component's
+                         own deploy in wave order, instead of a normal
+                         lexicon build)
+                        At a declared workspace root it refuses with WSP000;
+                        --root-only builds the root project alone
+  lint                  Check specifications for issues
+                        (at a declared workspace root: WSP000 unless --root-only)
+  list                  List discovered entities
+  describe              Show the effective config for one component
+  explain               Summarize discovered entities (--format markdown|json|okf;
+                        okf emits an OKF v0.2 knowledge bundle — one markdown
+                        concept per entity + index.md; -o <dir> writes the
+                        bundle tree, otherwise JSON path→content on stdout)
+  generate              Generate typed code from sources chant.config declares
+                        (k8s.crds, helm.charts) into src/generated/<lexicon>/
+                        (codegen.outDir); --check exits 1 when the committed
+                        output no longer matches its sources, as build does
+  vendor                Pull pinned, checksummed patterns into your repo
+                        (pull [name] | check | migrate; migrate moves
+                        vendor.json into .chant/workspace.lock.json)
+  import                Import external template into TypeScript
+                        (--agents re-expresses this machine's agent config as
+                         chant code instead of reading a template file)
+  audit [path|url]      Audit a repo's CI YAML for security issues
+                        (--format stylish|json|sarif|markdown|html, -o <file>,
+                         --tier merge-worthy|all, --fail-on merge-worthy|warning|error|none,
+                         --template <file> / --theme <file> for the html report,
+                         --max-files <n> to walk more than 1000 files)
+                        --agents audits this machine's agent configuration —
+                        instruction files, MCP servers, skills, plugins,
+                        permissions — instead of a repository
+                        (--scope system,user,project, --runtime claude,codex,...,
+                         --all-projects)
+  migrate <file>        Translate a workflow between lexicons
+                        (default: --from github --to gitlab)
+  carve advise          Read-only peelability advisor: rank which resources
+                        --from <dir>      are cheap to carve into native chant
+                        (--json, --report <path>). Emits nothing, changes nothing.
+                        --from a Terraform dir needs @cdktn/hcl2json
+                        (npm install -D @cdktn/hcl2json); --from a CDK cloud
+                        assembly (cdk.out) needs nothing and ranks constructs.
+  carve emit            Adopt a selected TF resource into chant source + report
+                        --from <tf-dir>   its boundary. --state <tfstate> adopts offline
+                        --select <addr>   (recommended for TF-managed resources); --env
+                        --state|--env     <env> adopts via live cloud import (--live-name
+                                          <logical-id> narrows a multi-resource stack).
+                                          Persists a carve manifest bridge/apply compose
+                                          with; scaffolds the output dir into a buildable
+                                          chant project (src/ + config + package.json).
+  carve bridge          Generate the surviving-TF patch (data sources + rewired
+                        --from <tf-dir>   refs) + deferred inputs + reversible runbook,
+                        [--select <addr>] plus one git-applyable .patch for the whole
+                                          edit. Writes proposals for review;
+                                          --apply-rewrites edits the .tf in place.
+                                          --select is optional when the output dir
+                                          holds one carve manifest.
+  carve apply           Apply graduation: ownership marker + finalized apply
+                        --from <tf-dir>   runbook (dial-turn observe→apply). BYOL —
+                        [--select <addr>] no cloud call; --write saves the doc. --select
+                        --env <env>       is optional with a carve manifest present.
+                                          --write-source stamps the ownership marker
+                                          into the emitted chant source.
+  carve status          Status read over a tree of carve manifests: every
+                        [--from <dir>]    *.carve.json under --from (default: cwd) with
+                        (--json)          its target, stage (planned/emitted/bridged/
+                                          applied) and path. Read-only.
+
+CI:
+  ci last-green [--json]  The newest first-parent commit of ci.green's branch
+                        with a ci/green tag and no ci/revoked tag. Reads local
+                        tags only; fetch them first.
+  ci tick [--dry-run] [--forge github]  Tag each commit within ci.green's
+                        window whose required phases all passed ci/green/<sha>,
+                        and revoke a green one that now fails ci/revoked/<sha>.
+                        Reads check runs from the forge, pushes the tags.
+  ci workflow [--workflow <name>]... [--output <file>]  Write
+              [--chant <command>] [--install <command>]
+              [--token-secret <NAME> | --app-id-var <VAR> --app-key-secret <NAME>]
+                        .github/workflows/chant-ci-green.yml, which runs the
+                        tick when a required workflow completes and every 15m.
+                        --chant replaces the npx @intentius/chant pin the tick
+                        runs; --install adds a step before it. --token-secret,
+                        or a GitHub App's id and key, pushes the tags with a
+                        token that may tag commits changing workflow files.
+
+Change sets:
+  change-set summary <file>  The grouped plan summary of a change-set
+                        [--format text|json|markdown]  document: members taking
+                        [--limit <chars>]  the same change grouped, every destroy,
+                                          replacement, failure and hole named.
+                                          markdown fits an MR/PR note of --limit
+                                          characters (default 65536). Read-only.
+
+Ops:
+  run <name>            Run an Op on the resolved runtime (--on; local by default)
+                        [--work <id>] [--holder <name>]: the work item an Op
+                        with a work lease runs under, and who holds it
+                        --fail-on-drift: exit 2 when the run completes and
+                        its Drift outcome is true (WatchOp failOn: "drift")
+  run list              List all Ops with the runtime's state for each
+  run status <name>     Show the runtime's state for one Op's latest run
+  run approve <op> <gate>  Record a gate's resolution and wake the runtime
+  run cancel <name>     Cancel the active run (requires --force)
+  run log <name>        Show run history for an Op
+  run wave --spec <file> --wave <k>  Plan, gate and apply wave k of an Op
+                        waves spec (#3679): the job a generated waves
+                        pipeline runs. --decide plans and decides only;
+                        --share <i> applies one share of a decided wave.
+                        --record-plans (no --wave), in a pull request's
+                        pipeline: plan every wave at its head and record the
+                        digests a pr-review approval mode compares
+  run resume [--op <name>] [--gate <name>]  Start again each CI job that
+                        waits at a gate an approval now answers, through the
+                        forge's API (#3683); approves nothing. --gate resumes
+                        that gate's job alone (#3854). Skips an approval a
+                        wave already applied under; restarts an apply that
+                        stopped once its run is gone (#3858). --dry-run
+                        starts nothing; with --json it says per gate whether
+                        it would resume and why
+  run --generate <provider>  Write one CI pipeline file per scheduled Op for
+                        github, gitlab or forgejo (#2533), from every Op that
+                        declares a schedule or from --spec <file.json>.
+                        Files go to the forge's own directory unless
+                        --output <dir>; --format json prints them instead
+  run --components <name|all>  Run discovered Component(s) through the interpret
+                        driver on the local executor (--env <env>; #585).
+                        On success, auto-emits a release-ledger record per
+                        component that published a digest (default: on;
+                        --no-release-record to opt out; #597)
+                        --progress-json: stream one NDJSON RunProgressEvent
+                        per line to stdout while the run executes, for a
+                        consumer to render live wave/component/phase/step
+                        progress instead of tailing raw logs (additive; run
+                        semantics/exit code unchanged)
+  operator               Run scheduled ticks for discovered ConvergeOps
+                        locally (#1485): acquire/renew a per-op
+                        lease (git ref CAS), tick on --interval, record every
+                        result as a ledger fact. --env <env> scopes to one
+                        environment; --interval <dur> (default 60s) and
+                        --lease-ttl <dur> (default 5m) tune cadence; --once
+                        runs a single round and exits (cron/systemd-timer/
+                        CronJob invokers use this instead of the daemon).
+                        --steward [<name>] runs a declared steward's local
+                        form instead (#2731): its scheduled Ops on their
+                        crons, under the steward's own lease, and its
+                        beside Ops as chant run processes of their own
+                        (#2861)
+  operator status        Last tick, outcomes, and pending gates per
+                        ConvergeOp, read from the chant/lifecycle orphan
+                        branch alone — no daemon needs to be running
+                        (--env <env>, --json)
+  operator log           Converge tick history and the gate resolutions
+                        against it, merged into one timestamp-ordered
+                        timeline, from the same orphan branch (--env <env>,
+                        --op <name>, --since <iso>, --limit <n>, --json).
+                        --json also carries the count of ledger lines that
+                        were unreadable, so a short timeline is never
+                        silently short
+  approve <op> <gate>    Record a gate's out-of-band resolution fact
+                        (--actor <name>, --note <text>, --url <url>) — the
+                        durable counterpart to the pending fact a run records
+                        when it reaches the gate; see the pending-gates list
+                        in operator status. --url is the PR/MR the resolution
+                        happened at, recorded typed rather than as free text,
+                        and defaults to the PR/MR of the surrounding CI job.
+                        The next "chant run <op>" walks through the gate.
+                        --expire clears a pending fact without approving it,
+                        so the gate is re-decided from scratch next run.
+                        --sign [<key file>] seals the approval with an ssh
+                        key; a gate the workspace's identity.gates names
+                        counts only an approval sealed by a key the signers
+                        file at base lists for --actor. --relayed-by
+                        <principal> records who carried the approval to chant
+                        for --actor (a follower, a bot); --sign covers it.
+                        --resume then starts the CI job that waits at the
+                        gate again (GitHub re-run, GitLab retry, Forgejo
+                        dispatch) with CHANT_FORGE_TOKEN
+                        On op policy-override the gate is the subject a
+                        policy denied: --rule <id> names each rule that
+                        denied it and --reason <text> says why the plan goes
+                        out anyway; the next run that plans the same digest
+                        applies it once, if .chant/overriders at base lists
+                        --actor
+
+  graph                 Show Op dependency graph (--stacks for cross-stack order,
+                        --format ir|mermaid|dot|layout for the lint-gated graph IR,
+                        a Mermaid flowchart, Graphviz DOT, or node positions;
+                        layout uses dagre by default (no native dep) — pass
+                        --node-sizes <json|-|@file> for size-aware spacing,
+                        --layout-engine graphviz to use dot instead;
+                        --detail 0..3: stacks|composites|declarables|attributes;
+                        --lens lexicon:<n>|stack:<n>|blast:<node> (--up/--down))
+                        --components --format ir --projection gitlab|github|forgejo:
+                        add the CI/pipeline projection (stages/jobs/needs) to
+                        the component-graph IR, from the same generator
+                        'build --components --generate' uses (#989)
+                        --traffic "<level>": ask the project's predicting
+                        lexicon what the estate does at that traffic level, and
+                        carry each entity's prediction on the IR. On the
+                        declared graph it predicts the file; with --live it
+                        predicts the account. The level reaches the engine
+                        verbatim; without the flag nothing is asked (#2377)
+
+Workspace (level 1, #2524):
+  workspace init [dir]  Propose a chant.workspace.json from the projects and
+                        packages already in the repository, print it with the
+                        directories that would leave the root project, and
+                        write it only on confirmation (--yes writes without
+                        asking; --name <name> names the workspace; --verbose
+                        lists every file leaving the root project)
+  workspace ls [dir]    List the declaration's members and example groups.
+                        A member that can't be read is listed with a reason
+                        code and still exits 0. --at <rev> reads a commit's
+                        git objects; --json prints the read-contract document
+  workspace status <env> [dir] [--compare-to <env>] [--json]
+                        Each member's latest release in <env>, as digest and
+                        git SHA, read from its ledger on the local
+                        chant/lifecycle branch (_members/<member>/ or the flat
+                        layout). --compare-to <env> shows a second environment
+                        beside it and marks the members whose digests differ.
+                        Read only; never fetches. --json prints the
+                        read-contract document
+  workspace records [--kind <kind file>] [--current] [--uncommitted | --at <rev>] [--base <rev>] [--require attested] [--json]
+                        Without --kind, every record kind the declaration
+                        names. Read the records a record kind locates, validated
+                        against its schema, with reason codes for invalid
+                        ones. --current leaves out superseded records; --at
+                        reads a commit's git objects. Needs no workspace file.
+                        Each record reports its provenance level, judged by
+                        the signers at --base (default: the target branch);
+                        --require attested exits 2 if any record is not
+                        attested. A pinned file that changed is a warning,
+                        asset-drift or asset-missing. In the working tree,
+                        each record says whether it is committed, modified
+                        or new against HEAD, with the branch and base;
+                        --uncommitted lists only the modified and new ones
+  workspace records [--kind <kind file>] --since <rev|session id> [--at <rev>] [--json]
+                        What changed in the records between <rev> and --at
+                        (default: the working tree): new and removed records,
+                        state transitions, new verdicts, new supersessions
+                        and changed pins. A session id compares the commits
+                        the session opened and closed at
+  workspace records pin <path>
+                        Print the path from the workspace root and the
+                        sha256 of a file, for a decision's evidence pin
+  workspace records new [<kind file>] --from <file|-> [--prefix <prefix>] [--sign [<key file>]] [--dry-run]
+                        Write one new record in the kind's directory from
+                        the JSON fields given, after validating them as
+                        records would read them. Without a kind file, the one
+                        kind the declaration names. Allocates the next id when
+                        the fields hold none. --sign seals the record's author
+                        (decided_by for decisions) with an ssh key. Prints
+                        {path, id} as JSON and never commits
+  workspace records amend <id> [--kind <kind file>] --set <file|-> [--expect <digest>] [--sign [<key file>]] [--dry-run]
+                        Set top-level fields of one record. A closed record
+                        never changes, and an approved one changes only its
+                        state (upward), pins and reviews; anything else is
+                        refused with amend-supersede-instead. Moving a
+                        record to its kind's ratified state (ratified for
+                        decisions) is refused with ratify-quorum-not-met
+                        until its quorum is met. --sign seals the author
+                        again; without it an amendment removes the author
+                        seal and says so. --expect refuses the write with
+                        record-conflict when the record's digest has moved
+                        on. Prints {path, id, changed, digest}
+  workspace records review <id> [--kind <kind file>] --verdict agree|dissent|abstain --by <principal> [--note <text>] [--session <id>] [--expect <digest>] [--sign [<key file>]] [--dry-run]
+                        Append a review to one record, dated and bound to
+                        the digest of the record text. A dissent needs
+                        --note. --sign seals it with an ssh key (git's
+                        user.signingkey without a file); under a signers
+                        file at base only a sealed verdict counts. With
+                        --session, the session must be open, and the verdict
+                        is appended to its verdicts too. --expect refuses a
+                        verdict on a record that moved on. Prints
+                        {path, id, review, digest}
+  workspace records close <session id> [--kind <session kind file>] [--expect <digest>] [--dry-run]
+                        Close an open review session: its state, close time,
+                        closing commit and seal, in one write. Without
+                        --kind, the one session kind the declaration names.
+                        Prints {path, id, changed, seal, closedRev}
+                        Every working-tree write holds the working tree's
+                        write lock (CHANT_WRITE_LOCK_WAIT_MS, default 15s)
+  workspace lock [acquire --holder <name> [--ttl <duration>] | release --token <token>] [--json]
+                        Who holds the working tree's write lock; take it for
+                        a batch of writes across chant calls, each run with
+                        CHANT_WRITE_LOCK=<token>, and give it back
+  workspace work claim|renew|release <id> --holder <name> [--kind <kind file>] [--ttl <seconds|duration>] [--token <token>] [--outcome <outcome>] [--note <text>] [--json]
+                        Take, heartbeat or give back the lease on a work item:
+                        refs/chant/lease/work/<id>, a compare-and-set ref with a
+                        fencing token and an expiry, pushed to the remote so
+                        separate clones coordinate. A claim is refused, exit 2,
+                        while anyone holds it live. Each change appends to
+                        _leases/<id>.jsonl on chant/lifecycle
+  workspace work history <id> [--kind <kind file>] [--json]
+                        A work item's lease history: each claim with its token
+                        and holder, and how it ended, released with an outcome
+                        or never released (expired or lost). Read-only
+  workspace work evidence <id> --holder <name> --token <token> --from <file|-> [--kind <kind file>]
+                        Attach evidence for one acceptance criterion under the
+                        lease you hold: the entry (criterion, result, title,
+                        a url or a path pinned by hash) is appended to the
+                        item's pins through records amend. Prints the
+                        work-evidence document and never commits
+  workspace runs [--unit <id>] [--decision <id>] [--by <principal>] [--since <rev>] [--follow-squash] [--json]
+                        The agent runs in the run ledger on chant/lifecycle, each
+                        with its model, tokens, cost and the commits it made,
+                        and totals per work item, decision and principal; a run
+                        that reports no cost is listed as unpriced, never zero.
+                        Read-only, never fetches; --follow-squash joins each
+                        squash merge to its pull request's runs, fetching a
+                        missing refs/pull/<n>/head from origin
+  workspace runs start --from <file|->
+                        Record that an agent run started: who it worked for,
+                        its harness, model, work item and lease. Prints the run
+                        and its Chant-Run trailer. chant never starts a run
+  workspace runs end <run id> [--from <file|->]
+                        Record how a started run ended: its outcome, tokens,
+                        cost and price source, the transcript pinned by hash,
+                        and the commits it made
+  workspace runs record --from <file|->
+                        Record a finished run, its start and end in one write
+  workspace runs sign <run id> (--key <runner.pem> | --envelope <file|->) [--base <rev>]
+                        Store a DSSE statement over an ended run (its record's
+                        hash, work item, harness, model and commits), signed
+                        with a runner or steward key .chant/trust.json lists
+                        at base, or signed elsewhere and checked here
+  workspace runs statement <run id> --signer <principal>
+                        Print the statement for a signer whose key is
+                        elsewhere, such as a lobby, with the payload to sign
+  workspace runs verify [<run id>] [--require signed] [--base <rev>] [--json]
+                        Judge each run's stored statements against the runner
+                        keys at base. Reports only, unless --require signed
+  workspace box listing set <member> [--from <file|->] [--cover <image> [--cover-path <path>]] [--by <principal>] [--dry-run]
+                        Change a box's listing (published, title, line, cover)
+                        in the declaration, in place, keeping its formatting
+                        and comments; --cover copies a PNG, JPEG or WebP into
+                        the repository. Judged by the write scope at base.
+                        Prints the box-listing-write document; never commits
+  workspace member add <name> --from <file|-> [--by <principal>] [--dry-run]
+  workspace member remove <name> [--by <principal>] [--dry-run]
+  workspace host set <name> --from <file|-> [--by <principal>] [--dry-run]
+                        Add or remove a member's entry, or add or replace a
+                        host's, in the declaration, in place, keeping its
+                        formatting and comments. Refuses a declaration that
+                        doesn't read, or two boxes sharing a port. Judged by
+                        the write scope at base. Prints the member-write
+                        document; never commits
+  workspace box factory set <member> --from <file|-> [--by <principal>] [--dry-run]
+                        Change a box's factory (builds, check, checks,
+                        builders, tiers, publish) in the declaration, in
+                        place, such as where a planted box publishes. Judged
+                        by the write scope at base. Prints the
+                        box-factory-write document; never commits
+  workspace box publish <member> (<item> | --records) [--by <principal>] [--head <owner/name>] [--dry-run]
+                        Publish a built work item, or the records kept
+                        uncommitted, through the publisher the box block names:
+                        run with a JSON request on stdin, its answer checked
+                        and its commit held to the apply record (ws-088).
+                        Prints the box-publish document; chant itself never
+                        commits, pushes or calls a forge
+  workspace wip [--branch <branch>] [--json]
+                        List the work-in-progress snapshots under
+                        refs/chant/wip/<branch>, newest first, and how far each
+                        ref the box's replicate policy names is from its remote.
+                        Reads locally; never fetches (#3172)
+  workspace wip save [--label <text>] [--by <principal>]
+                        Snapshot the whole working tree, uncommitted records
+                        included, onto refs/chant/wip/<branch> without touching
+                        the index or the branch; pushes when the policy says so
+  workspace wip restore [<snapshot>] [--by <principal>]
+                        Put the working tree back as the snapshot (the branch's
+                        latest by default) holds it, after a snapshot of how it
+                        is now; HEAD never moves
+  workspace wip push    Push the refs the box's replicate policy names to its
+                        remote, never forced, for the host's schedule
+  workspace wip fetch   On a replacement box, bring back what was replicated:
+                        create or fast-forward the local refs, then wip restore
+  workspace points [--open] [--kind <kind file>] [--at <rev>] [--json]
+                        List the decision points the declared answer kinds'
+                        points files declare, and the questions asked of them;
+                        --open keeps the escalated and proposed ones (ws-058)
+  workspace points ask <point> --inputs <file|-|json> [--candidates <file|-|json>] [--response <file>] [--subject <id>] [--store <tree|ledger>] [--kind <kind file>] [--dry-run]
+                        Ask a point's table, model and quorum deciders and
+                        record the answer: proposed from a model, escalated to
+                        people below its threshold. --response is a POST
+                        /v1/systemone response the caller got; chant calls no model.
+                        --candidates gives an ad-hoc point's question and
+                        candidates, { question, criteria }. --store ledger
+                        holds the question on chant/lifecycle and pushes it,
+                        for a checkout that does not outlive the run (CI)
+  workspace points answer <id> --answer <value> --by <name>... [--note <text>] [--relayed-by <principal>] [--kind <kind file>] [--resume] [--dry-run]
+                        Record people's answer to an open question, or confirm
+                        a model's proposal, once the point's quorum is met,
+                        with their note and who relayed it. --resume then
+                        starts again the CI job waiting at the gate the
+                        question names, when the answer passes it
+  workspace points retract <id> --by <name>... [--note <text>] [--kind <kind file>] [--dry-run]
+                        Take an answer back: the question is open for people
+                        again, and the answer stays in its retractions
+  workspace pin <path> [--json]
+                        Print the integrity value that pins the plugin at
+                        <path>, to put in a path pin of chant.workspace.json.
+                        chant checks it before it reads the plugin
+  workspace agent [<name>] [--json]
+                        Print an agent session from the declaration: the one
+                        member it is bound to, the record kinds and verbs its
+                        write scope allows, and the spec records --current
+                        prints. Without a name, the session CHANT_AGENT names
+  workspace verify [--base <rev>] [--head <rev>] [--require attested | attested-runs]
+                        Check the commits in base..head against the signers
+                        and roles read from base. A change to the signers file
+                        or .chant/trust.json needs a signature by a signer
+                        trusted at base, and a new signer set needs a
+                        threshold of the old one. A commit an agent run made
+                        is attested by the run's signed statement; with
+                        attested-runs, only those commits must be
+  workspace signers [--json] [rotate [--threshold <n>] | sign --key <file>]
+                        Show the signer history at base, or propose the next
+                        signer set and sign it with a current signer's key
+  workspace evidence sign --kind <kind file> --key <runner.pem> --check-id <id>
+                        Sign runner evidence over the records' hashes in a
+                        DSSE envelope, with a runner key .chant/trust.json
+                        lists. For CI and services, never a person's key
+  workspace evidence verify --envelope <file> [--at <rev>] [--json]
+                        Verify runner evidence offline, and whether the
+                        records it covers are unchanged
+  workspace lineage [--json]
+                        Show each scope in .chant/workspace.lock.json: its
+                        template and pin, locally edited files and open
+                        manual steps. Needs no workspace file
+  workspace lineage resolve <path>
+                        Close a manual step once the file is merged by hand
+  workspace upgrade [<scope>] [--to <ref|dir>] [--source <repo>[#<member>]] [--allow-code] [--dry-run] [--output <file>]
+                        Bring a lineage scope to a newer template version: fetch
+                        it, migrate and merge per file in a worktree, run build,
+                        lint and workspace check there, then gate on the digest
+                        of the patch (chant approve workspace-upgrade <scope>).
+                        A second run with the approval applies the patch.
+                        --source <repo>[#<member>] moves the scope to another
+                        template through that template's bridge migration
+  workspace adopt-lineage [<scope>] --from <repo>[@<ref>][#<member>] [--tags <glob>]
+                        [--index <file>] [--param name=value] [--dry-run] [--json]
+                        Give a scope a git lineage: match a scope with none
+                        against the template's versions and record the best
+                        one, with the adopted commit range in .chant/trust.json,
+                        or move a directory lineage onto the version that
+                        reproduces its recorded files
+  workspace hash-index --from <repo>[#<member>] [--tags <glob>] [--output <file>]
+                        Compute the per-version file hashes adopt-lineage
+                        matches against, for a template's CI to publish
+  workspace versions [<dir>] [--template <id>] [--available [--tags <glob>]] [--json]
+                        Report the template, chant and lexicon versions of
+                        every lineage lock under <dir>, grouped into families
+                        by template; --available also lists each git
+                        template's version tags and where each lock sits
+  workspace export [<member>[,<member>...]] [--to <member>] [--param name=value] [--dry-run] [--json]
+                        Write members that set travel, with their lineage and
+                        records, into the export member (role export) as a
+                        workspace of their own; with no member named, every
+                        member that travels and the workspace's own records.
+                        --param gives a host-bound parameter its value there
+  workspace import [<dir>] [--remove] [--dry-run] [--json]
+                        Bring an export back: merge per file against the
+                        export's hashes, switch host values back, record the
+                        return in .chant/returns/<id>.json with the commits the
+                        files were made in, then write the export member again
+                        or, with --remove, remove it
+  workspace admit <return id> [--note <text>] [--dry-run] [--json]
+                        Admit the signers of a return in .chant/trust.json, so
+                        its signed work reads as attested once merged
+  workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated] [--kind <kind file>] [--live --env <env>]
+                        Fail on an unreadable lineage lock or an open manual
+                        step, and, in a declared workspace, on a WSP check of
+                        the declaration, member ledgers, pipelines or
+                        generated files. --generated runs declared generators
+                        and compares their output. --kind warns on records
+                        whose pinned files changed. Needs no workspace file.
+                        --at reads a commit's git objects; --format json
+                        prints the read-contract document. --live --env
+                        resolves each declared member link against the live
+                        graph of <env> (each chant member runs chant graph
+                        --live, which reaches the account) and reports
+                        WSP141 and WSP142
+  workspace check --changes <base>..<head> [--work <id>] [--severity off|warn|fail] [--kind <kind file>...] [--json]
+                        Map each path the diff changes to the current records
+                        whose constrains cover it: change-uncovered when none
+                        does, change-out-of-scope when a record in hand (the
+                        --work item and its decisions) lists it in
+                        out_of_scope. The declaration's changes block sets
+                        the severity (warn by default) and ignore globs. When
+                        the declaration at base has writeScope or agents, each
+                        commit that writes outside its writer's scope fails
+                        the check (write-scope-member, write-scope-kind)
+  workspace patch <base>..<head>|<base>...<head>|<commit> [--path <p>...] [--max-bytes <n>] [--json]
+  workspace patch [<commit>] --worktree [--path <p>...] [--max-bytes <n>] [--json]
+                        The hunks of a diff, file by file: a range, a work
+                        branch, or one commit against its first parent. Each
+                        file's hunk text stops at --max-bytes (64 KiB) and
+                        says it was truncated
+  workspace build [dir] [--member <name>] [-o <dir>] [--dry-run]
+                        Build every chant member and example project, each with
+                        its own chant, one process per toolchain. -o <dir>
+                        writes <dir>/<member>.json; --member narrows the run;
+                        --dry-run prints which chant runs which project
+  workspace lint [dir] [--format stylish|json|sarif] [--member <name>]
+                        Lint every chant member and example project with its
+                        own chant; sarif writes one run per member
+  workspace audit [dir] [--json] [--member <name>]
+                        Audit each chant member with its own .chant-audit.json;
+                        every finding carries a member field
+  workspace graph [dir] [--at <rev>] [--member <name>] [--kind <kind file>] [-o <file>]
+                        Compose each chant member's chant graph into one IR,
+                        with <member>/<id> ids and groups.byMember: the
+                        read-contract document. --at <rev> runs each member's
+                        source as it was at that commit; --kind adds the
+                        records' asset and constrains links. A member whose
+                        source and toolchain are unchanged is served from
+                        the cache in $CHANT_CACHE_DIR or ~/.cache/chant;
+                        --no-cache reads every member
+  workspace graph --composites [--at <rev>] [--member <name>] [-o <file>]
+                        Each composite instance the members declare, with the
+                        components whose contract can deploy it; an instance
+                        with none lists an empty set
+  workspace graph --intent <path[:start-end]|path#symbol> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]
+                        The intent graph over one region: the commits that
+                        touched it, the decisions whose constrains cover it,
+                        the artifacts they pin, and findings with closed codes.
+                        Without --kind, every record kind the declaration names.
+                        --follow-squash follows a squash merge to its pull
+                        request's commits, fetching a missing ref from origin
+  workspace graph --intent --record <id> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]
+                        One decision's intent walk over every path: and member:
+                        entry it constrains: the commits in its window, each
+                        own, worked, within-other or unexplained, with counts
+
+Lifecycle (alias: lc):
+  lifecycle snapshot <env>  Query API, save metadata to orphan branch
+                            --deep: also record each resource's property tree,
+                            not just its identity — what a fold over topology
+                            needs (costs more provider calls; #1267)
+  lifecycle show <env>      Show latest lifecycle snapshot
+  lifecycle diff <env>      Compare current build against last snapshot
+                            --live: query cloud now and detect drift
+                            (lexicons with a deep reader also report
+                            property-level drift; --update-baseline records
+                            what it reports as accepted so it stops alerting)
+  lifecycle plan <env>      Typed change set (create/update/delete/adopt) vs live
+                            --deep: also report properties declared
+                            heldElsewhere(). Never changes what the plan
+                            proposes; costs a provider call pair per readable
+                            resource, so the read's cost becomes a function of
+                            estate size rather than stack count (#2405)
+  lifecycle affected        Stacks a change affects (--base <ref> [--include-dependents])
+                            --json: emit the ChangeSet as JSON
+  lifecycle whoami <env>    Who chant would act as in each configured lexicon,
+                            and what that principal is scoped to — read-only,
+                            before anything acts (--json, --strict)
+  lifecycle teardown <env>  Plan what deleting the environment would remove —
+                            marker-scoped (this project's stack + env); --yes
+                            executes the plan (production-like names also need
+                            --confirm-prod, or an interactive confirmation)
+  lifecycle log [env]       History of lifecycle snapshots
+
+Plan scenarios (#1292):
+  scenario check            Evaluate every declared Scenario's expect clause
+                            offline, against its given fixture (no cloud, no
+                            credentials); --json: emit verdicts as JSON.
+                            Nonzero exit on any failing scenario.
+
+Component release ledger + status:
+  components status [env]  What's built vs what's deployed where, joined by
+                            digest (--live: reconcile against live+ownership;
+                            --json: stable machine-readable contract;
+                            --compare-to <env>: cross-check the same
+                            component's recorded digest against another env)
+  components fan-out       Run a change out across the components downstream
+                            of it, in an order derived from the source
+                            (--base <ref> [--head <ref>] [--include-dependents],
+                             or --from-affected <file>; --dry-run prints the
+                             derivation and dispatches nothing; --gate <name>
+                             puts one approval over the whole set;
+                             --wave-gate <name> puts one on each wave, planned
+                             when the wave is reached, with --canary <name>
+                             for wave 1 and --wave <n> for one wave per CI
+                             job; --resume <file> finishes an attempt that
+                             stopped)
+  components pr-plan       Plan the components a pull request reaches and
+                            the ones that depend on them, and write the
+                            report and note (--base <ref> --pr <n>
+                            [--forge github|gitlab|forgejo] posts them);
+                            applies nothing
+  components pr-apply      On merge: plan the same members again and apply
+                            them only if an approval stands for that digest
+                            (chant approve pr-<n> pr-apply --plan <digest>);
+                            a moved plan refuses with exit 3
+                            (--require-review: the approver must have
+                            approved the pull request on the forge;
+                            --member <name>, both commands: a workspace
+                            member's loop, gate op pr-<n>-<member>;
+                            --resume <file> finishes an apply that failed
+                            partway under the same approval)
+  components release <env> Append one immutable release record
+                            (--component <name> --digest <sha256:...>
+                             [--git-sha <sha>] [--run-id <id>] [--actor <name>]);
+                            --release-plan <file> takes --digest's place,
+                            persisting the release plan the file holds to
+                            _plans/<digest>.json (ws-055) and recording its
+                            own digest
+  components export <env>  Materialize a persisted build archive manifest to
+                            a portable directory (--component <name>
+                            [--digest <manifestDigest>] -o <dir> [--json]);
+                            copies every image/template/asset/sbom entry
+                            byte-for-byte plus a self-describing manifest.json
+  components promote        Deploy the digests one environment's release
+                            ledger records to another, without a build
+                            (--from <env> --to <env> [--component <name>
+                             [--digest <sha256:...>]]; --dry-run prints the
+                             plan; the target's gates still apply)
+  components rollback <env> Redeploy an earlier release of an environment
+                            from its recorded digest (--component <name>
+                            [--digest <sha256:...>]; defaults to the release
+                            before the current one; --dry-run prints the plan)
+  components redeploy <env> Redeploy the release an environment's ledger
+                            records as current, after a deploy that failed
+                            partway (--component <name> [--digest <sha256:...>];
+                            --dry-run prints the plan; gates still apply)
+
+Lexicon development:
+  dev generate          Generate lexicon artifacts (+ validate + coverage)
+  dev publish           Package lexicon for distribution
+  dev onboard <name>    Patch CI, Dockerfiles, and workflows for a new lexicon
+  dev check-lexicon <dir>  Check lexicon completeness (tier 1/2/3)
+  dev surface-diff <dir>   Regen lexicon, validate, diff API surface vs committed baseline
+                           (--force: bypass spec cache; --update-snapshot: write new baseline;
+                            --bump: with --update-snapshot, bump package version by drift severity;
+                            --check: fail if the committed baseline drifted (never writes);
+                            --run-examples: also run example build harness;
+                            --pinned-digest <file>: verify spec digest before regen)
+  dev pinned-upgrade <dir> [pin]
+                           Report if a lexicon that declares upstreamPin (k8s, k3s, gcp, docker,
+                           gitlab, cedar, sql) has a newer upstream release; dry-run bump + regen +
+                           surface-diff, then revert. A pin that moves with other constants (sql's
+                           image digest) is reported with how to move it, not edited. A lexicon
+                           with several pins (sql: clickhouse, postgres-14 .. postgres-18) gets one
+                           report per pin; name a pin to check only that one
+                           (reports only; --force bypasses the spec cache, -f json for JSON)
+  dev rolling-upgrade <dir>  Report rolling-spec drift (aws, azure, github): regen from
+                           latest, diff surface vs committed baseline, print delta + PR
+                           label (dry run; --force bypasses the spec cache, --format json)
+
+Local:
+  emulator <up|down|status>  Boot/stop/inspect configured lexicons' local
+                           emulators (Floci etc.); --lexicon <name>, --json,
+                           --port; \`chant emulator --help\` lists ports and logins
+
+Servers:
+  serve lsp             Start the LSP server (stdio)
+  serve mcp             Start the MCP server (stdio)
+
+Project:
+  update                Sync lexicon types into .chant/types/
+  doctor                Check project health and configuration
+
+Options:
+  -o, --output <file>   Write output to file instead of stdout
+  -f, --format <fmt>    Output format (command-specific):
+                        - build: json (default) or yaml
+                        - list: text (default) or json
+                        - lint: stylish (default), json, or sarif
+      --lexicon-output <lexicon>=<path>
+                        build: write that lexicon's output to its own file
+                        (repeatable). Lexicons not named go to --output when
+                        given, and are skipped otherwise
+  -d, --lexicon <name>  Build only the specified lexicon (e.g. aws, gitlab);
+                        import: use this lexicon instead of detecting one
+      --env <name>      Active environment: sets CHANT_ENV so env-aware source
+                        re-evaluates for that environment (build + graph), and
+                        drives organizational policy. Must be in chant.config
+                        \`environments\` when declared.
+  -t, --template <name> Init template (e.g. node-pipeline, docker-build);
+                        records its lineage in .chant/workspace.lock.json
+  --skill <name>        Init: install only this skill from the lexicon
+  --skip-mcp            Init: scaffold without writing the project's .mcp.json
+  --fix                 Auto-fix fixable issues (lint command)
+  --force               Force overwrite existing files (import command)
+  -w, --watch           Watch for changes and rebuild/re-lint (build, lint)
+  -v, --verbose         Show stack traces on errors; (build) list every
+                        resolved build parameter and per-file fold decision
+                        instead of the one-line summaries
+  -h, --help            Show this help message
+  -V, --version         Print the installed chant's version
+  --on <lexicon>        Which runtime hosts the run: a configured lexicon with
+                        an opRuntime, or local. Omitted, run.on in
+                        chant.config.ts decides, then the built-in local
+                        runtime (every run subcommand; #2121, #2523)
+  --local               Run an Op with the local in-process executor (default)
+  -p, --profile <name>  Named connection profile the hosting runtime targets
+                        (fountain.profiles in chant.config.ts); each runtime's
+                        own default when omitted (#2124)
+  --json                Emit the structured run result as JSON (run command)
+  --report              With a path arg: SARIF report destination (migrate)
+                        OR '--report gitlab-mr': emit the GitLab MR plan-widget
+                        JSON (lifecycle plan)
+                        OR '--report markdown': emit a reviewer-facing markdown
+                        render, holes and disruption included (lifecycle plan)
+  --from <name>         Source lexicon for migrate (default: github)
+  --to <name>           Target lexicon for migrate (default: gitlab)
+  --emit <fmt>          Migration output format: yaml (default) or ts
+  --strict              Escalate needs-review/validation to errors (migrate);
+                        exit nonzero on an unresolved identity (lifecycle whoami)
+  --validate            Run external validator (glci/glab) after migrate
+  --use-composites      Rewrite to composite calls when patterns match (migrate)
+  --components          Target discovered Component declarations instead of
+                        lexicon resources (list, describe, graph, build, run)
+  --generate <lexicon>  Generate mode: synthesize CI YAML for <lexicon> (github,
+                        gitlab or forgejo) instead of running. build
+                        --components: one pipeline for the components; run:
+                        one pipeline file per scheduled Op
+  --spec <file>         (run --generate) JSON Op specs: an array, or
+                        { ops, options }
+  --promote-to <env>    (build --components --generate) Add a job that
+                        promotes the deployed releases to <env>
+  --no-release-record   Skip auto-emitting a release-ledger record after a
+                        successful \`run --components\` deploy (default: on;
+                        also settable via chant.config.ts's
+                        release.autoRecord: false; #597)
+  --fold                (build) Fold source modules statically instead of
+                        running them; folds resource constructors and
+                        composite factory calls (#1022/#1023), falling back
+                        to run per-file for anything else outside the fold
+                        subset (a cross-file-only reference, a re-export,
+                        \`export default\`, ...). Logs a fold/run count
+                        (per-file lines under --verbose). DEFAULT since #1134 — this flag forces it on
+                        over a chant.config.ts \`build.fold: false\`.
+  --no-fold             (build) Opt out of folding for this invocation: every
+                        source module is imported and run, the pre-#1134
+                        behavior. Beats chant.config.ts's build.fold.
+  --fold-rank [<path>]  (build, with --fold) Rank run-mode files by dominator
+                        retained-count over the forward import-failure graph
+                        (#1083) — fixing the top blocker unblocks the most
+                        files. Files held back only by the reverse rule
+                        (#1044) are reported separately, never folded into
+                        the ranking. With a path argument, also writes a
+                        Brendan Gregg collapsed-format export (weighted by
+                        retained count) there, for any flame/icicle viewer.
+  --sandbox             (build) Run run-fallback source files (or every
+                        file, without --fold) together, isolated, in one
+                        sandboxed child process instead of in-process
+                        (#1045). No filesystem write, no child process, no
+                        worker threads, no ambient environment visible to
+                        project source; network egress is NOT blocked (see
+                        docs). Default: off (also settable via
+                        chant.config.ts's build.sandbox: true; #1045)
+  --param <name=value>  (build, graph, run --components, components fan-out,
+                        components promote, components rollback,
+                        components redeploy) Bind a
+                        declared build-time parameter (chant.config.ts's buildParams)
+                        to a value, for source to read as params.<name>
+                        (#1064) instead of process.env — repeatable.
+                        Distinct from the AWS lexicon's deploy-time
+                        Parameter(): this resolves before synthesis, so it
+                        can change which resources are produced at all.
+                        Highest precedence. With init --from, it sets a
+                        template parameter that the template's
+                        chant.template.json declares instead (#2627).
+  --params-file <path>  (build, graph, run --components, components fan-out,
+                        components promote, components rollback,
+                        components redeploy) JSON file
+                        of { "name": value } build-time parameter values
+                        (#1064). Second precedence, after --param.
+                        init --from refuses it: pass --param instead.
+
+Examples:
+  chant build ./infra/
+  chant build ./infra/ --output stack.json
+  chant build ./infra/ --format yaml
+  chant build ./infra/ --watch
+  chant build ./infra/ --fold
+  chant build ./infra/ --components --generate gitlab
+  chant build ./infra/ --components --generate gitlab --output .gitlab-ci.yml
+  chant run --generate github
+  chant run --components search-service --env staging
+  chant run --components all --env production
+  chant components export prod --component search-service -o ./dist/search-service
+  chant import template.json --output ./infra/
+  chant import manifest.yaml --lexicon k8s --output ./infra/
+  chant import dash.json --lexicon grafana --parser-option acceptLossyV1
+  chant import --from prod --name my-bucket --output src/
+  chant lint ./infra/
+  chant lint ./infra/ --format sarif
+  chant lint ./infra/ --watch
+  chant list ./infra/
+  chant list ./infra/ --format json
+  chant describe myComponent src/
+  chant describe myComponent src/ --format json
+`);
+    const groupsHelp = formatCommandGroupsHelp(groups);
+    if (groupsHelp)
+        console.log(groupsHelp);
+}
+/**
+ * Best-effort load the current project's lexicon plugins for a purely
+ * read-only lookup (help composition, plugin-command dispatch) — never
+ * throws, empty on any failure (no config, no lexicons, not a chant
+ * project at all). Mirrors the existing best-effort loading already used
+ * for `emulator`/`components status` in {@link main} below.
+ */
+async function loadPluginsBestEffort() {
+    try {
+        const lexiconNames = await resolveProjectLexicons(resolve("."));
+        return await loadPlugins(lexiconNames);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * chant #1078 — the lexicon command-group seam's dispatch-time half. Core's
+ * own `parseArgs`/`resolveCommand` know nothing about a lexicon's mounted
+ * verbs, so this is only ever consulted after BOTH of those have already
+ * failed to make sense of the invocation: either `parseArgs` threw on a flag
+ * it doesn't recognize (which is *expected* for a mounted command's own
+ * vocabulary — core has none), or it parsed fine but `resolveCommand` found
+ * no match in the static registry (a mounted command with no extra flags,
+ * e.g. `chant kube version`). Either way, a lexicon-mounted command's group
+ * name and verb are always the first two CLI tokens (mirrors the `emulator
+ * <up|down|status>` compound shape from #920), so `rawArgv` — the untouched
+ * `process.argv.slice(2)` — is all this needs; nothing from the partially or
+ * fully parsed `ParsedArgs` is used, on purpose, since core's flag-parsing
+ * failure or success is irrelevant to a namespace it doesn't own.
+ *
+ * Returns `undefined` when nothing claims the leading token as a command
+ * group at all, so the caller falls back to its own error handling
+ * unchanged — a project with no lexicon exposing `commands()` (or none of
+ * its plugins matching) is completely unaffected.
+ */
+async function tryPluginCommand(rawArgv) {
+    const [groupName, verbName] = rawArgv;
+    if (!groupName || groupName.startsWith("-"))
+        return undefined;
+    const plugins = await loadPluginsBestEffort();
+    // A group declaring a `defaultVerb` (#2125) answers its bare name, so
+    // `chant acp` and `chant acp --durable-requests` both reach that verb. The
+    // slicing follows: with no verb token consumed, everything after the group
+    // name is the default verb's own argument list.
+    const group = collectCommandGroups(plugins).find((g) => g.name === groupName);
+    const useDefault = group?.defaultVerb !== undefined && (verbName === undefined || verbName.startsWith("-"));
+    const verb = useDefault ? group?.defaultVerb : verbName;
+    const rawArgs = rawArgv.slice(useDefault ? 1 : 2);
+    const result = await dispatchCommandGroup(plugins, groupName, verb, rawArgs);
+    if (result.kind === "no-group")
+        return undefined;
+    if (result.kind === "usage-error") {
+        console.error(formatError({ message: result.message, hint: result.hint }));
+        return 1;
+    }
+    return result.exitCode;
+}
+/**
+ * Load lexicon plugins for the given project path, or exit with an error.
+ */
+async function loadPluginsOrExit(path, lexicon) {
+    let plugins;
+    try {
+        // chant #3648 — `--lexicon <name>` loads that lexicon even when the
+        // project's config and imports name none.
+        const lexiconNames = await resolveProjectLexicons(resolve(path), { lexicon });
+        plugins = await loadPlugins(lexiconNames);
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        console.error(formatError({ message: errorMessage }));
+        process.exit(1);
+    }
+    if (plugins.length === 0) {
+        console.error(formatError({
+            message: "No lexicon detected",
+            hint: 'Run "chant init --lexicon <name>" to initialize a project, or add a lexicon to chant.config.ts',
+        }));
+        process.exit(1);
+    }
+    // #1344 — a lexicon that declares the shape of its own `chant.config.ts`
+    // namespace gets it validated here, once, before any command runs. The
+    // config schema is `.passthrough()`, so before this an unknown key inside a
+    // namespace was accepted and silently ignored: `forgejo: { runnerLabel: … }`
+    // left the dialect on its defaults with nothing said. A namespace whose
+    // lexicon declares no schema keeps that passthrough.
+    try {
+        const { config } = await loadChantConfigUpward(resolve(path));
+        const problems = validateLexiconConfig(plugins, config);
+        if (problems.length > 0) {
+            console.error(formatError({
+                message: `Invalid lexicon configuration in chant.config:\n${formatLexiconConfigProblems(problems)}`,
+                hint: "Remove or correct the key. A lexicon's namespace accepts only the keys it declares.",
+            }));
+            process.exit(1);
+        }
+    }
+    catch {
+        // No config, or one that failed to load — the caller's own handling stands.
+    }
+    return plugins;
+}
+/**
+ * #2700 — whether `path` is the root of a declared workspace and holds no
+ * lexicon of its own: no `lexicons` in a root config, and no lexicon import in
+ * the root's source, which leaves the members' directories out (#2527). A
+ * generated app repo can be this shape: its lexicons are all under a
+ * delivery directory, not the root. `chant serve mcp` starts there instead of
+ * refusing with "No lexicon detected", and serves core with the chant
+ * members' lexicons.
+ *
+ * A directory with no workspace declaration costs only `findWorkspaceRoot`'s
+ * existence checks, so a level-0 project reaches `loadPluginsOrExit` as before.
+ */
+async function isLexiconlessWorkspaceRoot(path) {
+    const target = resolve(path);
+    if (findWorkspaceRoot(target)?.dir !== target)
+        return false;
+    try {
+        await resolveProjectLexicons(target);
+        return false;
+    }
+    catch (error) {
+        return isNoLexiconDetected(error);
+    }
+}
+/** Whether `def` must run without evaluating the project's `chant.config.ts` (chant#2591). */
+function commandRunsNoConfig(def, args) {
+    return typeof def.runsNoConfig === "function" ? def.runsNoConfig(args) : def.runsNoConfig === true;
+}
+/**
+ * Run one level-0 command line in this process and return its exit code
+ * (#2537). `chant workspace member-run` calls it once per member, from inside
+ * the member's directory, so each member is built, linted, audited or graphed
+ * as `chant <verb> .` would do it there, while members that share a toolchain
+ * share one process. It is main()'s dispatch without the help, the root
+ * refusal and the lexicon command groups: the config is loaded, `--env` is
+ * checked, plugins are loaded when the command needs them, and the handler
+ * runs. A `process.exit` inside (loadPluginsOrExit's, say) is the caller's to
+ * catch.
+ */
+export async function runCommandInProcess(argv) {
+    const args = parseArgs(argv);
+    const match = resolveCommand(args, commandRegistry);
+    if (!match) {
+        console.error(formatError({ message: `Unknown command: ${args.command}` }));
+        return 1;
+    }
+    if (args.env)
+        process.env[ENV_VAR] = args.env;
+    let loadedConfig;
+    try {
+        // chant#2618 — `workspace audit` reaches `audit` through here, once per
+        // member. A `runsNoConfig` command skips the load, as it does in main().
+        if (!commandRunsNoConfig(match.def, args))
+            loadedConfig = await loadChantConfigUpward(resolve(args.path));
+    }
+    catch {
+        // A project with no config is the handler's to report, as in main().
+    }
+    const envErr = unknownEnvError(args.env, loadedConfig?.config.environments);
+    if (envErr) {
+        console.error(formatError({ message: envErr, hint: "Declare it in chant.config `environments`, or omit --env." }));
+        return 1;
+    }
+    const plugins = match.def.requiresPlugins ? await loadPluginsOrExit(match.compound ? "." : args.path, args.lexicon) : [];
+    return match.def.handler({ args, plugins, serializers: plugins.map((p) => p.serializer) });
+}
+// ── Command registry ──────────────────────────────────────────────
+/**
+ * Every command word `chant` answers to, and the handler behind it.
+ *
+ * Exported because a caller other than `main()` now needs to ask "is this a
+ * chant verb, and what runs it?" — the fountain lexicon's ACP server (#2125)
+ * treats a prompt as a chant command line, and the only honest answer to
+ * whether `chant lifecycle diff` is a verb is this list. A hand-kept copy
+ * would be wrong the first time a command is added, and the ACP server would
+ * refuse a verb that works at the terminal.
+ */
+export const commandRegistry = [
+    // Primary commands
+    { name: "build", requiresPlugins: true, handler: runBuild },
+    { name: "lint", handler: runLint },
+    { name: "list", handler: runList },
+    { name: "describe", handler: runDescribe },
+    { name: "explain", handler: runExplain },
+    { name: "search", handler: runSearch },
+    // chant#2591 — `import --agents` and `audit` read chant.config statically
+    // and never evaluate it (chant#2589 for audit, which audits code it must not run).
+    { name: "import", handler: runImport, runsNoConfig: (args) => args.agents === true },
+    { name: "audit", handler: runAudit, runsNoConfig: true },
+    { name: "migrate", handler: runMigrate },
+    // Read-only Terraform peelability advisor (#214). Compound so "advise" lands
+    // in args.path; the estate dir comes from --from. No plugins, no project.
+    { name: "carve advise", handler: runCarveAdvise },
+    // Emit step (#197): adopt a selected TF resource into chant source. The
+    // --state path is offline (no plugins); the --env live path loads the target
+    // lexicon lazily in the handler, so this command does not require plugins.
+    { name: "carve emit", handler: runCarveEmit },
+    // Boundary bridging (#197): patch the surviving TF (data sources + rewired
+    // refs) + runbook. No plugins; Terraform-side only. Read-only unless
+    // --apply-rewrites.
+    { name: "carve bridge", handler: runCarveBridge },
+    // Apply graduation (#197): ownership marker + finalized apply runbook.
+    // BYOL-honest — no cloud call; --write saves the graduation doc.
+    { name: "carve apply", handler: runCarveApply },
+    // Status read over a tree of carve manifests (#2038): the contract a
+    // renderer replaces its own walk-and-guess discovery with. Read-only.
+    { name: "carve status", handler: runCarveStatus },
+    // #3573 — which commits passed CI, kept as ci/green and ci/revoked tags (ws-103). Imported on first use.
+    { name: "ci last-green", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-green-cli.js")).runCiLastGreen(ctx) },
+    { name: "ci tick", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-green-cli.js")).runCiTick(ctx) },
+    { name: "ci workflow", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-green-cli.js")).runCiWorkflow(ctx) },
+    // #3188 — the grouped plan summary of a change-set document. Reads one file; imported on first use.
+    { name: "change-set summary", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/change-set.js")).runChangeSetSummary(ctx) },
+    { name: "init", handler: runInit, runsNoConfig: true },
+    { name: "init lexicon", handler: runInitLexicon },
+    { name: "update", handler: runUpdate },
+    { name: "doctor", handler: runDoctor },
+    // Dev subcommands
+    { name: "dev generate", requiresPlugins: true, handler: runDevGenerate },
+    { name: "dev publish", requiresPlugins: true, handler: runDevPublish },
+    { name: "dev onboard", handler: runDevOnboard, runsNoConfig: true },
+    { name: "dev check-lexicon", handler: runDevCheckLexicon },
+    { name: "dev surface-diff", handler: runDevSurfaceDiff },
+    { name: "dev pinned-upgrade", handler: runDevPinnedUpgrade },
+    { name: "dev rolling-upgrade", handler: runDevRollingUpgrade },
+    // Op / run subcommands
+    { name: "run list", handler: runOpList },
+    { name: "run status", handler: runOpStatus },
+    { name: "run approve", handler: runOpApprove },
+    { name: "run signal", handler: runOpSignalRenamed },
+    { name: "run cancel", handler: runOpCancel },
+    { name: "run log", handler: runOpLog },
+    { name: "run wave", handler: runOpWaveCommand },
+    // #3683 — start the CI jobs that wait at gates whose approval arrived. Imported on first use.
+    { name: "run resume", handler: async (ctx) => (await import("./handlers/gate-resume.js")).runResumeCommand(ctx) },
+    { name: "run", handler: runOp },
+    { name: "operator status", handler: runOperatorStatus },
+    { name: "operator log", handler: runOperatorLog },
+    { name: "operator", handler: runOperator },
+    { name: "approve", handler: runApprove },
+    { name: "graph", handler: runGraph },
+    { name: "vendor", handler: runVendor },
+    // Project-local codegen: typed code from sources chant.config declares
+    // (k8s.crds, helm.charts). Imported on first use.
+    { name: "generate", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/generate.js")).runGenerate(ctx) },
+    // Workspace reads (#2524). Imported on first use, so a level-0 command never
+    // loads anything under workspace/ (#2525 rule 5, pinned by #2526's goldens).
+    { name: "workspace records", handler: async (ctx) => (await import("../workspace/records-cli.js")).runWorkspaceRecords(ctx) },
+    // ws-058 (#2739) — decision points and the questions asked of them; never calls a model.
+    { name: "workspace points", handler: async (ctx) => (await import("../workspace/points-cli.js")).runWorkspacePoints(ctx) },
+    { name: "workspace init", handler: async (ctx) => (await import("../workspace/init.js")).runWorkspaceInit(ctx) },
+    { name: "workspace ls", handler: async (ctx) => (await import("../workspace/ls.js")).runWorkspaceLs(ctx) },
+    // #2732 — the work lease: claim, renew and release a work item.
+    { name: "workspace work", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/work-cli.js")).runWorkspaceWork(ctx) },
+    // #3033 — the agent run record: what each run cost and which commits it made. chant records runs and never starts one.
+    { name: "workspace runs", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/runs-cli.js")).runWorkspaceRuns(ctx) },
+    { name: "workspace status", handler: async (ctx) => (await import("../workspace/status.js")).runWorkspaceStatus(ctx) },
+    { name: "workspace lineage", handler: async (ctx) => (await import("../workspace/lineage-cli.js")).runWorkspaceLineage(ctx) },
+    { name: "workspace upgrade", handler: async (ctx) => (await import("../workspace/lineage-upgrade-cli.js")).runWorkspaceUpgrade(ctx) },
+    // #2551 — adopt a lineage, the hash index it matches against, and the versions of a family of workspaces.
+    { name: "workspace adopt-lineage", handler: async (ctx) => (await import("../workspace/lineage-adopt-cli.js")).runWorkspaceAdoptLineage(ctx) },
+    { name: "workspace hash-index", handler: async (ctx) => (await import("../workspace/lineage-adopt-cli.js")).runWorkspaceHashIndex(ctx) },
+    // #2552 — export a workspace or members, bring an export back, and admit a return's signers.
+    { name: "workspace export", handler: async (ctx) => (await import("../workspace/export-cli.js")).runWorkspaceExport(ctx) },
+    { name: "workspace import", handler: async (ctx) => (await import("../workspace/export-cli")).runWorkspaceImport(ctx) },
+    { name: "workspace admit", handler: async (ctx) => (await import("../workspace/export-cli.js")).runWorkspaceAdmit(ctx) },
+    { name: "workspace versions", handler: async (ctx) => (await import("../workspace/lineage-versions.js")).runWorkspaceVersions(ctx) },
+    // #2641 — workspace check reads member configs statically and never runs one.
+    { name: "workspace check", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/lineage-check.js")).runWorkspaceCheck(ctx) },
+    // The hunks of a diff, for a reader that runs no git of its own.
+    { name: "workspace patch", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/patch.js")).runWorkspacePatch(ctx) },
+    // #2537 — per-member commands. Each member runs under its own chant, one
+    // process per toolchain identity; `member-run` is that process's entry.
+    { name: "workspace build", handler: async (ctx) => (await import("../workspace/member-commands.js")).runWorkspaceMembers(ctx, "build") },
+    { name: "workspace lint", handler: async (ctx) => (await import("../workspace/member-commands.js")).runWorkspaceMembers(ctx, "lint") },
+    // chant#2618 — audit runs no project code, at the workspace level too.
+    { name: "workspace audit", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/member-commands.js")).runWorkspaceMembers(ctx, "audit") },
+    { name: "workspace graph", handler: async (ctx) => (await import("../workspace/member-commands.js")).runWorkspaceMembers(ctx, "graph") },
+    // Each unit decides for itself whether its config is loaded (runCommandInProcess).
+    { name: "workspace member-run", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/member-run.js")).runWorkspaceMemberRun(ctx, runCommandInProcess) },
+    // #3308 — a box's listing, written through chant so a tool never edits the declaration itself (ws-074).
+    { name: "workspace box", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/box-cli.js")).runWorkspaceBox(ctx) },
+    // #3596 — a declaration's members and hosts, written through chant so a lobby never edits the declaration itself (ws-074).
+    { name: "workspace member", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/declaration-write-cli.js")).runWorkspaceMember(ctx) },
+    { name: "workspace host", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/declaration-write-cli.js")).runWorkspaceHost(ctx) },
+    // #3173 — the working tree's write lock, held across chant calls for a batch of writes (ws-089).
+    { name: "workspace lock", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/write-lock-cli.js")).runWorkspaceLock(ctx) },
+    // #3172 — work in progress under refs/chant/wip/<branch>, replicated under the box's policy (ws-085).
+    { name: "workspace wip", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/wip-cli.js")).runWorkspaceWip(ctx) },
+    { name: "workspace pin", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/pin-cli.js")).runWorkspacePin(ctx) },
+    // #2548 — an agent session's member, write scope and spec, for a session that resumes.
+    { name: "workspace agent", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/agent-cli.js")).runWorkspaceAgent(ctx) },
+    { name: "workspace verify", handler: async (ctx) => (await import("../workspace/trust/verify-cli.js")).runWorkspaceVerify(ctx) },
+    { name: "workspace signers", handler: async (ctx) => (await import("../workspace/trust/signers-cli.js")).runWorkspaceSigners(ctx) },
+    { name: "workspace evidence", handler: async (ctx) => (await import("../workspace/trust/evidence-cli.js")).runWorkspaceEvidence(ctx) },
+    // State subcommands
+    { name: "lifecycle snapshot", requiresPlugins: true, handler: runLifecycleSnapshot },
+    { name: "lifecycle show", handler: runLifecycleShow },
+    { name: "lifecycle diff", requiresPlugins: true, handler: runLifecycleDiff },
+    { name: "lifecycle rollback", handler: runLifecycleRollback },
+    { name: "lifecycle plan", requiresPlugins: true, handler: runLifecyclePlan },
+    { name: "lifecycle affected", requiresPlugins: true, handler: runLifecycleAffected },
+    { name: "lifecycle whoami", requiresPlugins: true, handler: runLifecycleWhoami },
+    { name: "lifecycle teardown", requiresPlugins: true, handler: runLifecycleTeardown },
+    { name: "lifecycle log", handler: runLifecycleLog },
+    // Plan scenarios (#1292) — fully offline, no plugin network calls, but
+    // requiresPlugins:true so the build step has serializers to partition
+    // against, same as every other build-then-something verb.
+    { name: "scenario check", requiresPlugins: true, handler: runScenarioCheck },
+    // Component release ledger + status surface (#568, epic #551)
+    { name: "components fan-out", requiresPlugins: true, handler: runComponentsFanOut },
+    // #3183 — the pull-request loop the generated CI runs. Imported on first use.
+    { name: "components pr-plan", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/pr.js")).runComponentsPrPlan(ctx) },
+    { name: "components pr-apply", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/pr.js")).runComponentsPrApply(ctx) },
+    { name: "components status", requiresPlugins: true, handler: runComponentsStatus },
+    { name: "components release", handler: runComponentsReleaseRecord },
+    { name: "components export", handler: runComponentsExport },
+    { name: "components promote", handler: runComponentsPromote },
+    { name: "components rollback", handler: runComponentsRollback },
+    { name: "components redeploy", handler: runComponentsRedeploy },
+    // Local emulators of configured lexicons (#920). Compound so the action word
+    // lands in args.path (not consumed as a project dir) and projectPath is forced ".".
+    { name: "emulator up", requiresPlugins: true, handler: runEmulator },
+    { name: "emulator down", requiresPlugins: true, handler: runEmulator },
+    { name: "emulator status", requiresPlugins: true, handler: runEmulator },
+    // Serve subcommands
+    { name: "serve lsp", requiresPlugins: true, handler: runServeLsp },
+    { name: "serve mcp", requiresPlugins: true, handler: runServeMcp },
+    // Fallback for unknown subcommands (must come after compound entries)
+    { name: "carve", handler: runCarveUnknown },
+    { name: "emulator", requiresPlugins: true, handler: runEmulator },
+    { name: "lifecycle", handler: runLifecycleUnknown },
+    { name: "scenario", handler: runScenarioUnknown },
+    { name: "dev", handler: runDevUnknown },
+    { name: "serve", handler: runServeUnknown },
+    { name: "components", handler: runComponentsUnknown },
+    { name: "workspace", handler: async (ctx) => (await import("../workspace/records-cli.js")).runWorkspaceUnknown(ctx) },
+];
+/**
+ * Main entry point
+ */
+async function main() {
+    // #3878 — run from dist/ with plain node, TypeScript loads only when
+    // something imports it. A no-op from source.
+    installCompiledCli();
+    const rawArgv = process.argv.slice(2);
+    let args;
+    try {
+        args = parseArgs(rawArgv);
+    }
+    catch (err) {
+        // chant #1078 — core's parser has no idea what flags a lexicon's own
+        // mounted verb accepts, so an "unknown flag" here is expected, not a
+        // real error, until we've checked whether this invocation actually
+        // targets a command group. `tryPluginCommand` returns `undefined` when
+        // nothing claims the leading token, in which case this was a genuine
+        // core-flag error and the original is rethrown unchanged.
+        const code = await tryPluginCommand(rawArgv);
+        if (code !== undefined) {
+            await flushAndExit(code);
+            return;
+        }
+        throw err;
+    }
+    // #2701 — `chant --version` / `-V` prints the installed chant's version, the
+    // one the MCP server reports (./version.ts). With a command word it answers
+    // only for one of core's own commands; a lexicon-mounted verb keeps the flag.
+    if (args.version && (!args.command || resolveCommand(args, commandRegistry))) {
+        console.log(CHANT_VERSION);
+        await flushAndExit(0);
+        return;
+    }
+    // #3673 — `chant emulator --help` is the emulator's own usage, with the
+    // ports and sign-in each configured lexicon's emulator uses, not the
+    // global command list it used to print.
+    if (args.help && args.command === "emulator") {
+        console.log((await emulatorHandlers()).formatEmulatorHelp(await loadPluginsBestEffort().catch(() => [])));
+        await flushAndExit(0);
+        return;
+    }
+    if (args.help || !args.command) {
+        const groups = await loadPluginsBestEffort().then(collectCommandGroups).catch(() => []);
+        printHelp(groups);
+        process.exit(args.help ? 0 : 1);
+    }
+    // `--env <name>` is a build-context switch for the whole invocation: set it
+    // *before* anything imports the project so env-aware source (and thus the graph
+    // / build) reflects that environment. Set early, before config import, since
+    // chant.config itself may branch on the env. (#505)
+    if (args.env)
+        process.env[ENV_VAR] = args.env;
+    // chant #1113 — `--sandbox` is a property of the whole invocation, and it
+    // has to be known BEFORE the first config load, because `chant.config.ts` is
+    // itself project-authored code. Arming here, straight off the parsed flag,
+    // is the only ordering that works: the project's own `build.sandbox: true`
+    // cannot cover its own evaluation (reading it means running it), so the
+    // command-line flag is what puts the config inside the boundary. See
+    // `../config-sandbox.ts`.
+    if (args.sandbox)
+        armSandboxConfigEvaluation();
+    // chant #1131 — the same for `lint.policies`. Armed from the flag here so
+    // the mode is set for the whole invocation, not just `chant build`; the build
+    // command arms it again from the RESOLVED value (a project's own
+    // `build.sandbox: true` also sandboxes its policies — unlike the config,
+    // policies have no bootstrap limit, since they load long after the config is
+    // known). See `../lint/policy-sandbox.ts`.
+    if (args.sandbox)
+        armSandboxPolicyExecution();
+    // Initialize runtime adapter early — before plugins or commands run.
+    // chant #1117 — walks up from `args.path` to the project root: for a
+    // subdirectory build/command (`chant build src/<stack> --env prod`) the
+    // declared `environments` almost always live in the root `chant.config.ts`,
+    // not `args.path` itself.
+    //
+    // chant#2591 — a command marked `runsNoConfig` skips this load: it must not
+    // run the project's `chant.config.ts` (see `CommandDef.runsNoConfig`). Such a
+    // command gets no `--env` check against the declared environments either.
+    const earlyMatch = resolveCommand(args, commandRegistry);
+    const runsNoConfig = earlyMatch != null && commandRunsNoConfig(earlyMatch.def, args);
+    // #3878 — load the command's own modules (and the plugin loader, when it
+    // needs plugins) before anything imports TypeScript: once a chant.config.ts
+    // has registered tsx, every module after it is resolved and loaded through
+    // tsx's hooks, which costs far more than plain node.
+    await Promise.all([
+        earlyMatch ? handlerModules.get(earlyMatch.def.handler)?.() : undefined,
+        earlyMatch?.def.requiresPlugins ? import("./plugins.js") : undefined,
+    ]);
+    const projectPath0 = resolve(args.path === "." ? "." : args.path);
+    let loadedConfig;
+    try {
+        if (!runsNoConfig)
+            loadedConfig = await loadChantConfigUpward(projectPath0);
+        initRuntime();
+    }
+    catch {
+        // Config may not exist yet (e.g. `chant init`)
+        initRuntime();
+    }
+    // Reject an --env that isn't among the project's declared `environments`.
+    const envErr = unknownEnvError(args.env, loadedConfig?.config.environments);
+    if (envErr) {
+        console.error(formatError({ message: envErr, hint: 'Declare it in chant.config `environments`, or omit --env.' }));
+        process.exit(1);
+    }
+    const match = earlyMatch;
+    if (!match) {
+        // chant #1078 — not one of core's own commands; check whether a lexicon
+        // mounted a command group under this name before giving up. This is the
+        // "parsed fine, matched nothing" trigger for the seam — the flag-error
+        // trigger is above, in the `parseArgs` catch block.
+        const code = await tryPluginCommand(rawArgv);
+        if (code !== undefined) {
+            await flushAndExit(code);
+            return;
+        }
+        console.error(formatError({
+            message: `Unknown command: ${args.command}`,
+            hint: 'Run "chant --help" to see available commands',
+        }));
+        process.exit(1);
+    }
+    // #2537 (#2524 D0) — at the root of a declared workspace, `build` and
+    // `lint` refuse with WSP000 unless `--root-only` or `rootOnly: true` says
+    // to run on the root project alone. Both lookups only test whether files
+    // exist; the workspace code loads only when this project is a declared root.
+    if (match.def.name === "build" || match.def.name === "lint") {
+        const target = resolve(args.path);
+        const workspace = findWorkspaceRoot(target);
+        if (workspace && findProjectRoot(target) === workspace.dir) {
+            const { guardRootCommand } = await import("../workspace/root-refusal.js");
+            const refused = guardRootCommand({
+                verb: match.def.name,
+                target,
+                workspaceDir: workspace.dir,
+                rootOnly: args.rootOnly === true || loadedConfig?.config.rootOnly === true,
+            });
+            if (refused !== undefined) {
+                await flushAndExit(refused);
+                return;
+            }
+        }
+    }
+    // For compound commands (e.g. "run list", "lifecycle plan <env>"), the first
+    // positional is a subcommand argument — an environment, op, or lexicon name —
+    // not a project path. Plugins always load from the cwd; the handler reads its
+    // own positionals from args.extraPositional. Using extraPositional as the path
+    // here pointed plugin resolution at e.g. "./local" for `lifecycle plan local`,
+    // which then fell through to import-detection on an empty file set and failed
+    // with "No lexicon detected" even though chant.config.ts lists the lexicons.
+    const projectPath = match.compound ? "." : args.path;
+    // `chant build --components --generate <lexicon>` (#563, generate mode)
+    // discovers `Component` declarations, not lexicon resources — a project
+    // made entirely of components has no reason to declare a chant lexicon
+    // plugin at all. Load plugins best-effort here instead of exiting, so
+    // generate mode works whether or not `chant.config.ts` names a lexicon.
+    // `components status` (#568) is the same shape: a components-only project
+    // may have no lexicon plugin, and `--live` reconciliation is opt-in, so
+    // missing plugins there is "no live evidence" (a warning), not a hard exit.
+    const isGenerateComponents = match.def.name === "build" && args.components && !!args.generate;
+    const isComponentsStatus = match.def.name === "components status";
+    // `components fan-out` (#2420) needs serializers only when it derives the
+    // change signal itself (`--base` builds both refs). Reading one somebody
+    // else already produced (`--from-affected`) touches no lexicon at all, so a
+    // components-only project is not turned away for a step it will not run.
+    const isFanOutFromFile = match.def.name === "components fan-out" && !args.base;
+    // `emulator` (#920) is a property of the *configured* lexicons, not of any infra
+    // file — a fresh/local project with no declarables still boots Floci. Load from
+    // chant.config best-effort, like components status, rather than detectLexicon.
+    const isEmulator = match.def.name === "emulator" || match.def.name.startsWith("emulator ");
+    const plugins = match.def.requiresPlugins
+        ? isGenerateComponents || isComponentsStatus || isEmulator || isFanOutFromFile
+            ? await loadPlugins(await resolveProjectLexicons(resolve(projectPath)).catch(() => [])).catch(() => [])
+            : match.def.name === "serve mcp" && (await isLexiconlessWorkspaceRoot(projectPath))
+                ? [] // #2700 — runServeMcp loads the chant members' lexicons itself.
+                : await loadPluginsOrExit(projectPath, args.lexicon)
+        : [];
+    const serializers = plugins.map((p) => p.serializer);
+    const ctx = { args, plugins, serializers };
+    await flushAndExit(await match.def.handler(ctx));
+}
+/**
+ * Wait until a writable stream has flushed its buffer. `process.exit()` discards
+ * data still buffered for an async sink (a pipe or file), truncating large output
+ * at the ~64 KB pipe buffer — so `chant graph --format ir` piped into a consumer
+ * loses everything past 64 KB and its JSON won't parse. A TTY writes
+ * synchronously (`writableLength` stays 0), so this is a no-op there. Resolves on
+ * `error`/`close` too, so a reader that closes early (EPIPE) can't hang exit.
+ * Exported for testing.
+ */
+export function waitForStreamDrain(stream) {
+    return new Promise((resolve) => {
+        const tick = () => {
+            if (stream.writableLength === 0 || stream.writableEnded || stream.destroyed) {
+                cleanup();
+                resolve();
+                return;
+            }
+            stream.once("drain", tick);
+        };
+        const stop = () => {
+            cleanup();
+            resolve();
+        };
+        const cleanup = () => {
+            stream.off("drain", tick);
+            stream.off("error", stop);
+            stream.off("close", stop);
+        };
+        stream.once("error", stop);
+        stream.once("close", stop);
+        tick();
+    });
+}
+/** Flush stdout+stderr, then exit — so a large piped payload isn't truncated. */
+async function flushAndExit(code) {
+    await waitForStreamDrain(process.stdout);
+    await waitForStreamDrain(process.stderr);
+    process.exit(code);
+}
+// Only run main when executed directly, not when imported. Robust to symlinked
+// invocation paths — see isEntryPoint (a raw string compare silently no-ops the
+// whole CLI through the npm .bin shim / a symlinked checkout).
+const isMain = isEntryPoint(process.argv[1], import.meta.url);
+if (isMain) {
+    main().catch(async (err) => {
+        const verbose = process.argv.includes("--verbose") || process.argv.includes("-v");
+        if (verbose && err instanceof Error && err.stack) {
+            console.error(err.stack);
+        }
+        else {
+            console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+        }
+        await flushAndExit(1);
+    });
+}