@formigio/fazemos-cli 0.10.35 → 0.10.37

package/dist/index.js

@@ -110,6 +110,32 @@ function parseJson(val, flag) {
         process.exit(1);
     }
 }
+/**
+ * Parse JSON from an inline string or `@filepath`. Empty string returns null (clears the field).
+ * Used by --verification and --uat flags.
+ */
+function parseJsonOrFile(val, flag) {
+    if (val === '')
+        return null;
+    let raw = val;
+    if (val.startsWith('@')) {
+        const filePath = resolve(val.slice(1));
+        try {
+            raw = readFileSync(filePath, 'utf-8');
+        }
+        catch (err) {
+            console.error(chalk.red(`Cannot read ${flag} file "${filePath}": ${err.message}`));
+            process.exit(1);
+        }
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        console.error(chalk.red(`Invalid JSON for ${flag}. Check quoting and syntax.`));
+        process.exit(1);
+    }
+}
 /** Resolve a value that may be `@filepath` (reads file contents) or inline text. */
 function resolveFileOrInline(val) {
     if (val.startsWith('@')) {
@@ -1108,7 +1134,8 @@ projects
 });
 projects
     .command('create')
-    .description('Create a new project in the active organization. Owner/admin only. Slug is immutable after creation — pick carefully.')
+    .description('Create a new project in the active organization. Owner/admin only. Slug is immutable after creation — pick carefully.\n\n' +
+    'Next: `fazemos projects setup <slug>` to bind docs and connection.')
     .argument('<slug>', 'URL slug (lowercase letters, numbers, hyphens; 1-32 chars). Used in URLs and CLI config — cannot be changed.')
     .requiredOption('-n, --name <name>', 'Human-readable name (max 200 chars)')
     .option('-d, --description <desc>', 'Optional description (max 2000 chars)')
@@ -1337,7 +1364,8 @@ projects
 // ── F16 — projects set-connection (binds a Connection to a project) ─
 projects
     .command('set-connection')
-    .description('Bind a GitHub Connection to a project. Pass "none" to unbind. Owner/admin only.')
+    .description('If this is a fresh project, use `fazemos projects setup` instead — that command binds docs + connection together.\n\n' +
+    'Bind a GitHub Connection to a project. Pass "none" to unbind. Owner/admin only.')
     .argument('<slug>', 'Project slug')
     .argument('<connection>', 'Connection ID, or "none" to unbind')
     .action(async (slug, connection) => {
@@ -1390,6 +1418,200 @@ projects
         process.exit(1);
     }
 });
+// ── F42 — projects setup (binds docs + connection in one call) ──────────────
+projects
+    .command('setup')
+    .description('Bind docs repo, docs root, and/or VCS connection to an existing project in one audited admin call. ' +
+    'Owner/admin only — agent identities are rejected. At least one flag required.')
+    .argument('<slug>', 'Project slug')
+    .option('--docs-repo <owner/repo>', 'Docs repository in <owner>/<repo> format (omit to leave unchanged)')
+    .option('--docs-root <ROOT|path>', 'Docs root path. Pass ROOT (case-insensitive) for repo root. Omit to leave unchanged.')
+    .option('--vcs-connection-id <uuid>', 'VCS connection UUID to bind (omit to leave unchanged)')
+    .option('--json', 'Emit JSON instead of human-readable output')
+    .action(async (slug, opts) => {
+    // ── Client-side validation ──────────────────────────────────
+    const hasDocsRepo = opts.docsRepo !== undefined;
+    const hasDocsRoot = opts.docsRoot !== undefined;
+    const hasVcsConnectionId = opts.vcsConnectionId !== undefined;
+    if (!hasDocsRepo && !hasDocsRoot && !hasVcsConnectionId) {
+        const msg = 'No flags passed. Provide at least one of --docs-repo, --docs-root, --vcs-connection-id.';
+        if (opts.json) {
+            console.log(JSON.stringify({ error: { code: 'NO_FLAGS_PASSED', message: msg } }));
+        }
+        else {
+            console.error(chalk.red(msg));
+            console.error(chalk.gray('Run: fazemos projects setup --help'));
+        }
+        process.exit(1);
+        return; // guard: process.exit is mocked in tests
+    }
+    if (hasDocsRoot) {
+        const rawRoot = opts.docsRoot;
+        if (rawRoot.trim() === '') {
+            const msg = 'docs_root_empty: --docs-root cannot be an empty string or whitespace. Pass ROOT for repo root or a valid subpath.';
+            if (opts.json) {
+                console.log(JSON.stringify({ error: { code: 'docs_root_empty', message: msg } }));
+            }
+            else {
+                console.error(chalk.red(msg));
+                console.error(chalk.gray('See: docs/architecture/repo-root-vs-subdir-docs.md'));
+            }
+            process.exit(1);
+            return; // guard: process.exit is mocked in tests
+        }
+        if (rawRoot.length > 500) {
+            const msg = `docs_root_too_long: --docs-root exceeds 500 characters (got ${rawRoot.length}).`;
+            if (opts.json) {
+                console.log(JSON.stringify({ error: { code: 'docs_root_too_long', message: msg } }));
+            }
+            else {
+                console.error(chalk.red(msg));
+            }
+            process.exit(1);
+            return; // guard: process.exit is mocked in tests
+        }
+    }
+    if (hasDocsRepo && opts.docsRepo !== null) {
+        const repoPattern = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+        if (!repoPattern.test(opts.docsRepo)) {
+            const msg = `docs_repo_shape: --docs-repo must be in <owner>/<repo> format (got: ${opts.docsRepo}).`;
+            if (opts.json) {
+                console.log(JSON.stringify({ error: { code: 'docs_repo_shape', message: msg } }));
+            }
+            else {
+                console.error(chalk.red(msg));
+            }
+            process.exit(1);
+            return; // guard: process.exit is mocked in tests
+        }
+    }
+    // ── Resolve slug → project ID ──────────────────────────────
+    const orgId = requireActiveOrgOrExit();
+    let project = findProjectBySlug(orgId, slug);
+    if (!project) {
+        await refreshAuthMeCache();
+        project = findProjectBySlug(orgId, slug);
+    }
+    if (!project) {
+        const msg = `Unknown project: ${slug}`;
+        if (opts.json) {
+            console.log(JSON.stringify({ error: { code: 'PROJECT_NOT_FOUND', message: msg } }));
+        }
+        else {
+            console.error(chalk.red(msg));
+            console.log(chalk.gray('Run: fazemos projects list'));
+        }
+        process.exit(1);
+        return; // guard: process.exit is mocked in tests
+    }
+    // ── Build request body ─────────────────────────────────────
+    // OQ-3: ROOT (case-insensitive) → null (means "repo root" at API)
+    const body = {};
+    if (hasDocsRepo)
+        body.docsRepo = opts.docsRepo ?? null;
+    if (hasDocsRoot) {
+        body.docsRoot = opts.docsRoot.toUpperCase() === 'ROOT' ? null : opts.docsRoot;
+    }
+    if (hasVcsConnectionId)
+        body.vcsConnectionId = opts.vcsConnectionId ?? null;
+    // ── API call ───────────────────────────────────────────────
+    try {
+        const data = await api('POST', `/api/admin/projects/${project.id}/setup`, body, { noProjectHeader: true });
+        if (opts.json) {
+            console.log(JSON.stringify({
+                status: 'ok',
+                project: data.project,
+                auditLogId: data.auditLogId,
+                changes: data.changes,
+            }));
+            return;
+        }
+        // ── Human-readable success output (Sage UX §"Success output") ──
+        const p = data.project;
+        const changes = data.changes ?? {};
+        const changedFields = Object.keys(changes);
+        const passedFields = Object.keys(body);
+        const unchangedFields = passedFields.filter(f => !changedFields.includes(f));
+        console.log(chalk.green(`✓ ${p.name} (${p.slug}) — onboarded`));
+        if (changedFields.includes('docsRepo') || passedFields.includes('docsRepo')) {
+            const val = p.docsRepo ?? '(cleared)';
+            const marker = changedFields.includes('docsRepo') ? '' : chalk.gray(' (unchanged)');
+            console.log(`  docs_repo:           ${val}${marker}`);
+        }
+        if (changedFields.includes('docsRoot') || passedFields.includes('docsRoot')) {
+            const val = p.docsRoot === null ? 'ROOT  (repo root — no subdirectory)' : p.docsRoot;
+            const marker = changedFields.includes('docsRoot') ? '' : chalk.gray(' (unchanged)');
+            console.log(`  docs_root:           ${val}${marker}`);
+        }
+        if (changedFields.includes('vcsConnectionId') || passedFields.includes('vcsConnectionId')) {
+            const val = p.vcsConnectionId ?? '(cleared)';
+            const marker = changedFields.includes('vcsConnectionId') ? '' : chalk.gray(' (unchanged)');
+            console.log(`  vcs_connection_id:   ${val}${marker}`);
+        }
+        if (unchangedFields.length > 0) {
+            console.log(chalk.gray(`  (unchanged: ${unchangedFields.join(', ')})`));
+        }
+        console.log(`  Audit:               logged as project_setup (id: ${data.auditLogId})`);
+    }
+    catch (err) {
+        if (opts.json) {
+            console.log(JSON.stringify({ error: { code: err.code ?? 'ERROR', message: err.message } }));
+            process.exit(1);
+        }
+        if (err instanceof ApiError) {
+            switch (err.code) {
+                case 'PROJECT_NOT_FOUND':
+                    console.error(chalk.red(`Project not found: ${slug}`));
+                    console.log(chalk.gray('Run: fazemos projects list'));
+                    break;
+                case 'FORBIDDEN_ROLE':
+                    console.error(chalk.red('Access denied. Owner or admin role required. Agent identities are not permitted.'));
+                    break;
+                case 'AT_LEAST_ONE_FIELD_REQUIRED':
+                    console.error(chalk.red('At least one of --docs-repo, --docs-root, --vcs-connection-id must be provided.'));
+                    break;
+                case 'VALIDATION_ERROR': {
+                    const body2 = (err.body ?? {});
+                    const sub = body2.subCode ?? '';
+                    if (sub === 'docs_root_empty') {
+                        console.error(chalk.red('docs_root_empty: --docs-root cannot be empty or whitespace. Pass ROOT for repo root.'));
+                        console.error(chalk.gray('See: docs/architecture/repo-root-vs-subdir-docs.md'));
+                    }
+                    else if (sub === 'docs_root_too_long') {
+                        console.error(chalk.red('docs_root_too_long: --docs-root exceeds 500 characters.'));
+                    }
+                    else if (sub === 'docs_repo_shape') {
+                        console.error(chalk.red('docs_repo_shape: --docs-repo must be in <owner>/<repo> format.'));
+                    }
+                    else if (sub === 'vcs_connection_uuid') {
+                        console.error(chalk.red('vcs_connection_uuid: --vcs-connection-id must be a valid UUID.'));
+                    }
+                    else {
+                        console.error(chalk.red(`Validation error: ${err.message}`));
+                    }
+                    break;
+                }
+                case 'CONNECTION_NOT_FOUND':
+                    console.error(chalk.red('VCS connection not found.'));
+                    console.log(chalk.gray('List your connections: fazemos connections list'));
+                    break;
+                case 'CONNECTION_CROSS_ORG':
+                    console.error(chalk.red('That VCS connection belongs to a different organization.'));
+                    break;
+                case 'CONNECTION_NOT_ACTIVE':
+                    console.error(chalk.red('VCS connection is not active and cannot be bound.'));
+                    console.log(chalk.gray('Pick an active connection: fazemos connections list'));
+                    break;
+                default:
+                    console.error(chalk.red(err.message));
+            }
+        }
+        else {
+            console.error(chalk.red(err.message));
+        }
+        process.exit(1);
+    }
+});
 // ── F16 — Connections ───────────────────────────────────────
 const connections = program.command('connections').alias('conn').description('GitHub Connection commands');
 /**
@@ -3039,10 +3261,17 @@ templates
     .command('show')
     .description('Show template detail including phases, steps, I/O declarations, pipeline inputs, and revision number. Use this to inspect the full structure of a template and discover phase/step IDs needed by other commands.')
     .argument('<id>', 'Template ID (use "tpl list" to find IDs)')
-    .action(async (id) => {
+    .option('--json', 'Output the template definition as JSON (same as tpl export). Useful for piping/inspecting without a temp file.')
+    .option('--show-sections', 'Print full sections content for all steps (default: truncated at 200 chars)')
+    .action(async (id, opts) => {
     try {
         const data = await api('GET', `/api/pipeline-templates/${id}`);
         const t = data.template;
+        // --json mode: emit definition JSON (same as tpl export)
+        if (opts.json) {
+            console.log(JSON.stringify(t.definition, null, 2));
+            return;
+        }
         console.log(chalk.cyan(t.name));
         console.log(`  ID:      ${t.id}`);
         console.log(`  Status:  ${t.status}`);
@@ -3063,7 +3292,9 @@ templates
                 for (const step of phase.steps || []) {
                     const reviewer = step.reviewer ? ` reviewer:${step.reviewer}` : '';
                     const cycles = step.reviewer && step.max_review_cycles ? ` max-cycles:${step.max_review_cycles}` : '';
-                    console.log(`    Step: ${step.name} [${step.role || 'unassigned'}] (${step.step_type || step.stepType || 'human'})${reviewer}${cycles}`);
+                    // gate and human_approval are equivalent; normalise display
+                    const displayType = step.step_type || step.stepType || 'human';
+                    console.log(`    Step: ${step.name} [${step.role || 'unassigned'}] (${displayType})${reviewer}${cycles}`);
                     if (step.outputs?.length) {
                         console.log('      Outputs:');
                         for (const o of step.outputs) {
@@ -3125,9 +3356,101 @@ templates
                         if (ac.repos)
                             console.log(`        repos: ${JSON.stringify(ac.repos)}`);
                     }
+                    // sections (agent instructions) — truncated at 200 chars unless --show-sections
+                    if (step.sections) {
+                        const full = step.sections;
+                        if (opts.showSections || full.length <= 200) {
+                            console.log(`      Sections:\n${full.split('\n').map((l) => `        ${l}`).join('\n')}`);
+                        }
+                        else {
+                            console.log(`      Sections: ${full.slice(0, 200)}... (${full.length} chars total)`);
+                        }
+                    }
+                    // verification block
+                    if (step.verification) {
+                        console.log(`      Verification: ${JSON.stringify(step.verification)}`);
+                    }
+                    // uat block
+                    if (step.uat) {
+                        console.log(`      UAT: ${JSON.stringify(step.uat)}`);
+                    }
+                }
+            }
+        }
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+templates
+    .command('export')
+    .description('Export a template\'s full definition JSON to stdout or a file. Includes all phases, steps, sections, verification, uat, agent_config, I/O wires, and pipeline inputs. The exported JSON is the canonical input to "tpl update-definition". Round-trip: tpl export <id> > def.json && tpl update-definition <id> def.json is a no-op.')
+    .argument('<id>', 'Template ID (use "tpl list" to find IDs)')
+    .option('--out <file>', 'Write output to file instead of stdout')
+    .action(async (id, opts) => {
+    try {
+        const data = await api('GET', `/api/pipeline-templates/${id}`);
+        const t = data.template;
+        const json = JSON.stringify(t.definition, null, 2);
+        if (opts.out) {
+            const outPath = resolve(opts.out);
+            writeFileSync(outPath, json, 'utf-8');
+            console.log(chalk.green(`Definition written to ${outPath}`));
+        }
+        else {
+            console.log(json);
+        }
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+templates
+    .command('clone')
+    .description('Clone a template into a new draft. The cloned template has the same definition as the source (all phases, steps, sections, verification, uat, I/O wires) but fresh UUIDs for all step/phase IDs. The source template is unchanged. After cloning, use "tpl validate <new-id>" to verify, then "tpl activate" when ready.')
+    .argument('<sourceId>', 'Source template ID to clone from')
+    .requiredOption('--name <name>', 'Name for the new draft template')
+    .option('--description <desc>', 'Description for the new draft template')
+    .action(async (sourceId, opts) => {
+    try {
+        // Fetch source definition
+        const data = await api('GET', `/api/pipeline-templates/${sourceId}`);
+        const src = data.template;
+        // Deep-clone and remap all step/phase UUIDs so no shared IDs exist
+        const srcDef = JSON.parse(JSON.stringify(src.definition));
+        // Build a UUID remap table: old id → new id for phases and steps
+        const idMap = new Map();
+        for (const phase of srcDef.phases || []) {
+            idMap.set(phase.id, crypto.randomUUID());
+            for (const step of phase.steps || []) {
+                idMap.set(step.id, crypto.randomUUID());
+            }
+        }
+        // Apply remapping throughout the definition
+        for (const phase of srcDef.phases || []) {
+            phase.id = idMap.get(phase.id);
+            for (const step of phase.steps || []) {
+                step.id = idMap.get(step.id);
+                // Remap step input source_step_id references
+                for (const inp of step.inputs || []) {
+                    if (inp.source_step_id && idMap.has(inp.source_step_id)) {
+                        inp.source_step_id = idMap.get(inp.source_step_id);
+                    }
                 }
             }
         }
+        // Create new draft template
+        const body = { name: opts.name, definition: srcDef };
+        if (opts.description)
+            body.description = opts.description;
+        const created = await api('POST', '/api/pipeline-templates', body);
+        const newTpl = created.template;
+        console.log(chalk.green(`Cloned: ${newTpl.name}`));
+        console.log(`  ID: ${newTpl.id}`);
+        console.log(`  Source: ${src.name} (${sourceId})`);
+        console.log(chalk.dim(`  Run "fazemos tpl validate ${newTpl.id}" to verify the clone.`));
     }
     catch (err) {
         console.error(chalk.red(err.message));
@@ -3432,7 +3755,7 @@ templates
     .argument('<templateId>', 'Template ID')
     .requiredOption('--phase <phaseId>', 'Phase ID (from "tpl phases", "tpl show", or "tpl add-phase" output)')
     .requiredOption('--name <name>', 'Step name (must be unique within the phase)')
-    .option('--type <type>', 'Step type: human (manual task), agent (AI agent), script (automated), gate (approval checkpoint)', 'human')
+    .option('--type <type>', 'Step type: human (manual task), agent (AI agent), script (automated), gate/human_approval (approval checkpoint — gate and human_approval are equivalent aliases)', 'human')
     .option('--role <role>', 'Role or agent name (e.g., "kate", "marco", "dev-team")')
     .option('--description <desc>', 'Step description')
     .option('--reviewer <reviewer>', 'Reviewer role for review steps')
@@ -3449,6 +3772,8 @@ templates
     .option('--agent-config <json>', 'Per-step agent config overrides as JSON (e.g., \'{"model":"opus","maxBudgetUsd":20}\'). Overrides agent member defaults for: model, maxBudgetUsd, maxTurns, timeoutMs, cwd, repos')
     .option('--stream-silence-abort-ms <ms>', 'Stream silence abort threshold in milliseconds (30000-1800000)', parseStreamSilenceAbortMs)
     .option('--eval-max-turns <n>', 'Evaluator turn budget for tool-enabled (agent) evals on this step (8-30). Has no effect on script-typed steps (rejected by API).', parseEvalMaxTurns)
+    .option('--verification <json>', 'Step-level verification config as JSON or @filepath (e.g., \'{"type":"endpoint","target":"{{pipeline.backend_endpoint_target}}",...}\'). Used for TOOL-3 Tooth-1 deploy-guard verification.')
+    .option('--uat <json>', 'Step-level UAT config as JSON or @filepath (e.g., \'{"primary_path":"{{pipeline.uat_primary_path}}","reachable_env":"dev",...}\'). Used for TOOL-3 Tooth-3 UAT replay.')
     .action(async (templateId, opts) => {
     try {
         if (!VALID_STEP_TYPES.includes(opts.type)) {
@@ -3512,6 +3837,16 @@ templates
             step.stream_silence_abort_ms = opts.streamSilenceAbortMs;
         if (opts.evalMaxTurns !== undefined)
             step.eval_max_turns = opts.evalMaxTurns;
+        if (opts.verification != null) {
+            const v = parseJsonOrFile(opts.verification, '--verification');
+            if (v !== null)
+                step.verification = v;
+        }
+        if (opts.uat != null) {
+            const u = parseJsonOrFile(opts.uat, '--uat');
+            if (u !== null)
+                step.uat = u;
+        }
         // Positioning: --after or --sort-order
         if (opts.after && opts.sortOrder !== undefined) {
             console.error(chalk.red('Cannot use both --after and --sort-order'));
@@ -3598,7 +3933,7 @@ templates
     .argument('<templateId>', 'Template ID')
     .requiredOption('--step <stepId>', 'Step ID (from "tpl steps" output)')
     .option('--name <name>', 'New step name (must be unique within the phase)')
-    .option('--type <type>', 'Step type: human, agent, script, gate')
+    .option('--type <type>', 'Step type: human, agent, script, gate/human_approval (gate and human_approval are equivalent aliases for approval checkpoint steps)')
     .option('--role <role>', 'Role or agent name')
     .option('--description <desc>', 'Description')
     .option('--reviewer <reviewer>', 'Reviewer role (empty string to clear)')
@@ -3614,6 +3949,8 @@ templates
     .option('--stream-silence-abort-ms <ms>', 'Stream silence abort threshold in milliseconds (30000-1800000)', parseStreamSilenceAbortMs)
     .option('--eval-max-turns <n>', 'Evaluator turn budget for tool-enabled (agent) evals on this step (8-30). Mutually exclusive with --clear-eval-max-turns.', parseEvalMaxTurns)
     .option('--clear-eval-max-turns', 'Remove a previously-set eval_max_turns from this step, reverting to runner default. Mutually exclusive with --eval-max-turns.')
+    .option('--verification <json>', 'Step-level verification config as JSON or @filepath. Empty string clears the field. (e.g., \'{"type":"endpoint","target":"{{pipeline.backend_endpoint_target}}",...}\')')
+    .option('--uat <json>', 'Step-level UAT config as JSON or @filepath. Empty string clears the field. (e.g., \'{"primary_path":"{{pipeline.uat_primary_path}}","reachable_env":"dev",...}\')')
     .action(async (templateId, opts) => {
     try {
         if (opts.evalMaxTurns !== undefined && opts.clearEvalMaxTurns) {
@@ -3625,7 +3962,8 @@ templates
             || opts.reviewer != null || opts.maxReviewCycles != null || opts.parallelGroup != null
             || opts.image || opts.command || opts.timeout !== undefined || opts.workingDir || opts.env
             || opts.agentConfig || opts.sections != null || opts.streamSilenceAbortMs !== undefined
-            || opts.evalMaxTurns !== undefined || opts.clearEvalMaxTurns;
+            || opts.evalMaxTurns !== undefined || opts.clearEvalMaxTurns
+            || opts.verification != null || opts.uat != null;
         if (!hasUpdate) {
             console.error(chalk.red('Provide at least one field to update'));
             process.exit(1);
@@ -3705,6 +4043,26 @@ templates
         else if (opts.clearEvalMaxTurns) {
             delete step.eval_max_turns;
         }
+        // verification block — empty string clears, any other value replaces
+        if (opts.verification != null) {
+            const v = parseJsonOrFile(opts.verification, '--verification');
+            if (v === null) {
+                delete step.verification;
+            }
+            else {
+                step.verification = v;
+            }
+        }
+        // uat block — empty string clears, any other value replaces
+        if (opts.uat != null) {
+            const u = parseJsonOrFile(opts.uat, '--uat');
+            if (u === null) {
+                delete step.uat;
+            }
+            else {
+                step.uat = u;
+            }
+        }
         await api('PUT', `/api/pipeline-templates/${templateId}`, { definition: t.definition });
         console.log(chalk.green(`Updated step: ${step.name}`));
     }
@@ -5828,25 +6186,127 @@ async function resolveAgentId(nameOrId) {
 }
 agentsCmd
     .command('register')
-    .description('Register an agent')
+    .description('Register an agent and optionally provision an API credential (fzm_ key) in the same call. ' +
+    'Credential provisioning is on by default (pass --no-provision-credential to opt out). ' +
+    'Owner/admin only when provisioning credentials; agent identities are rejected.')
     .requiredOption('-n, --name <name>', 'Agent display name')
     .option('-r, --roles <roles>', 'Comma-separated roles', (v) => v.split(','))
     .option('--model <model>', 'Model (e.g., opus, sonnet, system)', 'sonnet')
+    .option('--project <slug>', 'Project slug to scope the credential to (defaults to active project). Required when provisioning a credential.')
+    .option('--no-provision-credential', 'Skip credential provisioning. Default: credential IS provisioned (pass this flag to opt out).')
+    .option('--force-rotate', 'Rotate an existing credential — revoke the old key and mint a new one in the same transaction.')
+    .option('--json', 'Emit JSON instead of human-readable output')
+    // NOTE: --no-provision-credential is the sole option definition; Commander v12 automatically
+    // creates --provision-credential as the positive form and defaults provisionCredential to true.
     .action(async (opts) => {
     try {
+        // F42 — CLI defaults --provision-credential to true (Sage UX lock).
+        // opts.provisionCredential is `true` unless --no-provision-credential was passed (sets it to false).
+        const provisionCredential = opts.provisionCredential !== false;
+        // Resolve credentialProjectId from --project or active project when provisioning.
+        let credentialProjectId;
+        if (provisionCredential) {
+            if (opts.project) {
+                // Resolve slug → id via cache; refresh once on miss.
+                const orgId = getActiveOrgId();
+                if (orgId) {
+                    let proj = findProjectBySlug(orgId, opts.project);
+                    if (!proj) {
+                        await refreshAuthMeCache();
+                        proj = findProjectBySlug(orgId, opts.project);
+                    }
+                    if (proj) {
+                        credentialProjectId = proj.id;
+                    }
+                    else {
+                        const msg = `Unknown project: ${opts.project}`;
+                        if (opts.json) {
+                            console.log(JSON.stringify({ error: { code: 'UNKNOWN_PROJECT', message: msg } }));
+                        }
+                        else {
+                            console.error(chalk.red(msg));
+                            console.log(chalk.gray('Run: fazemos projects list'));
+                        }
+                        process.exit(1);
+                        return; // guard: process.exit is mocked in tests
+                    }
+                }
+            }
+            else {
+                credentialProjectId = getActiveProjectId() ?? undefined;
+            }
+            if (!credentialProjectId) {
+                const msg = 'No active Project. Pass --project <slug> or fazemos projects switch <slug>.';
+                if (opts.json) {
+                    console.log(JSON.stringify({ error: { code: 'NO_ACTIVE_PROJECT', message: msg } }));
+                }
+                else {
+                    console.error(chalk.red(msg));
+                }
+                process.exit(1);
+                return; // guard: process.exit is mocked in tests
+            }
+        }
+        const agentEntry = {
+            displayName: opts.name,
+            roles: opts.roles || [opts.name],
+            config: { model: opts.model },
+            provisionCredential,
+        };
+        if (provisionCredential) {
+            agentEntry.credentialProjectId = credentialProjectId;
+            if (opts.forceRotate)
+                agentEntry.forceRotate = true;
+        }
         const data = await api('POST', '/api/agents/register', {
-            agents: [{
-                    displayName: opts.name,
-                    roles: opts.roles || [opts.name],
-                    config: { model: opts.model },
-                }],
+            agents: [agentEntry],
         });
+        if (opts.json) {
+            console.log(JSON.stringify({ agents: data.agents }));
+            return;
+        }
         for (const a of data.agents) {
             const icon = a.status === 'created' ? chalk.green('✓') : a.status === 'updated' ? chalk.yellow('↻') : '○';
             console.log(`  ${icon} ${a.display_name} (${a.status}) — ${a.member_id}`);
+            // F42 — credential block (matches `fazemos api-keys create` rendering per Sage UX)
+            if (a.credential) {
+                const cred = a.credential;
+                if (cred.status === 'minted' || cred.status === 'rotated') {
+                    console.log('');
+                    console.log(chalk.green(`  API credential ${cred.status}: ${opts.name}-key`));
+                    console.log(`    Key:  ${chalk.yellow(cred.rawKey)}`);
+                    console.log(`    ID:   ${cred.apiKeyId}`);
+                    console.log('');
+                    console.log(chalk.red('    ⚠ Save this key now — it will not be shown again.'));
+                }
+                else if (cred.status === 'exists') {
+                    console.log(chalk.gray(`    (credential already provisioned — use --force-rotate to rotate)`));
+                }
+            }
+            if (a.auditLogId) {
+                console.log(chalk.gray(`    Audit: ${a.auditLogId}`));
+            }
         }
     }
     catch (err) {
+        if (opts.json) {
+            console.log(JSON.stringify({ error: { code: err.code ?? 'ERROR', message: err.message } }));
+            process.exit(1);
+        }
+        if (err instanceof ApiError) {
+            if (err.code === 'FORBIDDEN_ROLE') {
+                console.error(chalk.red('Access denied. Owner or admin role required to provision credentials. Agent identities are not permitted.'));
+                process.exit(1);
+            }
+            if (err.code === 'CREDENTIAL_PROJECT_REQUIRED') {
+                console.error(chalk.red('credentialProjectId is required when provisionCredential=true. Pass --project <slug>.'));
+                process.exit(1);
+            }
+            if (err.code === 'CREDENTIAL_PROVISION_FAILED') {
+                console.error(chalk.red('Credential provisioning failed — transaction rolled back. Try again or contact your admin.'));
+                process.exit(1);
+            }
+        }
         console.error(chalk.red(err.message));
         process.exit(1);
     }