@formigio/fazemos-cli 0.8.0 → 0.9.0

package/dist/index.js

@@ -552,6 +552,7 @@ orgs
         }
         const data = await api('POST', `/api/organizations/${orgId}/members`, {
             displayName: opts.name,
+            memberType: 'agent',
             role: opts.role,
         });
         console.log(chalk.green(`Created agent: ${data.member.display_name}`));
@@ -5088,39 +5089,260 @@ agentsCmd
         process.exit(1);
     }
 });
+// ── F17 — Project-scoped agents ─────────────────────────────────
+// `agents list` / `agents show` become Project-scoped by default. The
+// pre-F17 Org-level list is still reachable via `--org-only`. Execution
+// status, heartbeats, metrics, budget, and events are unchanged — they
+// live on their own subcommands (agents metrics / work / events / budget /
+// heartbeat) and are not Project-scoped.
+//
+// Spec: specs/tech/platform/F17-project-scoped-agent-resolution-tech-spec.md §8
+// UX:   features/platform/F17-project-scoped-agent-resolution-ux.md §6
+/**
+ * F17 §8.1 — "No active Project AND no override flag" error block.
+ * Q1 ruling (2026-04-20, tech spec §15 item 12): fail with an actionable
+ * multi-line message, exit code 1. NO agents roster is rendered.
+ *
+ * The exact copy is locked in by the tech spec and must match verbatim —
+ * keep this the single call site so it stays canonical.
+ */
+function exitNoActiveProjectForAgentsList() {
+    console.error(chalk.red('Error: No active Project.'));
+    console.error('  Set one with: fazemos projects switch <slug>');
+    console.error('  Or override:  fazemos agents list --all-projects');
+    console.error('                fazemos agents list --org-only');
+    process.exit(1);
+}
+/**
+ * Render one row of the project-agents table. Shared between the default
+ * (active-Project) and `--all-projects` paths so column widths and source
+ * token formatting stay identical.
+ *
+ * Source tokens: the API returns `project_override` / `project` / `org`;
+ * display strips the underscore (tech spec §8.1 "Source column uses the
+ * exact tokens from the API `source` field", but the illustrative output
+ * in §8.1 prints `project-override` hyphenated — matching the UX §6.1
+ * display).
+ */
+function formatAgentSource(source) {
+    if (source === 'project_override')
+        return 'project-override';
+    return source;
+}
+/**
+ * Column-align a table — pad the first N-1 cells to the widest value in
+ * each column. Last column isn't padded (no trailing whitespace). Keeps
+ * the output readable without a dep on an ASCII-table library.
+ */
+function padTable(rows) {
+    if (!rows.length)
+        return [];
+    const cols = rows[0].length;
+    const widths = new Array(cols).fill(0);
+    for (const row of rows) {
+        for (let c = 0; c < cols; c++) {
+            if (row[c].length > widths[c])
+                widths[c] = row[c].length;
+        }
+    }
+    return rows.map((row) => row
+        .map((cell, c) => (c === cols - 1 ? cell : cell.padEnd(widths[c])))
+        .join('  '));
+}
 agentsCmd
     .command('list')
-    .description('List registered agents')
-    .option('-s, --status <status>', 'Filter by status (idle, busy, error, offline)')
+    .description('List agents available to the active Project (org baseline + Project overrides/additions). Use --org-only for the Org-level roster, --all-projects to see all Projects side-by-side.')
+    .option('--project <slug>', 'Override active project for this call')
+    .option('--all-projects', 'List agents across every Project in the active Org', false)
+    .option('--org-only', 'Show only the Org-level agent roster (pre-F17 behavior)', false)
     .action(async (opts) => {
     try {
-        const params = [];
-        if (opts.status)
-            params.push(`status=${opts.status}`);
-        const qs = params.length ? `?${params.join('&')}` : '';
-        const data = await api('GET', `/api/agents${qs}`);
-        if (!data.agents?.length) {
-            console.log(chalk.yellow('No agents registered'));
+        const orgId = requireActiveOrgOrExit();
+        // --org-only: pre-F17 behavior. Calls /api/agents directly; no
+        // Project context. Useful for admins auditing the Org baseline.
+        if (opts.orgOnly) {
+            const data = await api('GET', '/api/agents', undefined, { noProjectHeader: true });
+            if (!data.agents?.length) {
+                console.log(chalk.yellow('No agents registered at the Org level.'));
+                return;
+            }
+            const org = findOrgById(orgId);
+            console.log(chalk.cyan(`Org agents: ${org?.name ?? orgId}`));
+            console.log('');
+            const rows = [['NAME', 'STATUS', 'MODEL']];
+            for (const a of data.agents) {
+                rows.push([
+                    a.display_name,
+                    a.agent_status ?? 'unknown',
+                    a.agent_config?.model ?? '',
+                ]);
+            }
+            for (const line of padTable(rows))
+                console.log(line);
             return;
         }
-        for (const a of data.agents) {
-            const statusIcon = a.agent_status === 'busy' ? chalk.yellow('●')
-                : a.agent_status === 'idle' ? chalk.green('●')
-                    : a.agent_status === 'error' ? chalk.red('●')
-                        : chalk.gray('●');
-            const cost = a.total_cost_usd ? ` $${parseFloat(a.total_cost_usd).toFixed(2)}` : '';
-            const execs = a.total_executions ? ` (${a.total_executions} runs)` : '';
-            console.log(`  ${statusIcon} ${a.display_name} [${a.agent_status || 'unknown'}]${execs}${cost} — ${a.id}`);
+        // --all-projects: iterate Projects in the active Org, render a
+        // flat table with project_slug column.
+        if (opts.allProjects) {
+            // Refresh /auth/me so newly-created Projects are visible.
+            const me = await refreshAuthMeCache();
+            const meOrg = me?.orgs.find((o) => o.id === orgId) ?? findOrgById(orgId);
+            const projects = (meOrg?.projects ?? []).filter((p) => p.status === 'active');
+            if (!projects.length) {
+                console.log(chalk.yellow('No active projects in this organization.'));
+                return;
+            }
+            const rows = [['PROJECT', 'NAME', 'SOURCE', 'STATUS', 'MODEL']];
+            const excludedRows = [];
+            for (const p of projects) {
+                try {
+                    const data = await api('GET', `/api/organizations/${orgId}/projects/${p.id}/agents`, undefined, { noProjectHeader: true });
+                    for (const a of data.agents ?? []) {
+                        rows.push([
+                            p.slug,
+                            a.name,
+                            formatAgentSource(a.source),
+                            a.status ?? 'active',
+                            a.effective_config?.model ?? '',
+                        ]);
+                    }
+                    for (const ex of data.excluded ?? []) {
+                        excludedRows.push([
+                            p.slug,
+                            ex.name,
+                            'excluded',
+                            '—',
+                            '—',
+                        ]);
+                    }
+                }
+                catch (err) {
+                    // Don't break the whole list on one Project's fetch failure —
+                    // log it inline and continue. Matches the pattern of
+                    // `projects list` with stats errors.
+                    const msg = err instanceof Error ? err.message : String(err);
+                    console.error(chalk.yellow(`  (warning) ${p.slug}: ${msg}`));
+                }
+            }
+            if (rows.length === 1 && !excludedRows.length) {
+                console.log(chalk.yellow('No agents resolved for any Project.'));
+                return;
+            }
+            // Merge active + excluded rows into one alignment pass so the
+            // separator row lines up with the main table.
+            const activeCount = rows.length - 1;
+            const allRows = [...rows, ...excludedRows];
+            const formatted = padTable(allRows);
+            for (let i = 0; i <= activeCount; i++)
+                console.log(formatted[i]);
+            if (excludedRows.length) {
+                console.log('-----');
+                for (let i = activeCount + 1; i < formatted.length; i++)
+                    console.log(formatted[i]);
+            }
+            return;
+        }
+        // Default: Project-scoped. Require an active Project OR --project
+        // override; else emit the Q1 error and exit 1.
+        const projectId = await resolveProjectIdForAgentsList(opts.project);
+        if (!projectId)
+            exitNoActiveProjectForAgentsList();
+        const proj = findProjectById(orgId, projectId);
+        const org = findOrgById(orgId);
+        const data = await api('GET', `/api/organizations/${orgId}/projects/${projectId}/agents`, undefined, { noProjectHeader: true });
+        const projName = proj?.name ?? proj?.slug ?? projectId;
+        const orgName = org?.name ?? orgId;
+        console.log(chalk.cyan(`Project: ${projName}  (${orgName})`));
+        console.log('');
+        if (!data.agents?.length && !data.excluded?.length) {
+            console.log(chalk.yellow('No agents available in this Project.'));
+            if (data.org_agent_count === 0) {
+                console.log(chalk.gray('Your Org has no agents yet. Create one with: fazemos agents register --name <name>'));
+            }
+            return;
+        }
+        // Build one unified rows array so header + active rows + excluded
+        // rows share column widths. Excluded rows render below a dashed
+        // separator per tech spec §8.1.
+        const rows = [['NAME', 'SOURCE', 'STATUS', 'MODEL']];
+        const activeCount = data.agents?.length ?? 0;
+        for (const a of data.agents ?? []) {
+            rows.push([
+                a.name,
+                formatAgentSource(a.source),
+                a.status ?? 'active',
+                a.effective_config?.model ?? '',
+            ]);
+        }
+        for (const ex of data.excluded ?? []) {
+            rows.push([ex.name, 'excluded', '—', '—']);
+        }
+        const formatted = padTable(rows);
+        // Header + active rows first.
+        for (let i = 0; i <= activeCount; i++)
+            console.log(formatted[i]);
+        if ((data.excluded?.length ?? 0) > 0) {
+            console.log('-----');
+            for (let i = activeCount + 1; i < formatted.length; i++)
+                console.log(formatted[i]);
         }
     }
     catch (err) {
-        console.error(chalk.red(err.message));
-        process.exit(1);
+        handleScopedError(err);
     }
 });
+/**
+ * Resolve the projectId to use for Project-scoped `agents` subcommands.
+ * Returns the active projectId (from config) or the `--project <slug>`
+ * override resolved through the /auth/me cache. Returns `null` when no
+ * scope is available — the caller decides what error message to emit
+ * (agents-list uses the Q1 multi-line copy; other subcommands use
+ * handleScopedError via the shared MISSING_PROJECT_CONTEXT path).
+ */
+async function resolveProjectIdForAgentsList(slugOverride) {
+    if (slugOverride) {
+        const orgId = getActiveOrgId();
+        if (!orgId)
+            return null;
+        let project = findProjectBySlug(orgId, slugOverride);
+        if (!project) {
+            await refreshAuthMeCache();
+            project = findProjectBySlug(orgId, slugOverride);
+        }
+        if (!project) {
+            console.error(chalk.red(`Unknown project: ${slugOverride}`));
+            console.error(chalk.gray('Run: fazemos projects list'));
+            process.exit(1);
+        }
+        return project.id;
+    }
+    return getActiveProjectId();
+}
+/**
+ * Require a Project scope for a Project-scoped `agents` subcommand
+ * (override/exclude/add/revert/remove). Resolves --project override or
+ * active Project; exits 1 with the uniform "requirement missing: project"
+ * error (matches F15 KD9) if neither is set.
+ */
+async function requireProjectForAgents(slugOverride) {
+    const orgId = requireActiveOrgOrExit();
+    const projectId = await resolveProjectIdForAgentsList(slugOverride);
+    if (!projectId) {
+        console.error(chalk.red('Error: requirement missing: project'));
+        console.error('');
+        console.error(chalk.gray('Set one with:  fazemos projects switch <slug>'));
+        console.error(chalk.gray('Or pass:       --project <slug>'));
+        process.exit(1);
+    }
+    return { orgId, projectId };
+}
+// F17 — `agents show <name>` is redefined to show the effective Project
+// config + merge-source breakdown (tech spec §8.2). The pre-F17 "agent
+// runtime status / current execution" view lives on `agents status` so
+// operators who want heartbeat + running execution info still have it.
 agentsCmd
-    .command('show')
-    .description('Show agent status and details')
+    .command('status')
+    .description('Show agent runtime status (heartbeat, current execution, total cost). Pre-F17 behavior; see `agents show` for Project-scoped effective config.')
     .argument('<id>', 'Agent name or member ID')
     .action(async (id) => {
     try {
@@ -5150,6 +5372,605 @@ agentsCmd
         process.exit(1);
     }
 });
+/**
+ * F17 §8.2 — `agents show <name>`: effective Project config with
+ * merge-source breakdown. Renders:
+ *   - Agent name + display_name + source (one of: org / project /
+ *     project-override)
+ *   - EFFECTIVE CONFIG block with the merged, ready-to-use config
+ *   - SOURCE BREAKDOWN block (for 'project_override' only) listing
+ *     which fields came from the override vs inherited from Org
+ *   - Timestamp footer (Org baseline updated + override created)
+ *   - F18 forward-compat: `Role doc: <path>` line when role_doc_path
+ *     is populated; omitted when null (v1 behavior)
+ */
+agentsCmd
+    .command('show')
+    .description('Show the effective agent config for this Project, including merge-source breakdown when the agent has a Project override.')
+    .argument('<name>', 'Agent name (e.g., marco, kate)')
+    .option('--project <slug>', 'Override active Project for this call')
+    .action(async (name, opts) => {
+    try {
+        const { orgId, projectId } = await requireProjectForAgents(opts.project);
+        const data = await api('GET', `/api/organizations/${orgId}/projects/${projectId}/agents/${encodeURIComponent(name)}`, undefined, { noProjectHeader: true });
+        const a = data.agent;
+        const proj = findProjectById(orgId, projectId);
+        const projSlug = proj?.slug ?? projectId;
+        const sourceLabel = formatAgentSource(a.source);
+        console.log(chalk.cyan(`Agent: ${a.name}  (${a.display_name})`));
+        console.log(`Project: ${projSlug}  ·  Source: ${sourceLabel}`);
+        console.log('');
+        // EFFECTIVE CONFIG
+        console.log(chalk.cyan('EFFECTIVE CONFIG'));
+        const eff = (a.effective_config ?? {});
+        for (const key of Object.keys(eff).sort()) {
+            const v = eff[key];
+            if (typeof v === 'string') {
+                if (v.length > 120) {
+                    // Pretty-print long system prompts with soft wrap preserved.
+                    console.log(`  ${key}: ${JSON.stringify(v.slice(0, 120) + '...')}`);
+                }
+                else {
+                    console.log(`  ${key}: ${JSON.stringify(v)}`);
+                }
+            }
+            else {
+                console.log(`  ${key}: ${JSON.stringify(v)}`);
+            }
+        }
+        // SOURCE BREAKDOWN
+        console.log('');
+        if (a.source === 'project_override') {
+            console.log(chalk.cyan('SOURCE BREAKDOWN'));
+            const overrideFields = new Set(a.override_fields ?? []);
+            const allFields = new Set([
+                ...Object.keys(eff),
+                ...overrideFields,
+            ]);
+            const padKey = Math.max(...Array.from(allFields).map((k) => k.length), 4);
+            for (const key of Array.from(allFields).sort()) {
+                const src = overrideFields.has(key)
+                    ? 'Project override (replaces Org value)'
+                    : 'Org (inherited)';
+                console.log(`  ${key.padEnd(padKey)}  ← ${src}`);
+            }
+        }
+        else if (a.source === 'project') {
+            console.log(chalk.gray('Project-only — not available in other Projects.'));
+        }
+        else {
+            console.log(chalk.gray('Using Org-level config — no Project override active.'));
+        }
+        // Timestamps
+        console.log('');
+        if (a.org_baseline_updated_at) {
+            console.log(chalk.gray(`Org baseline last updated: ${new Date(a.org_baseline_updated_at).toISOString().slice(0, 10)}`));
+        }
+        if (a.override_updated_at && a.source !== 'org') {
+            const label = a.source === 'project_override' ? 'Override created' : 'Project-only created';
+            console.log(chalk.gray(`${label}: ${new Date(a.override_updated_at).toISOString().slice(0, 10)}`));
+        }
+        // F18 forward-compat: role doc line only when populated.
+        if (a.role_doc_path) {
+            const level = a.role_doc_level ? ` (${a.role_doc_level})` : '';
+            console.log('');
+            console.log(chalk.gray(`Role doc: ${a.role_doc_path}${level}`));
+        }
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.code === 'AGENT_NOT_FOUND') {
+            console.error(chalk.red(`Agent '${name}' not found in this Project.`));
+            console.error(chalk.gray('Run: fazemos agents list'));
+            process.exit(1);
+        }
+        handleScopedError(err);
+    }
+});
+// ── F17 §8.3-8.6 — Project-scoped write commands ────────────────────────
+//
+// Shared helpers:
+//   resolveConfigArg  — accept a JSON literal OR a file path (ends in
+//                       .json, OR has no leading '{'). Matches the spec's
+//                       "<json-or-file>" value shape.
+//   confirmOrAbort    — prompt unless --yes. Returns on accept, exits on
+//                       reject (non-destructive; exit code 0).
+//   dryRunLabel       — chalk tag for [DRY RUN] prefix on log lines.
+/**
+ * Accept either inline JSON or a file path as the `--config` value. Matches
+ * the pattern in `agents upload-all` and the UX §6.3 "if flag is a file
+ * path ... reads JSON from that file" contract.
+ *
+ * Heuristic: leading `{` or `[` → parse as JSON literal. Otherwise treat
+ * as a file path, read, and parse. Errors are surfaced with a clear
+ * message identifying which input failed.
+ */
+function resolveConfigArg(val, flag) {
+    const trimmed = val.trim();
+    if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(chalk.red(`Invalid JSON for ${flag}: ${msg}`));
+            process.exit(1);
+        }
+    }
+    // File path. Resolve relative to cwd.
+    const filePath = resolve(trimmed);
+    let raw;
+    try {
+        raw = readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(chalk.red(`Cannot read ${flag} file "${filePath}": ${msg}`));
+        process.exit(1);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(chalk.red(`Invalid JSON in ${filePath}: ${msg}`));
+        process.exit(1);
+    }
+}
+/**
+ * Y/N confirmation prompt. If `yes` is truthy, skips the prompt and
+ * returns. Otherwise prints the prompt and accepts only a y/yes response;
+ * anything else cancels with a "Cancelled." message and exits 0.
+ */
+async function confirmOrAbort(prompt, yes) {
+    if (yes)
+        return;
+    const answer = await promptLine(prompt);
+    if (!answer || !/^y(es)?$/i.test(answer.trim())) {
+        console.log(chalk.gray('Cancelled.'));
+        process.exit(0);
+    }
+}
+/**
+ * F17 Phase 3 Dex SB-2 — pre-check that the DELETE command matches the
+ * agent's actual source before firing the destructive call.
+ *
+ * Without this: `agents revert` on a Project-only agent DELETEs the row
+ * first, then the CLI detects `removed='project_only'` and tells the user
+ * to use `remove` — but the agent is already gone. Non-idempotent.
+ *
+ * With this: GET the agent, compare source, bail out BEFORE the DELETE
+ * if the caller used the wrong command.
+ *
+ * Returns silently when source matches; prints error + exits 1 otherwise.
+ * If the agent doesn't exist (404), lets the caller's error-handler chain
+ * surface the usual `AGENT_NOT_FOUND` copy.
+ */
+async function preCheckAgentSourceForDelete(opts) {
+    let data;
+    try {
+        data = await api('GET', `/api/organizations/${opts.orgId}/projects/${opts.projectId}/agents/${encodeURIComponent(opts.name)}`, undefined, { noProjectHeader: true });
+    }
+    catch (err) {
+        // Let the caller's error chain handle 404 / auth / etc.
+        throw err;
+    }
+    const actual = data.agent.source;
+    if (actual === opts.expectedSource)
+        return;
+    // Plain-English source label for the error.
+    const actualLabel = actual === 'project' ? 'a Project-only agent' :
+        actual === 'project_override' ? 'an Org agent with a Project override' :
+            'an Org agent (no Project customization)';
+    console.error(chalk.red(`${opts.name} is ${actualLabel}.`));
+    console.error(chalk.gray(`Use: ${opts.wrongCommandHint} ${opts.name}`));
+    process.exit(1);
+}
+/**
+ * F17 §8.3 — `agents override <name>`: create/update a Project override
+ * for the named Org agent. PATCH with `{override: <parsed>}`.
+ *
+ * --dry-run prints the shallow-merge diff and exits without calling the
+ * API (Kate Q2). --yes bypasses the confirmation prompt.
+ */
+agentsCmd
+    .command('override')
+    .description('Create or update a Project-level override for an Org agent. Shallow-merge: each top-level field in --config replaces the Org baseline field entirely.')
+    .argument('<name>', 'Agent name (e.g., marco)')
+    .requiredOption('--config <json-or-file>', 'Override config as inline JSON or a file path')
+    .option('--project <slug>', 'Override active Project for this call')
+    .option('--dry-run', 'Print the diff without calling the API', false)
+    .option('--yes', 'Skip the confirmation prompt', false)
+    .action(async (name, opts) => {
+    try {
+        const { orgId, projectId } = await requireProjectForAgents(opts.project);
+        const override = resolveConfigArg(opts.config, '--config');
+        if (typeof override !== 'object' || override === null || Array.isArray(override)) {
+            console.error(chalk.red('--config must be a JSON object, not an array or scalar.'));
+            process.exit(1);
+        }
+        // Fetch current state so we can print a diff and confirm.
+        let current;
+        try {
+            current = await api('GET', `/api/organizations/${orgId}/projects/${projectId}/agents/${encodeURIComponent(name)}`, undefined, { noProjectHeader: true });
+        }
+        catch (err) {
+            if (err instanceof ApiError && err.code === 'AGENT_NOT_FOUND') {
+                console.error(chalk.red(`Agent '${name}' not found in this Project.`));
+                console.error(chalk.gray('Use `fazemos agents add` to create a Project-only agent.'));
+                process.exit(1);
+            }
+            throw err;
+        }
+        const existing = current.agent;
+        const proj = findProjectById(orgId, projectId);
+        const projSlug = proj?.slug ?? projectId;
+        const fieldsToUpdate = Object.keys(override);
+        console.log(chalk.cyan(`Overriding ${name} for project: ${projSlug}`));
+        if (existing.source === 'org') {
+            console.log(`Source: org agent → project-override`);
+        }
+        else if (existing.source === 'project_override') {
+            console.log(`Source: project-override → project-override (updating)`);
+        }
+        else if (existing.source === 'project') {
+            console.log(chalk.yellow(`Warning: ${name} is a Project-only agent — this will be rejected by the API.`));
+            console.log(chalk.gray('Use `fazemos agents add` (update) or PATCH via the UI.'));
+        }
+        console.log(`Fields to update: ${fieldsToUpdate.join(', ')}`);
+        console.log('');
+        console.log(chalk.gray('Shallow merge: each field you set replaces that field in full.'));
+        console.log(chalk.gray('Arrays are not merged — they replace.'));
+        console.log('');
+        console.log(chalk.gray('Diff (Org baseline → Project override):'));
+        const baseline = (existing.org_baseline_config ?? {});
+        for (const k of fieldsToUpdate) {
+            const before = baseline[k];
+            const after = override[k];
+            const beforeStr = before === undefined ? chalk.gray('(unset)') : JSON.stringify(before).slice(0, 80);
+            const afterStr = JSON.stringify(after).slice(0, 80);
+            console.log(`  ${k}:`);
+            console.log(`    − ${beforeStr}`);
+            console.log(`    + ${afterStr}`);
+        }
+        console.log('');
+        if (opts.dryRun) {
+            console.log(chalk.yellow('[dry run] No changes sent to the API.'));
+            return;
+        }
+        if (existing.source === 'org' || existing.source === 'project_override') {
+            console.log(`This will diverge ${name}'s config in ${projSlug} from the Org baseline.`);
+            console.log(`Future Org-level changes to these fields will not propagate.`);
+            await confirmOrAbort('Proceed? [y/N]: ', !!opts.yes);
+        }
+        const result = await api('PATCH', `/api/organizations/${orgId}/projects/${projectId}/agents/${encodeURIComponent(name)}`, { override }, { noProjectHeader: true });
+        console.log(chalk.green(`${result.agent.name} override saved.`));
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.code === 'ORG_AGENT_NOT_FOUND') {
+            console.error(chalk.red(err.message));
+            console.error(chalk.gray('Use `fazemos agents add` to create a Project-only agent.'));
+            process.exit(1);
+        }
+        if (err instanceof ApiError && err.code === 'AGENT_EXCLUDED_USE_REINCLUDE_FIRST') {
+            console.error(chalk.red(err.message));
+            console.error(chalk.gray('Run: fazemos agents list  (to see excluded agents)'));
+            console.error(chalk.gray('Then: PATCH via the UI or a future CLI re-include subcommand.'));
+            process.exit(1);
+        }
+        handleScopedError(err);
+    }
+});
+/**
+ * F17 §8.4 — `agents exclude <name>`: PATCH with `{excluded: true}`.
+ *
+ * Before writing, fetches templates for the active Project and greps each
+ * one's definition for the agent name to produce the impact count in the
+ * confirmation prompt. --dry-run prints the impact and exits; --yes
+ * bypasses confirmation.
+ *
+ * Q6 (tech spec §15 item 13): shadow-on-excluded refuse behavior is
+ * server-side. CLI doesn't need special handling.
+ */
+agentsCmd
+    .command('exclude')
+    .description('Exclude an Org agent from the active Project. Pipelines that reference this agent in this Project will fail.')
+    .argument('<name>', 'Agent name (e.g., atlas)')
+    .option('--project <slug>', 'Override active Project for this call')
+    .option('--dry-run', 'Print impact without calling the API', false)
+    .option('--yes', 'Skip the confirmation prompt', false)
+    .action(async (name, opts) => {
+    try {
+        const { orgId, projectId } = await requireProjectForAgents(opts.project);
+        const proj = findProjectById(orgId, projectId);
+        const projSlug = proj?.slug ?? projectId;
+        // Preflight: fetch templates in this Project, grep for agent name in
+        // each template's definition.phases[].steps[].role. Per spec §8.4.
+        //
+        // This is N+1 (list + detail per template), but Projects typically
+        // have 3-10 templates so the latency is fine. If that grows we can
+        // switch to a server-side `?ref_agent=<name>` query — not needed in v1.
+        const tplList = await api('GET', `/api/pipeline-templates`, undefined, { noProjectHeader: false } // uses active Project header
+        );
+        const refs = [];
+        const targetName = name.toLowerCase();
+        for (const t of tplList.templates ?? []) {
+            try {
+                const detail = await api('GET', `/api/pipeline-templates/${t.id}`, undefined, { noProjectHeader: true });
+                const phases = detail.template?.definition?.phases ?? [];
+                let matched = false;
+                for (const phase of phases) {
+                    for (const step of phase.steps ?? []) {
+                        if ((step.role ?? '').toLowerCase() === targetName || (step.agent ?? '').toLowerCase() === targetName) {
+                            matched = true;
+                            break;
+                        }
+                    }
+                    if (matched)
+                        break;
+                }
+                if (matched)
+                    refs.push({ id: t.id, name: t.name });
+            }
+            catch {
+                // Ignore individual template fetch errors in preflight — the
+                // user will still see the main exclude message.
+            }
+        }
+        console.log(chalk.cyan(`Excluding ${name} from project: ${projSlug}`));
+        console.log('');
+        console.log(`${name} will not appear in this project's effective roster.`);
+        console.log(`Pipelines that reference ${name} will fail if run in this project.`);
+        console.log('');
+        console.log(`Pipelines referencing ${name} in this project: ${refs.length}`);
+        for (const r of refs)
+            console.log(` - ${r.name}`);
+        if (refs.length > 0) {
+            console.log('');
+            console.log(chalk.yellow(`Warning: ${refs.length} pipeline template${refs.length === 1 ? '' : 's'} reference ${name} and will fail.`));
+        }
+        console.log('');
+        if (opts.dryRun) {
+            console.log(chalk.yellow('[dry run] No changes sent to the API.'));
+            return;
+        }
+        await confirmOrAbort('Confirm? [y/N]: ', !!opts.yes);
+        await api('PATCH', `/api/organizations/${orgId}/projects/${projectId}/agents/${encodeURIComponent(name)}`, { excluded: true }, { noProjectHeader: true });
+        console.log(chalk.green(`${name} excluded from ${projSlug}.`));
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.code === 'AGENT_HAS_OVERRIDE_REVERT_FIRST') {
+            console.error(chalk.red(err.message));
+            console.error(chalk.gray(`Run: fazemos agents revert ${name}`));
+            process.exit(1);
+        }
+        if (err instanceof ApiError && err.code === 'ORG_AGENT_NOT_FOUND') {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+        handleScopedError(err);
+    }
+});
+/**
+ * F17 §8.5 — `agents add <name>`: POST a Project-only agent to the
+ * active Project. Required config keys: display_name (or displayName),
+ * systemPrompt, model. Optional: tools, plus anything else the Org
+ * schema supports.
+ *
+ * Shadow guard: API returns 409 AGENT_SHADOWS_ORG when the name collides
+ * with an active Org agent. CLI re-attempts with `allow_shadow=true`
+ * only if `--force-shadow` is passed. Without it (and without --yes),
+ * the CLI prompts; with --yes and no --force-shadow it errors.
+ */
+agentsCmd
+    .command('add')
+    .description('Add a Project-only agent to the active Project. The agent is scoped to this Project — it does not appear in other Projects.')
+    .argument('<name>', 'Agent name (lowercase, alphanumeric + hyphens, 1-64 chars)')
+    .requiredOption('--config <json-or-file>', 'Agent config as inline JSON or a file path. Required keys: display_name, systemPrompt, model.')
+    .option('--project <slug>', 'Override active Project for this call')
+    .option('--force-shadow', 'Force creation even if an Org agent with the same name exists (use with care — creates two agents with the same name).', false)
+    .option('--dry-run', 'Print the intended POST without calling the API', false)
+    .option('--yes', 'Skip the confirmation prompt', false)
+    .action(async (name, opts) => {
+    try {
+        const { orgId, projectId } = await requireProjectForAgents(opts.project);
+        const parsed = resolveConfigArg(opts.config, '--config');
+        // display_name can live in the config blob (as `displayName` or
+        // `display_name`) or be extracted to the top-level payload.
+        const displayName = (typeof parsed.display_name === 'string' && parsed.display_name) ||
+            (typeof parsed.displayName === 'string' && parsed.displayName) ||
+            undefined;
+        const configBlob = { ...parsed };
+        delete configBlob.display_name;
+        delete configBlob.displayName;
+        // Light client-side validation matching spec §4.2. The API
+        // enforces these authoritatively, but catching typos here is a
+        // better UX than a round-trip.
+        if (!displayName) {
+            console.error(chalk.red('--config must include `display_name` (or `displayName`).'));
+            process.exit(1);
+        }
+        if (!configBlob.systemPrompt || typeof configBlob.systemPrompt !== 'string') {
+            console.error(chalk.red('--config must include `systemPrompt` (string).'));
+            process.exit(1);
+        }
+        if (!configBlob.model || typeof configBlob.model !== 'string') {
+            console.error(chalk.red('--config must include `model` (string).'));
+            process.exit(1);
+        }
+        const proj = findProjectById(orgId, projectId);
+        const projSlug = proj?.slug ?? projectId;
+        console.log(chalk.cyan(`Adding Project-only agent to: ${projSlug}`));
+        console.log('');
+        console.log(`Name:    ${name}`);
+        console.log(`Display: ${displayName}`);
+        console.log(`Model:   ${configBlob.model}`);
+        console.log(`Source:  project-only (will not appear in other projects)`);
+        console.log('');
+        if (opts.dryRun) {
+            console.log(chalk.yellow('[dry run] No changes sent to the API.'));
+            console.log(chalk.gray('Body:'));
+            console.log(chalk.gray(JSON.stringify({ name, display_name: displayName, config: configBlob, allow_shadow: !!opts.forceShadow }, null, 2)));
+            return;
+        }
+        await confirmOrAbort('Create? [y/N]: ', !!opts.yes);
+        const body = {
+            name,
+            display_name: displayName,
+            config: configBlob,
+        };
+        if (opts.forceShadow)
+            body.allow_shadow = true;
+        try {
+            const result = await api('POST', `/api/organizations/${orgId}/projects/${projectId}/agents`, body, { noProjectHeader: true });
+            console.log(chalk.green(`${result.agent.name} created in ${projSlug}.`));
+        }
+        catch (err) {
+            if (err instanceof ApiError && err.code === 'AGENT_SHADOWS_ORG') {
+                if (opts.forceShadow)
+                    throw err; // should be impossible
+                console.error(chalk.yellow(`This name collides with Org agent '${name}'.`));
+                console.error(chalk.gray(`Options:`));
+                console.error(chalk.gray(`  - Pick a different name`));
+                console.error(chalk.gray(`  - Customize the Org agent instead: fazemos agents override ${name} --config ...`));
+                console.error(chalk.gray(`  - Force shadow (creates two agents with the same name): add --force-shadow`));
+                process.exit(1);
+            }
+            if (err instanceof ApiError && err.code === 'AGENT_EXCLUDED_IN_PROJECT') {
+                console.error(chalk.red(err.message));
+                console.error(chalk.gray('The Org agent is excluded in this Project. Re-include it first via the UI or a future CLI re-include subcommand.'));
+                process.exit(1);
+            }
+            if (err instanceof ApiError && err.code === 'AGENT_ALREADY_EXISTS') {
+                console.error(chalk.red(err.message));
+                console.error(chalk.gray(`Run: fazemos agents show ${name}  (to see the current config)`));
+                console.error(chalk.gray(`Or:  fazemos agents remove ${name}  (if you want to replace it)`));
+                process.exit(1);
+            }
+            throw err;
+        }
+    }
+    catch (err) {
+        handleScopedError(err);
+    }
+});
+/**
+ * F17 §8.6 — `agents revert <name>`: clear a Project override,
+ * reverting to the Org baseline. DELETE.
+ *
+ * Server distinguishes project_only vs override in the response. We
+ * assert the response is `removed=override` — if it came back as
+ * `removed=project_only`, we error with the spec's guidance to use
+ * `agents remove` instead.
+ */
+agentsCmd
+    .command('revert')
+    .description('Revert a Project override. The agent goes back to using the Org-level config.')
+    .argument('<name>', 'Agent name (e.g., marco)')
+    .option('--project <slug>', 'Override active Project for this call')
+    .option('--yes', 'Skip the confirmation prompt', false)
+    .action(async (name, opts) => {
+    try {
+        const { orgId, projectId } = await requireProjectForAgents(opts.project);
+        const proj = findProjectById(orgId, projectId);
+        const projSlug = proj?.slug ?? projectId;
+        console.log(chalk.cyan(`Reverting ${name} to Org default in project: ${projSlug}`));
+        console.log('');
+        console.log(`Removes Project override. ${name} will use the Org-level config.`);
+        console.log('');
+        // F17 Phase 3 Dex SB-2 — pre-check BEFORE the destructive DELETE so
+        // running `revert` on a Project-only agent errors out with guidance
+        // instead of silently removing the agent.
+        await preCheckAgentSourceForDelete({
+            orgId,
+            projectId,
+            name,
+            expectedSource: 'project_override',
+            wrongCommandHint: 'fazemos agents remove',
+        });
+        await confirmOrAbort('Confirm? [y/N]: ', !!opts.yes);
+        const result = await api('DELETE', `/api/organizations/${orgId}/projects/${projectId}/agents/${encodeURIComponent(name)}`, undefined, { noProjectHeader: true });
+        if (result.removed === 'project_only') {
+            // Should be unreachable after the preCheck, but keep as
+            // defense-in-depth against a race (user concurrently toggles the
+            // agent source between GET and DELETE).
+            console.error(chalk.red(`${name} was removed as Project-only, not reverted.`));
+            console.error(chalk.gray('(Concurrent change detected — the agent may have been swapped between `revert` pre-check and the DELETE. Re-create with `fazemos agents add` if needed.)'));
+            process.exit(1);
+        }
+        console.log(chalk.green(`${name} reverted to Org default.`));
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.code === 'NO_OVERRIDE_TO_REMOVE') {
+            console.error(chalk.red(`${name} has no Project override to revert.`));
+            console.error(chalk.gray('The agent is already using the Org-level config.'));
+            process.exit(1);
+        }
+        if (err instanceof ApiError && err.code === 'USE_PATCH_TO_REINCLUDE') {
+            console.error(chalk.red(err.message));
+            console.error(chalk.gray('To re-include an excluded agent, use the UI or PATCH with `{excluded:false}`.'));
+            process.exit(1);
+        }
+        handleScopedError(err);
+    }
+});
+/**
+ * F17 §8.6 — `agents remove <name>`: DELETE a Project-only agent. This
+ * is actual removal — the agent disappears from the Project. Not the same
+ * as reverting an override.
+ *
+ * Guards against accidental use on an Org override: asserts the server's
+ * `removed` field is `project_only`. If it came back as `override`, we
+ * surface the spec's guidance to use `agents revert` instead.
+ */
+agentsCmd
+    .command('remove')
+    .description('Remove a Project-only agent from the active Project. The agent is permanently removed.')
+    .argument('<name>', 'Agent name (e.g., gus)')
+    .option('--project <slug>', 'Override active Project for this call')
+    .option('--yes', 'Skip the confirmation prompt', false)
+    .action(async (name, opts) => {
+    try {
+        const { orgId, projectId } = await requireProjectForAgents(opts.project);
+        const proj = findProjectById(orgId, projectId);
+        const projSlug = proj?.slug ?? projectId;
+        console.log(chalk.cyan(`Removing Project-only agent ${name} from: ${projSlug}`));
+        console.log('');
+        console.log(`This agent exists only in this project. It will be permanently removed.`);
+        console.log(`Pipelines referencing ${name} will fail if run in this project.`);
+        console.log('');
+        // F17 Phase 3 Dex SB-2 (symmetric) — pre-check BEFORE DELETE so
+        // running `remove` on an Org override errors out with guidance
+        // instead of silently clearing the override.
+        await preCheckAgentSourceForDelete({
+            orgId,
+            projectId,
+            name,
+            expectedSource: 'project',
+            wrongCommandHint: 'fazemos agents revert',
+        });
+        await confirmOrAbort('Confirm? [y/N]: ', !!opts.yes);
+        const result = await api('DELETE', `/api/organizations/${orgId}/projects/${projectId}/agents/${encodeURIComponent(name)}`, undefined, { noProjectHeader: true });
+        if (result.removed === 'override') {
+            console.error(chalk.red(`${name} was cleared as an override, not removed as Project-only.`));
+            console.error(chalk.gray('(Concurrent change detected — the agent may have been swapped between `remove` pre-check and the DELETE. Re-apply with `fazemos agents override` if needed.)'));
+            process.exit(1);
+        }
+        console.log(chalk.green(`${name} removed from ${projSlug}.`));
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.code === 'NO_OVERRIDE_TO_REMOVE') {
+            console.error(chalk.red(`${name} is not a Project-only agent in this Project.`));
+            console.error(chalk.gray(`Run: fazemos agents list  (to see what's available)`));
+            process.exit(1);
+        }
+        if (err instanceof ApiError && err.code === 'USE_PATCH_TO_REINCLUDE') {
+            console.error(chalk.red(err.message));
+            console.error(chalk.gray('To re-include an excluded agent, use the UI or PATCH with `{excluded:false}`.'));
+            process.exit(1);
+        }
+        handleScopedError(err);
+    }
+});
 agentsCmd
     .command('metrics')
     .description('Show agent execution metrics')
@@ -5365,49 +6186,173 @@ agentsCmd
 });
 agentsCmd
     .command('upload-all')
-    .description('Upload all agent definitions from a directory')
+    .description('Upload all agent definitions from a directory. Default: Org-level (pre-F17 behavior, uploads systemPrompt only). With --project <slug>: uploads as Project overrides (agents that exist at Org level) or skips (names without an Org baseline — use `fazemos agents add` for Project-only creation).')
     .argument('<dir>', 'Directory containing .md agent definition files')
-    .action(async (dir) => {
+    .option('--project <slug>', 'Upload to a Project as overrides/additions instead of Org baseline')
+    .option('--dry-run', 'Print the plan without calling the API', false)
+    .option('--yes', 'Skip the confirmation prompt', false)
+    .action(async (dir, opts) => {
     try {
-        const orgId = getActiveOrgId();
-        if (!orgId) {
-            console.error(chalk.red('No active org'));
-            process.exit(1);
-        }
-        const membersData = await api('GET', `/api/organizations/${orgId}/members?type=agent`);
-        const agents = membersData.members.filter((m) => m.member_type === 'agent');
+        const orgId = requireActiveOrgOrExit();
         const resolvedDir = resolve(dir);
         const files = readdirSync(resolvedDir).filter(f => f.endsWith('.md'));
         if (!files.length) {
             console.log(chalk.yellow(`No .md files found in ${resolvedDir}`));
             return;
         }
-        let uploaded = 0;
-        let skipped = 0;
         const norm = (s) => s.toLowerCase().replace(/[-_\s]+/g, ' ').trim();
+        // ── Pre-F17 path: Org-level upload ────────────────────────────────
+        //
+        // --project not set. Kept bit-for-bit compatible with the original
+        // command: same log format, same PATCH path, same skip-on-missing-
+        // agent behavior. --dry-run/--yes are new and optional; they are
+        // inert on this path because the existing behavior doesn't prompt.
+        if (!opts.project) {
+            const membersData = await api('GET', `/api/organizations/${orgId}/members?type=agent`);
+            const agents = membersData.members.filter((m) => m.member_type === 'agent');
+            let uploaded = 0;
+            let skipped = 0;
+            for (const file of files) {
+                const raw = readFileSync(resolve(resolvedDir, file), 'utf-8');
+                const frontmatterMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+                const frontmatter = frontmatterMatch ? frontmatterMatch[1] : '';
+                const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
+                const name = nameMatch ? nameMatch[1].trim() : basename(file, '.md');
+                const agent = agents.find((a) => norm(a.display_name) === norm(name));
+                if (!agent) {
+                    console.log(chalk.yellow(`  ⊘ ${name} — no matching agent`));
+                    skipped++;
+                    continue;
+                }
+                const body = raw.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '').trim();
+                if (opts.dryRun) {
+                    console.log(chalk.yellow(`  [dry run] ${agent.display_name} (${body.length} chars) → Org systemPrompt`));
+                }
+                else {
+                    await api('PATCH', `/api/members/${agent.id}/agent-config`, { systemPrompt: body });
+                    console.log(chalk.green(`  ✓ ${agent.display_name} (${body.length} chars)`));
+                }
+                uploaded++;
+            }
+            const summaryVerb = opts.dryRun ? 'planned' : 'uploaded';
+            console.log(`\n${uploaded} ${summaryVerb}, ${skipped} skipped`);
+            return;
+        }
+        // ── F17 §8.7 — --project path: upload as Project overrides ────────
+        //
+        // HP-4 (Dex): today's upload-all parses ONLY `name:` from frontmatter
+        // and uploads the body as `systemPrompt`. The --project variant
+        // inherits that narrowness — it reads name + body, nothing else.
+        //
+        // Plan (per file):
+        //   - If the Project already has an effective agent at this name AND
+        //     the Org baseline exists: upload as a Project override via
+        //     PATCH /api/organizations/:orgId/projects/:projectId/agents/:name
+        //     with { override: { systemPrompt } }.
+        //   - If the body matches the current systemPrompt (Org baseline OR
+        //     existing override): skip (no change).
+        //   - If no Org agent with that name exists: SKIP with a warning
+        //     pointing the operator at `fazemos agents add`. Project-only
+        //     creation requires display_name + model which upload-all does
+        //     not parse today.
+        //
+        // Full-frontmatter upload-all is explicitly deferred (tech spec §8.7
+        // "Expanded-scope path explicitly deferred." — CLI-IMP-3 in backlog).
+        const { projectId } = await requireProjectForAgents(opts.project);
+        const proj = findProjectById(orgId, projectId);
+        const projSlug = proj?.slug ?? projectId;
+        // Resolve the Project's effective roster — gives us current
+        // systemPrompt values to diff against AND tells us which names have
+        // an Org baseline (source != 'project' — either 'org' or
+        // 'project_override') so we know what can be uploaded as an override.
+        const roster = await api('GET', `/api/organizations/${orgId}/projects/${projectId}/agents`, undefined, { noProjectHeader: true });
+        const byName = new Map();
+        for (const a of roster.agents ?? [])
+            byName.set(norm(a.name), a);
+        console.log(chalk.cyan(`Uploading agents to project: ${projSlug} (not Org level)`));
+        console.log('');
+        const plan = [];
         for (const file of files) {
             const raw = readFileSync(resolve(resolvedDir, file), 'utf-8');
-            // Extract name from frontmatter (name: field), fall back to filename
             const frontmatterMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
             const frontmatter = frontmatterMatch ? frontmatterMatch[1] : '';
             const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
             const name = nameMatch ? nameMatch[1].trim() : basename(file, '.md');
-            const agent = agents.find((a) => norm(a.display_name) === norm(name));
-            if (!agent) {
-                console.log(chalk.yellow(`  ⊘ ${name} — no matching agent`));
-                skipped++;
+            const body = raw.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '').trim();
+            const existing = byName.get(norm(name));
+            if (!existing) {
+                plan.push({ file, name, kind: 'skip-no-org-baseline' });
                 continue;
             }
-            const body = raw.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '').trim();
-            await api('PATCH', `/api/members/${agent.id}/agent-config`, { systemPrompt: body });
-            console.log(chalk.green(`  ✓ ${agent.display_name} (${body.length} chars)`));
-            uploaded++;
+            if (existing.source === 'project') {
+                // Project-only agent already exists at that name. upload-all
+                // doesn't touch Project-only agents in v1 — operator uses
+                // `agents override`-ish path, which for project-only is a PATCH
+                // with `{config: ...}`. That needs display_name/model which
+                // upload-all doesn't parse. Skip with a clear message.
+                plan.push({ file, name, kind: 'skip-is-project-only' });
+                continue;
+            }
+            const currentPrompt = existing.effective_config?.systemPrompt ?? '';
+            if (currentPrompt.trim() === body.trim()) {
+                plan.push({ file, name, kind: 'no-change' });
+                continue;
+            }
+            plan.push({ file, name, kind: 'override-update', body, before: currentPrompt });
+        }
+        // Print the plan.
+        for (const item of plan) {
+            const label = `  ${item.file.padEnd(24)} →`;
+            switch (item.kind) {
+                case 'override-update':
+                    console.log(`${label} Project override (systemPrompt diverges from Org baseline)`);
+                    break;
+                case 'no-change':
+                    console.log(chalk.gray(`${label} No change (Project body matches Org systemPrompt)`));
+                    break;
+                case 'skip-no-org-baseline':
+                    console.log(chalk.yellow(`${label} SKIPPED: no Org agent '${item.name}'; use 'fazemos agents add' for Project-only`));
+                    break;
+                case 'skip-is-project-only':
+                    console.log(chalk.yellow(`${label} SKIPPED: '${item.name}' is Project-only; upload-all only updates overrides on Org agents`));
+                    break;
+            }
+        }
+        const toUpload = plan.filter((p) => p.kind === 'override-update');
+        console.log('');
+        console.log(`Plan: ${toUpload.length} override${toUpload.length === 1 ? '' : 's'} to write, ${plan.filter(p => p.kind === 'no-change').length} unchanged, ${plan.filter(p => p.kind.startsWith('skip-')).length} skipped.`);
+        if (opts.dryRun) {
+            console.log('');
+            console.log(chalk.yellow('[dry run] No changes sent to the API.'));
+            return;
+        }
+        if (toUpload.length === 0) {
+            console.log(chalk.gray('Nothing to upload.'));
+            return;
+        }
+        console.log('');
+        console.log('Uploading as Project overrides. Org-level agents are unchanged.');
+        console.log(`This will diverge these agents' config in ${projSlug} from the Org baseline.`);
+        console.log(`Future Org-level changes to systemPrompt will not propagate to this Project`);
+        console.log(`for overridden fields.`);
+        console.log('');
+        await confirmOrAbort('Proceed? [y/N]: ', !!opts.yes);
+        let uploaded = 0;
+        for (const item of toUpload) {
+            try {
+                await api('PATCH', `/api/organizations/${orgId}/projects/${projectId}/agents/${encodeURIComponent(item.name)}`, { override: { systemPrompt: item.body } }, { noProjectHeader: true });
+                console.log(chalk.green(`  ✓ ${item.name} override saved (${item.body.length} chars)`));
+                uploaded++;
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.error(chalk.red(`  ✗ ${item.name}: ${msg}`));
+            }
         }
-        console.log(`\n${uploaded} uploaded, ${skipped} skipped`);
+        console.log(`\n${uploaded} of ${toUpload.length} uploaded.`);
     }
     catch (err) {
-        console.error(chalk.red(err.message));
-        process.exit(1);
+        handleScopedError(err);
     }
 });
 agentsCmd