orizu 0.3.7 → 0.4.1

package/dist/index.js

@@ -17,9 +17,13 @@ import { extractErrorMessage } from './error-response.js';
 import { parseGlobalFlags } from './global-flags.js';
 import { getCapabilities, renderHelpForArgs, renderRootHelp } from './help.js';
 import { runLocalAppPreview } from './preview-runtime.js';
+import { parseAssignmentManifestJsonl } from './task-assignment-manifest.js';
 import { assertSecureTokenTransport, authedFetch, getBaseUrl, resolveLoginBaseUrl, setGlobalFlags, } from './http.js';
-import { getSkillInstallPath, installSkillTarget, isSkillInstallTarget, SKILL_INSTALL_TARGETS, targetNeedsOverwrite, } from './skill-installer.js';
+import { computeSkillContentHash, getSkillInstallPath, getSkillTargetStatus, getTargetForAgent, installSkillTarget, isSkillInstallAgent, isSkillInstallTarget, resolveSkillSource, SKILL_INSTALL_AGENTS, SKILL_INSTALL_TARGETS, targetNeedsOverwrite, } from './skill-installer.js';
+import { renderBanner } from './banner.js';
 import { formatTaskCreateError } from './task-create-error.js';
+import { renderAgentSetupPrompt } from './setup-prompt.js';
+import { getWorkspaceRoot, initOrizuWorkspace, WORKSPACE_DIR_NAME, workspaceExists, } from './workspace.js';
 const MAX_README_LENGTH = 200_000;
 function getCliVersion() {
     const packageJson = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
@@ -34,14 +38,22 @@ function printLine(message = '') {
 function printVersion() {
     printLine(`orizu ${getCliVersion()}`);
 }
+function printBannerIfInteractive() {
+    if (!process.stdout.isTTY) {
+        return;
+    }
+    printLine(renderBanner());
+    printLine('');
+}
 function printUsage() {
+    printBannerIfInteractive();
     printLine(renderRootHelp());
 }
 function printPreviewUsage() {
     printLine(`\nLocal app preview:\n\n  orizu apps preview --file <path> --input-schema <json-path> --output-schema <json-path> --sample-row <json-path> [--screenshot <png-path>] [--headed] [--keep-open] [--component <name>]`);
 }
 function printOptimizationUsage() {
-    printLine(`\nOptimization lifecycle commands:\n\n  orizu optimizations start --project <team/project> --optimizer-version <id> --prompt-version <id[,id]> --selection-scorer <id> [--reflection-scorer <id>] [--pareto-scorer <id>] [--best-scorer <id>] --dataset-version <id> --split-set <id> [--train-split <name>] [--validation-split <name>] [--metadata <json|@file>] [--json]\n  orizu optimizations run-gepa --project <team/project> --optimizer-version-id <id> --candidate-version-id <id> --runner-version-id <id> --candidate-runner-dir <dir> --scorer-version-id <id> --scorer-runner-version-id <id> --scorer-runner-dir <dir> --dataset-version-id <id> --split-set-id <id> [--train-split train] [--val-split validation] [--num-threads auto|N] [--log-dir logs] [--no-skip-perfect-parent-reflection]\n  orizu optimizations export <run-id> [--out <path>] [--json]\n  orizu optimizations pause <run-id> [--reason <text>] [--json]\n  orizu optimizations resume <run-id> [--json]\n  orizu optimizations finish <run-id> [--best-score <n>] [--best-candidate <id>] [--result-prompt-version <id>] [--report <markdown|@file> | --report-file <path>] [--metadata <json|@file>] [--json]\n  orizu optimizations fail <run-id> [--reason <text>] [--report <markdown|@file> | --report-file <path>] [--metadata <json|@file>] [--json]\n  orizu optimizations cancel <run-id> [--reason <text>] [--report <markdown|@file> | --report-file <path>] [--json]`);
+    printLine(`\nOptimization lifecycle commands:\n\n  orizu optimizations start --project <team/project> --optimizer-version <id> --prompt-version <id[,id]> --selection-scorer <id> [--reflection-scorer <id>] [--pareto-scorer <id>] [--best-scorer <id>] --dataset-version <id> --split-set <id> [--train-split <name>] [--validation-split <name>] [--metadata <json|@file>] [--json]\n  orizu optimizations run-gepa --project <team/project> --optimizer-version-id <id> --candidate-version-id <id> --runner-version-id <id> --candidate-runner-dir <dir> --scorer-version-id <id> --scorer-runner-version-id <id> --scorer-runner-dir <dir> --dataset-version-id <id> --split-set-id <id> [--train-split train] [--val-split validation] [--budget auto|light|medium|heavy | --max-metric-calls <n> | --max-full-evals <n> | --max-iterations <n>] [--num-threads auto|N] [--reflection-retry-attempts N] [--reflection-http-timeout-seconds N] [--log-dir logs] [--no-skip-perfect-parent-reflection]\n  orizu optimizations export <run-id> [--out <path>] [--json]\n  orizu optimizations pause <run-id> [--reason <text>] [--json]\n  orizu optimizations resume <run-id> [--json]\n  orizu optimizations finish <run-id> [--best-score <n>] [--best-candidate <id>] [--result-prompt-version <id>] [--report <markdown|@file> | --report-file <path>] [--metadata <json|@file>] [--json]\n  orizu optimizations fail <run-id> [--reason <text>] [--report <markdown|@file> | --report-file <path>] [--metadata <json|@file>] [--json]\n  orizu optimizations cancel <run-id> [--reason <text>] [--report <markdown|@file> | --report-file <path>] [--json]`);
 }
 let cliArgs = process.argv.slice(2);
 let cliJsonOutput = false;
@@ -204,14 +216,16 @@ function printPromptSummaries(items, emptyMessage) {
         id: sanitizeTerminalText(item.id),
         name: sanitizeTerminalText(item.name),
         role: sanitizeTerminalText(item.role),
+        status: sanitizeTerminalText(item.status || 'active'),
     }));
     const idWidth = Math.max('ID'.length, ...rows.map(row => row.id.length));
     const nameWidth = Math.max('NAME'.length, ...rows.map(row => row.name.length));
     const roleWidth = Math.max('ROLE'.length, ...rows.map(row => row.role.length));
-    printLine(`${'ID'.padEnd(idWidth)}  ${'NAME'.padEnd(nameWidth)}  ${'ROLE'.padEnd(roleWidth)}`);
-    printLine(`${'-'.repeat(idWidth)}  ${'-'.repeat(nameWidth)}  ${'-'.repeat(roleWidth)}`);
+    const statusWidth = Math.max('STATUS'.length, ...rows.map(row => row.status.length));
+    printLine(`${'ID'.padEnd(idWidth)}  ${'NAME'.padEnd(nameWidth)}  ${'ROLE'.padEnd(roleWidth)}  ${'STATUS'.padEnd(statusWidth)}`);
+    printLine(`${'-'.repeat(idWidth)}  ${'-'.repeat(nameWidth)}  ${'-'.repeat(roleWidth)}  ${'-'.repeat(statusWidth)}`);
     rows.forEach(row => {
-        printLine(`${row.id.padEnd(idWidth)}  ${row.name.padEnd(nameWidth)}  ${row.role.padEnd(roleWidth)}`);
+        printLine(`${row.id.padEnd(idWidth)}  ${row.name.padEnd(nameWidth)}  ${row.role.padEnd(roleWidth)}  ${row.status.padEnd(statusWidth)}`);
     });
 }
 function printScorerSummaries(items) {
@@ -703,6 +717,10 @@ async function login() {
     const baseUrl = hasArg('--no-prompt-if-logged-in') ? getBaseUrl() : resolveLoginBaseUrl();
     assertSecureTokenTransport(baseUrl);
     if (hasArg('--no-prompt-if-logged-in') && getServerCredentials(baseUrl)) {
+        if (hasJsonFlag()) {
+            printJson({ status: 'already-logged-in', server: baseUrl });
+            return;
+        }
         printLine(`Already logged in to ${sanitizeTerminalText(baseUrl)}.`);
         return;
     }
@@ -781,6 +799,14 @@ async function login() {
         credentialType: 'pat',
         apiKey: loginData.apiKey,
     });
+    if (hasJsonFlag()) {
+        printJson({
+            status: 'logged-in',
+            server: baseUrl,
+            user: { id: loginData.user.id, email: loginData.user.email ?? null },
+        });
+        return;
+    }
     printLine(`Logged in as ${sanitizeTerminalText(loginData.user.email ?? loginData.user.id)}`);
 }
 async function whoami() {
@@ -789,12 +815,20 @@ async function whoami() {
         throw new Error(`whoami failed: ${await response.text()}`);
     }
     const data = await response.json();
+    if (hasJsonFlag()) {
+        printJson({ user: data.user, server: getBaseUrl() });
+        return;
+    }
     printLine(sanitizeTerminalText(data.user.email ?? data.user.id));
 }
 async function logout() {
     const baseUrl = getBaseUrl();
     const credentials = getServerCredentials(baseUrl);
     if (!credentials) {
+        if (hasJsonFlag()) {
+            printJson({ status: 'already-logged-out', server: baseUrl });
+            return;
+        }
         printLine(`Already logged out for ${sanitizeTerminalText(baseUrl)}.`);
         return;
     }
@@ -820,6 +854,10 @@ async function logout() {
         remoteLogoutError = sanitizeTerminalText(message).slice(0, 180);
     }
     clearServerCredentials(baseUrl);
+    if (hasJsonFlag()) {
+        printJson({ status: 'logged-out', server: baseUrl, remoteLogoutError });
+        return;
+    }
     if (remoteLogoutError) {
         console.warn(`Warning: remote logout failed: ${remoteLogoutError}`);
     }
@@ -832,6 +870,15 @@ async function printEnv() {
     const project = projectArg ? await resolveProjectSelection(projectArg) : null;
     const projectId = project?.id || getArg('--project-id') || process.env.ORIZU_PROJECT_ID || '';
     const projectSlug = project ? `${project.teamSlug}/${project.slug}` : process.env.ORIZU_PROJECT || '';
+    if (hasJsonFlag()) {
+        printJson({
+            ORIZU_API_URL: baseUrl,
+            ORIZU_TOKEN: token,
+            ORIZU_PROJECT_ID: projectId,
+            ...(projectSlug ? { ORIZU_PROJECT: projectSlug } : {}),
+        });
+        return;
+    }
     printLine(`export ORIZU_API_URL=${shellQuote(baseUrl)}`);
     printLine(`export ORIZU_TOKEN=${shellQuote(token)}`);
     printLine(`export ORIZU_PROJECT_ID=${shellQuote(projectId)}`);
@@ -868,24 +915,46 @@ async function logOptimizationEvent() {
         throw new Error(`Failed to log event: ${await response.text()}`);
     }
     const data = await parseJsonResponse(response, 'Optimization event log');
+    if (hasJsonFlag()) {
+        printJson({ eventId: data.eventId });
+        return;
+    }
     printLine(`Logged event ${sanitizeTerminalText(data.eventId)}`);
 }
 async function listPrompts() {
     const project = getArg('--project') || await resolveProjectSlug(null);
-    const response = await authedFetch(`/api/cli/prompts?project=${encodeURIComponent(project)}`);
+    const status = getArg('--status') || 'active';
+    if (!['active', 'archived', 'all'].includes(status)) {
+        throw new Error('Usage: orizu prompts list --project <team/project> [--status active|archived|all]');
+    }
+    const params = new URLSearchParams({ project, status });
+    const response = await authedFetch(`/api/cli/prompts?${params.toString()}`);
     if (!response.ok) {
         throw new Error(`Failed to fetch prompts: ${await response.text()}`);
     }
     const data = await parseJsonResponse(response, 'Prompts list');
+    if (hasJsonFlag()) {
+        printJson(data);
+        return;
+    }
     printPromptSummaries(data.prompts, 'No prompts found.');
 }
 async function listJudges() {
     const project = getArg('--project') || await resolveProjectSlug(null);
-    const response = await authedFetch(`/api/cli/judges?project=${encodeURIComponent(project)}`);
+    const status = getArg('--status') || 'active';
+    if (!['active', 'archived', 'all'].includes(status)) {
+        throw new Error('Usage: orizu judges list --project <team/project> [--status active|archived|all]');
+    }
+    const params = new URLSearchParams({ project, status });
+    const response = await authedFetch(`/api/cli/judges?${params.toString()}`);
     if (!response.ok) {
         throw new Error(`Failed to fetch judges: ${await response.text()}`);
     }
     const data = await parseJsonResponse(response, 'Judges list');
+    if (hasJsonFlag()) {
+        printJson(data);
+        return;
+    }
     printPromptSummaries(data.judges, 'No judges found.');
 }
 async function listPromptComments() {
@@ -922,6 +991,10 @@ async function listScorers() {
         throw new Error(`Failed to fetch scorers: ${await response.text()}`);
     }
     const data = await parseJsonResponse(response, 'Scorers list');
+    if (hasJsonFlag()) {
+        printJson(data);
+        return;
+    }
     printScorerSummaries(data.scorers);
 }
 async function registerScorer() {
@@ -1203,6 +1276,28 @@ async function setPromptLabel() {
     }
     printLine(`Moved ${sanitizeTerminalText(label)} to ${sanitizeTerminalText(promptVersionId)}`);
 }
+async function setPromptArchivedState(archived) {
+    const promptRef = getPositionalArg(2);
+    const project = getArg('--project') || await resolveProjectSlug(null);
+    const command = archived ? 'archive' : 'restore';
+    if (!promptRef) {
+        throw new Error(`Usage: orizu prompts ${command} <prompt-id-or-name> --project <team/project> [--json]`);
+    }
+    const response = await authedFetch(`/api/cli/prompts/${encodeURIComponent(promptRef)}?project=${encodeURIComponent(project)}`, {
+        method: 'PATCH',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ archived }),
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to ${command} prompt: ${await response.text()}`);
+    }
+    const data = await parseJsonResponse(response, `Prompt ${command}`);
+    if (hasJsonFlag()) {
+        printJson(data);
+        return;
+    }
+    printLine(`${archived ? 'Archived' : 'Restored'} prompt ${sanitizeTerminalText(data.prompt.name)} (${sanitizeTerminalText(data.prompt.id)})`);
+}
 async function bindPromptScorer(role) {
     const promptId = getPositionalArg(3);
     const project = getArg('--project') || await resolveProjectSlug(null);
@@ -1400,6 +1495,10 @@ async function submitRunResults() {
         throw new Error(`Failed to submit run: ${await response.text()}`);
     }
     const data = await parseJsonResponse(response, 'Run submit');
+    if (hasJsonFlag()) {
+        printJson({ run: data.run });
+        return;
+    }
     printLine(`Submitted run ${sanitizeTerminalText(data.run.id)} ` +
         `(${formatPercent(data.run.aggregateScore)}) -> ` +
         sanitizeTerminalText(data.run.perRowResultsStoragePath));
@@ -1857,9 +1956,17 @@ async function runGepaOptimization() {
     if (result.status !== 0) {
         throw new Error(`orizu-gepa failed with exit code ${result.status}`);
     }
+    if (hasJsonFlag()) {
+        printJson({ status: 'completed', exitCode: 0 });
+    }
 }
 async function listTeams() {
-    printTeams(await fetchTeams());
+    const teams = await fetchTeams();
+    if (hasJsonFlag()) {
+        printJson({ teams });
+        return;
+    }
+    printTeams(teams);
 }
 async function resolveTeamSlug(teamSlugArg) {
     if (teamSlugArg) {
@@ -1891,12 +1998,21 @@ async function createTeam() {
         throw new Error(`Failed to create team: ${await response.text()}`);
     }
     const data = await parseJsonResponse(response, 'Team create');
+    if (hasJsonFlag()) {
+        printJson({ team: data.team });
+        return;
+    }
     printLine(`Created team: ${sanitizeTerminalText(data.team.name)} (${sanitizeTerminalText(data.team.slug)})`);
 }
 async function listProjects() {
     const teamSlugArg = getArg('--team');
     const teamSlug = teamSlugArg ? normalizeSlugInput(teamSlugArg) : null;
-    printProjects(await fetchProjects(teamSlug || undefined));
+    const projects = await fetchProjects(teamSlug || undefined);
+    if (hasJsonFlag()) {
+        printJson({ projects });
+        return;
+    }
+    printProjects(projects);
 }
 async function createProject() {
     const name = getArg('--name');
@@ -1918,15 +2034,29 @@ async function createProject() {
         throw new Error(`Failed to create project: ${await response.text()}`);
     }
     const data = await parseJsonResponse(response, 'Project create');
+    if (hasJsonFlag()) {
+        printJson({ project: data.project });
+        return;
+    }
     printLine(`Created project ${sanitizeTerminalText(`${data.project.teamSlug}/${data.project.slug}`)}`);
 }
 async function listTasks() {
     const project = getArg('--project');
-    printTasks(await fetchTasks(project || undefined));
+    const tasks = await fetchTasks(project || undefined);
+    if (hasJsonFlag()) {
+        printJson({ tasks });
+        return;
+    }
+    printTasks(tasks);
 }
 async function listApps() {
     const project = getArg('--project') || await resolveProjectSlug(null);
-    printApps(await fetchApps(project));
+    const apps = await fetchApps(project);
+    if (hasJsonFlag()) {
+        printJson({ apps });
+        return;
+    }
+    printApps(apps);
 }
 function readSourceFile(pathArg) {
     const expandedPath = expandHomePath(pathArg);
@@ -1986,24 +2116,82 @@ async function askYesNo(question, defaultYes) {
         rl.close();
     }
 }
-async function promptSkillInstallTargets() {
+const SKILL_INSTALL_USAGE = `Usage: orizu install-skill [--agent <${SKILL_INSTALL_AGENTS.join('|')}>]... [--scope global|project] [--mode auto|link|copy] [--target <${SKILL_INSTALL_TARGETS.join('|')}>]... [--yes] [--dry-run]`;
+function describeSkillTarget(target) {
+    if (target === 'claude-user')
+        return 'Claude Code, for you across all projects';
+    if (target === 'claude-project')
+        return 'Claude Code, only for this project';
+    if (target === 'agent-user')
+        return 'Codex / Open Agent Skills, for you across all projects';
+    if (target === 'agents-project')
+        return 'Codex / Open Agent Skills, only for this project';
+    if (target === 'codex-project')
+        return 'Codex legacy project folder (.codex/skills)';
+    return 'Project instructions, managed Orizu section in AGENTS.md';
+}
+async function promptSkillInstallTargets(scope) {
     if (!isInteractiveTerminal()) {
-        throw new Error(`Usage: orizu install-skill --target <${SKILL_INSTALL_TARGETS.join('|')}> [--yes] [--dry-run]`);
+        throw new Error(SKILL_INSTALL_USAGE);
     }
-    printLine('Where should the Orizu CLI skill be installed?');
+    const choices = [
+        { label: describeSkillTarget(getTargetForAgent('claude', scope)), target: getTargetForAgent('claude', scope), defaultYes: true },
+        { label: describeSkillTarget(getTargetForAgent('codex', scope)), target: getTargetForAgent('codex', scope), defaultYes: true },
+        { label: describeSkillTarget('agents-md'), target: 'agents-md', defaultYes: false },
+    ];
+    printLine('Where should Orizu be available?');
     const targets = [];
-    for (const target of SKILL_INSTALL_TARGETS) {
-        const defaultYes = target === 'agent-user';
-        if (await askYesNo(`  Install to ${target}?`, defaultYes)) {
-            targets.push(target);
+    for (const choice of choices) {
+        const installPath = getSkillInstallPath(choice.target);
+        if (await askYesNo(`  ${choice.label}\n    ${installPath}?`, choice.defaultYes)) {
+            targets.push(choice.target);
+        }
+    }
+    if (await askYesNo('  Show advanced targets?', false)) {
+        for (const target of SKILL_INSTALL_TARGETS) {
+            if (targets.includes(target)) {
+                continue;
+            }
+            const installPath = getSkillInstallPath(target);
+            if (await askYesNo(`  ${describeSkillTarget(target)} [${target}]\n    ${installPath}?`, false)) {
+                targets.push(target);
+            }
         }
     }
     return targets;
 }
-function parseSkillInstallTargets() {
-    const rawTargets = getArgs('--target');
+function parseSkillInstallScope() {
+    const raw = getArg('--scope');
+    if (raw === null || raw === 'global') {
+        return 'global';
+    }
+    if (raw === 'project') {
+        return 'local';
+    }
+    throw new Error(`Unknown --scope '${raw}'. Choices: global, project.`);
+}
+function parseSkillInstallMode() {
+    const raw = getArg('--mode');
+    if (raw === null) {
+        return 'auto';
+    }
+    if (raw !== 'auto' && raw !== 'link' && raw !== 'copy') {
+        throw new Error(`Unknown --mode '${raw}'. Choices: auto, link, copy.`);
+    }
+    return raw;
+}
+function parseSkillInstallTargets(scope) {
     const targets = [];
-    for (const target of rawTargets) {
+    for (const agent of getArgs('--agent')) {
+        if (!isSkillInstallAgent(agent)) {
+            throw new Error(`Unknown agent '${agent}'. Available agents: ${SKILL_INSTALL_AGENTS.join(', ')}`);
+        }
+        const target = getTargetForAgent(agent, scope);
+        if (!targets.includes(target)) {
+            targets.push(target);
+        }
+    }
+    for (const target of getArgs('--target')) {
         if (!isSkillInstallTarget(target)) {
             throw new Error(`Unknown skill install target '${target}'. Available targets: ${SKILL_INSTALL_TARGETS.join(', ')}`);
         }
@@ -2022,36 +2210,412 @@ function formatSkillInstallAction(action) {
         return 'Would write';
     return 'Would update';
 }
-async function installSkillCommand() {
-    const skipConfirm = hasArg('--yes');
-    const dryRun = hasArg('--dry-run');
-    let targets = parseSkillInstallTargets();
-    if (targets.length === 0) {
-        targets = await promptSkillInstallTargets();
+function describePlannedWrite(target, action, mode, path) {
+    const verb = action.includes('create') || action === 'created' ? 'create' : 'replace';
+    if (target === 'agents-md') {
+        return `  ${path} (${verb} managed Orizu section)`;
     }
-    if (targets.length === 0) {
-        printLine('No targets selected; nothing to do.');
-        return;
+    if (mode === 'link') {
+        return `  ${path} (${verb}, symlink to the CLI-managed skill)`;
+    }
+    return `  ${path} (${verb}, full copy with sync metadata)`;
+}
+async function applySkillInstallTargets(targets, options) {
+    const cliVersion = getCliVersion();
+    const jsonMode = hasJsonFlag();
+    const planned = targets.map(target => installSkillTarget(target, { dryRun: true, mode: options.mode, cliVersion }));
+    if (!jsonMode) {
+        printLine('Planned writes:');
+        for (const plan of planned) {
+            printLine(describePlannedWrite(plan.target, plan.action, plan.mode, plan.path));
+        }
+        printLine('');
     }
+    if (options.dryRun) {
+        if (!jsonMode) {
+            printLine('Dry run: no files were changed.');
+        }
+        return planned.map(plan => ({
+            target: plan.target,
+            path: plan.path,
+            action: 'skipped',
+            mode: plan.mode,
+        }));
+    }
+    const outcomes = [];
     for (const target of targets) {
-        let overwrite = skipConfirm;
+        let overwrite = options.skipConfirm;
         const installPath = getSkillInstallPath(target);
-        if (!dryRun && !overwrite && targetNeedsOverwrite(target)) {
+        if (!overwrite && targetNeedsOverwrite(target)) {
             if (!isInteractiveTerminal()) {
                 throw new Error(`${installPath} already exists. Pass --yes to replace it.`);
             }
             overwrite = await askYesNo(`Replace ${installPath}?`, true);
             if (!overwrite) {
-                printLine(`Skipped ${installPath}`);
+                if (!jsonMode) {
+                    printLine(`Skipped ${installPath}`);
+                }
+                outcomes.push({ target, path: installPath, action: 'skipped', mode: null });
                 continue;
             }
         }
+        try {
+            const result = installSkillTarget(target, {
+                overwrite,
+                mode: options.mode,
+                cliVersion,
+            });
+            if (!jsonMode) {
+                const suffix = result.mode === 'link' ? ' (symlink)' : '';
+                printLine(`${formatSkillInstallAction(result.action)} ${result.path}${suffix}`);
+            }
+            outcomes.push({
+                target,
+                path: result.path,
+                action: result.action,
+                mode: result.mode,
+            });
+        }
+        catch (error) {
+            const message = error?.message || String(error);
+            if (!jsonMode) {
+                printLine(`Failed ${installPath}: ${message}`);
+            }
+            outcomes.push({ target, path: installPath, action: 'failed', mode: null, error: message });
+        }
+    }
+    return outcomes;
+}
+async function installSkillCommand() {
+    const skipConfirm = hasArg('--yes');
+    const dryRun = hasArg('--dry-run');
+    const scope = parseSkillInstallScope();
+    const mode = parseSkillInstallMode();
+    let targets = parseSkillInstallTargets(scope);
+    if (targets.length === 0) {
+        targets = await promptSkillInstallTargets(scope);
+    }
+    if (targets.length === 0) {
+        if (hasJsonFlag()) {
+            printJson({ installs: [] });
+            return;
+        }
+        printLine('No targets selected; nothing to do.');
+        return;
+    }
+    const outcomes = await applySkillInstallTargets(targets, { mode, skipConfirm, dryRun });
+    if (hasJsonFlag()) {
+        printJson({ dryRun, installs: outcomes });
+    }
+}
+function describeSkillTargetState(status) {
+    if (status.state === 'current')
+        return 'current';
+    if (status.state === 'stale')
+        return 'stale (run `orizu skills update`)';
+    if (status.state === 'broken-link')
+        return 'broken symlink (run `orizu skills update`)';
+    if (status.state === 'unmanaged')
+        return 'exists without a managed Orizu section';
+    return 'not installed';
+}
+function skillsStatusCommand() {
+    const source = resolveSkillSource();
+    const statuses = SKILL_INSTALL_TARGETS.map(target => getSkillTargetStatus(target));
+    if (hasJsonFlag()) {
+        printJson({
+            name: source.name,
+            root: source.root,
+            source: source.source,
+            cliVersion: getCliVersion(),
+            sourceHash: computeSkillContentHash(source.root),
+            targets: statuses.map(status => ({
+                target: status.target,
+                path: status.path,
+                state: status.state,
+                mode: status.mode,
+                linkTarget: status.linkTarget,
+                installedHash: status.installedHash,
+                meta: status.meta,
+            })),
+        });
+        return;
+    }
+    printLine(`Skill source: ${source.root} (${source.source})`);
+    printLine('');
+    for (const status of statuses) {
+        const mode = status.mode ? `, ${status.mode}` : '';
+        printLine(`  ${status.target.padEnd(16)} ${describeSkillTargetState(status)}${mode}`);
+        printLine(`  ${''.padEnd(16)} ${status.path}`);
+    }
+}
+async function skillsUpdateCommand() {
+    const dryRun = hasArg('--dry-run');
+    const cliVersion = getCliVersion();
+    const updates = [];
+    for (const target of SKILL_INSTALL_TARGETS) {
+        const status = getSkillTargetStatus(target);
+        if (status.state === 'missing' || status.state === 'unmanaged') {
+            continue;
+        }
+        if (status.state === 'current') {
+            updates.push({ target, path: status.path, action: 'already-current' });
+            continue;
+        }
+        if (dryRun) {
+            updates.push({ target, path: status.path, action: 'would-update' });
+            continue;
+        }
+        const refreshMode = status.mode === 'link' ? 'auto' : 'copy';
         const result = installSkillTarget(target, {
-            overwrite,
-            dryRun,
+            overwrite: true,
+            mode: refreshMode,
+            cliVersion,
+        });
+        updates.push({
+            target,
+            path: status.path,
+            action: status.state === 'broken-link' ? 'relinked' : result.action,
+        });
+    }
+    if (hasJsonFlag()) {
+        printJson({ updates });
+        return;
+    }
+    if (updates.length === 0) {
+        printLine('No Orizu skill installs found. Run `orizu install-skill` first.');
+        return;
+    }
+    for (const update of updates) {
+        if (update.action === 'already-current') {
+            printLine(`Current ${update.path}`);
+        }
+        else if (update.action === 'would-update') {
+            printLine(`Would update ${update.path}`);
+        }
+        else if (update.action === 'relinked') {
+            printLine(`Relinked ${update.path}`);
+        }
+        else {
+            printLine(`Updated ${update.path}`);
+        }
+    }
+}
+function skillsPathCommand() {
+    const source = resolveSkillSource();
+    if (hasJsonFlag()) {
+        printJson({
+            name: source.name,
+            root: source.root,
+            skillMd: source.skillMd,
+            source: source.source,
+            cliVersion: getCliVersion(),
+            skillHash: computeSkillContentHash(source.root),
         });
-        printLine(`${formatSkillInstallAction(result.action)} ${result.path}`);
+        return;
+    }
+    printLine(hasArg('--skill-md') ? source.skillMd : source.root);
+}
+const LAUNCHABLE_AGENTS = {
+    claude: 'claude',
+    codex: 'codex',
+};
+function findExecutable(name) {
+    const pathValue = process.env.PATH || '';
+    for (const dir of pathValue.split(delimiter)) {
+        if (!dir) {
+            continue;
+        }
+        const candidate = join(dir, name);
+        if (existsSync(candidate)) {
+            return candidate;
+        }
     }
+    return null;
+}
+function describeSetupAuthState() {
+    const baseUrl = getBaseUrl();
+    return {
+        state: getServerCredentials(baseUrl) ? 'signed-in' : 'signed-out',
+        baseUrl,
+    };
+}
+async function setupCommand() {
+    const dryRun = hasArg('--dry-run');
+    const skipConfirm = hasArg('--yes');
+    const noInput = hasArg('--no-input') || !isInteractiveTerminal();
+    printBannerIfInteractive();
+    printLine('Orizu setup');
+    printLine('');
+    // Phase 1: login
+    printLine('1. Authentication');
+    let auth = describeSetupAuthState();
+    if (hasArg('--skip-login')) {
+        printLine('   Skipped (--skip-login).');
+    }
+    else if (auth.state === 'signed-in') {
+        printLine(`   Already authenticated with ${sanitizeTerminalText(auth.baseUrl)}.`);
+    }
+    else if (noInput || dryRun) {
+        printLine('   Not signed in. Run `orizu login` to authenticate.');
+    }
+    else if (await askYesNo('   Sign in to Orizu now?', true)) {
+        await login();
+        auth = describeSetupAuthState();
+    }
+    else {
+        printLine('   Skipped. Run `orizu login` when ready.');
+    }
+    printLine('');
+    // Phase 2: agent integration
+    printLine('2. Agent integration');
+    const scope = parseSkillInstallScope();
+    const mode = parseSkillInstallMode();
+    let targets = hasArg('--no-install') ? [] : parseSkillInstallTargets(scope);
+    if (targets.length === 0 && !hasArg('--no-install')) {
+        if (noInput) {
+            printLine('   No agents selected. Pass --agent claude and/or --agent codex, or rerun interactively.');
+        }
+        else {
+            targets = await promptSkillInstallTargets(scope);
+        }
+    }
+    let installOutcomes = [];
+    if (targets.length > 0) {
+        installOutcomes = await applySkillInstallTargets(targets, { mode, skipConfirm, dryRun });
+    }
+    else if (hasArg('--no-install')) {
+        printLine('   Skipped (--no-install).');
+    }
+    printLine('');
+    // Phase 3: local workspace
+    printLine('3. Local workspace');
+    let workspaceState = 'skipped';
+    if (hasArg('--no-workspace')) {
+        printLine('   Skipped (--no-workspace).');
+    }
+    else if (workspaceExists()) {
+        workspaceState = 'exists';
+        printLine(`   ${WORKSPACE_DIR_NAME}/ already initialized.`);
+    }
+    else {
+        const wantsWorkspace = hasArg('--workspace') ||
+            (!noInput && await askYesNo(`   Create a gitignored ${WORKSPACE_DIR_NAME}/ workspace for local Orizu artifacts?`, true));
+        if (wantsWorkspace) {
+            const result = initOrizuWorkspace({
+                baseUrl: auth.baseUrl,
+                cliVersion: getCliVersion(),
+                dryRun,
+            });
+            workspaceState = result.state === 'would-create' ? 'would-create' : result.state;
+            for (const action of result.actions) {
+                printLine(`   ${dryRun ? 'Would ' : 'Did '}${action}`);
+            }
+        }
+        else {
+            printLine(`   Skipped. Rerun with --workspace to create ${WORKSPACE_DIR_NAME}/.`);
+        }
+    }
+    printLine('');
+    // Phase 4: coding-agent handoff
+    const handoffPrompt = renderAgentSetupPrompt({
+        workspacePath: workspaceState === 'created' || workspaceState === 'exists'
+            ? getWorkspaceRoot()
+            : null,
+    });
+    if (!hasArg('--no-handoff')) {
+        printLine('4. Coding-agent handoff');
+        printLine('   Give your coding agent this prompt to plan repo-specific Orizu adoption:');
+        printLine('');
+        printLine('--- prompt start ---');
+        printLine(handoffPrompt);
+        printLine('--- prompt end ---');
+        printLine('');
+        const detected = Object.keys(LAUNCHABLE_AGENTS).filter(agent => findExecutable(LAUNCHABLE_AGENTS[agent]));
+        if (detected.length > 0) {
+            printLine(`   Detected agents: ${detected.join(', ')}. Launch one with the prompt, e.g.:`);
+            for (const agent of detected) {
+                printLine(`     ${LAUNCHABLE_AGENTS[agent]} "$(orizu setup prompt)"`);
+            }
+        }
+        const launchAgent = getArg('--launch');
+        if (launchAgent) {
+            if (!(launchAgent in LAUNCHABLE_AGENTS)) {
+                throw new Error(`Unknown --launch agent '${launchAgent}'. Choices: ${Object.keys(LAUNCHABLE_AGENTS).join(', ')}.`);
+            }
+            const binary = findExecutable(LAUNCHABLE_AGENTS[launchAgent]);
+            if (!isInteractiveTerminal()) {
+                printLine('   Not launching: --launch requires an interactive terminal.');
+            }
+            else if (!binary) {
+                printLine(`   Not launching: '${LAUNCHABLE_AGENTS[launchAgent]}' was not found on PATH.`);
+            }
+            else if (dryRun) {
+                printLine(`   Would launch ${binary} with the setup prompt.`);
+            }
+            else if (skipConfirm || await askYesNo(`   Launch ${LAUNCHABLE_AGENTS[launchAgent]} with the setup prompt now?`, true)) {
+                printLine(`   Launching ${binary}…`);
+                spawnSync(binary, [handoffPrompt], { stdio: 'inherit' });
+            }
+        }
+        printLine('');
+    }
+    // Setup summary (success criteria checklist)
+    const summaryTargets = installOutcomes.length > 0
+        ? installOutcomes
+            .filter(outcome => outcome.action !== 'failed')
+            .map(outcome => ({ outcome, status: getSkillTargetStatus(outcome.target) }))
+        : [];
+    const source = resolveSkillSource();
+    if (hasJsonFlag()) {
+        printJson({
+            auth: { state: auth.state, server: auth.baseUrl },
+            integrations: installOutcomes.map(outcome => ({
+                target: outcome.target,
+                path: outcome.path,
+                action: outcome.action,
+                mode: outcome.mode,
+                error: outcome.error,
+            })),
+            skill: {
+                root: source.root,
+                source: source.source,
+                cliVersion: getCliVersion(),
+                skillHash: computeSkillContentHash(source.root),
+            },
+            workspace: { state: workspaceState, path: getWorkspaceRoot() },
+        });
+        return;
+    }
+    printLine('Setup summary');
+    printLine(`  Auth:         ${auth.state === 'signed-in' ? `signed in (${sanitizeTerminalText(auth.baseUrl)})` : 'not signed in — run `orizu login`'}`);
+    if (summaryTargets.length > 0) {
+        printLine('  Integrations:');
+        for (const { outcome, status } of summaryTargets) {
+            const modeLabel = status.mode ? `, ${status.mode}` : '';
+            printLine(`    ${outcome.target.padEnd(16)} ${status.state}${modeLabel}  ${outcome.path}`);
+        }
+    }
+    else {
+        printLine('  Integrations: none installed this run — `orizu install-skill` sets them up.');
+    }
+    const failed = installOutcomes.filter(outcome => outcome.action === 'failed');
+    for (const failure of failed) {
+        printLine(`    ${failure.target.padEnd(16)} failed: ${failure.error}`);
+    }
+    printLine(`  Skill source: ${source.root} (${source.source})`);
+    printLine(`  Workspace:    ${workspaceState === 'skipped' ? 'skipped' : `${getWorkspaceRoot()} (${workspaceState})`}`);
+    printLine('  Next:         hand the prompt above to your coding agent to plan repo-specific Orizu adoption.');
+}
+function setupPromptCommand() {
+    const prompt = renderAgentSetupPrompt({
+        workspacePath: workspaceExists() ? getWorkspaceRoot() : null,
+    });
+    if (hasJsonFlag()) {
+        printJson({ prompt });
+        return;
+    }
+    printLine(prompt);
 }
 function readJsonFile(pathArg) {
     const raw = readSourceFile(pathArg);
@@ -2281,6 +2845,10 @@ async function createAppFromFile() {
         throw new Error(`Failed to create app: ${await response.text()}`);
     }
     const data = await parseJsonResponse(response, 'App create');
+    if (hasJsonFlag()) {
+        printJson({ app: data.app, warnings: data.warnings || [] });
+        return;
+    }
     printLine(`Created app ${sanitizeTerminalText(data.app.name)} (${sanitizeTerminalText(data.app.id)}) v${data.app.versionNum}`);
     if (data.app.url) {
         printLine(`View app: ${formatTerminalLink(data.app.url)}`);
@@ -2316,6 +2884,14 @@ async function previewAppFromFile() {
         headed,
         keepOpen,
     });
+    if (hasJsonFlag()) {
+        printJson({
+            url: result.url,
+            screenshotPath: result.screenshotPath || null,
+            warnings: result.warnings,
+        });
+        return;
+    }
     printLine(`Preview rendered: ${formatTerminalLink(result.url)}`);
     if (result.screenshotPath) {
         printLine(`Screenshot: ${sanitizeTerminalText(result.screenshotPath)}`);
@@ -2358,6 +2934,10 @@ async function updateAppFromFile() {
         throw new Error(`Failed to update app: ${await response.text()}`);
     }
     const data = await parseJsonResponse(response, 'App update');
+    if (hasJsonFlag()) {
+        printJson({ app: data.app, warnings: data.warnings || [] });
+        return;
+    }
     printLine(`Updated app ${sanitizeTerminalText(data.app.name)} (${sanitizeTerminalText(data.app.id)}) to v${data.app.versionNum}`);
     if (data.warnings?.length) {
         printLine(`Warnings: ${sanitizeTerminalText(data.warnings.join('; '))}`);
@@ -2392,6 +2972,10 @@ async function linkAppDataset() {
         throw new Error(`Failed to link dataset: ${await response.text()}`);
     }
     const data = await parseJsonResponse(response, 'App link dataset');
+    if (hasJsonFlag()) {
+        printJson({ app: data.app, linkedDataset: data.linkedDataset, versionNum: data.versionNum });
+        return;
+    }
     printLine(`Linked dataset ${sanitizeTerminalText(data.linkedDataset.name)} (${sanitizeTerminalText(data.linkedDataset.id)}) to app ${sanitizeTerminalText(data.app.name)} (${sanitizeTerminalText(data.app.id)}) version ${data.versionNum}`);
 }
 function parseCommaSeparated(value) {
@@ -2403,43 +2987,69 @@ function parseCommaSeparated(value) {
         .map(item => item.trim())
         .filter(Boolean);
 }
+function readAssignmentManifest(path) {
+    if (!path) {
+        return null;
+    }
+    const content = readFileSync(expandHomePath(path), 'utf8');
+    return parseAssignmentManifestJsonl(content);
+}
 async function createTask() {
     const projectSlug = getArg('--project');
     const datasetId = getArg('--dataset');
     const appId = getArg('--app');
     const title = getArg('--title');
     const assignees = parseCommaSeparated(getArg('--assignees'));
+    const assignmentFile = getArg('--assignment-file');
     const publish = hasArg('--publish');
     const versionArg = getArg('--version');
     const instructions = getArg('--instructions');
     const labelsPerItemArg = getArg('--labels-per-item');
-    const labelsPerItem = labelsPerItemArg ? Number(labelsPerItemArg) : 1;
+    const parsedLabelsPerItem = labelsPerItemArg ? Number(labelsPerItemArg) : 1;
+    const labelsPerItem = Number.isInteger(parsedLabelsPerItem) && parsedLabelsPerItem > 0
+        ? parsedLabelsPerItem
+        : null;
     const parsedVersionNum = versionArg ? Number(versionArg) : Number.NaN;
     const versionNum = Number.isInteger(parsedVersionNum) && parsedVersionNum > 0 ? parsedVersionNum : null;
-    if (!projectSlug || !datasetId || !appId || !title || (publish && assignees.length === 0)) {
-        throw new Error('Usage: orizu tasks create --project <team/project> --dataset <datasetId> --app <appId> --title <title> [--assignees <userIdOrEmail1,userIdOrEmail2>] [--publish] [--version <n>] [--instructions <text>] [--labels-per-item <n>] [--json]');
+    if (assignmentFile && assignees.length > 0) {
+        throw new Error('Use either --assignment-file or --assignees, not both.');
+    }
+    const explicitAssignments = readAssignmentManifest(assignmentFile);
+    if (!projectSlug || !datasetId || !appId || !title || (publish && assignees.length === 0 && !explicitAssignments)) {
+        throw new Error('Usage: orizu tasks create --project <team/project> --dataset <datasetId> --app <appId> --title <title> [--assignees <userIdOrEmail1,userIdOrEmail2> | --assignment-file <path>] [--publish] [--version <n>] [--instructions <text>] [--labels-per-item <n>] [--json]');
     }
     if (versionArg && versionNum === null) {
         throw new Error('--version must be a positive integer');
     }
+    if (labelsPerItemArg && labelsPerItem === null) {
+        throw new Error('--labels-per-item must be a positive integer');
+    }
+    const requestBody = {
+        projectSlug,
+        datasetId,
+        appId,
+        versionNum,
+        title,
+        publish,
+        instructions,
+    };
+    if (explicitAssignments) {
+        requestBody.explicitAssignments = explicitAssignments;
+    }
+    else {
+        requestBody.memberIds = assignees;
+    }
+    if (!explicitAssignments || labelsPerItemArg) {
+        requestBody.requiredAssignmentsPerRow = labelsPerItem;
+    }
     const response = await authedFetch('/api/cli/tasks', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({
-            projectSlug,
-            datasetId,
-            appId,
-            versionNum,
-            title,
-            memberIds: assignees,
-            publish,
-            instructions,
-            requiredAssignmentsPerRow: labelsPerItem,
-        }),
+        body: JSON.stringify(requestBody),
     });
     if (!response.ok) {
         const cliError = await formatTaskCreateError(response);
-        if (hasArg('--json')) {
+        if (hasJsonFlag()) {
             const payload = cliError.structuredPayload ?? { error: cliError.message };
             printLine(JSON.stringify({
                 ...payload,
@@ -2449,7 +3059,7 @@ async function createTask() {
         throw cliError;
     }
     const data = await parseJsonResponse(response, 'Task create');
-    if (hasArg('--json')) {
+    if (hasJsonFlag()) {
         printLine(JSON.stringify({
             taskId: data.task.id,
             datasetId,
@@ -2458,13 +3068,16 @@ async function createTask() {
             taskUrl: `${getBaseUrl()}/d/${projectSlug}/tasks/${data.task.id}`,
             title: data.task.title,
             status: data.task.status,
+            assignmentMode: explicitAssignments ? 'custom' : 'auto',
             requiredAssignmentsPerRow: data.task.requiredAssignmentsPerRow,
             assignmentsCreated: data.assignmentsCreated,
             draft: data.task.status === 'draft',
             ...(data.task.status === 'draft'
                 ? {
                     message: 'Draft created. Test it manually before assigning.',
-                    publishCommand: `orizu tasks publish --task ${data.task.id} --assignees <userId1,userId2>`,
+                    publishCommand: explicitAssignments
+                        ? `orizu tasks publish --task ${data.task.id} --assignment-file ${assignmentFile ? shellQuote(assignmentFile) : '<path>'}`
+                        : `orizu tasks publish --task ${data.task.id} --assignees <userId1,userId2>`,
                 }
                 : {}),
             ...(data.assignmentShortfall !== undefined ? { assignmentShortfall: data.assignmentShortfall } : {}),
@@ -2479,33 +3092,44 @@ async function createTask() {
         `\n  Task ID:    ${sanitizeTerminalText(data.task.id)}` +
         `\n  Dataset ID: ${sanitizeTerminalText(datasetId)}` +
         `\n  Version:    v${data.task.versionNum} (${sanitizeTerminalText(data.task.versionId)})` +
+        `\n  Mode:       ${explicitAssignments ? 'custom row map' : 'auto distribute'}` +
         `\n  Labels/row: ${data.task.requiredAssignmentsPerRow}` +
         `\n  Assignments: ${data.assignmentsCreated}` +
         (data.warning ? `\n  Warning:    ${sanitizeTerminalText(data.warning)}` : '') +
         `\n  URL:        ${sanitizeTerminalText(taskUrl)}` +
         (isDraft
-            ? `\n\nThis task is a draft. Test it manually before assigning.\nPublish after approval: orizu tasks publish --task ${sanitizeTerminalText(data.task.id)} --assignees <userId1,userId2>`
+            ? `\n\nThis task is a draft. Test it manually before assigning.\nPublish after approval: ${explicitAssignments
+                ? `orizu tasks publish --task ${sanitizeTerminalText(data.task.id)} --assignment-file ${sanitizeTerminalText(assignmentFile || '<path>')}`
+                : `orizu tasks publish --task ${sanitizeTerminalText(data.task.id)} --assignees <userId1,userId2>`}`
             : ''));
 }
 async function publishTask() {
     const taskId = getArg('--task');
     const assignees = parseCommaSeparated(getArg('--assignees'));
-    if (!taskId || assignees.length === 0) {
-        throw new Error('Usage: orizu tasks publish --task <taskId> --assignees <userId1,userId2> [--json]');
+    const assignmentFile = getArg('--assignment-file');
+    if (assignmentFile && assignees.length > 0) {
+        throw new Error('Use either --assignment-file or --assignees, not both.');
+    }
+    const explicitAssignments = readAssignmentManifest(assignmentFile);
+    if (!taskId || (assignees.length === 0 && !explicitAssignments)) {
+        throw new Error('Usage: orizu tasks publish --task <taskId> (--assignees <userId1,userId2> | --assignment-file <path>) [--json]');
     }
     const response = await authedFetch(`/api/cli/tasks/${encodeURIComponent(taskId)}/publish`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ memberIds: assignees }),
+        body: JSON.stringify(explicitAssignments
+            ? { explicitAssignments }
+            : { memberIds: assignees }),
     });
     if (!response.ok) {
         throw new Error(`Failed to publish task: ${await extractErrorMessage(response)}`);
     }
     const data = await parseJsonResponse(response, 'Task publish');
-    if (hasArg('--json')) {
+    if (hasJsonFlag()) {
         printLine(JSON.stringify({
             taskId: data.task.id,
             status: data.task.status,
+            assignmentMode: explicitAssignments ? 'custom' : 'auto',
             assignmentsCreated: data.assignmentsCreated,
             assignmentsProcessed: data.assignmentsProcessed,
             ...(data.assignmentsRemoved !== undefined
@@ -2519,6 +3143,7 @@ async function publishTask() {
         return;
     }
     printLine(`Published task ${sanitizeTerminalText(data.task.id)} [${sanitizeTerminalText(data.task.status)}]` +
+        `\n  Mode:        ${explicitAssignments ? 'custom row map' : 'auto distribute'}` +
         `\n  Assignments: ${data.assignmentsCreated}` +
         (data.assignmentsRemoved !== undefined
             ? `\n  Replaced:    ${data.assignmentsRemoved} old assignments removed`
@@ -2528,19 +3153,50 @@ async function publishTask() {
 async function assignTask() {
     const taskId = getArg('--task');
     const assignees = parseCommaSeparated(getArg('--assignees'));
-    if (!taskId || assignees.length === 0) {
-        throw new Error('Usage: orizu tasks assign --task <taskId> --assignees <userId1,userId2>');
+    const assignmentFile = getArg('--assignment-file');
+    if (assignmentFile && assignees.length > 0) {
+        throw new Error('Use either --assignment-file or --assignees, not both.');
+    }
+    const explicitAssignments = readAssignmentManifest(assignmentFile);
+    if (!taskId || (assignees.length === 0 && !explicitAssignments)) {
+        throw new Error('Usage: orizu tasks assign --task <taskId> (--assignees <userId1,userId2> | --assignment-file <path>) [--replace-existing] [--json]');
+    }
+    const requestBody = explicitAssignments
+        ? { explicitAssignments }
+        : { memberIds: assignees };
+    if (hasArg('--replace-existing')) {
+        requestBody.replaceExisting = true;
     }
     const response = await authedFetch(`/api/cli/tasks/${encodeURIComponent(taskId)}/assign`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ memberIds: assignees }),
+        body: JSON.stringify(requestBody),
     });
     if (!response.ok) {
         throw new Error(`Failed to assign task: ${await response.text()}`);
     }
     const data = await parseJsonResponse(response, 'Task assign');
-    printLine(`Created ${data.assignmentsCreated} assignments.`);
+    if (hasJsonFlag()) {
+        printJson({
+            assignmentMode: explicitAssignments ? 'custom' : 'auto',
+            assignmentsProcessed: data.assignmentsProcessed ?? data.assignmentsCreated,
+            assignmentsCreated: data.assignmentsCreated,
+            ...(data.assignmentsRemoved !== undefined
+                ? { assignmentsRemoved: data.assignmentsRemoved }
+                : {}),
+            ...(data.assignmentShortfall !== undefined
+                ? { assignmentShortfall: data.assignmentShortfall }
+                : {}),
+            ...(data.warning ? { warning: data.warning } : {}),
+        });
+        return;
+    }
+    printLine(`Created ${data.assignmentsCreated} assignments.` +
+        `\n  Mode: ${explicitAssignments ? 'custom row map' : 'auto distribute'}` +
+        (data.assignmentsRemoved !== undefined
+            ? `\n  Replaced: ${data.assignmentsRemoved} old assignments removed`
+            : '') +
+        (data.warning ? `\n  Warning: ${sanitizeTerminalText(data.warning)}` : ''));
 }
 async function taskStatus() {
     const taskId = getArg('--task');
@@ -2550,7 +3206,7 @@ async function taskStatus() {
     const response = await authedFetch(`/api/cli/tasks/${encodeURIComponent(taskId)}/status`);
     if (!response.ok) {
         const rawBody = await response.text();
-        if (hasArg('--json')) {
+        if (hasJsonFlag()) {
             let errorPayload = { error: rawBody };
             try {
                 const parsed = JSON.parse(rawBody);
@@ -2577,7 +3233,7 @@ async function taskStatus() {
         throw new Error(`Failed to fetch task status: ${errorMsg}`);
     }
     const data = await parseJsonResponse(response, 'Task status');
-    if (hasArg('--json')) {
+    if (hasJsonFlag()) {
         printLine(JSON.stringify(data, null, 2));
         return;
     }
@@ -2599,6 +3255,10 @@ async function updateTaskStatus(targetStatus) {
         throw new Error(`Failed to ${verb} task: ${await response.text()}`);
     }
     const data = await parseJsonResponse(response, 'Task status update');
+    if (hasJsonFlag()) {
+        printJson({ task: data.task });
+        return;
+    }
     const action = targetStatus === 'paused' ? 'Paused' : 'Unpaused';
     printLine(`${action} task ${sanitizeTerminalText(data.task.id)} [${sanitizeTerminalText(data.task.status)}]`);
 }
@@ -2656,7 +3316,7 @@ async function appDetail() {
     if (!detail) {
         throw new Error(`App '${appId}' not found in project '${projectSlug}'`);
     }
-    if (hasArg('--json')) {
+    if (hasJsonFlag()) {
         printLine(JSON.stringify(detail, null, 2));
         return;
     }
@@ -2709,11 +3369,24 @@ async function exportAppSource() {
         ? expandHomePath(outPathArg)
         : defaultAppExportFilename(data.app.name, data.version.versionNum);
     writeTextFileEnsuringDir(filename, data.version.code);
+    if (hasJsonFlag()) {
+        printJson({
+            app: { id: data.app.id, name: data.app.name },
+            versionNum: data.version.versionNum,
+            savedTo: filename,
+        });
+        return;
+    }
     printLine(`Saved app ${sanitizeTerminalText(data.app.name)} v${data.version.versionNum} source to ${sanitizeTerminalText(filename)}`);
 }
 async function listTeamMembers() {
     const teamSlug = await resolveTeamSlug(getArg('--team'));
-    printTeamMembers(await fetchTeamMembers(teamSlug));
+    const members = await fetchTeamMembers(teamSlug);
+    if (hasJsonFlag()) {
+        printJson({ team: teamSlug, members });
+        return;
+    }
+    printTeamMembers(members);
 }
 async function addTeamMember() {
     const teamSlug = await resolveTeamSlug(getArg('--team'));
@@ -2730,6 +3403,10 @@ async function addTeamMember() {
         throw new Error(`Failed to add team member: ${await response.text()}`);
     }
     const data = await parseJsonResponse(response, 'Team member add');
+    if (hasJsonFlag()) {
+        printJson({ member: data.member });
+        return;
+    }
     printLine(`Added team member ${sanitizeTerminalText(data.member.email)} (${sanitizeTerminalText(data.member.id)})`);
 }
 async function removeTeamMember() {
@@ -2747,6 +3424,10 @@ async function removeTeamMember() {
     if (!response.ok) {
         throw new Error(`Failed to remove team member: ${await response.text()}`);
     }
+    if (hasJsonFlag()) {
+        printJson({ removed: { id: member.id, email: member.email } });
+        return;
+    }
     printLine(`Removed team member ${sanitizeTerminalText(member.email)}`);
 }
 async function changeTeamMemberRole() {
@@ -2773,6 +3454,10 @@ async function changeTeamMemberRole() {
     if (!response.ok) {
         throw new Error(`Failed to update member role: ${await response.text()}`);
     }
+    if (hasJsonFlag()) {
+        printJson({ member: { id: member.id, email: member.email, role } });
+        return;
+    }
     printLine(`Updated ${sanitizeTerminalText(member.email)} role to ${sanitizeTerminalText(role)}`);
 }
 async function createDatasetFromRows(project, name, sourceType, rows, readmeMarkdown = null) {
@@ -2849,6 +3534,10 @@ async function uploadJsonlDatasetInChunks(file, project, datasetName, readmeMark
     if (!dataset) {
         throw new Error('Dataset file contains no rows');
     }
+    if (hasJsonFlag()) {
+        printJson({ dataset });
+        return;
+    }
     printLine(`Uploaded dataset ${sanitizeTerminalText(dataset.name)} (${sanitizeTerminalText(dataset.id)}) with ${dataset.rowCount} rows.`);
     if (dataset.url) {
         printLine(`View dataset: ${formatTerminalLink(dataset.url)}`);
@@ -2872,6 +3561,10 @@ async function uploadDataset() {
     }
     const { rows, sourceType } = parseDatasetFile(file);
     const data = await createDatasetFromRows(project, datasetName, sourceType, rows, readmeMarkdown);
+    if (hasJsonFlag()) {
+        printJson({ dataset: data.dataset });
+        return;
+    }
     printLine(`Uploaded dataset ${sanitizeTerminalText(data.dataset.name)} (${sanitizeTerminalText(data.dataset.id)}) with ${data.dataset.rowCount} rows.`);
     if (data.dataset.url) {
         printLine(`View dataset: ${formatTerminalLink(data.dataset.url)}`);
@@ -2976,6 +3669,10 @@ async function downloadDataset() {
         : `${datasetId}.${format}`;
     const bytes = new Uint8Array(await response.arrayBuffer());
     writeFileSync(filename, bytes);
+    if (hasJsonFlag()) {
+        printJson({ datasetId, format, savedTo: filename });
+        return;
+    }
     printLine(`Saved dataset ${sanitizeTerminalText(datasetId)} (${format.toUpperCase()}) to ${sanitizeTerminalText(filename)}`);
 }
 const MAX_INPUT_FILE_SIZE_BYTES = 50 * 1024 * 1024; // 50 MB
@@ -3101,6 +3798,10 @@ async function appendDatasetRows() {
         }
     }
     if (lastResult) {
+        if (hasJsonFlag()) {
+            printJson({ dataset: lastResult.dataset, appendedCount: totalAppended });
+            return;
+        }
         printLine(`Appended ${totalAppended} rows to dataset ${sanitizeTerminalText(lastResult.dataset.name)} (${sanitizeTerminalText(lastResult.dataset.id)}). New row count: ${lastResult.dataset.rowCount}`);
     }
 }
@@ -3147,6 +3848,10 @@ async function editDatasetRows() {
         throw new Error(`Edit rows failed: ${await response.text()}`);
     }
     const data = await parseJsonResponse(response, 'Dataset edit rows');
+    if (hasJsonFlag()) {
+        printJson({ dataset: data.dataset, updatedCount: data.updatedCount });
+        return;
+    }
     printLine(`Updated ${data.updatedCount} rows in dataset ${sanitizeTerminalText(data.dataset.name)} (${sanitizeTerminalText(data.dataset.id)}). Current row count: ${data.dataset.rowCount}`);
 }
 async function deleteDatasetRows() {
@@ -3175,6 +3880,10 @@ async function deleteDatasetRows() {
         throw new Error(`Delete rows failed: ${await response.text()}`);
     }
     const data = await parseJsonResponse(response, 'Dataset delete rows');
+    if (hasJsonFlag()) {
+        printJson({ dataset: data.dataset, deletedCount: data.deletedCount });
+        return;
+    }
     printLine(`Deleted ${data.deletedCount} rows from dataset ${sanitizeTerminalText(data.dataset.name)} (${sanitizeTerminalText(data.dataset.id)}). New row count: ${data.dataset.rowCount}`);
 }
 async function confirmDatasetDeletion(dataset) {
@@ -3213,6 +3922,10 @@ async function deleteDataset() {
         throw new Error(`Delete failed: ${await response.text()}`);
     }
     const data = await parseJsonResponse(response, 'Dataset delete');
+    if (hasJsonFlag()) {
+        printJson({ dataset: data.dataset, deleted: true });
+        return;
+    }
     printLine(`Deleted dataset ${sanitizeTerminalText(data.dataset.id)}.`);
 }
 async function lockDataset() {
@@ -3236,6 +3949,10 @@ async function lockDataset() {
         throw new Error(`Lock failed: ${await response.text()}`);
     }
     const data = await parseJsonResponse(response, 'Dataset lock');
+    if (hasJsonFlag()) {
+        printJson({ dataset: data.dataset });
+        return;
+    }
     printLine(`Locked dataset ${sanitizeTerminalText(data.dataset.name)} (${sanitizeTerminalText(data.dataset.id)}) at ${sanitizeTerminalText(data.dataset.lockedAt)}. Row count: ${data.dataset.rowCount}`);
 }
 async function cloneDataset() {
@@ -3259,6 +3976,10 @@ async function cloneDataset() {
         throw new Error(`Clone failed: ${await response.text()}`);
     }
     const data = await parseJsonResponse(response, 'Dataset clone');
+    if (hasJsonFlag()) {
+        printJson({ dataset: data.dataset });
+        return;
+    }
     printLine(`Cloned dataset ${sanitizeTerminalText(data.dataset.parentDatasetId)} -> ${sanitizeTerminalText(data.dataset.name)} (${sanitizeTerminalText(data.dataset.id)}). Row count: ${data.dataset.rowCount}`);
 }
 async function downloadAnnotations() {
@@ -3281,6 +4002,10 @@ async function downloadAnnotations() {
         : fallbackName;
     const bytes = new Uint8Array(await response.arrayBuffer());
     writeFileSync(filename, bytes);
+    if (hasJsonFlag()) {
+        printJson({ taskId, format, savedTo: filename });
+        return;
+    }
     printLine(`Saved ${format.toUpperCase()} export to ${sanitizeTerminalText(filename)}`);
 }
 function readRunnerManifest(runnerDir) {
@@ -3493,7 +4218,12 @@ async function runnersExec() {
         else {
             writeFileSync(outPath, resultJsonl);
         }
-        printLine(`Wrote ${context.rows.length} runner results to ${sanitizeTerminalText(outPath)}`);
+        if (hasJsonFlag()) {
+            printJson({ rowCount: context.rows.length, out: outPath });
+        }
+        else {
+            printLine(`Wrote ${context.rows.length} runner results to ${sanitizeTerminalText(outPath)}`);
+        }
     }
     finally {
         materializedRunner.cleanup();
@@ -3527,6 +4257,9 @@ export async function main(rawArgs = process.argv.slice(2)) {
     }
     const helpTarget = extractHelpTarget(cliArgs);
     if (helpTarget !== null) {
+        if (helpTarget.length === 0) {
+            printBannerIfInteractive();
+        }
         printLine(renderHelpForArgs(helpTarget));
         return;
     }
@@ -3544,6 +4277,14 @@ export async function main(rawArgs = process.argv.slice(2)) {
         printCapabilities();
         return;
     }
+    if (command === 'setup' && subcommand === 'prompt') {
+        setupPromptCommand();
+        return;
+    }
+    if (command === 'setup') {
+        await setupCommand();
+        return;
+    }
     if (command === 'install-skill') {
         await installSkillCommand();
         return;
@@ -3552,6 +4293,18 @@ export async function main(rawArgs = process.argv.slice(2)) {
         await installSkillCommand();
         return;
     }
+    if (command === 'skills' && subcommand === 'path') {
+        skillsPathCommand();
+        return;
+    }
+    if (command === 'skills' && subcommand === 'status') {
+        skillsStatusCommand();
+        return;
+    }
+    if (command === 'skills' && subcommand === 'update') {
+        await skillsUpdateCommand();
+        return;
+    }
     if (command === 'login') {
         await login();
         return;
@@ -3621,6 +4374,14 @@ export async function main(rawArgs = process.argv.slice(2)) {
         await pushPromptArtifact('prompt');
         return;
     }
+    if (command === 'prompts' && subcommand === 'archive') {
+        await setPromptArchivedState(true);
+        return;
+    }
+    if (command === 'prompts' && subcommand === 'restore') {
+        await setPromptArchivedState(false);
+        return;
+    }
     if (command === 'prompts' && subcommand === 'labels' && cliArgs[2] === 'set') {
         await setPromptLabel();
         return;