@formigio/fazemos-cli 0.3.0 → 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')
@@ -549,19 +929,111 @@ members
     }
 });
 members
-    .command('list')
-    .description('List worksheet members')
-    .requiredOption('-w, --worksheet <id>', 'Worksheet ID')
-    .action(async (opts) => {
+    .command('list')
+    .description('List worksheet members')
+    .requiredOption('-w, --worksheet <id>', 'Worksheet ID')
+    .action(async (opts) => {
+    try {
+        const data = await api('GET', `/api/worksheets/${opts.worksheet}/members`);
+        if (!data.members?.length) {
+            console.log(chalk.yellow('No members'));
+            return;
+        }
+        for (const m of data.members) {
+            console.log(`  ${chalk.cyan(m.display_name)} (${m.worksheet_role}) — ${m.member_id}`);
+        }
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+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('-m, --member <id>', 'Worksheet member ID (from "members list" output)')
+    .requiredOption('-r, --role <role>', 'New role: lead or contributor')
+    .action(async (opts) => {
+    try {
+        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 {
-        const data = await api('GET', `/api/worksheets/${opts.worksheet}/members`);
-        if (!data.members?.length) {
-            console.log(chalk.yellow('No members'));
-            return;
-        }
-        for (const m of data.members) {
-            console.log(`  ${chalk.cyan(m.display_name)} (${m.worksheet_role}) — ${m.member_id}`);
-        }
+        await api('DELETE', `/api/members/${id}`);
+        console.log(chalk.green('Member removed from organization'));
     }
     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 = [];
@@ -1996,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')
@@ -2400,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')