@formigio/fazemos-cli 0.8.1 → 0.10.0

package/dist/index.js

@@ -5089,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 {
@@ -5151,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')
@@ -5366,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;
+            }
         }
-        console.log(`\n${uploaded} uploaded, ${skipped} skipped`);
+        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} of ${toUpload.length} uploaded.`);
     }
     catch (err) {
-        console.error(chalk.red(err.message));
-        process.exit(1);
+        handleScopedError(err);
     }
 });
 agentsCmd
@@ -5702,5 +6646,560 @@ ops
         process.exit(1);
     }
 });
+// ── F18 — Project-scoped docs surface ────────────────────────────────
+// Spec: specs/tech/platform/F18-project-scoped-docs-surface-tech-spec.md §8
+//
+// Five subcommands expose the Project docs tree + individual file reads
+// that F17 + F18 API ship. Active-Project-aware (F15): resolve active
+// Project from config; `--project <slug>` overrides. No active Project +
+// no override → exit 1 with the uniform "requirement missing: project"
+// block (matches handleScopedError + the F17 agents subcommands).
+//
+// Server-side F18 /docs/file currently returns a flat
+//   { path, file_type, content, sha, cached_at, etag }
+// envelope (see fazemos-api src/services/projectDocsService.ts). The tech
+// spec §4.2 also describes `frontmatter`, `body`, and `source` fields on
+// the response — those are Phase 3 web-surface additions not present in
+// the Phase 2 D2 API. The CLI renders the header line from the response's
+// `file_type` and the composed `<docs_root>/<path>` string (since the
+// source.path field doesn't exist yet on the wire). This is called out in
+// the handoff report as an API contract gap.
+//
+// Step-doc 422 handling (Phase 2 revision R2): when the server returns
+// 422 with code STEP_DOC_* and a `validation_errors` array, `docs cat`
+// prints the errors to stderr and exits 2 (distinct from the generic
+// error exit 1 so scripts can branch on "malformed doc" vs other failures).
+const docs = program.command('docs').description('Project docs browser. Read the Project-scoped tree and individual files that F18 exposes (Project agents, steps, and general docs) without opening the web UI.');
+/**
+ * F18 — resolve {orgId, projectId, projectSlug} for a docs subcommand.
+ * Mirrors F17's `requireProjectForAgents` but also surfaces the project
+ * slug for display purposes (header lines, GitHub URLs, local-path probe).
+ *
+ * On no-active-Project + no-override: emits the uniform F15 "requirement
+ * missing: project" block and exits 1. Reuses the wording from
+ * handleScopedError — the KD9 convention says the CLI always prints this
+ * as a triple-hint block (switch / --project / --all-projects), but
+ * --all-projects has no meaning for docs subcommands (each Project has
+ * its own docs tree — "all-projects" would be N API calls with no unified
+ * output). We omit the --all-projects hint here on purpose.
+ */
+async function requireProjectForDocs(slugOverride) {
+    const orgId = requireActiveOrgOrExit();
+    let projectId = null;
+    let projectSlug = null;
+    if (slugOverride) {
+        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);
+        }
+        projectId = project.id;
+        projectSlug = project.slug;
+    }
+    else {
+        projectId = getActiveProjectId();
+        if (projectId) {
+            const proj = findProjectById(orgId, projectId);
+            projectSlug = proj?.slug ?? null;
+        }
+    }
+    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);
+    }
+    // projectSlug can still be null if the cache is empty and we went the
+    // active-project path — refresh once so the smoke-test path of "I just
+    // authed in another shell" doesn't print UUIDs in headers.
+    if (!projectSlug) {
+        await refreshAuthMeCache();
+        const proj = findProjectById(orgId, projectId);
+        projectSlug = proj?.slug ?? projectId; // fall back to UUID if still unknown
+    }
+    return { orgId, projectId, projectSlug };
+}
+/**
+ * Render the `source` block as a short header label for `docs cat`.
+ * Tech spec §4.2 discriminator:
+ *   file                → "file"
+ *   file + level='org'  → "file (org)"
+ *   system_config       → "system config"
+ *   template            → "template"
+ * Falls back to "file" when the response pre-dates Phase 4b and omits
+ * the `source` block entirely (defensive — the API always ships it now).
+ */
+function renderOriginLabel(source) {
+    if (!source)
+        return 'file';
+    if (source.type === 'system_config')
+        return 'system config';
+    if (source.type === 'template')
+        return 'template';
+    if (source.level === 'org' || source.level === 'org_db')
+        return 'file (org)';
+    return 'file';
+}
+/**
+ * Fetch a Project's docs tree. Returns the raw payload. Swallows nothing —
+ * callers that want empty-state friendly output should branch on
+ * `payload.empty` + `payload.reason`.
+ */
+async function fetchDocsTree(orgId, projectId) {
+    return (await api('GET', `/api/organizations/${orgId}/projects/${projectId}/docs/tree`, undefined, { noProjectHeader: true }));
+}
+/**
+ * Render a flat list of tree entries as an indented text tree. The API
+ * returns paths with embedded slashes ("docs/product/fazemos-concept.md")
+ * and entries for both files and directories. We build a directory map
+ * from the entries and walk it alphabetically for stable output.
+ *
+ * Output format matches tech spec §8.2 — directory names end with `/`,
+ * files get 2-space indent per nesting level, and a file-type badge is
+ * appended for `agent` / `step` files (not `doc` — those are the default
+ * and badging every markdown file would be noisy). Size is NOT printed
+ * (noisy at list scale). Directory file-counts are computed locally.
+ */
+function renderDocsTree(entries) {
+    const root = { name: '', fullPath: '', isDir: true, children: new Map() };
+    function insert(path, entry, forceDir = false) {
+        const parts = path.split('/');
+        let cur = root;
+        for (let i = 0; i < parts.length; i++) {
+            const part = parts[i];
+            const isLast = i === parts.length - 1;
+            const isDir = !isLast || forceDir || entry?.type === 'dir';
+            let child = cur.children.get(part);
+            if (!child) {
+                child = {
+                    name: part,
+                    fullPath: parts.slice(0, i + 1).join('/'),
+                    isDir,
+                    children: new Map(),
+                };
+                cur.children.set(part, child);
+            }
+            if (isLast) {
+                child.entry = entry;
+                // Once marked as dir (by its own entry), don't downgrade.
+                if (isDir)
+                    child.isDir = true;
+            }
+            cur = child;
+        }
+    }
+    for (const e of entries) {
+        insert(e.path, e, e.type === 'dir');
+    }
+    function countFiles(node) {
+        if (!node.isDir)
+            return 1;
+        let n = 0;
+        for (const c of node.children.values())
+            n += countFiles(c);
+        return n;
+    }
+    const lines = [];
+    function walk(node, depth) {
+        const kids = Array.from(node.children.values()).sort((a, b) => {
+            // Directories first, then files, both alphabetical.
+            if (a.isDir !== b.isDir)
+                return a.isDir ? -1 : 1;
+            return a.name.localeCompare(b.name);
+        });
+        for (const c of kids) {
+            const indent = '  '.repeat(depth);
+            if (c.isDir) {
+                const count = countFiles(c);
+                const tag = count ? chalk.gray(`  (${count} ${count === 1 ? 'file' : 'files'})`) : '';
+                lines.push(`${indent}${c.name}/${tag}`);
+                walk(c, depth + 1);
+            }
+            else {
+                const ft = c.entry?.file_type;
+                const badge = ft === 'agent'
+                    ? chalk.cyan(' [agent]')
+                    : ft === 'step'
+                        ? chalk.magenta(' [step]')
+                        : '';
+                lines.push(`${indent}${c.name}${badge}`);
+            }
+        }
+    }
+    walk(root, 0);
+    return lines;
+}
+/**
+ * Format the "Synced N ago" sub-header from a cached_at ISO string. Keep
+ * wording identical to UX §5.1 example ("Synced just now") when <30s.
+ */
+function formatSyncedLine(cachedAtIso) {
+    try {
+        const cached = new Date(cachedAtIso).getTime();
+        const now = Date.now();
+        const seconds = Math.max(0, Math.floor((now - cached) / 1000));
+        if (seconds < 30)
+            return 'Synced just now';
+        if (seconds < 90)
+            return 'Synced 1 minute ago';
+        if (seconds < 60 * 60)
+            return `Synced ${Math.floor(seconds / 60)} minutes ago`;
+        if (seconds < 2 * 60 * 60)
+            return 'Synced 1 hour ago';
+        return `Synced ${Math.floor(seconds / 3600)} hours ago`;
+    }
+    catch {
+        return `Synced at ${cachedAtIso}`;
+    }
+}
+// ── docs tree ────────────────────────────────────────────────────────
+docs
+    .command('tree')
+    .description('Show the Project\'s docs tree (agents/, steps/, docs/, plus the Project CLAUDE.md). Output is stable text suitable for piping.')
+    .option('--include-shared', 'Also print Org-shared docs (under `docs/` and root CLAUDE.md) as a second section', false)
+    .option('--project <slug>', 'Override active Project for this call')
+    .action(async (opts) => {
+    try {
+        const { orgId, projectId, projectSlug } = await requireProjectForDocs(opts.project);
+        const payload = await fetchDocsTree(orgId, projectId);
+        const repoBadge = payload.repo ? `${payload.repo} at ${payload.root ?? ''}` : '(no repo configured)';
+        console.log(chalk.cyan(`Docs — ${projectSlug} (${repoBadge})`));
+        console.log(chalk.gray(formatSyncedLine(payload.cached_at)));
+        console.log('');
+        if (payload.empty) {
+            if (payload.reason === 'no_docs_repo') {
+                console.log(chalk.yellow('No docs repository configured.'));
+                console.log(chalk.gray('  Set one with: fazemos projects update <slug> --docs-repo <owner/name> --docs-root <path>'));
+            }
+            else if (payload.reason === 'no_connection') {
+                console.log(chalk.yellow('Project has no active GitHub Connection.'));
+                console.log(chalk.gray('  Set one up with: fazemos connections ...'));
+            }
+            else {
+                console.log(chalk.yellow('Docs tree is empty.'));
+            }
+            return;
+        }
+        for (const line of renderDocsTree(payload.tree))
+            console.log(line);
+        if (opts.includeShared) {
+            console.log('');
+            console.log(chalk.gray('── Org shared ─────────────────────────────────────────'));
+            if (payload.org_shared && payload.org_shared.length) {
+                for (const line of renderDocsTree(payload.org_shared))
+                    console.log(line);
+            }
+            else {
+                // Phase 2 API does not yet populate org_shared (see the file-level
+                // note at the top of this block). Tell the operator what we see.
+                console.log(chalk.gray('(no org-shared docs returned by the API — Phase 2 ships Project-only)'));
+            }
+        }
+    }
+    catch (err) {
+        handleScopedError(err);
+    }
+});
+// ── docs cat ─────────────────────────────────────────────────────────
+/**
+ * F18 §8 — step-doc validation failure exit code. Distinct from the
+ * generic error exit 1 so operator scripts can branch on "file is
+ * structurally invalid" vs "server 5xx / auth / other".
+ */
+const DOCS_STEP_VALIDATION_EXIT = 2;
+docs
+    .command('cat')
+    .description('Print a Project doc to stdout. Adds a one-line header showing the file type and source path. On malformed step docs, prints validation errors to stderr and exits 2.')
+    .argument('<path>', 'Relative path under docs_root (e.g., agents/marco.md, steps/feature-pipeline/tech-spec.md)')
+    .option('--project <slug>', 'Override active Project for this call')
+    .action(async (relPath, opts) => {
+    try {
+        const { orgId, projectId } = await requireProjectForDocs(opts.project);
+        // Phase 4b: the API now ships `source.path` on every /docs/file
+        // response (tech spec §4.2), so the Phase-3b tree pre-fetch that
+        // compensated for the missing field is gone. `source.path` is the
+        // authoritative repo-relative path. `tree` is only needed for the
+        // Org-shared fallback below (kept for resilience — if the server
+        // ever omits `source`, this still degrades to a helpful header).
+        let payload;
+        try {
+            payload = (await api('GET', `/api/organizations/${orgId}/projects/${projectId}/docs/file?path=${encodeURIComponent(relPath)}`, undefined, { noProjectHeader: true }));
+        }
+        catch (err) {
+            // Phase 2 revision R2: 422 on malformed step docs. The API
+            // returns `{ error, code: STEP_DOC_*, details: { path, validation_errors: [...] } }`.
+            if (err instanceof ApiError &&
+                err.status === 422 &&
+                typeof err.code === 'string' &&
+                err.code.startsWith('STEP_DOC_')) {
+                const body = (err.body ?? {});
+                console.error(chalk.red(`Error: ${err.message}`));
+                console.error(chalk.red(`  Code: ${err.code}`));
+                const ve = body.details?.validation_errors ?? [];
+                if (ve.length) {
+                    console.error(chalk.red('  Validation errors:'));
+                    for (const v of ve) {
+                        const field = v.field ? `${v.field}: ` : '';
+                        console.error(chalk.red(`    - ${field}${v.message ?? v.code ?? 'unknown'}`));
+                    }
+                }
+                process.exit(DOCS_STEP_VALIDATION_EXIT);
+            }
+            throw err;
+        }
+        // Header: file type + source discriminator + repo-relative path.
+        // Phase 4b: `source.path` / `source.type` / `source.level` are
+        // always present on a 200. The header reflects the §4.2 source
+        // block so an operator piping `docs cat` to a reviewer sees
+        // exactly where the bytes came from (file vs. system_config vs.
+        // template-inline).
+        const sourcePath = payload.source?.path ?? payload.path;
+        const typeLabel = payload.file_type === 'agent'
+            ? chalk.cyan('agent')
+            : payload.file_type === 'step'
+                ? chalk.magenta('step')
+                : chalk.gray('doc');
+        const originLabel = renderOriginLabel(payload.source);
+        console.log(chalk.gray(`# ${typeLabel} ${chalk.gray('·')} ${originLabel}: ${sourcePath}`));
+        console.log('');
+        if (payload.content == null) {
+            // DB-sourced response (system_config / template) per tech spec §4.2.
+            // content is null; the callable body is in `body` (Phase 3+).
+            if (payload.body) {
+                console.log(payload.body);
+            }
+            else {
+                console.log(chalk.gray('(no file content — this doc is sourced from system config / template inline; body field not yet exposed)'));
+            }
+            return;
+        }
+        // Trim trailing newlines; re-emit exactly one so `| grep` output
+        // doesn't end with multiple blank lines.
+        process.stdout.write(payload.content);
+        if (!payload.content.endsWith('\n'))
+            process.stdout.write('\n');
+    }
+    catch (err) {
+        handleScopedError(err);
+    }
+});
+docs
+    .command('search')
+    .description('Search the Project docs tree by filename/path (case-insensitive). Phase 3: path-match only; server-side full-text search is deferred per spec §8.6.')
+    .argument('<query>', 'Substring to search for in file paths')
+    .option('--scope <scope>', 'Scope: this-project (default) | agents | steps | all', 'this-project')
+    .option('--project <slug>', 'Override active Project for this call')
+    .action(async (query, opts) => {
+    const scope = (opts.scope ?? 'this-project');
+    if (!['this-project', 'agents', 'steps', 'all'].includes(scope)) {
+        console.error(chalk.red(`Invalid --scope "${opts.scope}". Allowed: this-project, agents, steps, all`));
+        process.exit(1);
+    }
+    try {
+        const { orgId, projectId } = await requireProjectForDocs(opts.project);
+        const payload = await fetchDocsTree(orgId, projectId);
+        const pool = [];
+        for (const e of payload.tree)
+            if (e.type === 'file')
+                pool.push(e);
+        if (scope === 'all') {
+            for (const e of payload.org_shared ?? [])
+                if (e.type === 'file')
+                    pool.push(e);
+        }
+        const filtered = pool.filter((e) => {
+            if (scope === 'agents')
+                return e.file_type === 'agent';
+            if (scope === 'steps')
+                return e.file_type === 'step';
+            return true; // this-project | all
+        });
+        const q = query.toLowerCase();
+        const matches = filtered.filter((e) => e.path.toLowerCase().includes(q));
+        if (!matches.length) {
+            console.log(chalk.yellow(`No matches for "${query}" in scope "${scope}".`));
+            return;
+        }
+        // Highlight the matched substring. chalk.yellow the match so it's
+        // visible even in monochrome terminals (dim doesn't show well on
+        // light backgrounds).
+        for (const e of matches) {
+            const low = e.path.toLowerCase();
+            let out = '';
+            let i = 0;
+            while (i < e.path.length) {
+                const at = low.indexOf(q, i);
+                if (at < 0) {
+                    out += e.path.slice(i);
+                    break;
+                }
+                out += e.path.slice(i, at);
+                out += chalk.yellow(e.path.slice(at, at + q.length));
+                i = at + q.length;
+            }
+            const badge = e.file_type === 'agent'
+                ? chalk.cyan(' [agent]')
+                : e.file_type === 'step'
+                    ? chalk.magenta(' [step]')
+                    : '';
+            console.log(`  ${out}${badge}`);
+        }
+        console.log(chalk.gray(`\n${matches.length} ${matches.length === 1 ? 'match' : 'matches'} in scope "${scope}".`));
+    }
+    catch (err) {
+        handleScopedError(err);
+    }
+});
+// ── docs path ────────────────────────────────────────────────────────
+/**
+ * F18 §8.5 — print the local workspace clone path for this Project,
+ * falling back to the GitHub URL when no local clone is detected.
+ *
+ * Local detection heuristic:
+ *   1. $FAZEMOS_WORKSPACE_PATH env var, if set + dir exists.
+ *   2. `~/development/<repo-name>/` (the Fazemos convention) + dir exists.
+ * If either matches, the full path is `<workspace>/<docs_root>`.
+ *
+ * When neither matches, we print the GitHub tree URL
+ * (https://github.com/<owner>/<repo>/tree/<branch>/<root>) so `open $(fazemos docs path)`
+ * on a fresh machine gracefully routes to the web UI instead of failing.
+ */
+docs
+    .command('path')
+    .description('Print the local filesystem path to this Project\'s docs root, or the GitHub URL if no local workspace clone is detected. Useful for `cd $(fazemos docs path)`.')
+    .option('--project <slug>', 'Override active Project for this call')
+    .action(async (opts) => {
+    try {
+        const { orgId, projectId } = await requireProjectForDocs(opts.project);
+        const payload = await fetchDocsTree(orgId, projectId);
+        if (!payload.repo) {
+            console.error(chalk.red('Project has no docs repository configured.'));
+            process.exit(1);
+        }
+        const repo = payload.repo;
+        const root = payload.root ?? '';
+        const branch = payload.branch ?? 'main';
+        // Local probe.
+        const candidates = [];
+        if (process.env.FAZEMOS_WORKSPACE_PATH)
+            candidates.push(process.env.FAZEMOS_WORKSPACE_PATH);
+        const home = process.env.HOME;
+        const repoName = repo.split('/').pop() ?? '';
+        if (home && repoName)
+            candidates.push(`${home}/development/${repoName}`);
+        for (const c of candidates) {
+            try {
+                if (existsSync(c) && statSync(c).isDirectory()) {
+                    // Emit to stdout only — the whole point is that `cd $(fazemos docs path)` works.
+                    console.log(root ? `${c}/${root}` : c);
+                    return;
+                }
+            }
+            catch {
+                // ignore
+            }
+        }
+        // No local clone — print the GitHub URL.
+        const url = root
+            ? `https://github.com/${repo}/tree/${branch}/${root}`
+            : `https://github.com/${repo}/tree/${branch}`;
+        console.log(url);
+    }
+    catch (err) {
+        handleScopedError(err);
+    }
+});
+// ── docs open ────────────────────────────────────────────────────────
+/**
+ * F18 §8 — open a doc. If the workspace repo is cloned locally AND we're
+ * currently inside that clone (heuristic: cwd's git-root has a remote
+ * matching the Project's configured docs_repo), launch $EDITOR. Otherwise
+ * print the GitHub blob URL so operators on a fresh machine get a sensible
+ * fallback.
+ *
+ * Why the "cwd is the git clone" heuristic rather than just "any clone
+ * exists anywhere on disk"? Operators routinely run the CLI from inside
+ * workspace shells (that's where the Fazemos CLI lives in the workflow)
+ * and expect `fazemos docs open` to touch the same clone they're editing.
+ * If they're in a different shell, opening GitHub in a browser is the
+ * safer action than editing a clone they didn't ask about.
+ */
+docs
+    .command('open')
+    .description('Open a Project doc. If you\'re inside the workspace repo clone, launches $EDITOR on the file; otherwise prints the GitHub blob URL.')
+    .argument('<path>', 'Relative path under docs_root (e.g., agents/marco.md)')
+    .option('--project <slug>', 'Override active Project for this call')
+    .action(async (relPath, opts) => {
+    try {
+        const { orgId, projectId } = await requireProjectForDocs(opts.project);
+        const payload = await fetchDocsTree(orgId, projectId);
+        if (!payload.repo) {
+            console.error(chalk.red('Project has no docs repository configured.'));
+            process.exit(1);
+        }
+        const repo = payload.repo;
+        const root = payload.root ?? '';
+        const branch = payload.branch ?? 'main';
+        // Heuristic: are we inside a git clone whose origin matches `repo`?
+        let localWorkspacePath = null;
+        try {
+            const gitRoot = execSync('git rev-parse --show-toplevel', {
+                encoding: 'utf-8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+            }).trim();
+            if (gitRoot) {
+                const originUrl = execSync('git config --get remote.origin.url', {
+                    encoding: 'utf-8',
+                    stdio: ['ignore', 'pipe', 'ignore'],
+                    cwd: gitRoot,
+                }).trim();
+                // Accept any URL form that ends with the repo's `owner/name`
+                // (with optional `.git` suffix). Covers https, ssh, and git://.
+                const re = new RegExp(`[:/]${repo.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\$&')}(?:\\.git)?$`);
+                if (re.test(originUrl)) {
+                    localWorkspacePath = gitRoot;
+                }
+            }
+        }
+        catch {
+            // Not a git repo, or git not available — fall through to URL.
+        }
+        if (localWorkspacePath) {
+            const fullPath = root
+                ? `${localWorkspacePath}/${root}/${relPath}`
+                : `${localWorkspacePath}/${relPath}`;
+            const editor = process.env.EDITOR || process.env.VISUAL;
+            if (!editor) {
+                console.error(chalk.red('No $EDITOR or $VISUAL configured. Set one (e.g., `export EDITOR=code`) or re-run from outside the workspace clone to get the GitHub URL.'));
+                // Still print the full local path so the operator can open it manually.
+                console.log(fullPath);
+                process.exit(1);
+            }
+            try {
+                execSync(`${editor} "${fullPath}"`, { stdio: 'inherit' });
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.error(chalk.red(`Failed to launch editor: ${msg}`));
+                process.exit(1);
+            }
+            return;
+        }
+        // Not inside the workspace clone — print the GitHub blob URL.
+        const url = root
+            ? `https://github.com/${repo}/blob/${branch}/${root}/${relPath}`
+            : `https://github.com/${repo}/blob/${branch}/${relPath}`;
+        console.log(url);
+    }
+    catch (err) {
+        handleScopedError(err);
+    }
+});
 program.parse();
 //# sourceMappingURL=index.js.map