@gavana.ai/cli 0.2.0

package/src/runner.mjs

@@ -0,0 +1,1968 @@
+import crypto from "node:crypto";
+import { execFile as execFileCallback } from "node:child_process";
+import fs from "node:fs/promises";
+import http from "node:http";
+import path from "node:path";
+import { promisify } from "node:util";
+
+import { CanvasAgentApiError, createCanvasAgentClient, markdownForResult } from "./client.mjs";
+import { GAVANA_CLI_VERSION, gavanaCapabilitySummary } from "./capabilities.mjs";
+import { GAVANA_CLI_GROUP_HELP, gavanaCommandActions, gavanaCommandGroupUsageLines, gavanaCommandGroups, gavanaCommandIsKnown, gavanaCommandUsageLines } from "./commands.mjs";
+import { agentConfigFilePath, listAgentProfiles, readAgentConfig, readAgentConfigMetadata, removeAgentProfile, setActiveAgentProfile, writeAgentConfig } from "./config.mjs";
+
+const BOOLEAN_OPTIONS = new Set(["help", "version", "pretty", "raw", "yes", "wait", "no-wait", "progress", "token-stdin", "no-verify", "no-browser", "audio", "no-audio", "read-only"]);
+const REPEATABLE_OPTIONS = new Set(["reference", "reference-role", "input", "param", "target", "ratio", "approved", "field"]);
+const MAX_REFERENCE_IMAGES = 16;
+const MAX_VIDEO_REFERENCE_IMAGES = 9;
+const MAX_REFERENCE_IMAGE_BYTES = 50 * 1024 * 1024;
+const execFile = promisify(execFileCallback);
+
+export async function runGavanaCli(argv = process.argv.slice(2), runtime = {}) {
+    const stdout = runtime.stdout || process.stdout;
+    const stderr = runtime.stderr || process.stderr;
+    const env = runtime.env || process.env;
+    const parsed = parseArguments(argv);
+    if (parsed.options.help || (!parsed.positionals.length && parsed.options.version !== true)) {
+        stdout.write(`${helpText(parsed.positionals[0], parsed.positionals[1])}\n`);
+        return 0;
+    }
+
+    const [group, action, ...positionals] = parsed.positionals;
+    try {
+        validateOutputOptions(parsed.options);
+
+        // The command table gates dispatch. Checking here rather than scanning the
+        // dispatch branches from a test is what makes an undeclared command
+        // unreachable instead of merely detectable, and it holds however the branches
+        // below are written.
+        //
+        // It runs before every command handler, including `version` and
+        // `capabilities`. Those two answer without reading their action, so a guard
+        // placed after them let `gavana version bogus` print a version and exit 0 —
+        // the table said the command did not exist and the CLI accepted it anyway.
+        //
+        // `gavana --version` carries no positionals, so group is undefined and the
+        // guard passes it through to the flag handler below; `gavana bogus --version`
+        // is now rejected, because a global flag should not resurrect an unknown
+        // command.
+        if (group !== undefined && !gavanaCommandIsKnown(group, action)) {
+            throw usageError(`Unknown command: ${[group, action].filter(Boolean).join(" ")}. Run with --help.`);
+        }
+        if (parsed.options.version === true) {
+            writeResult(stdout, { name: "@gavana.ai/cli", version: GAVANA_CLI_VERSION, node: process.version }, parsed.options);
+            return 0;
+        }
+        if (group === "version") {
+            writeResult(stdout, { name: "@gavana.ai/cli", version: GAVANA_CLI_VERSION, node: process.version }, parsed.options);
+            return 0;
+        }
+        if (group === "capabilities") {
+            writeResult(stdout, gavanaCapabilitySummary(), parsed.options);
+            return 0;
+        }
+        if (group === "completion") {
+            const shell = action || firstString(parsed.options.shell) || path.basename(env.SHELL || "zsh");
+            stdout.write(`${completionScript(shell)}\n`);
+            return 0;
+        }
+        if (group === "config") {
+            const result = await runConfigCommand(action, positionals, parsed.options, env);
+            writeResult(stdout, result, parsed.options);
+            return 0;
+        }
+        if (group === "auth") {
+            const result = await runAuthCommand(action, positionals, parsed.options, env, runtime);
+            writeResult(stdout, result, parsed.options);
+            return 0;
+        }
+
+        const selectedProfile = firstString(parsed.options.profile) || env.GAVANA_PROFILE || env.CRAFTBOARD_PROFILE || "";
+        const profileEnv = selectedProfile ? { ...env, GAVANA_PROFILE: selectedProfile } : env;
+        const config = group === "mcp" ? await readAgentConfigMetadata(profileEnv) : await readAgentConfig(profileEnv);
+        const token = firstString(parsed.options.token) || env.GAVANA_AGENT_TOKEN || env.CRAFTBOARD_AGENT_TOKEN || config.token;
+        const baseUrl = firstString(parsed.options["base-url"]) || env.GAVANA_BASE_URL || env.CRAFTBOARD_BASE_URL || config.baseUrl || "https://app.gavana.ai";
+        if (group === "mcp") {
+            writeResult(stdout, await runMcpCommand(action, positionals, parsed.options, baseUrl.replace(/\/+$/, ""), runtime), parsed.options);
+            return 0;
+        }
+        if (group === "doctor") {
+            const credentialOverride = Boolean(firstString(parsed.options.token) || env.GAVANA_AGENT_TOKEN || env.CRAFTBOARD_AGENT_TOKEN);
+            const result = await runDoctor(token ? createCanvasAgentClient({ token, baseUrl, surface: "cli", fetchImpl: runtime.fetchImpl }) : null, config, env, baseUrl, credentialOverride ? "Environment or command-line override" : "");
+            writeResult(stdout, result, parsed.options);
+            return result.ok ? 0 : 1;
+        }
+        const client = createCanvasAgentClient({ token, baseUrl, surface: "cli", fetchImpl: runtime.fetchImpl });
+        return await runTrackedRemoteCommand(client, `${group}.${String(action || "default").toLowerCase()}`, runtime.analyticsEnabled ?? !runtime.fetchImpl, async () => {
+            if (group === "api") {
+                writeResult(stdout, await runApiCommand(client, action, positionals, parsed.options), parsed.options);
+                return 0;
+            }
+            const result = await executeCommand(client, group, action, positionals, parsed.options, {
+                env,
+                stderr,
+                readClipboardImage: runtime.readClipboardImage,
+                legacyCampaignCommandsEnabled:
+                    runtime.legacyCampaignCommandsEnabled ??
+                    (env.GAVANA_ENABLE_LEGACY_CAMPAIGN_COMMANDS === "true" ||
+                        env.CRAFTBOARD_ENABLE_LEGACY_CAMPAIGN_COMMANDS === "true" ||
+                        process.env.GAVANA_ENABLE_LEGACY_CAMPAIGN_COMMANDS === "true" ||
+                        process.env.CRAFTBOARD_ENABLE_LEGACY_CAMPAIGN_COMMANDS === "true"),
+            });
+            writeResult(stdout, result, parsed.options);
+            return exitCodeForResult(group, action, result);
+        });
+    } catch (error) {
+        const normalized = normalizeCliError(error);
+        stderr.write(`${JSON.stringify({ ok: false, error: normalized })}\n`);
+        return exitCodeForError(normalized);
+    }
+}
+
+async function runTrackedRemoteCommand(client, name, enabled, handler) {
+    if (!enabled || typeof client.reportAnalyticsEvent !== "function" || typeof client.runWithAnalyticsContext !== "function") return handler();
+    const invocationId = crypto.randomUUID();
+    const traceId = crypto.randomUUID();
+    const startedAt = Date.now();
+    void client.reportAnalyticsEvent({ name, status: "started", invocationId, traceId });
+    const context = { invocationId, traceId };
+    return client.runWithAnalyticsContext(context, async () => {
+        try {
+            const exitCode = await handler();
+            void client.reportAnalyticsEvent({
+                name,
+                status: exitCode === 0 ? "succeeded" : "failed",
+                invocationId,
+                traceId,
+                durationMs: Date.now() - startedAt,
+            });
+            return exitCode;
+        } catch (error) {
+            void client.reportAnalyticsEvent({
+                name,
+                status: error?.code === "timeout" ? "timed_out" : error?.code === "canceled" ? "canceled" : "failed",
+                invocationId,
+                traceId,
+                errorCode: String(error?.code || "command_failed").slice(0, 120),
+                durationMs: Date.now() - startedAt,
+            });
+            throw error;
+        }
+    });
+}
+
+export const runCraftboardAgentCli = runGavanaCli;
+
+function exitCodeForResult(group, action, result) {
+    const waitedImage = group === "image" && (action === "generate" || action === "edit" || action === "variations");
+    const waitedVideo = group === "video" && action === "generate";
+    const waitedAction = group === "action" && action === "run";
+    const waitedJob = group === "job" && action === "wait";
+    const waitedRun = group === "run" && action === "wait";
+    const waitedRecipe = group === "recipe" && action === "run";
+    if ((waitedImage || waitedVideo || waitedAction || waitedJob || waitedRun || waitedRecipe) && (result?.status === "failed" || result?.status === "canceled" || result?.status === "expired")) return 9;
+    return 0;
+}
+
+async function executeCommand(client, group, action, args, options, runtime) {
+    if (group === "campaign" && !runtime.legacyCampaignCommandsEnabled) {
+        throw usageError("The retired campaign command surface is disabled. Use Recipe Library forks and explicit canvas/image commands instead.");
+    }
+    if (group === "recipe") {
+        if (action === "search") return client.searchRecipes(firstString(options.query) || args.join(" "), paginationOptions(options, 100));
+        if (action === "get") {
+            return client.getRecipe(firstString(options.recipe) || requiredArg(args, 0, "recipe get requires recipe:<id>."), firstString(options.version));
+        }
+        if (action === "fork") {
+            const supplied = await optionalJsonInput(options);
+            const recipeId = firstString(options.recipe) || supplied?.recipeId || requiredArg(args, 0, "recipe fork requires recipe:<id>.");
+            return client.forkRecipe(
+                recipeId,
+                supplied || {
+                    canvasId: firstString(options.canvas) || requiredArg(args, 1, "recipe fork requires --canvas canvas:<id>."),
+                    ...(firstString(options.version) ? { version: firstString(options.version) } : {}),
+                    ...(firstString(options["base-revision"]) ? { baseRevision: firstString(options["base-revision"]) } : {}),
+                    ...(options.x !== undefined ? { x: requiredNumber(options.x, "--x must be a number.") } : {}),
+                    ...(options.y !== undefined ? { y: requiredNumber(options.y, "--y must be a number.") } : {}),
+                    idempotencyKey: firstString(options["idempotency-key"]),
+                },
+            );
+        }
+        if (action === "run") {
+            const prepared = await recipeRunInput(client, args, options, runtime);
+            const { __destination, __recipe, ...input } = prepared;
+            const queued = await client.startRecipeRun(__recipe, input);
+            if (options["no-wait"] === true) return { ...queued, destination: __destination };
+            const result = await client.waitForRun(queued.run || queued.handle || queued.id, {
+                timeoutMs: secondsOption(options.timeout, 15 * 60) * 1000,
+                intervalMs: secondsOption(options.interval, 1.5, true) * 1000,
+                onProgress:
+                    options.progress === true
+                        ? (progress) => {
+                              runtime.stderr.write(`${JSON.stringify({ ok: true, progress: { run: progress.run || progress.handle || progress.id, status: progress.status } })}\n`);
+                          }
+                        : undefined,
+            });
+            return { ...result, destination: __destination };
+        }
+    }
+
+    if (group === "campaign") {
+        if (action === "plan") {
+            const supplied = await optionalJsonInput(options);
+            if (supplied) return client.planCampaign(supplied);
+            const product = firstString(options.product);
+            const brandKitId = firstString(options["brand-kit"]);
+            const brandKitRevision = options["brand-kit-revision"] !== undefined ? requiredNumber(options["brand-kit-revision"], "--brand-kit-revision must be an integer.") : undefined;
+            const brief = firstString(options.brief);
+            const finalOutputCount = options.count !== undefined ? requiredNumber(options.count, "--count must be an integer.") : undefined;
+            const aspectRatios = repeatableStrings(options.ratio);
+            return client.planCampaign({
+                canvasId: firstString(options.canvas),
+                recipeId: firstString(options.recipe),
+                ...(firstString(options["recipe-version"]) ? { recipeVersion: firstString(options["recipe-version"]) } : {}),
+                ...(product ? { product } : {}),
+                ...(brandKitId ? { brandKitId } : {}),
+                ...(brandKitRevision !== undefined ? { brandKitRevision } : {}),
+                ...(brief ? { brief } : {}),
+                ...(finalOutputCount !== undefined ? { finalOutputCount } : {}),
+                ...(aspectRatios.length ? { aspectRatios } : {}),
+                idempotencyKey: firstString(options["idempotency-key"]),
+            });
+        }
+        if (action === "start") {
+            const supplied = await optionalJsonInput(options);
+            return client.startCampaign(
+                supplied || {
+                    campaignId: firstString(options.campaign) || requiredArg(args, 0, "campaign start requires campaign:<id>."),
+                    idempotencyKey: firstString(options["idempotency-key"]),
+                },
+            );
+        }
+        if (action === "get") {
+            return client.getCampaign(firstString(options.run) || requiredArg(args, 0, "campaign get requires run:<id>."));
+        }
+        if (action === "review") {
+            const supplied = await optionalJsonInput(options);
+            const runId = supplied?.runId || firstString(options.run) || requiredArg(args, 0, "campaign review requires run:<id>.");
+            return client.reviewCampaign(
+                runId,
+                supplied || {
+                    approvedOutputNodeIds: repeatableStrings(options.approved),
+                    idempotencyKey: firstString(options["idempotency-key"]),
+                },
+            );
+        }
+        if (action === "cancel") {
+            requireConfirmation(options, "campaign cancel stops the campaign run and pending image work. Re-run with --yes.");
+            return client.cancelCampaign(firstString(options.run) || requiredArg(args, 0, "campaign cancel requires run:<id>."));
+        }
+    }
+
+    if (group === "canvas") {
+        if (action === "list") return client.listCanvases(paginationOptions(options, 25));
+        if (action === "agent") return client.getOrCreateAgentCanvas();
+        if (action === "create") {
+            const input = (await optionalJsonInput(options)) || {
+                ...(firstString(options.id) ? { id: firstString(options.id) } : {}),
+                title: firstString(options.title) || args.join(" ") || "Untitled canvas",
+            };
+            return client.createCanvas(input);
+        }
+        if (action === "get") return client.getCanvas(requiredArg(args, 0, "canvas get requires canvas:<id>."));
+        if (action === "render") {
+            const canvas = requiredArg(args, 0, "canvas render requires canvas:<id>.");
+            const svg = await client.renderCanvas(canvas);
+            const outputFile = firstString(options.file);
+            if (outputFile && outputFile !== "-") {
+                const filePath = path.resolve(outputFile);
+                await fs.writeFile(filePath, svg, "utf8");
+                return { mediaType: "image/svg+xml", file: filePath, bytes: Buffer.byteLength(svg) };
+            }
+            return { mediaType: "image/svg+xml", svg };
+        }
+        if (action === "apply") {
+            const canvas = requiredArg(args, 0, "canvas apply requires canvas:<id>.");
+            const input = (await optionalJsonInput(options)) || {};
+            const operations = input.operations || parseJsonOption(options.operations, "--operations must be a JSON array.");
+            if (!Array.isArray(operations)) throw usageError("canvas apply requires --json/--file or --operations with an operation array.");
+            if (operations.some((operation) => operation?.type === "node.delete" || operation?.type === "connection.delete")) {
+                requireConfirmation(options, "canvas apply contains destructive operations. Re-run with --yes.");
+            }
+            const baseRevision = input.baseRevision || firstString(options["base-revision"]) || (await client.getCanvas(canvas)).canvas.revision;
+            return client.applyOperations(canvas, {
+                baseRevision,
+                idempotencyKey: input.idempotencyKey || firstString(options["idempotency-key"]) || crypto.randomUUID(),
+                operations,
+                ...(input.force === true || options.force === true ? { force: true } : {}),
+            });
+        }
+    }
+
+    if (group === "node") {
+        if (action === "get") {
+            return client.getNode(requiredArg(args, 0, "node get requires a canvas reference."), requiredArg(args, 1, "node get requires node:<id>."));
+        }
+        if (action === "create") {
+            const canvas = requiredArg(args, 0, "node create requires a canvas reference.");
+            const nodeInput = (await optionalJsonInput(options)) || nodeFromOptions(options);
+            return applySingleOperation(client, canvas, options, {
+                type: "node.create",
+                ...(firstString(options["client-id"]) ? { clientId: firstString(options["client-id"]) } : {}),
+                node: nodeInput,
+            });
+        }
+        if (action === "update") {
+            const canvas = requiredArg(args, 0, "node update requires a canvas reference.");
+            const nodeId = requiredArg(args, 1, "node update requires node:<id>.");
+            const patch = (await optionalJsonInput(options)) || nodePatchFromOptions(options);
+            if (!Object.keys(patch).length) throw usageError("node update needs --json/--file or a title, content, prompt, position, or size option.");
+            return applySingleOperation(client, canvas, options, { type: "node.update", nodeId, patch });
+        }
+        if (action === "move") {
+            const canvas = requiredArg(args, 0, "node move requires a canvas reference.");
+            const nodeId = requiredArg(args, 1, "node move requires node:<id>.");
+            return applySingleOperation(client, canvas, options, {
+                type: "node.move",
+                nodeId,
+                position: { x: requiredNumber(options.x, "--x is required."), y: requiredNumber(options.y, "--y is required.") },
+            });
+        }
+        if (action === "resize") {
+            const canvas = requiredArg(args, 0, "node resize requires a canvas reference.");
+            const nodeId = requiredArg(args, 1, "node resize requires node:<id>.");
+            return applySingleOperation(client, canvas, options, {
+                type: "node.resize",
+                nodeId,
+                width: requiredNumber(options.width, "--width is required."),
+                height: requiredNumber(options.height, "--height is required."),
+            });
+        }
+        if (action === "delete") {
+            requireConfirmation(options, "node delete changes existing canvas work. Re-run with --yes.");
+            const canvas = requiredArg(args, 0, "node delete requires a canvas reference.");
+            const nodeId = requiredArg(args, 1, "node delete requires node:<id>.");
+            return applySingleOperation(client, canvas, options, { type: "node.delete", nodeId });
+        }
+    }
+
+    if (group === "connection") {
+        if (action === "list") {
+            const canvas = await client.getCanvas(requiredArg(args, 0, "connection list requires a canvas reference."));
+            return { canvas: canvas.canvas.handle, revision: canvas.canvas.revision, connections: canvas.canvas.connections };
+        }
+        if (action === "create") {
+            const canvas = requiredArg(args, 0, "connection create requires a canvas reference.");
+            return applySingleOperation(client, canvas, options, {
+                type: "connection.create",
+                ...(firstString(options["client-id"]) ? { clientId: firstString(options["client-id"]) } : {}),
+                from: firstString(options.from) || requiredArg(args, 1, "connection create requires --from node:<id>."),
+                to: firstString(options.to) || requiredArg(args, 2, "connection create requires --to node:<id>."),
+                ...(firstString(options.mode) ? { mode: firstString(options.mode) } : {}),
+            });
+        }
+        if (action === "delete") {
+            requireConfirmation(options, "connection delete changes existing canvas work. Re-run with --yes.");
+            const canvas = requiredArg(args, 0, "connection delete requires a canvas reference.");
+            const connectionId = requiredArg(args, 1, "connection delete requires connection:<id>.");
+            return applySingleOperation(client, canvas, options, { type: "connection.delete", connectionId });
+        }
+    }
+
+    if (group === "asset") {
+        if (action === "list") return client.listAssets(firstString(options.canvas) || args[0], paginationOptions(options, 200));
+        if (action === "get") return client.getAsset(requiredArg(args, 0, "asset get requires asset:<id> or asset:<ownerUid>:<id>."));
+        if (action === "upload") {
+            const reference = firstString(options.file) || requiredArg(args, 0, "asset upload requires an image path or clipboard.");
+            const [prepared] = await prepareReferenceInputs([reference], runtime);
+            if (prepared.kind !== "local") throw usageError("asset upload requires an image path, -, or clipboard.");
+            return client.uploadAsset(prepared);
+        }
+    }
+
+    if (group === "ai-connection" || group === "provider") {
+        if (action === "list") return client.listConnections(paginationOptions(options, 100));
+    }
+
+    if (group === "model") {
+        if (action === "list") {
+            return client.listModels(
+                {
+                    query: firstString(options.query) || args.join(" "),
+                    provider: firstString(options.provider),
+                    capability: firstString(options.capability),
+                },
+                paginationOptions(options, 100),
+            );
+        }
+        if (action === "get") return client.getModel(firstString(options.model) || requiredArg(args, 0, "model get requires model:<id>."));
+    }
+
+    if (group === "action") {
+        if (action === "list") return client.listActions(firstString(options.query) || args.join(" "), paginationOptions(options, 100));
+        if (action === "get") return client.getAction(firstString(options.action) || requiredArg(args, 0, "action get requires action:<id>."));
+        if (action === "run") {
+            const prepared = await actionInput(client, args, options, runtime);
+            const { __destination, __action, ...input } = prepared;
+            const queued = await client.startAction(__action, input);
+            if (options["no-wait"] === true) return { ...queued, destination: __destination };
+            const result = await client.waitForRun(queued.run || queued.id, {
+                timeoutMs: secondsOption(options.timeout, 15 * 60) * 1000,
+                intervalMs: secondsOption(options.interval, 1.5, true) * 1000,
+                onProgress:
+                    options.progress === true
+                        ? (progress) => {
+                              runtime.stderr.write(
+                                  `${JSON.stringify({
+                                      ok: true,
+                                      progress: {
+                                          run: progress.run || progress.handle || (progress.id ? progress.id.replace(/^job:/, "run:") : undefined),
+                                          id: progress.id,
+                                          status: progress.status,
+                                      },
+                                  })}\n`,
+                              );
+                          }
+                        : undefined,
+            });
+            return { ...result, destination: __destination };
+        }
+    }
+
+    if (group === "image" && (action === "generate" || action === "edit" || action === "variations")) {
+        const prepared = await imageInput(client, action, args, options, runtime);
+        const { __destination, ...input } = prepared;
+        const queued = await client.startImage(action, input);
+        const shouldWait = options["no-wait"] !== true;
+        if (!shouldWait) return { ...queued, destination: __destination };
+        const result = await client.waitForRun(queued.run || queued.id, {
+            timeoutMs: secondsOption(options.timeout, 15 * 60) * 1000,
+            intervalMs: secondsOption(options.interval, 1.5, true) * 1000,
+            onProgress:
+                options.progress === true
+                    ? (progress) => {
+                          runtime.stderr.write(
+                              `${JSON.stringify({
+                                  ok: true,
+                                  progress: {
+                                      run: progress.run || progress.handle || (progress.id ? progress.id.replace(/^job:/, "run:") : undefined),
+                                      id: progress.id,
+                                      status: progress.status,
+                                  },
+                              })}\n`,
+                          );
+                      }
+                    : undefined,
+        });
+        return { ...result, destination: __destination };
+    }
+
+    if (group === "video" && action === "generate") {
+        const downloadPath = requestedVideoDownloadPath(options.download, "--download");
+        if (downloadPath && options["no-wait"] === true) throw usageError("--download cannot be combined with --no-wait. Use video download after the job succeeds.");
+        const input = await videoInput(client, options, runtime);
+        const queued = await client.startVideo(input);
+        if (options["no-wait"] === true) return queued;
+        const result = await client.waitForJob(queued.id, {
+            timeoutMs: secondsOption(options.timeout, 30 * 60) * 1000,
+            intervalMs: secondsOption(options.interval, 1.5, true) * 1000,
+            onProgress:
+                options.progress === true
+                    ? (progress) => {
+                          runtime.stderr.write(
+                              `${JSON.stringify({
+                                  ok: true,
+                                  progress: {
+                                      id: progress.id,
+                                      status: progress.status,
+                                      ...(progress.progress === undefined ? {} : { percent: progress.progress }),
+                                  },
+                              })}\n`,
+                          );
+                      }
+                    : undefined,
+        });
+        if (!downloadPath || result?.status !== "succeeded") return result;
+        return { ...result, download: await saveVideoJobOutput(client, result.id || queued.id, downloadPath, options.yes === true) };
+    }
+
+    if (group === "video" && action === "download") {
+        const job = requiredArg(args, 0, "video download requires job:<id>.");
+        const outputFile = requestedVideoDownloadPath(options.file, "--file");
+        if (!outputFile) throw usageError("video download requires --file path/to/video.mp4.");
+        return saveVideoJobOutput(client, job, outputFile, options.yes === true);
+    }
+
+    if (group === "job") {
+        if (action === "get") return client.getJob(requiredArg(args, 0, "job get requires job:<id>."));
+        if (action === "wait") {
+            const job = requiredArg(args, 0, "job wait requires job:<id>.");
+            return client.waitForJob(job, {
+                timeoutMs: secondsOption(options.timeout, 15 * 60) * 1000,
+                intervalMs: secondsOption(options.interval, 1.5, true) * 1000,
+                onProgress:
+                    options.progress === true
+                        ? (progress) => {
+                              runtime.stderr.write(
+                                  `${JSON.stringify({
+                                      ok: true,
+                                      progress: {
+                                          run: progress.run || progress.handle || (progress.id ? progress.id.replace(/^job:/, "run:") : undefined),
+                                          id: progress.id,
+                                          status: progress.status,
+                                      },
+                                  })}\n`,
+                              );
+                          }
+                        : undefined,
+            });
+        }
+        if (action === "cancel") {
+            requireConfirmation(options, "job cancel stops image, video, or Action work. Re-run with --yes.");
+            return client.cancelJob(requiredArg(args, 0, "job cancel requires job:<id>."));
+        }
+    }
+
+    if (group === "run") {
+        if (action === "get") return client.getRun(requiredArg(args, 0, "run get requires run:<id>."));
+        if (action === "wait") {
+            const run = requiredArg(args, 0, "run wait requires run:<id>.");
+            return client.waitForRun(run, {
+                timeoutMs: secondsOption(options.timeout, 15 * 60) * 1000,
+                intervalMs: secondsOption(options.interval, 1.5, true) * 1000,
+                onProgress:
+                    options.progress === true
+                        ? (progress) => {
+                              runtime.stderr.write(`${JSON.stringify({ ok: true, progress: { run: progress.run || progress.handle || progress.id, status: progress.status } })}\n`);
+                          }
+                        : undefined,
+            });
+        }
+        if (action === "cancel") {
+            requireConfirmation(options, "run cancel stops active Recipe, image, or Action work. Re-run with --yes.");
+            return client.cancelRun(requiredArg(args, 0, "run cancel requires run:<id>."));
+        }
+    }
+
+    throw usageError(`Unknown command: ${[group, action].filter(Boolean).join(" ")}. Run with --help.`);
+}
+
+async function runAuthCommand(action, _args, options, env, runtime) {
+    const fetchImpl = runtime.fetchImpl;
+    if (action === "login") {
+        const profile = firstString(options.profile) || env.GAVANA_PROFILE || env.CRAFTBOARD_PROFILE || "";
+        const profileEnv = profile ? { ...env, GAVANA_PROFILE: profile } : env;
+        const current = await readAgentConfig(profileEnv);
+        let token = firstString(options.token) || env.GAVANA_AGENT_TOKEN || env.CRAFTBOARD_AGENT_TOKEN || (options["token-stdin"] === true ? (await readAllStdin()).trim() : "");
+        const baseUrl = createCanvasAgentClient({
+            token: "configuration-validation",
+            baseUrl: firstString(options["base-url"]) || env.GAVANA_BASE_URL || env.CRAFTBOARD_BASE_URL || current.baseUrl || "https://app.gavana.ai",
+            fetchImpl: runtime.fetchImpl,
+        }).baseUrl;
+        let loginMethod = "token";
+        if (!token) {
+            const login = runtime.oauthLogin
+                ? await runtime.oauthLogin({ baseUrl, readOnly: options["read-only"] === true, profile: profile || current.profile })
+                : await performBrowserOAuthLogin({ baseUrl, readOnly: options["read-only"] === true, noBrowser: options["no-browser"] === true, runtime });
+            token = login.accessToken;
+            loginMethod = "browser";
+        }
+        let verification;
+        let configPath;
+        try {
+            if (options["no-verify"] !== true) {
+                const client = createCanvasAgentClient({ token, baseUrl, surface: "cli", fetchImpl });
+                verification = await verifyAuthentication(client);
+            }
+            configPath = await writeAgentConfig({ token, baseUrl, authMode: loginMethod === "browser" ? "oauth" : "token", ...(profile ? { profile } : {}) }, env);
+        } catch (error) {
+            if (loginMethod === "browser") await revokeBrowserOAuthToken(baseUrl, token, fetchImpl || globalThis.fetch).catch(() => undefined);
+            throw error;
+        }
+        return {
+            authenticated: true,
+            profile: profile || current.profile,
+            baseUrl,
+            configPath,
+            token: maskToken(token),
+            verified: options["no-verify"] !== true,
+            loginMethod,
+            ...(verification?.authType ? { authType: verification.authType } : {}),
+            ...(Array.isArray(verification?.scopes) ? { scopes: verification.scopes } : {}),
+        };
+    }
+    if (action === "status") {
+        const profile = firstString(options.profile) || env.GAVANA_PROFILE || env.CRAFTBOARD_PROFILE || "";
+        const profileEnv = profile ? { ...env, GAVANA_PROFILE: profile } : env;
+        const config = await readAgentConfig(profileEnv);
+        const token = firstString(options.token) || env.GAVANA_AGENT_TOKEN || env.CRAFTBOARD_AGENT_TOKEN || config.token;
+        const baseUrl = firstString(options["base-url"]) || env.GAVANA_BASE_URL || env.CRAFTBOARD_BASE_URL || config.baseUrl;
+        if (!token || !baseUrl) return { authenticated: false, configured: false, configPath: agentConfigFilePath(env) };
+        const client = createCanvasAgentClient({ token, baseUrl, surface: "cli", fetchImpl });
+        const verification = await verifyAuthentication(client);
+        let canvasCount = verification.canvasCount;
+        if (canvasCount === undefined && (verification.authType !== "agent" || verification.scopes?.includes("canvas:read"))) {
+            try {
+                const canvases = await client.listCanvases();
+                canvasCount = Array.isArray(canvases?.canvases) ? canvases.canvases.length : 0;
+            } catch {
+                // Authentication already succeeded. Canvas availability is only
+                // optional status context and must not redefine token validity.
+            }
+        }
+        return {
+            ...verification,
+            profile: config.profile,
+            configured: Boolean(config.token && config.baseUrl),
+            baseUrl: client.baseUrl,
+            token: maskToken(token),
+            ...(canvasCount === undefined ? {} : { canvasCount }),
+            configPath: agentConfigFilePath(env),
+        };
+    }
+    if (action === "logout") {
+        const profile = firstString(options.profile) || env.GAVANA_PROFILE || env.CRAFTBOARD_PROFILE || "";
+        const profileEnv = profile ? { ...env, GAVANA_PROFILE: profile } : env;
+        const config = await readAgentConfig(profileEnv);
+        if (config.authMode === "oauth" && config.token && config.baseUrl) {
+            await revokeBrowserOAuthToken(config.baseUrl, config.token, fetchImpl || globalThis.fetch);
+        }
+        return { authenticated: false, ...(await removeAgentProfile(profile, env)) };
+    }
+    throw usageError("auth supports login, status, and logout.");
+}
+
+async function revokeBrowserOAuthToken(baseUrl, token, fetchImpl) {
+    if (typeof fetchImpl !== "function") throw new CanvasAgentApiError("This runtime cannot revoke the browser login.", { code: "logout_failed" });
+    const response = await fetchImpl(`${String(baseUrl).replace(/\/+$/, "")}/oauth/revoke`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+        body: new URLSearchParams({ token }),
+    });
+    if (!response.ok) {
+        const payload = await response.json().catch(() => null);
+        throw new CanvasAgentApiError(payload?.error_description || "Gavana could not revoke this browser login.", { status: response.status, code: "logout_failed" });
+    }
+}
+
+export async function performBrowserOAuthLogin({ baseUrl, readOnly = false, noBrowser = false, runtime = {} }) {
+    const fetchImpl = runtime.fetchImpl || globalThis.fetch;
+    if (typeof fetchImpl !== "function") throw usageError("This runtime does not provide fetch for browser login.");
+    const origin = new URL(createCanvasAgentClient({ token: "configuration-validation", baseUrl, fetchImpl }).baseUrl).origin;
+    const verifier = crypto.randomBytes(32).toString("base64url");
+    const challenge = crypto.createHash("sha256").update(verifier, "ascii").digest("base64url");
+    const state = crypto.randomBytes(24).toString("base64url");
+    const callback = runtime.createOAuthCallbackServer ? await runtime.createOAuthCallbackServer(state) : await createOAuthCallbackServer(state);
+    try {
+        const scopes = readOnly ? "canvas:read asset:read" : "canvas:read canvas:write asset:read image:generate video:generate job:manage";
+        const registrationResponse = await fetchImpl(`${origin}/oauth/register`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Accept: "application/json" },
+            body: JSON.stringify({
+                client_name: "Gavana CLI",
+                redirect_uris: [callback.redirectUri],
+                token_endpoint_auth_method: "none",
+                grant_types: ["authorization_code"],
+                response_types: ["code"],
+                scope: scopes,
+            }),
+        });
+        const registration = await registrationResponse.json().catch(() => null);
+        if (!registrationResponse.ok || !registration?.client_id) throw usageError(registration?.error_description || "Gavana could not register the CLI OAuth client.");
+
+        const authorize = new URL(`${origin}/oauth/authorize`);
+        authorize.search = new URLSearchParams({
+            response_type: "code",
+            client_id: registration.client_id,
+            redirect_uri: callback.redirectUri,
+            code_challenge: challenge,
+            code_challenge_method: "S256",
+            resource: `${origin}/api/canvas-agent/v1`,
+            scope: scopes,
+            state,
+        }).toString();
+        (runtime.stderr || process.stderr).write(`Open this URL to connect Gavana:\n${authorize}\n`);
+        if (!noBrowser) await (runtime.openBrowser ? runtime.openBrowser(authorize.toString()) : openBrowser(authorize.toString()));
+        const { code } = await callback.wait(runtime.oauthTimeoutMs || 180_000);
+        const tokenResponse = await fetchImpl(`${origin}/oauth/token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+            body: new URLSearchParams({
+                grant_type: "authorization_code",
+                code,
+                client_id: registration.client_id,
+                redirect_uri: callback.redirectUri,
+                code_verifier: verifier,
+                resource: `${origin}/api/canvas-agent/v1`,
+            }),
+        });
+        const payload = await tokenResponse.json().catch(() => null);
+        if (!tokenResponse.ok || !payload?.access_token) throw usageError(payload?.error_description || "Gavana could not finish CLI browser login.");
+        return { accessToken: payload.access_token, scope: payload.scope || scopes };
+    } finally {
+        await callback.close();
+    }
+}
+
+async function createOAuthCallbackServer(expectedState) {
+    let settle;
+    let reject;
+    const result = new Promise((resolve, rejectResult) => {
+        settle = resolve;
+        reject = rejectResult;
+    });
+    const server = http.createServer((request, response) => {
+        const url = new URL(request.url || "/", "http://127.0.0.1");
+        if (url.pathname !== "/oauth/callback") {
+            response.writeHead(404).end("Not found");
+            return;
+        }
+        if (url.searchParams.get("state") !== expectedState) {
+            response.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" }).end("Gavana login state did not match. Return to the terminal and retry.");
+            reject(usageError("Gavana browser login state did not match."));
+            return;
+        }
+        const error = url.searchParams.get("error");
+        const code = url.searchParams.get("code");
+        if (error || !code) {
+            response.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" }).end("Gavana login was not approved. You can close this window.");
+            reject(usageError(url.searchParams.get("error_description") || error || "Gavana browser login was not approved."));
+            return;
+        }
+        response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" }).end("<!doctype html><title>Gavana connected</title><p>Gavana CLI is connected. You can close this window.</p>");
+        settle({ code });
+    });
+    await new Promise((resolve, rejectListen) => {
+        server.once("error", rejectListen);
+        server.listen(0, "127.0.0.1", resolve);
+    });
+    const address = server.address();
+    if (!address || typeof address === "string") throw usageError("Gavana could not start the local OAuth callback.");
+    return {
+        redirectUri: `http://127.0.0.1:${address.port}/oauth/callback`,
+        wait: (timeoutMs) =>
+            Promise.race([
+                result,
+                new Promise((_, rejectTimeout) => {
+                    const timer = setTimeout(() => rejectTimeout(usageError("Gavana browser login timed out. Run auth login again.")), timeoutMs);
+                    timer.unref?.();
+                }),
+            ]),
+        close: () => new Promise((resolve) => server.close(() => resolve())),
+    };
+}
+
+async function openBrowser(url) {
+    if (process.platform === "darwin") return execFile("open", [url]);
+    if (process.platform === "win32") return execFile("cmd", ["/c", "start", "", url]);
+    return execFile("xdg-open", [url]);
+}
+
+async function runConfigCommand(action, args, options, env) {
+    if (action === "list" || action === "profiles" || !action) return listAgentProfiles(env);
+    if (action === "use") {
+        const profile = firstString(options.profile) || requiredArg(args, 0, "config use requires a profile name.");
+        return { active: true, ...(await setActiveAgentProfile(profile, env)) };
+    }
+    if (action === "get") {
+        const profile = firstString(options.profile) || args[0] || "";
+        const config = await readAgentConfig(profile ? { ...env, GAVANA_PROFILE: profile } : env);
+        return {
+            profile: config.profile,
+            baseUrl: config.baseUrl || "",
+            configured: Boolean(config.token && config.baseUrl),
+            token: config.token ? maskToken(config.token) : "",
+            configPath: agentConfigFilePath(env),
+        };
+    }
+    throw usageError("config supports list, get, and use.");
+}
+
+async function runDoctor(client, config, env, baseUrl, credentialSource = "") {
+    const checks = [
+        { name: "node", ok: Number(process.versions.node.split(".")[0]) >= 20, detail: process.version },
+        {
+            name: "credentials",
+            ok: Boolean(client),
+            detail: credentialSource || (config.token && config.baseUrl ? agentConfigFilePath(env) : client ? "Environment or command-line override" : "Run gavana auth login or set GAVANA_AGENT_TOKEN."),
+        },
+        { name: "base_url", ok: /^https:\/\//.test(baseUrl) || /^http:\/\/(?:127\.0\.0\.1|localhost|\[::1\])(?::\d+)?(?:\/|$)/.test(baseUrl), detail: baseUrl },
+    ];
+    if (!client) {
+        checks.push({ name: "authentication", ok: false, detail: "No token is configured. Run gavana auth login." });
+        return { ok: false, profile: config.profile, checks };
+    }
+    try {
+        const status = await verifyAuthentication(client);
+        checks.push({ name: "authentication", ok: Boolean(status?.authenticated !== false), detail: status?.authType || "verified" });
+    } catch (error) {
+        const normalized = normalizeCliError(error);
+        checks.push({ name: "authentication", ok: false, detail: normalized.message, code: normalized.code, requestId: normalized.requestId });
+    }
+    return { ok: checks.every((check) => check.ok), profile: config.profile, checks };
+}
+
+async function runApiCommand(client, methodOrPath, args, options) {
+    const knownMethod = /^(get|post|put|patch|delete)$/i.test(methodOrPath || "");
+    const method = knownMethod ? methodOrPath.toUpperCase() : "GET";
+    const pathname = knownMethod ? requiredArg(args, 0, "api requires a versioned path such as /canvases.") : methodOrPath;
+    if (!pathname || !/^\/[A-Za-z0-9_./-]*$/.test(pathname) || pathname.includes("..")) throw usageError("api path must stay inside /api/canvas-agent/v1.");
+    const fields = Object.fromEntries(
+        repeatableStrings(options.field).map((field) => {
+            const separator = field.indexOf("=");
+            if (separator < 1) throw usageError("--field requires NAME=VALUE.");
+            return [field.slice(0, separator), field.slice(separator + 1)];
+        }),
+    );
+    const supplied = await optionalJsonInput(options);
+    const input = supplied || (Object.keys(fields).length ? fields : undefined);
+    if (method === "GET" && input) return client.request(pathname, { query: input });
+    return client.request(pathname, { method, ...(input === undefined ? {} : { body: input }) });
+}
+
+async function runMcpCommand(action, args, options, baseUrl, runtime) {
+    if (action !== "install" && action !== "config") throw usageError("mcp supports install and config.");
+    const clientName = (firstString(options.client) || args[0] || "codex").toLowerCase();
+    if (action === "install" && clientName !== "codex" && clientName !== "claude") {
+        throw usageError("mcp install supports codex and claude. Use mcp config for cursor, chatgpt, or local clients.");
+    }
+    const endpoint = `${baseUrl}${options["read-only"] === true ? "/mcp/readonly" : "/mcp"}`;
+    const definition = mcpClientDefinition(clientName, endpoint, options["read-only"] === true);
+    if (action === "config" || !definition.command) return definition;
+    const execute = runtime.execFile || execFile;
+    await execute(definition.command, definition.args);
+    return { ...definition, installed: true };
+}
+
+function mcpClientDefinition(clientName, endpoint, readOnly = false) {
+    if (clientName === "codex") return { client: "codex", transport: "streamable-http", endpoint, command: "codex", args: ["mcp", "add", "gavana", "--url", endpoint] };
+    if (clientName === "claude") return { client: "claude", transport: "streamable-http", endpoint, command: "claude", args: ["mcp", "add", "--transport", "http", "gavana", endpoint] };
+    if (clientName === "cursor") return { client: "cursor", transport: "streamable-http", endpoint, config: { mcpServers: { gavana: { url: endpoint } } } };
+    if (clientName === "chatgpt") return { client: "chatgpt", transport: "streamable-http", endpoint, instructions: "Add the endpoint as a custom MCP connector, then complete Gavana OAuth in the browser." };
+    if (clientName === "stdio" || clientName === "local") {
+        return {
+            client: "local",
+            transport: "stdio",
+            command: "npx",
+            args: ["-y", "@gavana.ai/mcp@0.2.0"],
+            env: readOnly ? { GAVANA_MCP_READ_ONLY: "true" } : {},
+            credentialSource: "Reads the active Gavana CLI profile or inherited GAVANA_BASE_URL and GAVANA_AGENT_TOKEN environment variables.",
+        };
+    }
+    throw usageError("mcp client must be codex, claude, cursor, chatgpt, or local.");
+}
+
+function completionScript(shell) {
+    // Generated from the command table, so a new command is completable the moment
+    // it is declared. This list used to be a third hand-maintained copy of the
+    // catalog, beside dispatch and help.
+    // Hidden groups and hidden actions fall out inside the table, so there is no
+    // second list here to drift against it.
+    const groups = gavanaCommandGroups();
+    const commands = groups.join(" ");
+    // Second level: the actions under each group. The table knows them, so the
+    // shells may as well.
+    const actionsByGroup = groups.map((group) => [group, gavanaCommandActions(group)]).filter(([, actions]) => actions.length);
+
+    if (shell === "zsh") {
+        const cases = actionsByGroup.map(([group, actions]) => `        ${group}) _values 'action' ${actions.join(" ")} ;;`).join("\n");
+        // The case has to sit inside the ->args state. `*::arg:->args` re-slices
+        // $words so $words[1] is the group, but only once _arguments has set $state;
+        // running the case unconditionally reads $words[1] as "gavana" and matches
+        // nothing, which is how the previous version silently completed no actions.
+        // `(( CURRENT == 2 ))` keeps actions to the action position. Inside ->args
+        // the words array is re-sliced so the group is $words[1] and the action is
+        // $words[2]; without the check the same action list is offered for every
+        // later argument, so `gavana canvas list <TAB>` re-offered the canvas
+        // actions where a canvas handle belongs.
+        return `#compdef gavana\n_arguments '1:command:(${commands})' '*::arg:->args'\ncase $state in\n  args)\n    if (( CURRENT == 2 )); then\n      case $words[1] in\n${cases}\n      esac\n    fi\n  ;;\nesac`;
+    }
+    if (shell === "bash") {
+        const cases = actionsByGroup.map(([group, actions]) => `      ${group}) words='${actions.join(" ")}' ;;`).join("\n");
+        // Groups complete at position 1 and actions at position 2, and nowhere else.
+        // Falling back to the root list meant `gavana doctor <TAB>` offered every
+        // group as a doctor action, and a group with no actions offered them forever.
+        return `_gavana_complete() {\n  local words=''\n  if [ "\${COMP_CWORD}" -eq 1 ]; then\n    words='${commands}'\n  elif [ "\${COMP_CWORD}" -eq 2 ]; then\n    case "\${COMP_WORDS[1]}" in\n${cases}\n    esac\n  fi\n  COMPREPLY=( $(compgen -W "\${words}" -- "\${COMP_WORDS[COMP_CWORD]}") )\n}\ncomplete -F _gavana_complete gavana`;
+    }
+    if (shell === "fish") {
+        return [
+            ...groups.map((command) => `complete -c gavana -f -n '__fish_use_subcommand' -a '${command}'`),
+            // `not __fish_seen_subcommand_from <actions>` is fish's equivalent of the
+            // zsh position check: __fish_seen_subcommand_from stays true for the rest
+            // of the line, so without it the group's actions were offered again after
+            // one had already been chosen.
+            ...actionsByGroup.flatMap(([group, actions]) =>
+                actions.map((action) => `complete -c gavana -f -n '__fish_seen_subcommand_from ${group}; and not __fish_seen_subcommand_from ${actions.join(" ")}' -a '${action}'`),
+            ),
+        ].join("\n");
+    }
+    throw usageError("completion supports zsh, bash, and fish.");
+}
+
+async function verifyAuthentication(client) {
+    try {
+        return await client.getAuthStatus();
+    } catch (error) {
+        if (!(error instanceof CanvasAgentApiError) || error.status !== 404) throw error;
+        const canvases = await client.listCanvases();
+        return {
+            authenticated: true,
+            authType: "legacy",
+            canvasCount: Array.isArray(canvases?.canvases) ? canvases.canvases.length : 0,
+        };
+    }
+}
+
+async function applySingleOperation(client, canvas, options, operation) {
+    const baseRevision = firstString(options["base-revision"]) || (await client.getCanvas(canvas)).canvas.revision;
+    return client.applyOperations(canvas, {
+        baseRevision,
+        idempotencyKey: firstString(options["idempotency-key"]) || crypto.randomUUID(),
+        operations: [operation],
+    });
+}
+
+async function recipeRunInput(client, args, options, runtime) {
+    const supplied = (await optionalJsonInput(options)) || {};
+    const recipeReference = supplied.recipeId || firstString(options.recipe) || requiredArg(args, 0, "recipe run requires recipe:<id>.");
+    const definition = (await client.getRecipe(recipeReference, supplied.version || firstString(options.version))).recipe;
+    const destination = supplied.destination || firstString(options.destination) || supplied.canvasId || firstString(options.canvas);
+    if (!destination) throw usageError("recipe run requires --destination agent-canvas, new-canvas, or canvas:<id>.");
+    const canvasTitle = supplied.canvasTitle || firstString(options["canvas-title"]);
+    if (destination === "new-canvas" && !canvasTitle) throw usageError("recipe run with --destination new-canvas requires --canvas-title.");
+    const idempotencyKey = supplied.idempotencyKey || firstString(options["idempotency-key"]) || crypto.randomUUID();
+    const canvasResult = await client.resolveCanvasDestination(destination, {
+        idempotencyKey,
+        title: canvasTitle,
+    });
+    const canvasId = canvasResult.canvas.handle;
+    const suppliedOptionInputs = repeatableStrings(options.input);
+    if (supplied.inputs && suppliedOptionInputs.length) throw usageError("Provide Recipe inputs in JSON or with --input KEY=VALUE, not both.");
+    const requestedInputs = supplied.inputs || recipeInputPairs(suppliedOptionInputs);
+    const instanceNodeId = supplied.instanceNodeId || firstString(options["instance-node"]);
+    if ((!requestedInputs || !Object.keys(requestedInputs).length) && !instanceNodeId) {
+        throw usageError("recipe run requires one --input KEY=VALUE for every declared input, or --instance-node for a connected private Recipe.");
+    }
+    const inputs = await prepareRecipeInputs(client, definition, requestedInputs || {}, canvasId, runtime);
+    const webhook = cliWebhookInput(supplied, options, runtime.env);
+    return {
+        canvasId,
+        baseRevision: supplied.baseRevision || firstString(options["base-revision"]) || canvasResult.canvas.revision,
+        idempotencyKey,
+        ...(supplied.version || firstString(options.version) ? { version: supplied.version || firstString(options.version) } : {}),
+        ...(instanceNodeId ? { instanceNodeId } : {}),
+        ...(Object.keys(inputs).length ? { inputs } : {}),
+        ...(supplied.model || firstString(options.model) ? { model: supplied.model || firstString(options.model) } : {}),
+        ...(supplied.size || firstString(options.size) ? { size: supplied.size || firstString(options.size) } : {}),
+        ...(supplied.quality || firstString(options.quality) ? { quality: supplied.quality || firstString(options.quality) } : {}),
+        ...(webhook ? { webhook } : {}),
+        __recipe: definition.handle || recipeReference,
+        __destination: {
+            requested: String(destination),
+            canvasId,
+        },
+    };
+}
+
+function recipeInputPairs(entries) {
+    const inputs = {};
+    for (const entry of entries) {
+        const separator = entry.indexOf("=");
+        if (separator < 1) throw usageError("--input requires KEY=VALUE for Recipe runs.");
+        const key = entry.slice(0, separator).trim();
+        const value = entry.slice(separator + 1).trim();
+        if (!key || !value) throw usageError("--input requires a non-empty KEY=VALUE.");
+        if (inputs[key] !== undefined) throw usageError(`Recipe input ${key} was provided more than once.`);
+        inputs[key] = value;
+    }
+    return inputs;
+}
+
+async function prepareRecipeInputs(client, definition, requested, canvasReference, runtime) {
+    if (!requested || typeof requested !== "object" || Array.isArray(requested)) throw usageError("Recipe inputs must be KEY=VALUE pairs.");
+    const aliases = new Map();
+    const firstWords = new Map();
+    for (const input of definition.inputs || []) {
+        aliases.set(input.nodeId, input);
+        aliases.set(normalizeRecipeInputKey(input.label), input);
+        const firstWord = normalizeRecipeInputKey(input.label).split("-")[0];
+        firstWords.set(firstWord, firstWords.has(firstWord) ? null : input);
+    }
+    for (const [key, input] of firstWords) {
+        if (input) aliases.set(key, input);
+    }
+
+    const normalized = {};
+    for (const [key, rawValue] of Object.entries(requested)) {
+        const port = aliases.get(key) || aliases.get(normalizeRecipeInputKey(key));
+        if (!port) throw usageError(`Unknown Recipe input ${key}. Run recipe get ${definition.handle || `recipe:${definition.id}`} to see its input keys.`);
+        if (normalized[port.nodeId] !== undefined) throw usageError(`Recipe input ${port.label} was provided more than once.`);
+        if (typeof rawValue !== "string" || !rawValue.trim()) throw usageError(`Recipe input ${port.label} must be a non-empty string.`);
+        const value = rawValue.trim();
+        if (port.nodeType === "image") {
+            const imageValue = value.startsWith("@") ? value.slice(1) : value;
+            const prepared = await prepareReferenceInput(imageValue, runtime);
+            normalized[port.nodeId] = (await uploadLocalReferenceInputs(client, [prepared], canvasReference))[0];
+        } else if (/^(?:node:|asset:)/.test(value)) {
+            normalized[port.nodeId] = value;
+        } else if (value.startsWith("@@")) {
+            normalized[port.nodeId] = value.slice(1);
+        } else if (value.startsWith("@")) {
+            const file = value.slice(1);
+            if (!file) throw usageError(`Recipe input ${port.label} uses @path/to/file for text files.`);
+            normalized[port.nodeId] = file === "-" ? await readAllStdin() : await fs.readFile(path.resolve(file), "utf8");
+        } else {
+            normalized[port.nodeId] = value;
+        }
+    }
+    return normalized;
+}
+
+function normalizeRecipeInputKey(value) {
+    return String(value || "")
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+
+async function actionInput(client, args, options, runtime) {
+    const supplied = (await optionalJsonInput(options)) || {};
+    const webhook = cliWebhookInput(supplied, options, runtime.env);
+    const actionReference = supplied.actionId || firstString(options.action) || requiredArg(args, 0, "action run requires action:<id>.");
+    const definition = (await client.getAction(actionReference)).action;
+    const destination = supplied.destination || firstString(options.destination) || supplied.canvasId || firstString(options.canvas);
+    if (!destination) throw usageError("action run requires --destination agent-canvas, new-canvas, or canvas:<id>.");
+    const canvasTitle = supplied.canvasTitle || firstString(options["canvas-title"]);
+    if (destination === "new-canvas" && !canvasTitle) throw usageError("action run with --destination new-canvas requires --canvas-title.");
+    const idempotencyKey = supplied.idempotencyKey || firstString(options["idempotency-key"]) || crypto.randomUUID();
+    const rawInputs = repeatableStrings(supplied.inputs || options.input);
+    if (rawInputs.length !== definition.inputs.length) {
+        throw usageError(`${definition.title} requires exactly ${definition.inputs.length} --input value${definition.inputs.length === 1 ? "" : "s"} in the order shown by action get.`);
+    }
+    const preparedInputs = await prepareReferenceInputs(rawInputs, runtime);
+    const canvasResult = await client.resolveCanvasDestination(destination, {
+        idempotencyKey,
+        title: canvasTitle,
+    });
+    const canvasId = canvasResult.canvas.handle;
+    const inputs = await uploadLocalReferenceInputs(client, preparedInputs, canvasId);
+    const params = actionParameters(definition, supplied.params, options);
+    const targetNodeId = supplied.targetNodeId || firstString(options.target) || firstString(options["target-node"]);
+    const preparedDestination = await client.prepareImageDestination({
+        canvasResult,
+        destination,
+        operation: "action",
+        idempotencyKey,
+        baseRevision: supplied.baseRevision || firstString(options["base-revision"]),
+        targetNodeId,
+        count: 1,
+        targetTitle: supplied.targetTitle || firstString(options.title) || `${definition.title} result`,
+    });
+    return {
+        canvasId,
+        baseRevision: preparedDestination.baseRevision,
+        idempotencyKey,
+        targetNodeId: preparedDestination.targetNodeIds[0],
+        inputs,
+        params,
+        ...(webhook ? { webhook } : {}),
+        __action: definition.id,
+        __destination: {
+            requested: String(destination),
+            canvasId,
+            targetNodeIds: preparedDestination.targetNodeIds,
+        },
+    };
+}
+
+function actionParameters(definition, suppliedParams, options) {
+    const params = suppliedParams && typeof suppliedParams === "object" && !Array.isArray(suppliedParams) ? { ...suppliedParams } : {};
+    for (const entry of repeatableStrings(options.param)) {
+        const separator = entry.indexOf("=");
+        if (separator < 1) throw usageError("--param requires NAME=VALUE.");
+        params[entry.slice(0, separator)] = entry.slice(separator + 1);
+    }
+    for (const parameter of definition?.parameters || []) {
+        const optionName = String(parameter.id).replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+        if (options[optionName] === undefined) continue;
+        const raw = firstString(options[optionName]);
+        if (parameter.type === "number" || parameter.valueType === "number") {
+            params[parameter.id] = requiredNumber(raw, `--${optionName} must be a number.`);
+        } else {
+            params[parameter.id] = raw;
+        }
+    }
+    return params;
+}
+
+async function imageInput(client, operation, args, options, runtime) {
+    const supplied = (await optionalJsonInput(options)) || {};
+    const webhook = cliWebhookInput(supplied, options, runtime.env);
+    const destination = supplied.destination || firstString(options.destination) || supplied.canvasId || firstString(options.canvas) || args[0];
+    if (!destination) throw usageError(`image ${operation} requires --destination agent-canvas, new-canvas, or canvas:<id>.`);
+    const canvasTitle = supplied.canvasTitle || firstString(options["canvas-title"]);
+    if (destination === "new-canvas" && !canvasTitle) throw usageError(`image ${operation} with --destination new-canvas requires --canvas-title.`);
+    const idempotencyKey = supplied.idempotencyKey || firstString(options["idempotency-key"]) || crypto.randomUUID();
+    const targetNodeIds = supplied.targetNodeIds || repeatableStrings(options.target);
+    const singleTarget = supplied.targetNodeId || firstString(options["target-node"]);
+    const count = supplied.count !== undefined || options.count !== undefined ? (supplied.count ?? requiredNumber(options.count, "--count must be a number.")) : undefined;
+    if (count !== undefined && (!Number.isInteger(Number(count)) || Number(count) < 1 || Number(count) > 4)) throw usageError("--count must be an integer between 1 and 4.");
+    const referenceInputs = imageReferenceInputs(supplied.references, options.reference, supplied.referenceRoles, options["reference-role"]);
+    const preparedReferences = await prepareReferenceInputs(referenceInputs.map((reference) => reference.value), runtime);
+    const canvasResult = await client.resolveCanvasDestination(destination, {
+        idempotencyKey,
+        title: canvasTitle,
+    });
+    const canvasId = canvasResult.canvas.handle;
+    const referenceHandles = await uploadLocalReferenceInputs(client, preparedReferences, canvasId);
+    const references = referenceHandles.map((handle, index) => ({ handle, ...(referenceInputs[index]?.role ? { role: referenceInputs[index].role } : {}) }));
+    const source = supplied.source || firstString(options.source);
+    const prompt = supplied.prompt || firstString(options.prompt);
+    const preparedDestination = await client.prepareImageDestination({
+        canvasResult,
+        destination,
+        operation,
+        idempotencyKey,
+        baseRevision: supplied.baseRevision || firstString(options["base-revision"]),
+        targetNodeIds,
+        targetNodeId: singleTarget,
+        count,
+        prompt,
+        size: supplied.size || firstString(options.size),
+        targetTitle: supplied.targetTitle || firstString(options.title),
+        targetX: supplied.targetX ?? (options.x === undefined ? undefined : requiredNumber(options.x, "--x must be a number.")),
+        targetY: supplied.targetY ?? (options.y === undefined ? undefined : requiredNumber(options.y, "--y must be a number.")),
+        targetWidth: supplied.targetWidth ?? (options.width === undefined ? undefined : requiredNumber(options.width, "--width must be a number.")),
+        targetHeight: supplied.targetHeight ?? (options.height === undefined ? undefined : requiredNumber(options.height, "--height must be a number.")),
+    });
+    const {
+        destination: _destination,
+        canvasTitle: _canvasTitle,
+        targetTitle: _targetTitle,
+        targetNodeId: _targetNodeId,
+        targetNodeIds: _targetNodeIds,
+        targetX: _targetX,
+        targetY: _targetY,
+        targetWidth: _targetWidth,
+        targetHeight: _targetHeight,
+        ...jobSupplied
+    } = supplied;
+    return {
+        ...jobSupplied,
+        canvasId,
+        baseRevision: preparedDestination.baseRevision,
+        idempotencyKey,
+        targetNodeIds: preparedDestination.targetNodeIds,
+        ...(prompt ? { prompt } : {}),
+        ...(supplied.promptNodeId || firstString(options["prompt-node"]) ? { promptNodeId: supplied.promptNodeId || firstString(options["prompt-node"]) } : {}),
+        ...(references.length ? { references: references.some((reference) => reference.role) ? references : referenceHandles } : {}),
+        ...(source ? { source } : {}),
+        ...(supplied.connectionId || firstString(options.connection) ? { connectionId: supplied.connectionId || firstString(options.connection) } : {}),
+        ...(supplied.model || firstString(options.model) ? { model: supplied.model || firstString(options.model) } : {}),
+        ...(supplied.size || firstString(options.size) ? { size: supplied.size || firstString(options.size) } : {}),
+        ...(supplied.quality || firstString(options.quality) ? { quality: supplied.quality || firstString(options.quality) } : {}),
+        ...(count !== undefined ? { count } : {}),
+        ...(webhook ? { webhook } : {}),
+        __destination: {
+            requested: String(destination),
+            canvasId,
+            targetNodeIds: preparedDestination.targetNodeIds,
+        },
+    };
+}
+
+function imageReferenceInputs(supplied, optionReferences, suppliedRoles, optionRoles) {
+    const rawReferences = supplied === undefined ? repeatableStrings(optionReferences) : Array.isArray(supplied) ? supplied : (() => { throw usageError("references must be an array."); })();
+    const roles = suppliedRoles === undefined ? repeatableStrings(optionRoles) : Array.isArray(suppliedRoles) ? suppliedRoles.map(String) : (() => { throw usageError("referenceRoles must be an array."); })();
+    if (roles.length && roles.length !== rawReferences.length) throw usageError("Provide one --reference-role for every --reference, in the same order.");
+    return rawReferences.map((entry, index) => {
+        const typed = entry && typeof entry === "object" && !Array.isArray(entry) ? entry : null;
+        if (typed && Object.keys(typed).some((key) => key !== "handle" && key !== "role")) throw usageError('A typed reference may contain only "handle" and "role".');
+        const value = typeof entry === "string" ? entry.trim() : typeof typed?.handle === "string" ? typed.handle.trim() : "";
+        if (!value) throw usageError("Each image reference needs a handle or local image path.");
+        const suppliedRole = typed?.role;
+        if (suppliedRole !== undefined && typeof suppliedRole !== "string") throw usageError("A typed reference role must be a string.");
+        if (suppliedRole !== undefined && roles.length) throw usageError("Set a reference role in JSON or with --reference-role, not both.");
+        const role = roles.length ? roles[index]?.trim() : typeof suppliedRole === "string" ? suppliedRole.trim() : "";
+        if (role && !["identity", "construction", "texture", "fit", "style"].includes(role)) {
+            throw usageError("Reference roles must be identity, construction, texture, fit, or style.");
+        }
+        return { value, ...(role ? { role } : {}) };
+    });
+}
+
+async function videoInput(client, options, runtime) {
+    const supplied = (await optionalJsonInput(options)) || {};
+    const modelReference = videoStringValue(supplied.model, options.model, "--model", true);
+    if (!modelReference) throw usageError("video generate requires --model model:<id> or a connected provider model id.");
+    const connectionId = videoStringValue(supplied.connectionId, options.connection, "--connection");
+    const prompt = videoStringValue(supplied.prompt, options.prompt, "--prompt", true);
+    if (!prompt) throw usageError("video generate requires --prompt.");
+    if (prompt.length > 8_000) throw usageError("--prompt must contain 8,000 characters or fewer.");
+
+    const firstFrameInput = videoStringValue(supplied.firstFrame, options["first-frame"], "--first-frame");
+    const lastFrameInput = videoStringValue(supplied.lastFrame, options["last-frame"], "--last-frame");
+    if (lastFrameInput && !firstFrameInput) throw usageError("--last-frame requires --first-frame.");
+    const rawReferences = repeatableStrings(supplied.references || options.reference);
+    if (rawReferences.length > MAX_VIDEO_REFERENCE_IMAGES) {
+        throw usageError(`Video generation accepts up to ${MAX_VIDEO_REFERENCE_IMAGES} --reference values.`);
+    }
+    const canvasId = videoStringValue(supplied.canvasId, options.canvas, "--canvas");
+    const nodeInputs = [firstFrameInput, lastFrameInput, ...rawReferences].filter((value) => String(value || "").startsWith("node:"));
+    if (nodeInputs.length && !canvasId) throw usageError("--canvas canvas:<id> is required when a video frame or reference uses node:<id>.");
+
+    if (options.duration !== undefined && typeof options.duration !== "string") throw usageError("--duration requires a whole number of seconds.");
+    const durationSeconds = supplied.durationSeconds !== undefined || options.duration !== undefined ? (supplied.durationSeconds ?? requiredNumber(options.duration, "--duration must be a whole number of seconds.")) : undefined;
+    if (durationSeconds !== undefined && (!Number.isInteger(Number(durationSeconds)) || Number(durationSeconds) < 1 || Number(durationSeconds) > 120)) {
+        throw usageError("--duration must be a whole number from 1 through 120.");
+    }
+    const aspectRatio = videoStringValue(supplied.aspectRatio, options["aspect-ratio"], "--aspect-ratio");
+    const resolution = videoStringValue(supplied.resolution, options.resolution, "--resolution");
+    const generateAudio = videoAudioOption(supplied, options);
+    const idempotencyKey = videoStringValue(supplied.idempotencyKey, options["idempotency-key"], "--idempotency-key") || crypto.randomUUID();
+    if (idempotencyKey.length < 8 || idempotencyKey.length > 200) {
+        throw usageError("--idempotency-key must contain 8 through 200 characters.");
+    }
+    const ownerUid = videoStringValue(supplied.ownerUid, undefined, "ownerUid");
+
+    const model = await resolveCliVideoModel(client, modelReference, connectionId);
+    validateVideoModelInput(model, {
+        firstFrame: firstFrameInput,
+        lastFrame: lastFrameInput,
+        references: rawReferences,
+        durationSeconds,
+        aspectRatio,
+        resolution,
+        generateAudio,
+    });
+
+    const preparedFirstFrame = firstFrameInput ? await prepareVideoReferenceInput(String(firstFrameInput), runtime) : undefined;
+    const preparedLastFrame = lastFrameInput ? await prepareVideoReferenceInput(String(lastFrameInput), runtime) : undefined;
+    const preparedReferences = await Promise.all(rawReferences.map((value) => prepareVideoReferenceInput(value, runtime)));
+    ensureUniqueVideoReferences(preparedReferences);
+    const uploadedFrames = await uploadLocalReferenceInputs(client, [preparedFirstFrame, preparedLastFrame, ...preparedReferences].filter(Boolean));
+    const firstFrame = preparedFirstFrame ? uploadedFrames.shift() : undefined;
+    const lastFrame = preparedLastFrame ? uploadedFrames.shift() : undefined;
+
+    return {
+        model: model.handle || modelReference,
+        ...(connectionId ? { connectionId } : {}),
+        prompt,
+        idempotencyKey,
+        ...(canvasId ? { canvasId } : {}),
+        ...(ownerUid ? { ownerUid } : {}),
+        ...(aspectRatio ? { aspectRatio } : {}),
+        ...(durationSeconds !== undefined ? { durationSeconds: Number(durationSeconds) } : {}),
+        ...(resolution ? { resolution } : {}),
+        ...(generateAudio !== undefined ? { generateAudio } : {}),
+        ...(firstFrame ? { firstFrame } : {}),
+        ...(lastFrame ? { lastFrame } : {}),
+        ...(uploadedFrames.length ? { references: uploadedFrames } : {}),
+    };
+}
+
+function requestedVideoDownloadPath(value, label) {
+    if (value === undefined) return "";
+    const outputPath = firstString(value).trim();
+    if (!outputPath) throw usageError(`${label} requires an output file path.`);
+    return outputPath;
+}
+
+async function saveVideoJobOutput(client, jobReference, requestedPath, overwrite) {
+    const filePath = path.resolve(requestedPath);
+    const temporaryPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.gavana-${process.pid}-${crypto.randomUUID()}.part`);
+    if (!overwrite) {
+        try {
+            await fs.stat(filePath);
+            throw usageError(`Output file already exists: ${filePath}. Re-run with --yes to replace it.`);
+        } catch (error) {
+            if (error instanceof CanvasAgentApiError) throw error;
+            if (error?.code !== "ENOENT") throw error;
+        }
+    }
+    const response = await client.downloadJobOutput(jobReference);
+    if (!response?.body) throw new CanvasAgentApiError("Gavana returned an empty video download.", { code: "invalid_response" });
+    let file;
+    let bytes = 0;
+    try {
+        file = await fs.open(temporaryPath, "wx", 0o600);
+        for await (const chunk of response.body) {
+            const buffer = Buffer.from(chunk);
+            bytes += buffer.byteLength;
+            await file.write(buffer);
+        }
+        await file.close();
+        file = undefined;
+        if (overwrite) {
+            await fs.rename(temporaryPath, filePath);
+        } else {
+            try {
+                await fs.link(temporaryPath, filePath);
+            } catch (error) {
+                if (error?.code === "EEXIST") throw usageError(`Output file already exists: ${filePath}. Re-run with --yes to replace it.`);
+                throw error;
+            }
+            await fs.unlink(temporaryPath).catch(() => undefined);
+        }
+        return {
+            job: jobReference,
+            file: filePath,
+            bytes,
+            contentType: response.headers.get("content-type") || "video/mp4",
+        };
+    } catch (error) {
+        await file?.close().catch(() => undefined);
+        await fs.unlink(temporaryPath).catch(() => undefined);
+        throw error;
+    }
+}
+
+function videoStringValue(jsonValue, optionValue, label, required = false) {
+    if (jsonValue !== undefined && optionValue !== undefined) throw usageError(`Configure ${label.replace(/^--/, "")} in JSON or with ${label}, not both.`);
+    const value = jsonValue !== undefined ? jsonValue : optionValue;
+    if (value === undefined || value === null) return "";
+    if (typeof value !== "string" || !value.trim()) {
+        if (required) return "";
+        throw usageError(`${label} requires a non-empty value.`);
+    }
+    return value.trim();
+}
+
+function videoAudioOption(supplied, options) {
+    if (options.audio !== undefined && options.audio !== true) throw usageError("--audio does not take a value. Use --no-audio to disable it.");
+    if (options["no-audio"] !== undefined && options["no-audio"] !== true) throw usageError("--no-audio does not take a value.");
+    if (options.audio === true && options["no-audio"] === true) throw usageError("Use either --audio or --no-audio, not both.");
+    if (supplied.generateAudio !== undefined && (options.audio === true || options["no-audio"] === true)) {
+        throw usageError("Configure generateAudio in JSON or with --audio/--no-audio, not both.");
+    }
+    const value = options.audio === true ? true : options["no-audio"] === true ? false : supplied.generateAudio;
+    if (value !== undefined && typeof value !== "boolean") throw usageError("generateAudio must be true or false.");
+    return value;
+}
+
+async function resolveCliVideoModel(client, reference, connectionId) {
+    if (reference.startsWith("model:")) {
+        const result = await client.getModel(reference);
+        const model = result?.model;
+        if (!model) throw usageError(`Gavana did not return ${reference}.`);
+        if (connectionId && model.connectionId !== connectionId) throw usageError("--connection does not match the selected model handle.");
+        return model;
+    }
+    const result = await client.listModels({ query: reference, capability: "video.generate" }, { limit: 100 });
+    const matches = (result?.models || []).filter((model) => model.type === "video" && model.modelId === reference && (!connectionId || model.connectionId === connectionId));
+    if (!matches.length) throw usageError(`Video model ${reference} was not found. Run gavana model list --capability video.generate.`);
+    if (matches.length > 1) throw usageError(`Video model ${reference} exists on more than one connection. Use its model:<id> handle from gavana model list.`);
+    return matches[0];
+}
+
+function validateVideoModelInput(model, input) {
+    if (model.type !== "video" || !Array.isArray(model.capabilities) || !model.capabilities.includes("video.generate")) {
+        throw usageError(`${model.handle || model.modelId || "The selected model"} cannot generate video.`);
+    }
+    if (input.firstFrame && !model.capabilities.includes("video.generate.fromImage")) {
+        throw usageError(`${model.name || model.modelId} does not support --first-frame.`);
+    }
+    if (input.lastFrame && !model.capabilities.includes("video.generate.fromFrames")) {
+        throw usageError(`${model.name || model.modelId} does not support --last-frame.`);
+    }
+    if (input.references.length && !model.capabilities.includes("video.generate.fromReferences")) {
+        throw usageError(`${model.name || model.modelId} does not support --reference.`);
+    }
+    const parameters = Array.isArray(model.parameters) ? model.parameters : [];
+    const firstFrameParameter = parameters.find((parameter) => parameter.name === "first_frame");
+    if (firstFrameParameter?.required && !input.firstFrame) {
+        throw usageError(`${model.name || model.modelId} requires --first-frame.`);
+    }
+    validateVideoModelOption(model, parameters, ["duration", "duration_seconds"], input.durationSeconds, "--duration");
+    validateVideoModelOption(model, parameters, ["aspect_ratio", "aspectRatio"], input.aspectRatio, "--aspect-ratio");
+    validateVideoModelOption(model, parameters, ["resolution"], input.resolution, "--resolution");
+    if (input.generateAudio !== undefined && !parameters.some((parameter) => parameter.name === "generate_audio")) {
+        throw usageError(`${model.name || model.modelId} does not support --audio/--no-audio.`);
+    }
+}
+
+function validateVideoModelOption(model, parameters, names, value, flag) {
+    if (value === undefined || value === "") return;
+    const parameter = parameters.find((candidate) => names.includes(candidate.name));
+    if (!parameter) throw usageError(`${model.name || model.modelId} does not support ${flag}.`);
+    if (Array.isArray(parameter.options) && parameter.options.length) {
+        const supported = parameter.options.map((option) => String(option.value));
+        if (!supported.includes(String(value))) {
+            throw usageError(`${model.name || model.modelId} does not support ${flag} ${value}. Supported values: ${supported.join(", ")}.`);
+        }
+        return;
+    }
+    const numeric = Number(value);
+    if (parameter.min !== undefined && numeric < Number(parameter.min)) throw usageError(`${flag} must be at least ${parameter.min} for ${model.name || model.modelId}.`);
+    if (parameter.max !== undefined && numeric > Number(parameter.max)) throw usageError(`${flag} must be at most ${parameter.max} for ${model.name || model.modelId}.`);
+}
+
+function cliWebhookInput(supplied, options, env) {
+    const optionUrl = firstString(options["webhook-url"]);
+    if (options["webhook-url"] !== undefined && !optionUrl) throw usageError("--webhook-url requires a public HTTPS URL.");
+    if (supplied.webhook && optionUrl) throw usageError("Configure webhook in the JSON input or with --webhook-url, not both.");
+    if (supplied.webhook) return supplied.webhook;
+
+    const requestedSecretEnv = firstString(options["webhook-secret-env"]);
+    if (options["webhook-secret-env"] !== undefined && !requestedSecretEnv) throw usageError("--webhook-secret-env requires an environment variable name.");
+    if (!optionUrl && requestedSecretEnv) throw usageError("--webhook-secret-env requires --webhook-url.");
+    if (!optionUrl) return undefined;
+
+    const secretEnv = requestedSecretEnv || (env?.GAVANA_WEBHOOK_SECRET ? "GAVANA_WEBHOOK_SECRET" : env?.CRAFTBOARD_WEBHOOK_SECRET ? "CRAFTBOARD_WEBHOOK_SECRET" : "GAVANA_WEBHOOK_SECRET");
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(secretEnv)) throw usageError("--webhook-secret-env must name a valid environment variable.");
+    const secret = String(env?.[secretEnv] || "");
+    if (secret.length < 32 || secret.length > 512) {
+        throw usageError(`${secretEnv} must contain a webhook secret between 32 and 512 characters.`);
+    }
+    return { url: optionUrl, secret };
+}
+
+async function prepareReferenceInputs(values, runtime) {
+    if (values.length > MAX_REFERENCE_IMAGES) throw usageError(`An image job can use up to ${MAX_REFERENCE_IMAGES} references.`);
+    return Promise.all(values.map((value) => prepareReferenceInput(value, runtime)));
+}
+
+async function prepareReferenceInput(value, runtime) {
+    if (/^(?:node:[A-Za-z0-9_-]{1,180}|asset:(?:[A-Za-z0-9_-]{1,180}:)?[A-Za-z0-9_-]{1,180})$/.test(value)) return { kind: "handle", handle: value };
+
+    let bytes;
+    let fileName;
+    if (value === "clipboard") {
+        const readClipboardImage = runtime.readClipboardImage || readMacClipboardImage;
+        ({ bytes, fileName } = await readClipboardImage());
+    } else if (value === "-") {
+        bytes = await readBinaryStdin();
+        fileName = "stdin-image";
+    } else {
+        const filePath = path.resolve(value);
+        let stat;
+        try {
+            stat = await fs.stat(filePath);
+        } catch {
+            throw usageError(`Reference must be node:<id>, asset:<id>, an image path, -, or clipboard: ${value}`);
+        }
+        if (!stat.isFile()) throw usageError(`Reference image path is not a file: ${value}`);
+        if (stat.size > MAX_REFERENCE_IMAGE_BYTES) throw usageError(`Reference image is too large: ${value}`);
+        bytes = await fs.readFile(filePath);
+        fileName = path.basename(filePath);
+    }
+
+    const imageBytes = Buffer.from(bytes || []);
+    if (!imageBytes.byteLength) throw usageError(`Reference image is empty: ${value}`);
+    if (imageBytes.byteLength > MAX_REFERENCE_IMAGE_BYTES) throw usageError(`Reference image is too large: ${value}`);
+    if (!sniffRasterImageContentType(imageBytes)) throw usageError(`Reference image must be a PNG, JPEG, WebP, or GIF: ${value}`);
+    return { kind: "local", bytes: imageBytes, fileName: cleanUploadFileName(fileName) };
+}
+
+async function prepareVideoReferenceInput(value, runtime) {
+    if (/^https:\/\//i.test(value)) {
+        let url;
+        try {
+            url = new URL(value);
+        } catch {
+            throw usageError(`Video image URL is invalid: ${value}`);
+        }
+        if (url.username || url.password) throw usageError("Video image URLs cannot contain credentials.");
+        return { kind: "url", url: url.toString() };
+    }
+    return prepareReferenceInput(value, runtime);
+}
+
+function ensureUniqueVideoReferences(references) {
+    const keys = references.map((reference) => (reference.kind === "local" ? `local:${crypto.createHash("sha256").update(reference.bytes).digest("base64url")}` : `${reference.kind}:${reference.handle || reference.url}`));
+    if (new Set(keys).size !== keys.length) throw usageError("Video --reference values must be unique.");
+}
+
+async function uploadLocalReferenceInputs(client, references, canvasReference) {
+    const handles = [];
+    const uploads = new Map();
+    for (const reference of references) {
+        if (reference.kind === "handle") {
+            handles.push(reference.handle);
+            continue;
+        }
+        if (reference.kind === "url") {
+            handles.push(reference.url);
+            continue;
+        }
+        const fingerprint = crypto.createHash("sha256").update(reference.bytes).digest("base64url");
+        if (!uploads.has(fingerprint)) uploads.set(fingerprint, client.uploadAsset({ ...reference, canvasReference }));
+        const uploaded = await uploads.get(fingerprint);
+        handles.push(uploaded.asset.handle);
+    }
+    return handles;
+}
+
+async function readMacClipboardImage() {
+    if (process.platform !== "darwin") throw usageError("clipboard references are currently available on macOS. Pass an image path instead.");
+    const script = [
+        "ObjC.import('AppKit');",
+        "ObjC.import('stdlib');",
+        "const pasteboard = $.NSPasteboard.generalPasteboard;",
+        "const types = ['public.png', 'public.jpeg', 'org.webmproject.webp', 'com.compuserve.gif'];",
+        "let data = null; let selectedType = '';",
+        "for (const type of types) { const candidate = pasteboard.dataForType($(type)); if (candidate) { data = candidate; selectedType = type; break; } }",
+        "if (!data) $.exit(2);",
+        "$.puts(ObjC.unwrap(data.base64EncodedStringWithOptions(0)));",
+        "$.puts(selectedType);",
+    ].join("\n");
+    try {
+        const { stdout } = await execFile("osascript", ["-l", "JavaScript", "-e", script], { encoding: "utf8", maxBuffer: Math.ceil(MAX_REFERENCE_IMAGE_BYTES * 1.4) });
+        const [encoded, mediaType] = stdout.trim().split(/\r?\n/);
+        const bytes = Buffer.from(encoded || "", "base64");
+        if (!bytes.byteLength) throw new Error("empty clipboard");
+        const extension = mediaType === "public.jpeg" ? "jpg" : mediaType === "org.webmproject.webp" ? "webp" : mediaType === "com.compuserve.gif" ? "gif" : "png";
+        return { bytes, fileName: `clipboard.${extension}` };
+    } catch {
+        throw usageError("Clipboard does not contain a PNG, JPEG, WebP, or GIF image. Copy an image or pass its file path.");
+    }
+}
+
+function sniffRasterImageContentType(bytes) {
+    if (bytes.length >= 8 && bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) return "image/png";
+    if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return "image/jpeg";
+    if (bytes.length >= 12 && bytes.toString("ascii", 0, 4) === "RIFF" && bytes.toString("ascii", 8, 12) === "WEBP") return "image/webp";
+    if (bytes.length >= 6 && (bytes.toString("ascii", 0, 6) === "GIF87a" || bytes.toString("ascii", 0, 6) === "GIF89a")) return "image/gif";
+    return "";
+}
+
+function cleanUploadFileName(value) {
+    const name = path.basename(String(value || "reference-image"));
+    return name.replace(/[\r\n]/g, " ").slice(0, 160) || "reference-image";
+}
+
+function nodeFromOptions(options) {
+    const metadata = parseJsonOption(options.metadata, "--metadata must be a JSON object.") || {};
+    if (firstString(options.content)) metadata.content = firstString(options.content);
+    if (firstString(options.prompt)) metadata.prompt = firstString(options.prompt);
+    return {
+        type: firstString(options.type) || "text",
+        title: firstString(options.title) || "Agent Node",
+        position: { x: numberOption(options.x, 0), y: numberOption(options.y, 0) },
+        ...(options.width !== undefined ? { width: requiredNumber(options.width, "--width must be a number.") } : {}),
+        ...(options.height !== undefined ? { height: requiredNumber(options.height, "--height must be a number.") } : {}),
+        ...(Object.keys(metadata).length ? { metadata } : {}),
+    };
+}
+
+function nodePatchFromOptions(options) {
+    const patch = {};
+    if (firstString(options.title)) patch.title = firstString(options.title);
+    if (options.x !== undefined || options.y !== undefined) {
+        if (options.x === undefined || options.y === undefined) throw usageError("Pass both --x and --y when updating a node position.");
+        patch.position = { x: requiredNumber(options.x, "--x must be a number."), y: requiredNumber(options.y, "--y must be a number.") };
+    }
+    if (options.width !== undefined) patch.width = requiredNumber(options.width, "--width must be a number.");
+    if (options.height !== undefined) patch.height = requiredNumber(options.height, "--height must be a number.");
+    const metadata = parseJsonOption(options.metadata, "--metadata must be a JSON object.") || {};
+    if (options.content !== undefined) metadata.content = firstString(options.content);
+    if (options.prompt !== undefined) metadata.prompt = firstString(options.prompt);
+    if (Object.keys(metadata).length) patch.metadata = metadata;
+    return patch;
+}
+
+async function optionalJsonInput(options) {
+    const inline = firstString(options.json);
+    const file = firstString(options.file);
+    if (inline && file) throw usageError("Use either --json or --file, not both.");
+    if (inline) return parseJson(inline, "--json contains invalid JSON.");
+    if (file) {
+        const text = file === "-" ? await readAllStdin() : await fs.readFile(path.resolve(file), "utf8");
+        return parseJson(text, `${file} contains invalid JSON.`);
+    }
+    return null;
+}
+
+function parseArguments(argv) {
+    const positionals = [];
+    const options = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === "-r") {
+            options.raw = true;
+            continue;
+        }
+        if (argument === "-h") {
+            options.help = true;
+            continue;
+        }
+        if (argument === "-v" || argument === "-V") {
+            options.version = true;
+            continue;
+        }
+        if (argument === "--") {
+            positionals.push(...argv.slice(index + 1));
+            break;
+        }
+        if (!argument.startsWith("--")) {
+            positionals.push(argument);
+            continue;
+        }
+        const equalsAt = argument.indexOf("=");
+        const key = argument.slice(2, equalsAt >= 0 ? equalsAt : undefined);
+        let value;
+        if (equalsAt >= 0) {
+            value = argument.slice(equalsAt + 1);
+        } else if (BOOLEAN_OPTIONS.has(key)) {
+            value = true;
+        } else if (argv[index + 1] !== undefined && !argv[index + 1].startsWith("--")) {
+            value = argv[index + 1];
+            index += 1;
+        } else {
+            value = true;
+        }
+        if (REPEATABLE_OPTIONS.has(key)) {
+            options[key] = [...(Array.isArray(options[key]) ? options[key] : options[key] === undefined ? [] : [options[key]]), value];
+        } else {
+            options[key] = value;
+        }
+    }
+    return { positionals, options };
+}
+
+function writeResult(stdout, result, options) {
+    const output = firstString(options.output) || "json";
+    const jq = firstString(options.jq);
+    const selected = jq ? selectJsonPath(result, jq) : result;
+    const raw = options.raw === true || output === "raw";
+
+    if (output === "markdown") {
+        stdout.write(`${markdownForResult(selected)}\n`);
+        return;
+    }
+    if (output === "human") {
+        stdout.write(`${humanOutput(selected)}\n`);
+        return;
+    }
+    if (raw) {
+        if (Array.isArray(selected) && selected.length === 0) return;
+        stdout.write(`${rawOutput(selected)}\n`);
+        return;
+    }
+    if (output === "jsonl") {
+        const rows = Array.isArray(selected) ? selected : [selected];
+        if (!rows.length) return;
+        stdout.write(`${rows.map((row) => JSON.stringify(row)).join("\n")}\n`);
+        return;
+    }
+    const payload = jq ? selected : { ok: true, result };
+    stdout.write(`${JSON.stringify(payload, null, options.pretty === true ? 2 : 0)}\n`);
+}
+
+export function selectJsonPath(value, expression) {
+    const query = validateJsonPathExpression(expression);
+    if (query === ".") return value;
+
+    const tokens = parseJsonPathTokens(query);
+    let values = [value];
+    let projected = false;
+    for (const token of tokens) {
+        if (token.type === "property") {
+            values = values.map((item) => (item !== null && typeof item === "object" ? item[token.name] : undefined));
+            continue;
+        }
+        if (token.type === "index") {
+            values = values.map((item) => (Array.isArray(item) ? item[token.index] : undefined));
+            continue;
+        }
+        projected = true;
+        values = values.flatMap((item) => (Array.isArray(item) ? item : []));
+    }
+    const normalized = values.map((item) => (item === undefined ? null : item));
+    return projected ? normalized : normalized[0];
+}
+
+function validateOutputOptions(options) {
+    if (options.output !== undefined && !firstString(options.output)) throw usageError("--output requires human, json, jsonl, markdown, or raw.");
+    if (options.jq !== undefined && !firstString(options.jq)) throw usageError("--jq requires a path such as .canvases[].handle.");
+    const output = firstString(options.output) || "json";
+    if (!["human", "json", "jsonl", "markdown", "raw"].includes(output)) throw usageError("--output must be human, json, jsonl, markdown, or raw.");
+    if (options.raw === true && output !== "json" && output !== "raw") throw usageError("-r/--raw cannot be combined with --output human, jsonl, or markdown.");
+    const jq = firstString(options.jq);
+    if (jq) validateJsonPathExpression(jq);
+}
+
+function validateJsonPathExpression(expression) {
+    const query = String(expression || "").trim();
+    if (!query.startsWith(".") || query.length > 500) throw usageError("--jq must be a jq-style path such as .canvases[].handle.");
+    if (query !== ".") parseJsonPathTokens(query);
+    return query;
+}
+
+function parseJsonPathTokens(query) {
+    const tokens = [];
+    let index = 1;
+    while (index < query.length) {
+        if (query[index] === ".") {
+            index += 1;
+            if (index >= query.length) throw usageError("--jq path cannot end with a dot.");
+        }
+        if (query[index] === "[") {
+            const close = query.indexOf("]", index);
+            if (close < 0) throw usageError("--jq contains an unterminated array selector.");
+            const selector = query.slice(index + 1, close);
+            if (!selector) tokens.push({ type: "projection" });
+            else if (/^(?:0|[1-9]\d*)$/u.test(selector)) tokens.push({ type: "index", index: Number(selector) });
+            else throw usageError("--jq supports [] and non-negative array indexes only.");
+            index = close + 1;
+            continue;
+        }
+        const match = query.slice(index).match(/^[A-Za-z_][A-Za-z0-9_-]*/u);
+        if (!match) throw usageError("--jq supports property paths, array indexes, and [] projections only.");
+        const name = match[0];
+        if (name === "__proto__" || name === "prototype" || name === "constructor") throw usageError("--jq property is not allowed.");
+        tokens.push({ type: "property", name });
+        index += name.length;
+        if (index < query.length && query[index] !== "." && query[index] !== "[") throw usageError("--jq path is invalid.");
+    }
+    return tokens;
+}
+
+function rawOutput(value) {
+    const values = Array.isArray(value) ? value : [value];
+    return values
+        .map((item) => {
+            if (item === null) return "null";
+            if (typeof item === "string") return item;
+            if (typeof item === "number" || typeof item === "boolean") return String(item);
+            return JSON.stringify(item);
+        })
+        .join("\n");
+}
+
+function humanOutput(value, indent = "") {
+    if (value === null || value === undefined) return `${value}`;
+    if (typeof value !== "object") return String(value);
+    if (Array.isArray(value)) return value.map((item, index) => `${indent}${index + 1}. ${typeof item === "object" ? `\n${humanOutput(item, `${indent}   `)}` : String(item)}`).join("\n");
+    return Object.entries(value)
+        .map(([key, item]) => {
+            const label = key.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/_/g, " ");
+            if (item && typeof item === "object") return `${indent}${label}:\n${humanOutput(item, `${indent}  `)}`;
+            return `${indent}${label}: ${item ?? ""}`;
+        })
+        .join("\n");
+}
+
+function normalizeCliError(error) {
+    if (error instanceof CanvasAgentApiError) {
+        return {
+            code: error.code || "request_failed",
+            message: error.message,
+            ...(error.status ? { status: error.status } : {}),
+            ...(error.fields ? { fields: error.fields } : {}),
+            ...(error.details ? { details: error.details } : {}),
+            ...(error.requestId ? { requestId: error.requestId } : {}),
+        };
+    }
+    if (error?.code === "usage") return { code: "usage", message: error instanceof Error ? error.message : "The Gavana command is invalid." };
+    if (error?.code === "ENOENT") return { code: "not_found", message: error.message };
+    return { code: "internal", message: error instanceof Error ? error.message : "Gavana CLI failed." };
+}
+
+function exitCodeForError(error) {
+    if (
+        error.code === "usage" ||
+        error.code === "configuration" ||
+        error.code === "validation" ||
+        error.code === "input_validation_error" ||
+        error.code === "invalid_json" ||
+        error.status === 400 ||
+        error.status === 413 ||
+        error.status === 415 ||
+        error.status === 422
+    )
+        return 2;
+    if (error.code === "unauthorized" || error.code === "forbidden" || error.status === 401 || error.status === 403) return 3;
+    if (error.code === "conflict" || error.status === 409) return 4;
+    if (error.code === "not_found" || error.status === 404) return 5;
+    if (error.code === "network") return 7;
+    if (error.code === "timeout") return 8;
+    return 1;
+}
+
+function requiredArg(args, index, message) {
+    const value = args[index];
+    if (!value) throw usageError(message);
+    return value;
+}
+
+function requireConfirmation(options, message) {
+    if (options.yes !== true) throw usageError(message);
+}
+
+function parseJsonOption(value, message) {
+    const text = firstString(value);
+    return text ? parseJson(text, message) : null;
+}
+
+function parseJson(value, message) {
+    try {
+        return JSON.parse(value);
+    } catch {
+        throw usageError(message);
+    }
+}
+
+function firstString(value) {
+    if (Array.isArray(value)) return value.length ? String(value[value.length - 1]) : "";
+    return typeof value === "string" ? value : "";
+}
+
+function repeatableStrings(value) {
+    if (value === undefined) return [];
+    return (Array.isArray(value) ? value : [value])
+        .map(String)
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
+
+function requiredNumber(value, message) {
+    const number = Number(Array.isArray(value) ? value[value.length - 1] : value);
+    if (!Number.isFinite(number)) throw usageError(message);
+    return number;
+}
+
+function numberOption(value, fallback) {
+    return value === undefined ? fallback : requiredNumber(value, "Expected a number.");
+}
+
+function paginationOptions(options, maximum) {
+    const message = `--limit must be an integer from 1 through ${maximum}.`;
+    if (options.limit !== undefined && typeof options.limit !== "string") throw usageError(message);
+    const limit = options.limit === undefined ? undefined : requiredNumber(options.limit, message);
+    if (limit !== undefined && (!Number.isInteger(limit) || limit < 1 || limit > maximum)) throw usageError(message);
+    if (options.cursor !== undefined && !firstString(options.cursor)) throw usageError("--cursor requires page.nextCursor from the previous response.");
+    const cursor = firstString(options.cursor).trim();
+    if (cursor.length > 8_192) throw usageError("--cursor is invalid.");
+    return {
+        ...(limit !== undefined ? { limit } : {}),
+        ...(cursor ? { cursor } : {}),
+    };
+}
+
+function secondsOption(value, fallback, allowZero = false) {
+    if (value === undefined) return fallback;
+    const seconds = requiredNumber(value, "Expected seconds as a number.");
+    if (seconds < (allowZero ? 0 : 0.05)) throw usageError("Seconds must be positive.");
+    return seconds;
+}
+
+function usageError(message) {
+    return new CanvasAgentApiError(message, { code: "usage" });
+}
+
+function maskToken(token) {
+    const value = String(token || "");
+    return value.length > 12 ? `${value.slice(0, 7)}…${value.slice(-4)}` : "configured";
+}
+
+async function readAllStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf8");
+}
+
+async function readBinaryStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks);
+}
+
+function helpText(group, action) {
+    const commandHelp = commandHelpText(group, action);
+    if (commandHelp) return commandHelp;
+    return `Gavana Canvas CLI — JSON-first agent control
+
+Usage:
+${gavanaCommandUsageLines()
+    .map((line) => `  ${line}`)
+    .join("\n")}
+
+Global options:
+  --output FORMAT          human, json, jsonl, markdown, or raw; JSON is the default
+  --pretty                 Pretty-print JSON
+  --jq PATH                Select a jq-style path, for example .canvases[].handle
+  -r, --raw                Print selected strings and numbers without JSON quotes
+  --limit N                Maximum list items to return
+  --cursor VALUE           Continue a list from page.nextCursor
+  --base-url URL           Overrides saved configuration
+  --profile NAME           Use one named account/environment profile
+  --token-stdin            Read a login token from stdin
+  --base-revision VALUE    Enforce a previously read canvas revision
+  --idempotency-key VALUE  Make retries deterministic
+  --destination VALUE      agent-canvas, new-canvas, or an existing canvas handle
+  --model VALUE            Provider model id or model: handle from model list
+  --connection VALUE       Disambiguate a provider model id by connection
+  --reference VALUE        Image reference; repeat for multiple visuals
+  --reference-role ROLE    Optional role for the matching --reference: identity, construction, texture, fit, or style
+  --input VALUE            Recipe KEY=VALUE or Action input; repeat as needed
+  --param NAME=VALUE       Action parameter; repeat for multiple parameters
+  --webhook-url URL        Send one signed callback when a Run finishes
+  --webhook-secret-env VAR Read the signing secret from VAR (default: GAVANA_WEBHOOK_SECRET)
+  --canvas-title VALUE     Title used when --destination is new-canvas
+  --no-wait                Return immediately after queueing Recipe, image, video, or Action work
+  --progress               Write Run or video Job state transitions to stderr
+
+Video options:
+  --prompt VALUE           Video instruction (required)
+  --duration SECONDS       Exact model-supported duration from 1 through 120
+  --aspect-ratio VALUE     Exact model-supported aspect ratio
+  --resolution VALUE       Exact model-supported resolution
+  --first-frame VALUE      node:, asset:, public HTTPS URL, local image, -, or clipboard
+  --last-frame VALUE       Ending frame; requires --first-frame
+  --reference VALUE        Model reference image; repeat up to nine times
+  --canvas VALUE           Canvas containing any node: frame or reference
+  --audio | --no-audio    Request or disable generated audio when supported
+  --download VALUE        Stream a successful generated video to this file
+
+Image --reference values, Action inputs, and Recipe Image ports accept node:<id>,
+asset:<id>, shared asset:<ownerUid>:<id>, a local PNG/JPEG/WebP/GIF path, -, or
+clipboard (macOS). Local visuals upload privately before the Run. Recipe written
+ports treat @path as text; upload a visual first and pass its asset: handle when
+that written port explicitly accepts an image reference. For image generation,
+repeat --reference-role in the same order as --reference to preserve each
+visual's identity, construction, texture, fit, or style role.
+Image and Action commands create target nodes automatically when --target is omitted.
+
+For history-safe token entry in zsh (macOS):
+  read -rs 'GAVANA_AGENT_TOKEN?Paste Agent Access token: '; printf '\\n'; printf '%s' "$GAVANA_AGENT_TOKEN" | gavana auth login --base-url URL --token-stdin; unset GAVANA_AGENT_TOKEN
+
+Compatibility: craftboard commands and CRAFTBOARD_* environment variables remain supported.`;
+}
+
+// The page every group without its own prose closes with.
+const GROUP_HELP_COMMON_OPTIONS = "Common options:\n  --profile NAME   Select a saved profile\n  --output FORMAT  human, json, jsonl, markdown, or raw\n  --help           Show command-specific help";
+
+/**
+ * One group's help page, generated from the command table.
+ *
+ * This used to be a second hand-maintained catalog covering twelve groups, with
+ * five more written out longhand in helpText. The two catalogs had drifted in both
+ * directions. The group pages were behind on `asset list --cursor`,
+ * `asset:<ownerUid>`, and every worked example. The root list was behind on
+ * `--yes` for `canvas apply` and `video download`, and on `--progress` for `job
+ * wait` and `run wait` — all four real flags that only the group pages mentioned.
+ * Generating from one table means a command declared once is documented
+ * everywhere, including on the pages nobody remembered to update.
+ */
+function commandHelpText(group, action) {
+    if (!group || !gavanaCommandGroups({ includeHidden: true }).includes(group)) return "";
+    const page = GAVANA_CLI_GROUP_HELP[group];
+    // A group with no sub-command and no prose of its own gets no page: `gavana
+    // version --help` and `gavana doctor --help` answer with the full manual,
+    // because a page repeating their single root usage line would say less than
+    // the root help they replaced.
+    if (!page && !gavanaCommandActions(group, { includeHidden: true }).length) return "";
+    const selected = gavanaCommandGroupUsageLines(group, action);
+    if (!selected.length) {
+        // A group whose every command is hidden has no page at all, and falling
+        // through to the root help is the honest answer. An unknown action inside a
+        // real group is a mistake worth naming.
+        if (!gavanaCommandGroupUsageLines(group).length) return "";
+        return `Unknown ${group} action: ${action}.\n\n${commandHelpText(group)}`;
+    }
+    const title = page?.title || `Gavana ${group} commands`;
+    const footer = page ? page.note : GROUP_HELP_COMMON_OPTIONS;
+    const usage = `${title}\n\nUsage:\n${selected.map((line) => `  ${line}`).join("\n")}`;
+    return footer ? `${usage}\n\n${footer}` : usage;
+}