@formigio/fazemos-cli 0.2.4 → 0.4.0

package/dist/index.js

@@ -224,6 +224,32 @@ orgs
         process.exit(1);
     }
 });
+orgs
+    .command('show')
+    .description('Show organization details. Defaults to the active org if no ID is provided. Use "orgs list" to find org IDs.')
+    .argument('[id]', 'Organization ID (defaults to active org)')
+    .action(async (id) => {
+    try {
+        const orgId = id || getActiveOrgId();
+        if (!orgId) {
+            console.error(chalk.red('No active org. Run: fazemos orgs switch <slug>'));
+            process.exit(1);
+        }
+        const data = await api('GET', `/api/organizations/${orgId}`);
+        const org = data.organization;
+        console.log(chalk.cyan(org.name));
+        console.log(`  ID:     ${org.id}`);
+        console.log(`  Slug:   ${org.slug}`);
+        if (org.description)
+            console.log(`  Desc:   ${org.description}`);
+        if (org.member_count != null)
+            console.log(`  Members: ${org.member_count}`);
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
 orgs
     .command('switch')
     .description('Switch active organization')
@@ -264,6 +290,82 @@ orgs
         process.exit(1);
     }
 });
+orgs
+    .command('update')
+    .description('Update the active organization. Provide at least one of --name or --description. Requires an active org (use "orgs switch" first).')
+    .option('-n, --name <name>', 'New organization name')
+    .option('-d, --description <desc>', 'New description')
+    .action(async (opts) => {
+    try {
+        if (!opts.name && opts.description == null) {
+            console.error(chalk.red('Provide --name and/or --description'));
+            process.exit(1);
+        }
+        const orgId = getActiveOrgId();
+        if (!orgId) {
+            console.error(chalk.red('No active org. Run: fazemos orgs switch <slug>'));
+            process.exit(1);
+        }
+        const body = {};
+        if (opts.name)
+            body.name = opts.name;
+        if (opts.description != null)
+            body.description = opts.description;
+        const data = await api('PATCH', `/api/organizations/${orgId}`, body);
+        console.log(chalk.green(`Updated: ${data.organization.name}`));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+orgs
+    .command('invite')
+    .description('Invite a human member to the organization by email. The invitee receives an email to join. Use "orgs add-agent" for AI agents instead.')
+    .requiredOption('-e, --email <email>', 'Email address to invite')
+    .option('-r, --role <role>', 'Organization role: admin (full access) or member (default)', 'member')
+    .action(async (opts) => {
+    try {
+        const orgId = getActiveOrgId();
+        if (!orgId) {
+            console.error(chalk.red('No active org. Run: fazemos orgs switch <slug>'));
+            process.exit(1);
+        }
+        const data = await api('POST', `/api/organizations/${orgId}/members/invite`, {
+            email: opts.email,
+            role: opts.role,
+        });
+        console.log(chalk.green(`Invited ${opts.email} as ${opts.role}`));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+orgs
+    .command('add-agent')
+    .description('Create an AI agent member in the organization. The agent can then be assigned work via actions, commitments, or pipeline steps. Use "agents register" for bulk registration with roles and config.')
+    .requiredOption('-n, --name <name>', 'Agent display name (e.g., "kate", "marco")')
+    .option('-r, --role <role>', 'Organization role (admin, member)', 'member')
+    .action(async (opts) => {
+    try {
+        const orgId = getActiveOrgId();
+        if (!orgId) {
+            console.error(chalk.red('No active org. Run: fazemos orgs switch <slug>'));
+            process.exit(1);
+        }
+        const data = await api('POST', `/api/organizations/${orgId}/members`, {
+            displayName: opts.name,
+            role: opts.role,
+        });
+        console.log(chalk.green(`Created agent: ${data.member.display_name}`));
+        console.log(`  ID: ${data.member.id}`);
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
 orgs
     .command('members')
     .description('List org members')
@@ -339,6 +441,91 @@ ws
         process.exit(1);
     }
 });
+ws
+    .command('update')
+    .description('Update worksheet properties. Provide at least one field. Use "ws list" to find IDs, "ws show <id>" to see current values.')
+    .argument('<id>', 'Worksheet ID')
+    .option('-n, --name <name>', 'New worksheet name')
+    .option('-p, --purpose <purpose>', 'New purpose (e.g., "From X to Y by When")')
+    .option('--cadence <cadence>', 'Check-in cadence: weekly, biweekly, or monthly')
+    .action(async (id, opts) => {
+    try {
+        if (!opts.name && !opts.purpose && !opts.cadence) {
+            console.error(chalk.red('Provide --name, --purpose, and/or --cadence'));
+            process.exit(1);
+        }
+        const body = {};
+        if (opts.name)
+            body.name = opts.name;
+        if (opts.purpose)
+            body.purpose = opts.purpose;
+        if (opts.cadence)
+            body.checkInCadence = opts.cadence;
+        const data = await api('PATCH', `/api/worksheets/${id}`, body);
+        console.log(chalk.green(`Updated: ${data.worksheet.name}`));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+ws
+    .command('archive')
+    .description('Archive a worksheet. Archived worksheets are hidden from "ws list" by default but can be found with "ws list -s archived". This is not reversible from the CLI.')
+    .argument('<id>', 'Worksheet ID')
+    .action(async (id) => {
+    try {
+        await api('POST', `/api/worksheets/${id}/archive`);
+        console.log(chalk.green('Worksheet archived'));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+ws
+    .command('progress')
+    .description('Show the aggregated progress board for a worksheet. Combines outcomes, milestones, commitments, and actions into a single view. Use "ws show <id>" for the raw detail view instead.')
+    .argument('<id>', 'Worksheet ID')
+    .action(async (id) => {
+    try {
+        const data = await api('GET', `/api/worksheets/${id}/progress-board`);
+        const board = data.progressBoard || data;
+        console.log(chalk.cyan('Progress Board'));
+        if (board.outcomes?.length) {
+            console.log(chalk.cyan('\n  Outcomes:'));
+            for (const o of board.outcomes) {
+                const progress = o.target_value ? ` ${o.current_value ?? 0}/${o.target_value}` : '';
+                console.log(`    ${o.status === 'achieved' ? '✓' : '○'} ${o.name}${progress}`);
+            }
+        }
+        if (board.milestones?.length) {
+            console.log(chalk.cyan('\n  Milestones:'));
+            for (const m of board.milestones) {
+                const icon = m.status === 'reached' ? '✓' : m.status === 'missed' ? '✗' : '○';
+                console.log(`    ${icon} ${m.name}${m.target_date ? ` (${m.target_date})` : ''}`);
+            }
+        }
+        if (board.commitments?.length) {
+            console.log(chalk.cyan('\n  Commitments:'));
+            for (const c of board.commitments) {
+                const icon = c.status === 'completed' ? chalk.green('✓') : c.status === 'missed' ? chalk.red('✗') : '○';
+                console.log(`    ${icon} ${c.description} — ${c.status}`);
+            }
+        }
+        if (board.actions?.length) {
+            console.log(chalk.cyan('\n  Actions:'));
+            for (const a of board.actions) {
+                const progress = a.target_value ? ` ${a.current_value ?? 0}/${a.target_value}` : '';
+                console.log(`    ${a.description}${progress}`);
+            }
+        }
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
 ws
     .command('show')
     .description('Show worksheet detail')
@@ -483,6 +670,41 @@ outcomes
         process.exit(1);
     }
 });
+outcomes
+    .command('update')
+    .description('Update an outcome. Provide at least one field to change. Use "oc update-value" to change just the current value, or "oc link/unlink" to manage parent linkage. Use "ws show <id>" to find outcome IDs.')
+    .requiredOption('-w, --worksheet <id>', 'Worksheet ID')
+    .requiredOption('-o, --outcome <id>', 'Outcome ID (from "ws show" output)')
+    .option('-n, --name <name>', 'New outcome name')
+    .option('-d, --description <desc>', 'New description')
+    .option('-m, --measurement <method>', 'How it is measured (e.g., "Count of active users")')
+    .option('-t, --target <value>', 'Target value (numeric)', parseNumber)
+    .option('-s, --status <status>', 'Status: active, achieved, or dropped')
+    .action(async (opts) => {
+    try {
+        const body = {};
+        if (opts.name)
+            body.name = opts.name;
+        if (opts.description != null)
+            body.description = opts.description;
+        if (opts.measurement)
+            body.measurement = opts.measurement;
+        if (opts.target !== undefined)
+            body.targetValue = opts.target;
+        if (opts.status)
+            body.status = opts.status;
+        if (Object.keys(body).length === 0) {
+            console.error(chalk.red('Provide at least one field to update'));
+            process.exit(1);
+        }
+        await api('PATCH', `/api/worksheets/${opts.worksheet}/outcomes/${opts.outcome}`, body);
+        console.log(chalk.green('Outcome updated'));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
 outcomes
     .command('update-value')
     .description('Update an outcome current value')
@@ -499,6 +721,101 @@ outcomes
         process.exit(1);
     }
 });
+outcomes
+    .command('remove')
+    .description('Permanently delete an outcome from a worksheet. If the outcome has linked children, those links will be broken. This cannot be undone.')
+    .requiredOption('-w, --worksheet <id>', 'Worksheet ID')
+    .requiredOption('-o, --outcome <id>', 'Outcome ID (from "ws show" output)')
+    .action(async (opts) => {
+    try {
+        await api('DELETE', `/api/worksheets/${opts.worksheet}/outcomes/${opts.outcome}`);
+        console.log(chalk.green('Outcome deleted'));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+outcomes
+    .command('reorder')
+    .description('Reorder outcomes on a worksheet. Pass all outcome IDs in the desired display order. IDs not included will be appended at the end.')
+    .requiredOption('-w, --worksheet <id>', 'Worksheet ID')
+    .requiredOption('--ids <ids>', 'Comma-separated outcome IDs in desired order (e.g., --ids id1,id2,id3)', (v) => v.split(','))
+    .action(async (opts) => {
+    try {
+        await api('PATCH', `/api/worksheets/${opts.worksheet}/outcomes/reorder`, { outcomeIds: opts.ids });
+        console.log(chalk.green('Outcomes reordered'));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+outcomes
+    .command('linkable')
+    .description('List outcomes from other worksheets that can be linked to as parents. Use this to discover valid --parent IDs for "oc link". Only shows outcomes that would not create a circular reference.')
+    .requiredOption('-w, --worksheet <id>', 'Worksheet ID whose outcomes you want to link from')
+    .action(async (opts) => {
+    try {
+        const data = await api('GET', `/api/outcomes/linkable?worksheetId=${opts.worksheet}`);
+        if (!data.outcomes?.length) {
+            console.log(chalk.yellow('No linkable outcomes'));
+            return;
+        }
+        for (const o of data.outcomes) {
+            const ws = o.worksheet_name ? ` on ${o.worksheet_name}` : '';
+            console.log(`  ${o.name}${ws} — ${o.id}`);
+        }
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+outcomes
+    .command('children')
+    .description('Show outcomes from other worksheets that are linked to this outcome as children. These are outcomes where "oc link --parent <this-id>" was used.')
+    .argument('<id>', 'Parent outcome ID')
+    .action(async (id) => {
+    try {
+        const data = await api('GET', `/api/outcomes/${id}/children`);
+        if (!data.children?.length) {
+            console.log(chalk.yellow('No child outcomes'));
+            return;
+        }
+        for (const c of data.children) {
+            const progress = c.target_value ? ` ${c.current_value ?? 0}/${c.target_value}` : '';
+            const ws = c.worksheet_name ? ` on ${c.worksheet_name}` : '';
+            console.log(`  ${c.status === 'achieved' ? '✓' : '○'} ${c.name}${progress}${ws} — ${c.id}`);
+        }
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+outcomes
+    .command('tree')
+    .description('Show the full hierarchy tree for an outcome, including all descendant outcomes across worksheets. Useful for seeing how team-level outcomes roll up to org-level goals.')
+    .argument('<id>', 'Root outcome ID')
+    .action(async (id) => {
+    try {
+        const data = await api('GET', `/api/outcomes/${id}/tree`);
+        const printNode = (node, indent) => {
+            const progress = node.target_value ? ` ${node.current_value ?? 0}/${node.target_value}` : '';
+            const ws = node.worksheet_name ? ` on ${node.worksheet_name}` : '';
+            console.log(`${indent}${node.status === 'achieved' ? '✓' : '○'} ${node.name}${progress}${ws}`);
+            for (const child of node.children || []) {
+                printNode(child, indent + '  ');
+            }
+        };
+        printNode(data.tree || data, '  ');
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
 // ── Milestones ──────────────────────────────────────────────
 const milestones = program.command('milestones').alias('ms').description('Milestone commands');
 milestones
@@ -527,8 +844,71 @@ milestones
         process.exit(1);
     }
 });
+milestones
+    .command('update')
+    .description('Update a milestone. Provide at least one field to change. Use "ws show <id>" to find milestone IDs and see current values.')
+    .argument('<id>', 'Milestone ID (from "ws show" output)')
+    .option('-n, --name <name>', 'New milestone name')
+    .option('-d, --description <desc>', 'New description')
+    .option('-t, --target-date <date>', 'New target date (YYYY-MM-DD)')
+    .option('-s, --status <status>', 'Status: pending (default), reached, or missed')
+    .action(async (id, opts) => {
+    try {
+        const body = {};
+        if (opts.name)
+            body.name = opts.name;
+        if (opts.description != null)
+            body.description = opts.description;
+        if (opts.targetDate)
+            body.targetDate = opts.targetDate;
+        if (opts.status)
+            body.status = opts.status;
+        if (Object.keys(body).length === 0) {
+            console.error(chalk.red('Provide at least one field to update'));
+            process.exit(1);
+        }
+        await api('PATCH', `/api/milestones/${id}`, body);
+        console.log(chalk.green('Milestone updated'));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+milestones
+    .command('remove')
+    .description('Permanently delete a milestone. This cannot be undone.')
+    .argument('<id>', 'Milestone ID (from "ws show" output)')
+    .action(async (id) => {
+    try {
+        await api('DELETE', `/api/milestones/${id}`);
+        console.log(chalk.green('Milestone deleted'));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+milestones
+    .command('reorder')
+    .description('Reorder milestones on a worksheet. Pass all milestone IDs in the desired display order.')
+    .requiredOption('-w, --worksheet <id>', 'Worksheet ID')
+    .requiredOption('--ids <ids>', 'Comma-separated milestone IDs in desired order (e.g., --ids id1,id2,id3)', (v) => v.split(','))
+    .action(async (opts) => {
+    try {
+        await api('PATCH', `/api/worksheets/${opts.worksheet}/milestones/reorder`, { milestoneIds: opts.ids });
+        console.log(chalk.green('Milestones reordered'));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
 // ── Members ─────────────────────────────────────────────────
-const members = program.command('members').description('Worksheet member commands');
+const members = program.command('members').description('Member commands (worksheet and org level).\n\n' +
+    '  Worksheet members: add, list, update, remove — manage who works on a worksheet.\n' +
+    '  Org members: show, update-org, delete — manage org-level member records.\n' +
+    '  Use "orgs members" to list all org members and find member IDs.');
 members
     .command('add')
     .description('Add a member to a worksheet')
@@ -568,32 +948,124 @@ members
         process.exit(1);
     }
 });
-// ── Actions ─────────────────────────────────────────────────
-const actions = program.command('actions').alias('ac').description('Action (lead measure) commands');
-actions
-    .command('add')
-    .description('Add an action to a worksheet')
+members
+    .command('update')
+    .description('Change a worksheet member\'s role. Use "members list -w <id>" to find worksheet member IDs.')
     .requiredOption('-w, --worksheet <id>', 'Worksheet ID')
-    .requiredOption('-n, --name <name>', 'Action description')
-    .option('-o, --outcome <id>', 'Linked outcome ID')
-    .option('-m, --measurement <method>', 'How it is measured')
-    .option('-t, --target <value>', 'Target value', parseNumber)
-    .option('-c, --current <value>', 'Current value', parseNumber)
+    .requiredOption('-m, --member <id>', 'Worksheet member ID (from "members list" output)')
+    .requiredOption('-r, --role <role>', 'New role: lead or contributor')
     .action(async (opts) => {
     try {
-        const body = { description: opts.name };
-        if (opts.outcome)
-            body.outcomeId = opts.outcome;
-        if (opts.measurement)
-            body.measurement = opts.measurement;
-        if (opts.target !== undefined)
-            body.targetValue = opts.target;
-        if (opts.current !== undefined)
-            body.currentValue = opts.current;
-        const data = await api('POST', `/api/worksheets/${opts.worksheet}/actions`, body);
-        const a = data.action;
-        console.log(chalk.green(`Added action: ${a.description}`));
-        console.log(`  ID: ${a.id}`);
+        await api('PATCH', `/api/worksheets/${opts.worksheet}/members/${opts.member}`, { role: opts.role });
+        console.log(chalk.green(`Member role updated to ${opts.role}`));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+members
+    .command('remove')
+    .description('Remove a member from a worksheet. The member remains in the organization but loses access to this worksheet.')
+    .requiredOption('-w, --worksheet <id>', 'Worksheet ID')
+    .requiredOption('-m, --member <id>', 'Worksheet member ID (from "members list" output)')
+    .action(async (opts) => {
+    try {
+        await api('DELETE', `/api/worksheets/${opts.worksheet}/members/${opts.member}`);
+        console.log(chalk.green('Member removed from worksheet'));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+members
+    .command('show')
+    .description('Show an organization member\'s detail, including role, type, and agent status. Use "orgs members" to find member IDs.')
+    .argument('<id>', 'Member ID (from "orgs members" output)')
+    .action(async (id) => {
+    try {
+        const data = await api('GET', `/api/members/${id}`);
+        const m = data.member;
+        console.log(chalk.cyan(m.display_name));
+        console.log(`  ID:     ${m.id}`);
+        console.log(`  Role:   ${m.role}`);
+        console.log(`  Type:   ${m.member_type}`);
+        if (m.email)
+            console.log(`  Email:  ${m.email}`);
+        if (m.agent_status)
+            console.log(`  Status: ${m.agent_status}`);
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+members
+    .command('update-org')
+    .description('Update an organization member\'s role or display name. This is the org-level role, not the worksheet role. Use "members update" for worksheet roles instead.')
+    .argument('<id>', 'Member ID (from "orgs members" output)')
+    .option('-r, --role <role>', 'New org role: admin or member')
+    .option('-n, --name <name>', 'New display name')
+    .action(async (id, opts) => {
+    try {
+        const body = {};
+        if (opts.role)
+            body.role = opts.role;
+        if (opts.name)
+            body.displayName = opts.name;
+        if (Object.keys(body).length === 0) {
+            console.error(chalk.red('Provide --role and/or --name'));
+            process.exit(1);
+        }
+        await api('PATCH', `/api/members/${id}`, body);
+        console.log(chalk.green('Member updated'));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+members
+    .command('delete')
+    .description('Permanently remove a member from the organization. This removes them from all worksheets and revokes access. Cannot be undone.')
+    .argument('<id>', 'Member ID (from "orgs members" output)')
+    .action(async (id) => {
+    try {
+        await api('DELETE', `/api/members/${id}`);
+        console.log(chalk.green('Member removed from organization'));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+// ── Actions ─────────────────────────────────────────────────
+const actions = program.command('actions').alias('ac').description('Action (lead measure) commands');
+actions
+    .command('add')
+    .description('Add an action to a worksheet')
+    .requiredOption('-w, --worksheet <id>', 'Worksheet ID')
+    .requiredOption('-n, --name <name>', 'Action description')
+    .option('-o, --outcome <id>', 'Linked outcome ID')
+    .option('-m, --measurement <method>', 'How it is measured')
+    .option('-t, --target <value>', 'Target value', parseNumber)
+    .option('-c, --current <value>', 'Current value', parseNumber)
+    .action(async (opts) => {
+    try {
+        const body = { description: opts.name };
+        if (opts.outcome)
+            body.outcomeId = opts.outcome;
+        if (opts.measurement)
+            body.measurement = opts.measurement;
+        if (opts.target !== undefined)
+            body.targetValue = opts.target;
+        if (opts.current !== undefined)
+            body.currentValue = opts.current;
+        const data = await api('POST', `/api/worksheets/${opts.worksheet}/actions`, body);
+        const a = data.action;
+        console.log(chalk.green(`Added action: ${a.description}`));
+        console.log(`  ID: ${a.id}`);
     }
     catch (err) {
         console.error(chalk.red(err.message));
@@ -637,6 +1109,55 @@ actions
         process.exit(1);
     }
 });
+actions
+    .command('update')
+    .description('Update an action. Provide at least one field to change. Use "ac update-value" to change just the current value. Use "ac list -w <id>" to find action IDs.')
+    .requiredOption('-w, --worksheet <id>', 'Worksheet ID')
+    .requiredOption('-a, --action <id>', 'Action ID (from "ac list" or "ws show" output)')
+    .option('-n, --name <name>', 'New action description')
+    .option('-m, --measurement <method>', 'How it is measured (e.g., "PRs merged per week")')
+    .option('-t, --target <value>', 'Target value (numeric)', parseNumber)
+    .option('-o, --outcome <id>', 'Link to a different outcome ID')
+    .action(async (opts) => {
+    try {
+        const body = {};
+        if (opts.name)
+            body.description = opts.name;
+        if (opts.measurement)
+            body.measurement = opts.measurement;
+        if (opts.target !== undefined)
+            body.targetValue = opts.target;
+        if (opts.outcome)
+            body.outcomeId = opts.outcome;
+        if (Object.keys(body).length === 0) {
+            console.error(chalk.red('Provide at least one field to update'));
+            process.exit(1);
+        }
+        await api('PATCH', `/api/worksheets/${opts.worksheet}/actions/${opts.action}`, body);
+        console.log(chalk.green('Action updated'));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+actions
+    .command('execute')
+    .description('Trigger an agent execution for an action. The API determines which agent to use based on the action\'s configuration. For more control over agent selection and parameters, use the top-level "execute" command instead.')
+    .requiredOption('-w, --worksheet <id>', 'Worksheet ID')
+    .requiredOption('-a, --action <id>', 'Action ID (from "ac list" or "ws show" output)')
+    .action(async (opts) => {
+    try {
+        const data = await api('POST', `/api/worksheets/${opts.worksheet}/actions/${opts.action}/execute`);
+        console.log(chalk.green('Execution triggered'));
+        if (data.execution?.id)
+            console.log(`  Execution ID: ${data.execution.id}`);
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
 // ── Commitments ─────────────────────────────────────────────
 const commitments = program.command('commitments').alias('cm').description('Commitment commands');
 commitments
@@ -697,6 +1218,243 @@ commitments
         process.exit(1);
     }
 });
+commitments
+    .command('execute')
+    .description('Trigger an agent execution for a commitment. The API determines which agent to use based on the commitment\'s configuration. For more control, use the top-level "execute" command instead.')
+    .requiredOption('-w, --worksheet <id>', 'Worksheet ID')
+    .requiredOption('-c, --commitment <id>', 'Commitment ID (from "cm list" or "ws show" output)')
+    .action(async (opts) => {
+    try {
+        const data = await api('POST', `/api/worksheets/${opts.worksheet}/commitments/${opts.commitment}/execute`);
+        console.log(chalk.green('Execution triggered'));
+        if (data.execution?.id)
+            console.log(`  Execution ID: ${data.execution.id}`);
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+// ── Notes ───────────────────────────────────────────────────
+const notes = program.command('notes').alias('nt').description('Worksheet note commands. Notes are freeform text attached to a worksheet for capturing context, decisions, or observations.');
+notes
+    .command('add')
+    .description('Add a note to a worksheet. Notes are timestamped and attributed to the current user. Good for recording decisions, context, or observations that don\'t fit into outcomes or actions.')
+    .requiredOption('-w, --worksheet <id>', 'Worksheet ID')
+    .requiredOption('-t, --text <text>', 'Note text (e.g., "Decided to defer mobile until Q3")')
+    .action(async (opts) => {
+    try {
+        const data = await api('POST', `/api/worksheets/${opts.worksheet}/notes`, { text: opts.text });
+        const n = data.note;
+        console.log(chalk.green('Note added'));
+        console.log(`  ID: ${n.id}`);
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+notes
+    .command('list')
+    .description('List notes on a worksheet')
+    .requiredOption('-w, --worksheet <id>', 'Worksheet ID')
+    .action(async (opts) => {
+    try {
+        const data = await api('GET', `/api/worksheets/${opts.worksheet}/notes`);
+        if (!data.notes?.length) {
+            console.log(chalk.yellow('No notes'));
+            return;
+        }
+        for (const n of data.notes) {
+            const time = n.created_at ? new Date(n.created_at).toLocaleString() : '';
+            const author = n.author_name || '';
+            console.log(`  ${chalk.gray(time)} ${author ? chalk.cyan(author) + ' — ' : ''}${n.text}`);
+            console.log(`    ID: ${n.id}`);
+        }
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+notes
+    .command('remove')
+    .description('Permanently delete a note. Use "nt list -w <id>" to find note IDs.')
+    .argument('<id>', 'Note ID (from "nt list" output)')
+    .action(async (id) => {
+    try {
+        await api('DELETE', `/api/notes/${id}`);
+        console.log(chalk.green('Note deleted'));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+// ── Check-ins ───────────────────────────────────────────────
+const checkins = program.command('check-ins').alias('ci').description('Check-in commands.\n\n' +
+    '  Check-ins are periodic reviews of worksheet progress (weekly, biweekly, etc.).\n' +
+    '  During a check-in, members report on commitments and make new ones.\n\n' +
+    '  Typical flow:\n' +
+    '    1. ci create -w <id>                 Start a new check-in\n' +
+    '    2. ci report <id> --reports [...]    Report on past commitments\n' +
+    '    3. ci add-commitment <id> -d "..."   Make new commitments\n' +
+    '    4. ci complete <id>                  Close the check-in');
+checkins
+    .command('create')
+    .description('Start a new check-in for a worksheet. This creates a check-in record where members can report on past commitments and make new ones. Only one check-in is typically open at a time.')
+    .requiredOption('-w, --worksheet <id>', 'Worksheet ID')
+    .option('-n, --name <name>', 'Check-in name (e.g., "Week of 2026-03-23")')
+    .action(async (opts) => {
+    try {
+        const body = {};
+        if (opts.name)
+            body.name = opts.name;
+        const data = await api('POST', `/api/worksheets/${opts.worksheet}/check-ins`, body);
+        const ci = data.checkIn;
+        console.log(chalk.green('Check-in created'));
+        console.log(`  ID: ${ci.id}`);
+        if (ci.status)
+            console.log(`  Status: ${ci.status}`);
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+checkins
+    .command('list')
+    .description('List check-ins for a worksheet')
+    .requiredOption('-w, --worksheet <id>', 'Worksheet ID')
+    .action(async (opts) => {
+    try {
+        const data = await api('GET', `/api/worksheets/${opts.worksheet}/check-ins`);
+        if (!data.checkIns?.length) {
+            console.log(chalk.yellow('No check-ins'));
+            return;
+        }
+        for (const ci of data.checkIns) {
+            const icon = ci.status === 'completed' ? chalk.green('✓') : '○';
+            const date = ci.created_at ? new Date(ci.created_at).toLocaleDateString() : '';
+            console.log(`  ${icon} ${ci.name || date} (${ci.status}) — ${ci.id}`);
+        }
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+checkins
+    .command('show')
+    .description('Show check-in detail including commitment reports and new commitments made during the check-in.')
+    .argument('<id>', 'Check-in ID (from "ci list" output)')
+    .action(async (id) => {
+    try {
+        const data = await api('GET', `/api/check-ins/${id}`);
+        const ci = data.checkIn;
+        console.log(chalk.cyan(ci.name || `Check-in ${ci.id}`));
+        console.log(`  ID:      ${ci.id}`);
+        console.log(`  Status:  ${ci.status}`);
+        if (ci.created_at)
+            console.log(`  Created: ${ci.created_at}`);
+        if (ci.reports?.length) {
+            console.log(chalk.cyan('\n  Reports:'));
+            for (const r of ci.reports) {
+                const icon = r.status === 'completed' ? chalk.green('✓') : r.status === 'missed' ? chalk.red('✗') : '○';
+                console.log(`    ${icon} ${r.commitment_description || r.commitment_id} — ${r.status}`);
+                if (r.notes)
+                    console.log(`      ${r.notes}`);
+            }
+        }
+        if (ci.commitments?.length) {
+            console.log(chalk.cyan('\n  Commitments:'));
+            for (const c of ci.commitments) {
+                const icon = c.status === 'completed' ? chalk.green('✓') : '○';
+                console.log(`    ${icon} ${c.description} — due ${c.due_date} — ${c.id}`);
+            }
+        }
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+checkins
+    .command('update')
+    .description('Update a check-in\'s name or notes. The check-in must still be open (not completed).')
+    .argument('<id>', 'Check-in ID (from "ci list" output)')
+    .option('-n, --name <name>', 'New check-in name')
+    .option('--notes <text>', 'General notes for this check-in')
+    .action(async (id, opts) => {
+    try {
+        const body = {};
+        if (opts.name)
+            body.name = opts.name;
+        if (opts.notes != null)
+            body.notes = opts.notes;
+        if (Object.keys(body).length === 0) {
+            console.error(chalk.red('Provide at least one field to update'));
+            process.exit(1);
+        }
+        await api('PATCH', `/api/check-ins/${id}`, body);
+        console.log(chalk.green('Check-in updated'));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+checkins
+    .command('report')
+    .description('Submit commitment reports for a check-in. Each report records whether a past commitment was completed, missed, or is still in progress.\n\n  Example:\n    ci report <id> --reports \'[{"commitmentId":"abc","status":"completed","notes":"Shipped it"}]\'')
+    .argument('<id>', 'Check-in ID (from "ci list" output)')
+    .requiredOption('--reports <json>', 'JSON array of reports. Each: {commitmentId, status (completed|missed|in_progress), notes?}')
+    .action(async (id, opts) => {
+    try {
+        const reports = JSON.parse(opts.reports);
+        await api('POST', `/api/check-ins/${id}/reports`, { reports });
+        console.log(chalk.green(`Submitted ${reports.length} report(s)`));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+checkins
+    .command('add-commitment')
+    .description('Make a new commitment during a check-in. This is how team members pledge specific deliverables for the next period. The commitment will appear in "cm list" and be reportable in the next check-in.')
+    .argument('<id>', 'Check-in ID (from "ci list" output)')
+    .requiredOption('-d, --description <desc>', 'What you commit to do (e.g., "Ship the new API endpoint")')
+    .requiredOption('--due <date>', 'Due date (YYYY-MM-DD)')
+    .option('-a, --action <id>', 'Link to an action ID for tracking')
+    .action(async (id, opts) => {
+    try {
+        const body = { description: opts.description, dueDate: opts.due };
+        if (opts.action)
+            body.actionId = opts.action;
+        const data = await api('POST', `/api/check-ins/${id}/commitments`, body);
+        console.log(chalk.green(`Commitment added: ${data.commitment.description}`));
+        console.log(`  ID: ${data.commitment.id}`);
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+checkins
+    .command('complete')
+    .description('Close a check-in. Once completed, no more reports or commitments can be added. This finalizes the check-in record.')
+    .argument('<id>', 'Check-in ID (from "ci list" output)')
+    .action(async (id) => {
+    try {
+        await api('POST', `/api/check-ins/${id}/complete`);
+        console.log(chalk.green('Check-in completed'));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
 // ── Template I/O helpers ───────────────────────────────────
 function allSteps(definition) {
     const steps = [];
@@ -717,8 +1475,24 @@ function requireDraftStatus(template) {
         process.exit(1);
     }
 }
+function findPhaseById(definition, phaseId) {
+    return (definition?.phases || []).find((p) => p.id === phaseId);
+}
+const VALID_STEP_TYPES = ['human', 'agent', 'script', 'gate'];
 // ── Templates ──────────────────────────────────────────────
-const templates = program.command('templates').alias('tpl').description('Pipeline template commands');
+const templates = program.command('templates').alias('tpl').description('Pipeline template commands.\n\n' +
+    '  Templates define multi-step workflows: template → phases → steps → I/O.\n' +
+    '  Lifecycle: draft → active → archived (archived → draft to unarchive).\n' +
+    '  Structural edits (add/remove/edit phases, steps, I/O) require draft status.\n\n' +
+    '  Typical workflow:\n' +
+    '    1. tpl create -n "Name"           Create empty draft template\n' +
+    '    2. tpl add-phase <id> --name ...  Add phases\n' +
+    '    3. tpl add-step <id> --phase ...  Add steps to phases\n' +
+    '    4. tpl add-output / add-input     Wire I/O between steps\n' +
+    '    5. tpl validate <id>              Check for errors\n' +
+    '    6. tpl activate <id>              Make available for instances\n\n' +
+    '  Use "tpl steps <id>" to list step IDs needed by --step options.\n' +
+    '  Use "tpl show <id>" to see full structure with I/O declarations.');
 templates
     .command('list')
     .description('List pipeline templates')
@@ -744,8 +1518,8 @@ templates
 });
 templates
     .command('show')
-    .description('Show template detail')
-    .argument('<id>', 'Template ID')
+    .description('Show template detail including phases, steps, I/O declarations, and pipeline inputs. 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) => {
     try {
         const data = await api('GET', `/api/pipeline-templates/${id}`);
@@ -803,19 +1577,243 @@ templates
     }
 });
 templates
-    .command('create')
-    .description('Create a pipeline template')
-    .requiredOption('-n, --name <name>', 'Template name')
-    .option('-d, --description <desc>', 'Description')
-    .action(async (opts) => {
+    .command('create')
+    .description('Create an empty pipeline template in draft status. After creation, use add-phase, add-step, and I/O commands to build the structure, then activate.')
+    .requiredOption('-n, --name <name>', 'Template name')
+    .option('-d, --description <desc>', 'Description')
+    .action(async (opts) => {
+    try {
+        const body = { name: opts.name, definition: { phases: [] } };
+        if (opts.description)
+            body.description = opts.description;
+        const data = await api('POST', '/api/pipeline-templates', body);
+        const t = data.template;
+        console.log(chalk.green(`Created: ${t.name}`));
+        console.log(`  ID: ${t.id}`);
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+templates
+    .command('import')
+    .description('Import a JOE template JSON file as a Fazemos pipeline template. Imports steps, outputs, inputs, and pipeline-level inputs. Step IDs are remapped to new UUIDs and input references are updated accordingly.')
+    .argument('<file>', 'Path to JOE template JSON file')
+    .action(async (file) => {
+    try {
+        const raw = JSON.parse(readFileSync(resolve(file), 'utf-8'));
+        // Map JOE template to Fazemos format
+        const joeSteps = raw.steps || [];
+        // Build ID mapping so input source_step_id references survive UUID reassignment
+        const idMap = new Map();
+        for (const s of joeSteps) {
+            if (s.id)
+                idMap.set(s.id, crypto.randomUUID());
+        }
+        const definition = {
+            inputs: (raw.inputs || []).map((i) => ({
+                name: i.name,
+                type: i.type || 'text',
+                required: i.required !== false,
+                ...(i.description ? { description: i.description } : {}),
+                ...(i.default_value != null ? { default_value: i.default_value } : {}),
+            })),
+            phases: [{
+                    id: crypto.randomUUID(),
+                    name: raw.name || 'Main',
+                    description: raw.description || '',
+                    deliverables: [],
+                    steps: joeSteps.map((s, i) => ({
+                        id: idMap.get(s.id) || crypto.randomUUID(),
+                        name: s.name,
+                        description: s.description || '',
+                        step_type: s.executionMode === 'script' ? 'script' : (s.agent ? 'agent' : 'human'),
+                        role: s.role || s.agent || 'unassigned',
+                        inputs: (s.inputs || []).map((inp) => ({
+                            name: inp.name,
+                            ...(inp.source_step_id ? { source_step_id: idMap.get(inp.source_step_id) || inp.source_step_id, source_output_name: inp.source_output_name } : {}),
+                            ...(inp.pipeline_input ? { pipeline_input: inp.pipeline_input } : {}),
+                            ...(inp.description ? { description: inp.description } : {}),
+                            required: inp.required !== false,
+                        })),
+                        outputs: (s.outputs || []).map((o) => ({
+                            name: o.name,
+                            type: o.type || 'text',
+                            ...(o.description ? { description: o.description } : {}),
+                            required: o.required !== false,
+                            ...(o.format ? { format: o.format } : {}),
+                        })),
+                        sections: s.sections || '',
+                        reviewer: s.reviewer || null,
+                        max_review_cycles: s.maxReviewCycles || 0,
+                        execution_config: s.executionMode === 'script' ? {
+                            image: s.image || '',
+                            command: s.command || '',
+                        } : null,
+                        parallel_group: null,
+                        sort_order: i,
+                    })),
+                }],
+        };
+        const body = {
+            name: raw.name || file,
+            description: raw.description || '',
+            definition,
+        };
+        const data = await api('POST', '/api/pipeline-templates', body);
+        const t = data.template;
+        console.log(chalk.green(`Imported: ${t.name} (${joeSteps.length} steps)`));
+        console.log(`  ID: ${t.id}`);
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+templates
+    .command('update-definition')
+    .description('Update a template definition from a JSON file')
+    .argument('<id>', 'Template ID')
+    .argument('<file>', 'Path to definition JSON file')
+    .action(async (id, file) => {
+    try {
+        const definition = JSON.parse(readFileSync(resolve(file), 'utf-8'));
+        await api('PUT', `/api/pipeline-templates/${id}`, { definition });
+        console.log(chalk.green('Template definition updated'));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+templates
+    .command('activate')
+    .description('Activate a draft template (required before creating pipeline instances). Template must have at least one phase with at least one step. Status changes from draft → active.')
+    .argument('<id>', 'Template ID')
+    .action(async (id) => {
+    try {
+        await api('PATCH', `/api/pipeline-templates/${id}/status`, { status: 'active' });
+        console.log(chalk.green('Template activated'));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+// ── Template structure commands ─────────────────────────────
+templates
+    .command('update')
+    .description('Update template name or description. Works on any status (draft, active, or archived). Does not modify the definition or bump version.')
+    .argument('<id>', 'Template ID')
+    .option('-n, --name <name>', 'New name')
+    .option('-d, --description <desc>', 'New description')
+    .action(async (id, opts) => {
+    try {
+        if (!opts.name && opts.description == null) {
+            console.error(chalk.red('Provide --name and/or --description'));
+            process.exit(1);
+        }
+        const body = {};
+        if (opts.name)
+            body.name = opts.name;
+        if (opts.description != null)
+            body.description = opts.description;
+        const data = await api('PUT', `/api/pipeline-templates/${id}`, body);
+        console.log(chalk.green(`Updated: ${data.template.name}`));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+templates
+    .command('archive')
+    .description('Archive an active template. Archived templates cannot be used to create new instances. Use "tpl unarchive" to move back to draft for editing.')
+    .argument('<id>', 'Template ID')
+    .action(async (id) => {
+    try {
+        await api('PATCH', `/api/pipeline-templates/${id}/status`, { status: 'archived' });
+        console.log(chalk.green('Template archived'));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+templates
+    .command('unarchive')
+    .description('Move an archived template back to draft status for editing. After edits, use "tpl activate" to make it available again.')
+    .argument('<id>', 'Template ID')
+    .action(async (id) => {
+    try {
+        await api('PATCH', `/api/pipeline-templates/${id}/status`, { status: 'draft' });
+        console.log(chalk.green('Template moved to draft'));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+templates
+    .command('add-phase')
+    .description('Add a phase to a template. Phases group steps into logical stages (e.g., "Design", "Build", "Test"). Template must be in draft status. Phase names must be unique within the template. Returns the generated phase ID needed by add-step.')
+    .argument('<templateId>', 'Template ID')
+    .requiredOption('--name <name>', 'Phase name (must be unique within the template)')
+    .option('--description <desc>', 'Phase description')
+    .action(async (templateId, opts) => {
+    try {
+        const data = await api('GET', `/api/pipeline-templates/${templateId}`);
+        const t = data.template;
+        requireDraftStatus(t);
+        if (!t.definition.phases)
+            t.definition.phases = [];
+        if (t.definition.phases.find((p) => p.name === opts.name)) {
+            console.error(chalk.red(`Phase "${opts.name}" already exists`));
+            process.exit(1);
+        }
+        const phase = {
+            id: crypto.randomUUID(),
+            name: opts.name,
+            description: opts.description || '',
+            deliverables: [],
+            steps: [],
+        };
+        t.definition.phases.push(phase);
+        await api('PUT', `/api/pipeline-templates/${templateId}`, { definition: t.definition });
+        console.log(chalk.green(`Added phase: ${opts.name}`));
+        console.log(`  ID: ${phase.id}`);
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+templates
+    .command('remove-phase')
+    .description('Remove a phase from a template. Blocked if the phase contains steps unless --force is used. Template must be in draft status. Use "tpl show" to find phase IDs.')
+    .argument('<templateId>', 'Template ID')
+    .requiredOption('--phase <phaseId>', 'Phase ID (from "tpl show" output)')
+    .option('--force', 'Remove even if phase contains steps')
+    .action(async (templateId, opts) => {
     try {
-        const body = { name: opts.name, definition: { phases: [] } };
-        if (opts.description)
-            body.description = opts.description;
-        const data = await api('POST', '/api/pipeline-templates', body);
+        const data = await api('GET', `/api/pipeline-templates/${templateId}`);
         const t = data.template;
-        console.log(chalk.green(`Created: ${t.name}`));
-        console.log(`  ID: ${t.id}`);
+        requireDraftStatus(t);
+        const idx = (t.definition.phases || []).findIndex((p) => p.id === opts.phase);
+        if (idx === -1) {
+            console.error(chalk.red(`Phase "${opts.phase}" not found`));
+            process.exit(1);
+        }
+        const phase = t.definition.phases[idx];
+        if (phase.steps?.length && !opts.force) {
+            console.error(chalk.yellow(`Phase "${phase.name}" has ${phase.steps.length} steps`));
+            console.error(chalk.yellow('Use --force to remove anyway'));
+            process.exit(1);
+        }
+        t.definition.phases.splice(idx, 1);
+        await api('PUT', `/api/pipeline-templates/${templateId}`, { definition: t.definition });
+        console.log(chalk.green(`Removed phase: ${phase.name}`));
     }
     catch (err) {
         console.error(chalk.red(err.message));
@@ -823,74 +1821,137 @@ templates
     }
 });
 templates
-    .command('import')
-    .description('Import a JOE template JSON file as a Fazemos pipeline template')
-    .argument('<file>', 'Path to JOE template JSON file')
-    .action(async (file) => {
+    .command('edit-phase')
+    .description('Edit a phase name or description. Template must be in draft status. Provide at least one of --name or --description.')
+    .argument('<templateId>', 'Template ID')
+    .requiredOption('--phase <phaseId>', 'Phase ID (from "tpl show" output)')
+    .option('--name <name>', 'New phase name (must be unique within the template)')
+    .option('--description <desc>', 'New phase description')
+    .action(async (templateId, opts) => {
     try {
-        const raw = JSON.parse(readFileSync(resolve(file), 'utf-8'));
-        // Map JOE template to Fazemos format
-        const joeSteps = raw.steps || [];
-        // Build ID mapping so input source_step_id references survive UUID reassignment
-        const idMap = new Map();
-        for (const s of joeSteps) {
-            if (s.id)
-                idMap.set(s.id, crypto.randomUUID());
+        if (!opts.name && opts.description == null) {
+            console.error(chalk.red('Provide --name and/or --description'));
+            process.exit(1);
         }
-        const definition = {
-            inputs: (raw.inputs || []).map((i) => ({
-                name: i.name,
-                type: i.type || 'text',
-                required: i.required !== false,
-                ...(i.description ? { description: i.description } : {}),
-                ...(i.default_value != null ? { default_value: i.default_value } : {}),
-            })),
-            phases: [{
-                    id: crypto.randomUUID(),
-                    name: raw.name || 'Main',
-                    description: raw.description || '',
-                    deliverables: [],
-                    steps: joeSteps.map((s, i) => ({
-                        id: idMap.get(s.id) || crypto.randomUUID(),
-                        name: s.name,
-                        description: s.description || '',
-                        step_type: s.executionMode === 'script' ? 'script' : (s.agent ? 'agent' : 'human'),
-                        role: s.role || s.agent || 'unassigned',
-                        inputs: (s.inputs || []).map((inp) => ({
-                            name: inp.name,
-                            ...(inp.source_step_id ? { source_step_id: idMap.get(inp.source_step_id) || inp.source_step_id, source_output_name: inp.source_output_name } : {}),
-                            ...(inp.pipeline_input ? { pipeline_input: inp.pipeline_input } : {}),
-                            ...(inp.description ? { description: inp.description } : {}),
-                            required: inp.required !== false,
-                        })),
-                        outputs: (s.outputs || []).map((o) => ({
-                            name: o.name,
-                            type: o.type || 'text',
-                            ...(o.description ? { description: o.description } : {}),
-                            required: o.required !== false,
-                            ...(o.format ? { format: o.format } : {}),
-                        })),
-                        sections: s.sections || '',
-                        reviewer: s.reviewer || null,
-                        max_review_cycles: s.maxReviewCycles || 0,
-                        execution_config: s.executionMode === 'script' ? {
-                            image: s.image || '',
-                            command: s.command || '',
-                        } : null,
-                        parallel_group: null,
-                        sort_order: i,
-                    })),
-                }],
-        };
-        const body = {
-            name: raw.name || file,
-            description: raw.description || '',
-            definition,
+        const data = await api('GET', `/api/pipeline-templates/${templateId}`);
+        const t = data.template;
+        requireDraftStatus(t);
+        const phase = findPhaseById(t.definition, opts.phase);
+        if (!phase) {
+            console.error(chalk.red(`Phase "${opts.phase}" not found`));
+            process.exit(1);
+        }
+        if (opts.name) {
+            if (t.definition.phases.find((p) => p.id !== opts.phase && p.name === opts.name)) {
+                console.error(chalk.red(`Phase name "${opts.name}" already exists`));
+                process.exit(1);
+            }
+            phase.name = opts.name;
+        }
+        if (opts.description != null)
+            phase.description = opts.description;
+        await api('PUT', `/api/pipeline-templates/${templateId}`, { definition: t.definition });
+        console.log(chalk.green(`Updated phase: ${phase.name}`));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+templates
+    .command('add-step')
+    .description('Add a step to a phase. Template must be in draft status. Step names must be unique within their phase. Returns the generated step ID needed by I/O commands (add-output, add-input, etc.). Use "tpl show" or "tpl steps" to find existing step IDs.')
+    .argument('<templateId>', 'Template ID')
+    .requiredOption('--phase <phaseId>', 'Phase ID (from "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('--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')
+    .option('--max-review-cycles <n>', 'Max review cycles before auto-approval', '0')
+    .option('--parallel-group <group>', 'Group name for parallel execution (steps in the same group run concurrently)')
+    .action(async (templateId, opts) => {
+    try {
+        if (!VALID_STEP_TYPES.includes(opts.type)) {
+            console.error(chalk.red(`Invalid step type "${opts.type}". Valid: ${VALID_STEP_TYPES.join(', ')}`));
+            process.exit(1);
+        }
+        const data = await api('GET', `/api/pipeline-templates/${templateId}`);
+        const t = data.template;
+        requireDraftStatus(t);
+        const phase = findPhaseById(t.definition, opts.phase);
+        if (!phase) {
+            console.error(chalk.red(`Phase "${opts.phase}" not found`));
+            process.exit(1);
+        }
+        if (!phase.steps)
+            phase.steps = [];
+        if (phase.steps.find((s) => s.name === opts.name)) {
+            console.error(chalk.red(`Step "${opts.name}" already exists in phase "${phase.name}"`));
+            process.exit(1);
+        }
+        const step = {
+            id: crypto.randomUUID(),
+            name: opts.name,
+            description: opts.description || '',
+            step_type: opts.type,
+            role: opts.role || 'unassigned',
+            inputs: [],
+            outputs: [],
+            sections: '',
+            reviewer: opts.reviewer || null,
+            max_review_cycles: parseInt(opts.maxReviewCycles) || 0,
+            execution_config: null,
+            parallel_group: opts.parallelGroup || null,
+            sort_order: phase.steps.length,
         };
-        const data = await api('POST', '/api/pipeline-templates', body);
+        phase.steps.push(step);
+        await api('PUT', `/api/pipeline-templates/${templateId}`, { definition: t.definition });
+        console.log(chalk.green(`Added step: ${opts.name} (${opts.type}) to phase ${phase.name}`));
+        console.log(`  ID: ${step.id}`);
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+templates
+    .command('remove-step')
+    .description('Remove a step from a template. Blocked if other steps reference this step\'s outputs as inputs unless --force is used. Template must be in draft status. Use "tpl steps" to find step IDs.')
+    .argument('<templateId>', 'Template ID')
+    .requiredOption('--step <stepId>', 'Step ID (from "tpl steps" output)')
+    .option('--force', 'Remove even if other steps reference this step\'s outputs')
+    .action(async (templateId, opts) => {
+    try {
+        const data = await api('GET', `/api/pipeline-templates/${templateId}`);
         const t = data.template;
-        console.log(chalk.green(`Imported: ${t.name} (${joeSteps.length} steps)`));
-        console.log(`  ID: ${t.id}`);
+        requireDraftStatus(t);
+        // Find the step and its phase
+        let targetPhase = null;
+        let stepIdx = -1;
+        for (const phase of t.definition.phases || []) {
+            const idx = (phase.steps || []).findIndex((s) => s.id === opts.step);
+            if (idx !== -1) {
+                targetPhase = phase;
+                stepIdx = idx;
+                break;
+            }
+        }
+        if (!targetPhase) {
+            console.error(chalk.red(`Step "${opts.step}" not found`));
+            process.exit(1);
+        }
+        const step = targetPhase.steps[stepIdx];
+        // Check for references from other steps
+        const refs = allSteps(t.definition).filter((s) => s.id !== step.id && (s.inputs || []).some((inp) => inp.source_step_id === step.id));
+        if (refs.length && !opts.force) {
+            console.error(chalk.yellow(`Step "${step.name}" is referenced by: ${refs.map((r) => r.name).join(', ')}`));
+            console.error(chalk.yellow('Use --force to remove anyway'));
+            process.exit(1);
+        }
+        targetPhase.steps.splice(stepIdx, 1);
+        await api('PUT', `/api/pipeline-templates/${templateId}`, { definition: t.definition });
+        console.log(chalk.green(`Removed step: ${step.name}`));
     }
     catch (err) {
         console.error(chalk.red(err.message));
@@ -898,13 +1959,64 @@ templates
     }
 });
 templates
-    .command('activate')
-    .description('Activate a template (required before creating instances)')
-    .argument('<id>', 'Template ID')
-    .action(async (id) => {
+    .command('edit-step')
+    .description('Edit step properties. Template must be in draft status. Provide at least one field to update. Use "tpl steps" to find step IDs.')
+    .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('--role <role>', 'Role or agent name')
+    .option('--description <desc>', 'Description')
+    .option('--reviewer <reviewer>', 'Reviewer role (empty string to clear)')
+    .option('--max-review-cycles <n>', 'Max review cycles')
+    .option('--parallel-group <group>', 'Parallel execution group (empty string to clear)')
+    .action(async (templateId, opts) => {
     try {
-        await api('PATCH', `/api/pipeline-templates/${id}/status`, { status: 'active' });
-        console.log(chalk.green('Template activated'));
+        const hasUpdate = opts.name || opts.type || opts.role || opts.description != null
+            || opts.reviewer != null || opts.maxReviewCycles != null || opts.parallelGroup != null;
+        if (!hasUpdate) {
+            console.error(chalk.red('Provide at least one field to update'));
+            process.exit(1);
+        }
+        if (opts.type && !VALID_STEP_TYPES.includes(opts.type)) {
+            console.error(chalk.red(`Invalid step type "${opts.type}". Valid: ${VALID_STEP_TYPES.join(', ')}`));
+            process.exit(1);
+        }
+        const data = await api('GET', `/api/pipeline-templates/${templateId}`);
+        const t = data.template;
+        requireDraftStatus(t);
+        const step = findStepById(t.definition, opts.step);
+        if (!step) {
+            console.error(chalk.red(`Step "${opts.step}" not found`));
+            process.exit(1);
+        }
+        if (opts.name) {
+            // Check uniqueness within the step's phase
+            for (const phase of t.definition.phases || []) {
+                if (phase.steps?.find((s) => s.id === step.id)) {
+                    if (phase.steps.find((s) => s.id !== step.id && s.name === opts.name)) {
+                        console.error(chalk.red(`Step name "${opts.name}" already exists in phase "${phase.name}"`));
+                        process.exit(1);
+                    }
+                    break;
+                }
+            }
+            step.name = opts.name;
+        }
+        if (opts.type)
+            step.step_type = opts.type;
+        if (opts.role)
+            step.role = opts.role;
+        if (opts.description != null)
+            step.description = opts.description;
+        if (opts.reviewer != null)
+            step.reviewer = opts.reviewer || null;
+        if (opts.maxReviewCycles != null)
+            step.max_review_cycles = parseInt(opts.maxReviewCycles) || 0;
+        if (opts.parallelGroup != null)
+            step.parallel_group = opts.parallelGroup || null;
+        await api('PUT', `/api/pipeline-templates/${templateId}`, { definition: t.definition });
+        console.log(chalk.green(`Updated step: ${step.name}`));
     }
     catch (err) {
         console.error(chalk.red(err.message));
@@ -914,7 +2026,7 @@ templates
 // ── Template I/O commands ──────────────────────────────────
 templates
     .command('steps')
-    .description('List step IDs and names in a template')
+    .description('List step IDs and names in a template. Use this to discover step IDs needed by --step options in add-output, add-input, remove-step, edit-step, etc.')
     .argument('<id>', 'Template ID')
     .action(async (id) => {
     try {
@@ -935,14 +2047,14 @@ templates
 });
 templates
     .command('add-output')
-    .description('Add an output declaration to a step')
+    .description('Declare what a step produces. Outputs can be consumed by downstream steps via add-input. Template must be in draft status. Output names must be unique within the step.')
     .argument('<templateId>', 'Template ID')
-    .requiredOption('--step <stepId>', 'Step ID')
-    .requiredOption('--name <name>', 'Output name')
-    .requiredOption('--type <type>', `Output type: ${VALID_IO_TYPES.join(', ')}`)
-    .option('--description <desc>', 'Description')
-    .option('--optional', 'Mark as not required')
-    .option('--format <format>', 'Format hint (file_path, commit_sha, semver, date, etc.)')
+    .requiredOption('--step <stepId>', 'Step ID (from "tpl steps" output)')
+    .requiredOption('--name <name>', 'Output name (unique within the step, e.g., "requirements", "metrics_data")')
+    .requiredOption('--type <type>', 'Data type: text, markdown, number, boolean, url, json, object, array')
+    .option('--description <desc>', 'Human-readable description of what this output contains')
+    .option('--optional', 'Mark as not required (default: required)')
+    .option('--format <format>', 'Format hint: file_path, commit_sha, semver, date, datetime, email, integer, percentage')
     .action(async (templateId, opts) => {
     try {
         if (!VALID_IO_TYPES.includes(opts.type)) {
@@ -979,10 +2091,10 @@ templates
 });
 templates
     .command('remove-output')
-    .description('Remove an output declaration from a step')
+    .description('Remove an output declaration from a step. Blocked if downstream steps consume this output via add-input unless --force is used. Template must be in draft status.')
     .argument('<templateId>', 'Template ID')
-    .requiredOption('--step <stepId>', 'Step ID')
-    .requiredOption('--name <name>', 'Output name')
+    .requiredOption('--step <stepId>', 'Step ID (from "tpl steps" output)')
+    .requiredOption('--name <name>', 'Output name to remove')
     .option('--force', 'Remove even if downstream steps reference this output')
     .action(async (templateId, opts) => {
     try {
@@ -1017,15 +2129,18 @@ templates
 });
 templates
     .command('add-input')
-    .description('Add an input declaration to a step')
+    .description('Declare what a step consumes. Two modes (mutually exclusive):\n' +
+    '  Step-sourced: --source-step + --source-output (consumes output from another step)\n' +
+    '  Pipeline-sourced: --pipeline-input (consumes a template-level input)\n' +
+    'Validates that the source step/output/pipeline-input exists. Template must be in draft status.')
     .argument('<templateId>', 'Template ID')
-    .requiredOption('--step <stepId>', 'Step ID')
-    .requiredOption('--name <name>', 'Input name')
-    .option('--source-step <stepId>', 'Source step ID (for step-sourced inputs)')
-    .option('--source-output <name>', 'Source output name (for step-sourced inputs)')
-    .option('--pipeline-input <name>', 'Pipeline-level input name (for pipeline-sourced inputs)')
-    .option('--description <desc>', 'Description')
-    .option('--optional', 'Mark as not required')
+    .requiredOption('--step <stepId>', 'Step ID receiving the input (from "tpl steps" output)')
+    .requiredOption('--name <name>', 'Local input name (unique within the step)')
+    .option('--source-step <stepId>', 'Upstream step ID that produces the data (use with --source-output)')
+    .option('--source-output <name>', 'Output name on the source step (use with --source-step)')
+    .option('--pipeline-input <name>', 'Pipeline-level input name (use instead of --source-step/--source-output)')
+    .option('--description <desc>', 'What this data is used for')
+    .option('--optional', 'Mark as not required (default: required)')
     .action(async (templateId, opts) => {
     try {
         const hasSrc = opts.sourceStep || opts.sourceOutput;
@@ -1106,10 +2221,10 @@ templates
 });
 templates
     .command('remove-input')
-    .description('Remove an input declaration from a step')
+    .description('Remove an input declaration from a step. Template must be in draft status.')
     .argument('<templateId>', 'Template ID')
-    .requiredOption('--step <stepId>', 'Step ID')
-    .requiredOption('--name <name>', 'Input name')
+    .requiredOption('--step <stepId>', 'Step ID (from "tpl steps" output)')
+    .requiredOption('--name <name>', 'Input name to remove')
     .action(async (templateId, opts) => {
     try {
         const data = await api('GET', `/api/pipeline-templates/${templateId}`);
@@ -1136,12 +2251,12 @@ templates
 });
 templates
     .command('add-pipeline-input')
-    .description('Add a pipeline-level input to the template')
+    .description('Add a template-level input that is provided when creating a pipeline instance. Steps can consume these via "tpl add-input --pipeline-input <name>". Template must be in draft status.')
     .argument('<templateId>', 'Template ID')
-    .requiredOption('--name <name>', 'Input name')
-    .requiredOption('--type <type>', `Input type: ${VALID_IO_TYPES.join(', ')}`)
-    .option('--description <desc>', 'Description')
-    .option('--optional', 'Not required at instance creation')
+    .requiredOption('--name <name>', 'Input name (unique within the template)')
+    .requiredOption('--type <type>', 'Data type: text, markdown, number, boolean, url, json, object, array')
+    .option('--description <desc>', 'Human-readable description')
+    .option('--optional', 'Not required at instance creation (default: required)')
     .option('--default <value>', 'Default value')
     .action(async (templateId, opts) => {
     try {
@@ -1174,9 +2289,9 @@ templates
 });
 templates
     .command('remove-pipeline-input')
-    .description('Remove a pipeline-level input from the template')
+    .description('Remove a template-level input. Blocked if steps reference this input via --pipeline-input unless --force is used. Template must be in draft status.')
     .argument('<templateId>', 'Template ID')
-    .requiredOption('--name <name>', 'Input name')
+    .requiredOption('--name <name>', 'Pipeline input name to remove')
     .option('--force', 'Remove even if steps reference this input')
     .action(async (templateId, opts) => {
     try {
@@ -1207,7 +2322,7 @@ templates
 });
 templates
     .command('validate')
-    .description('Validate template I/O contracts')
+    .description('Validate template I/O contracts. Checks for: circular dependencies between steps, missing source step/output references, self-references, duplicate input names per step. Also reports warnings for unreferenced outputs and info for steps with no outputs declared. Run before activating to catch errors early.')
     .argument('<id>', 'Template ID')
     .action(async (id) => {
     try {
@@ -1639,6 +2754,50 @@ step
         process.exit(1);
     }
 });
+step
+    .command('approve')
+    .description('Approve a submitted step. The step must be in "submitted" status (awaiting review). Approval marks the step as completed and may trigger downstream steps to be queued. Use "pl show <id>" to see step statuses.')
+    .argument('<instanceId>', 'Pipeline instance ID')
+    .argument('<stepId>', 'Step instance ID')
+    .option('--notes <text>', 'Approval notes (visible to the step assignee)')
+    .action(async (instanceId, stepId, opts) => {
+    try {
+        const body = {};
+        if (opts.notes)
+            body.notes = opts.notes;
+        const data = await api('POST', `/api/pipeline-instances/${instanceId}/steps/${stepId}/approve`, body);
+        console.log(chalk.green(`Step approved: ${data.step?.step_name || stepId}`));
+        if (data.queued_steps?.length) {
+            console.log(chalk.cyan(`\n  Next steps queued: ${data.queued_steps.length}`));
+            for (const qs of data.queued_steps) {
+                console.log(`    ○ ${qs.step_name} [${qs.role || '-'}]`);
+            }
+        }
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+step
+    .command('revise')
+    .description('Request revision on a submitted step. Sends the step back to "in_progress" with feedback. The assignee can then resubmit. The step\'s review cycle counter increments; if max cycles are reached, the step auto-approves.')
+    .argument('<instanceId>', 'Pipeline instance ID')
+    .argument('<stepId>', 'Step instance ID')
+    .requiredOption('--reason <text>', 'Revision feedback explaining what needs to change')
+    .action(async (instanceId, stepId, opts) => {
+    try {
+        const data = await api('POST', `/api/pipeline-instances/${instanceId}/steps/${stepId}/revise`, {
+            reason: opts.reason,
+        });
+        console.log(chalk.green(`Revision requested: ${data.step?.step_name || stepId}`));
+        console.log(`  Status: ${data.step?.status}`);
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
 step
     .command('skip')
     .description('Skip a step')
@@ -2043,6 +3202,82 @@ executions
         process.exit(1);
     }
 });
+executions
+    .command('dispatch')
+    .description('Dispatch a pending execution, claiming it for container launch. Moves the execution from "pending" to "dispatched". Typically called by the execution dispatcher, not manually.')
+    .argument('<id>', 'Execution ID')
+    .action(async (id) => {
+    try {
+        const data = await api('POST', `/api/executions/${id}/dispatch`);
+        console.log(chalk.green(`Execution dispatched: ${data.execution?.id || id}`));
+        console.log(`  Status: ${data.execution?.status}`);
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+executions
+    .command('complete')
+    .description('Mark an execution as completed with optional results. Typically called by the agent container when work is done. Use "ex update" for partial updates during execution.')
+    .argument('<id>', 'Execution ID')
+    .option('-o, --output <json>', 'Final output data as JSON')
+    .option('--cost <usd>', 'Total cost in USD', parseNumber)
+    .option('--input-tokens <n>', 'Total input token count', parseNumber)
+    .option('--output-tokens <n>', 'Total output token count', parseNumber)
+    .option('--duration <ms>', 'Total duration in milliseconds', parseNumber)
+    .action(async (id, opts) => {
+    try {
+        const body = {};
+        if (opts.output)
+            body.outputData = JSON.parse(opts.output);
+        if (opts.cost !== undefined)
+            body.costUsd = opts.cost;
+        if (opts.inputTokens !== undefined)
+            body.inputTokens = opts.inputTokens;
+        if (opts.outputTokens !== undefined)
+            body.outputTokens = opts.outputTokens;
+        if (opts.duration !== undefined)
+            body.durationMs = opts.duration;
+        await api('POST', `/api/executions/${id}/complete`, body);
+        console.log(chalk.green('Execution completed'));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+executions
+    .command('fail')
+    .description('Mark an execution as failed with an error message. Typically called by the agent container on unrecoverable errors. Partial output and cost data can still be recorded.')
+    .argument('<id>', 'Execution ID')
+    .requiredOption('--error <text>', 'Error message describing the failure')
+    .option('-o, --output <json>', 'Partial output data as JSON (any work completed before failure)')
+    .option('--cost <usd>', 'Cost incurred in USD', parseNumber)
+    .option('--input-tokens <n>', 'Input token count', parseNumber)
+    .option('--output-tokens <n>', 'Output token count', parseNumber)
+    .option('--duration <ms>', 'Duration in milliseconds before failure', parseNumber)
+    .action(async (id, opts) => {
+    try {
+        const body = { error: opts.error };
+        if (opts.output)
+            body.outputData = JSON.parse(opts.output);
+        if (opts.cost !== undefined)
+            body.costUsd = opts.cost;
+        if (opts.inputTokens !== undefined)
+            body.inputTokens = opts.inputTokens;
+        if (opts.outputTokens !== undefined)
+            body.outputTokens = opts.outputTokens;
+        if (opts.duration !== undefined)
+            body.durationMs = opts.duration;
+        await api('POST', `/api/executions/${id}/fail`, body);
+        console.log(chalk.green('Execution marked as failed'));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
 executions
     .command('cloudwatch-logs')
     .alias('cw')