@4ge/cli 0.1.0 → 0.2.1

package/dist/base.js

@@ -117,7 +117,7 @@ export class BaseCommand extends Command {
         options?.onStatusChange?.('refreshing-token');
         const credential = await ensureFreshToken();
         if (!credential) {
-            const message = 'Not authenticated. Run `4ge auth login --token <api_key>` first.';
+            const message = 'Not authenticated. Run `4ge auth:login --token <api_key>` first.';
             if (this.isJsonMode) {
                 this.outputErrorAndExit({ message, code: 'NO_CREDENTIALS' });
             }

package/dist/commands/auth/status.js

@@ -12,7 +12,7 @@ export default class AuthStatus extends BaseCommand {
                 this.outputErrorAndExit({ message: 'Not authenticated', code: 'NO_CREDENTIALS' });
             }
             else {
-                this.log('Not authenticated. Run `4ge auth login --token <api_key>` to authenticate.');
+                this.log('Not authenticated. Run `4ge auth:login --token <api_key>` to authenticate.');
             }
             return;
         }
@@ -37,7 +37,7 @@ export default class AuthStatus extends BaseCommand {
                 this.outputErrorAndExit({
                     message,
                     code,
-                    hint: refreshError.message || "Run '4ge auth login' to re-authenticate."
+                    hint: refreshError.message || "Run '4ge auth:login' to re-authenticate."
                 });
             }
             else {
@@ -47,7 +47,7 @@ export default class AuthStatus extends BaseCommand {
                 else {
                     this.log('⚠ Session expired — token refresh failed.');
                 }
-                this.log(`  ${refreshError.message || "Run '4ge auth login' to re-authenticate."}`);
+                this.log(`  ${refreshError.message || "Run '4ge auth:login' to re-authenticate."}`);
             }
             return;
         }
@@ -65,7 +65,7 @@ export default class AuthStatus extends BaseCommand {
                         this.outputErrorAndExit({
                             message: 'API validation failed for 4GE_API_KEY',
                             code: 'ENV_CREDENTIAL_OVERRIDE',
-                            hint: 'The 4GE_API_KEY environment variable is overriding stored credentials but is invalid. Unset it to use credentials from "4ge auth login".'
+                            hint: 'The 4GE_API_KEY environment variable is overriding stored credentials but is invalid. Unset it to use credentials from "4ge auth:login".'
                         });
                     }
                     else {
@@ -77,7 +77,7 @@ export default class AuthStatus extends BaseCommand {
                         this.log('⚠ Using API key from 4GE_API_KEY environment variable, but server validation failed.');
                         this.log('');
                         this.log('The 4GE_API_KEY environment variable takes priority over stored credentials.');
-                        this.log('FIX: Unset 4GE_API_KEY (e.g., `unset 4GE_API_KEY`) to use credentials from `4ge auth login`.');
+                        this.log('FIX: Unset 4GE_API_KEY (e.g., `unset 4GE_API_KEY`) to use credentials from `4ge auth:login`.');
                     }
                     else {
                         this.log(`Authenticated via ${activeCredential.source}${activeCredential.profile ? ` (profile: ${activeCredential.profile})` : ''}, but API validation failed.`);

package/dist/commands/config/index.js

@@ -3,7 +3,7 @@ export default class ConfigIndex extends Command {
     static description = 'Manage CLI configuration';
     static hidden = true;
     async run() {
-        this.log('Use `4ge config manage` for interactive configuration.');
-        this.log('Use `4ge config show`, `4ge config get`, or `4ge config set` for direct access.');
+        this.log('Use `4ge config:manage` for interactive configuration.');
+        this.log('Use `4ge config:show`, `4ge config:get`, or `4ge config:set` for direct access.');
     }
 }

package/dist/commands/config/show.js

@@ -26,8 +26,8 @@ export default class ConfigShow extends BaseCommand {
             ] }));
         if (this.isInteractiveMode) {
             await this.handleActionHints([
-                { label: 'Set config', command: '4ge config set <key> <value>' },
-                { label: 'Get config', command: '4ge config get <key>' },
+                { label: 'Set config', command: '4ge config:set <key> <value>' },
+                { label: 'Get config', command: '4ge config:get <key>' },
             ]);
         }
     }

package/dist/commands/epic/list.js

@@ -75,7 +75,7 @@ export default class EpicList extends BaseCommand {
                         const selectedId = await this.selectOption('Select an epic for details:', options, { headerVariant: 'compact' });
                         if (selectedId) {
                             const { default: chalk } = await import('chalk');
-                            this.log(`\n  🚀 Run: ${chalk.cyan(`4ge epic show ${selectedId}`)}\n`);
+                            this.log(`\n  🚀 Run: ${chalk.cyan(`4ge epic:show ${selectedId}`)}\n`);
                         }
                     }
                     if (metadata?.action_hints) {

package/dist/commands/feature/list.js

@@ -77,7 +77,7 @@ export default class FeatureList extends BaseCommand {
                         const selectedId = await this.selectOption('Select a feature for details:', options, { headerVariant: 'compact' });
                         if (selectedId) {
                             const { default: chalk } = await import('chalk');
-                            this.log(`\n  🚀 Run: ${chalk.cyan(`4ge feature show ${selectedId}`)}\n`);
+                            this.log(`\n  🚀 Run: ${chalk.cyan(`4ge feature:show ${selectedId}`)}\n`);
                         }
                     }
                     if (metadata?.action_hints) {

package/dist/commands/flow/index.js

@@ -0,0 +1,10 @@
+import { Help } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+export default class FlowIndex extends BaseCommand {
+    static description = 'Manage feature flows in your project';
+    async run() {
+        await this.renderHeader('ready', 'compact');
+        const help = new Help(this.config);
+        await help.showHelp(['flow']);
+    }
+}

package/dist/commands/flow/list.js

@@ -0,0 +1,85 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { listFlows } from '../../generated/api/sdk.gen.js';
+import { zListFlowsResponse } from '../../generated/api/zod.gen.js';
+import { validateResponse } from '../../core/api/index.js';
+import { DataTable } from '../../ui/index.js';
+export default class FlowList extends BaseCommand {
+    static description = 'List flows for a feature in the current project';
+    static examples = [
+        '<%= config.bin %> flow:list --feature-id <uuid>',
+        '<%= config.bin %> flow:list --feature-id <uuid> --roadmap now --json',
+        '<%= config.bin %> flow:list --feature-id <uuid> --status IN_DEVELOPMENT',
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        'feature-id': Flags.string({
+            description: 'Feature ID whose flows to list (a feature owns one implied flow)',
+            required: true,
+        }),
+        roadmap: Flags.string({
+            description: 'Filter by roadmap status (now|next|later)',
+            options: ['now', 'next', 'later'],
+        }),
+        status: Flags.string({
+            description: 'Filter by status (e.g. BACKLOG, IN_DEVELOPMENT, COMPLETE)',
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(FlowList);
+        await this.renderHeader('ready', 'compact');
+        const client = await this.getClient();
+        const projectId = await this.getProjectIdOrExit();
+        try {
+            const response = await this.withSpinner('Fetching flows...', () => listFlows({
+                client,
+                path: {
+                    projectId,
+                    featureId: flags['feature-id'],
+                },
+                query: {
+                    ...(flags.roadmap ? { roadmap: flags.roadmap } : {}),
+                    ...(flags.status ? { status: flags.status } : {}),
+                },
+            }));
+            const { data, error } = response;
+            const validated = validateResponse(data, error, zListFlowsResponse);
+            const items = validated.data;
+            const metadata = validated.metadata;
+            if (this.isJsonMode) {
+                this.outputJson(items, { source: 'flow list' });
+            }
+            else {
+                await this.renderInk(_jsx(DataTable, { data: items, columns: [
+                        { key: 'label', header: 'Title', minWidth: 20 },
+                        { key: 'id', header: 'ID' },
+                        { key: 'status', header: 'Status', color: 'auto' },
+                        { key: 'roadmap_status', header: 'Roadmap' },
+                        { key: 'step_count', header: 'Steps' },
+                        { key: 'parent_feature_id', header: 'Feature ID' },
+                    ], title: `Flows in feature ${flags['feature-id']}${flags.roadmap ? ` (${flags.roadmap})` : ''}`, emptyMessage: `No flows found${flags.roadmap ? ` for roadmap: ${flags.roadmap}` : ''}` }));
+                if (this.isInteractiveMode) {
+                    if (items.length > 0) {
+                        const options = items.map((item) => ({
+                            label: item.label || item.id,
+                            value: item.id,
+                            description: item.status || '',
+                        }));
+                        const selectedId = await this.selectOption('Select a flow for details:', options, { headerVariant: 'compact' });
+                        if (selectedId) {
+                            const { default: chalk } = await import('chalk');
+                            this.log(`\n  🚀 Run: ${chalk.cyan(`4ge flow:show ${selectedId}`)}\n`);
+                        }
+                    }
+                    if (metadata?.action_hints) {
+                        await this.handleActionHints(metadata.action_hints);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            this.handleError('An unexpected error occurred', err);
+        }
+    }
+}

package/dist/commands/flow/pull.js

@@ -0,0 +1,109 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { getCollectionDir } from '../../core/config/index.js';
+import { resolveRecursive } from '../../core/config/defaults.js';
+import { getFlow, getFlowTree } from '../../generated/api/sdk.gen.js';
+import { zGetFlowTreeResponse, zGetFlowResponse } from '../../generated/api/zod.gen.js';
+import { validateResponse } from '../../core/api/index.js';
+import { SuccessMessage } from '../../ui/index.js';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+export default class FlowPull extends BaseCommand {
+    static description = 'Download flow details';
+    static examples = [
+        '<%= config.bin %> flow:pull --id <uuid>',
+        '<%= config.bin %> flow:pull --id <uuid> --json',
+        '<%= config.bin %> flow:pull --id <uuid> --recursive',
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        id: Flags.string({
+            description: 'Flow ID',
+            required: true,
+        }),
+        recursive: Flags.boolean({
+            description: 'Pull full flow tree (flow + step nodes) instead of just the flow detail',
+            allowNo: true,
+        }),
+        save: Flags.boolean({
+            description: 'Force save to disk even in JSON mode',
+            default: false,
+        }),
+        stdout: Flags.boolean({
+            description: 'Print to stdout without saving',
+            default: false,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(FlowPull);
+        if (flags.json && flags.stdout) {
+            this.error('Cannot use --json and --stdout together');
+        }
+        if (flags.save && flags.stdout) {
+            this.error('Cannot use --stdout and --save together');
+        }
+        await this.renderHeader('ready', 'compact');
+        await this.migrateAssetsIfNeeded();
+        const client = await this.getClient();
+        const projectId = await this.getProjectIdOrExit();
+        const isRecursive = resolveRecursive(flags.recursive, this.localConfig);
+        const spinnerMsg = isRecursive ? `Pulling flow ${flags.id} tree...` : `Pulling flow ${flags.id}...`;
+        const response = await this.withSpinner(spinnerMsg, () => {
+            if (isRecursive) {
+                return getFlowTree({
+                    client,
+                    path: {
+                        projectId,
+                        flowId: flags.id,
+                    },
+                });
+            }
+            else {
+                return getFlow({
+                    client,
+                    path: {
+                        projectId,
+                        flowId: flags.id,
+                    },
+                });
+            }
+        });
+        const { data, error } = response;
+        try {
+            let flow;
+            let metadata;
+            if (isRecursive) {
+                const validated = validateResponse(data, error, zGetFlowTreeResponse);
+                flow = validated.data;
+                metadata = validated.metadata;
+            }
+            else {
+                const validated = validateResponse(data, error, zGetFlowResponse);
+                flow = validated.data;
+                metadata = validated.metadata;
+            }
+            const savePath = path.join(getCollectionDir('flows'), `${flags.id}.json`);
+            if (this.isJsonMode) {
+                this.outputJson(flow);
+                if (flags.save) {
+                    await this.saveToFile(savePath, flow);
+                }
+            }
+            else if (flags.stdout) {
+                this.log(JSON.stringify(flow, null, 2));
+            }
+            else {
+                await this.saveToFile(savePath, flow);
+                await this.renderInk(_jsx(SuccessMessage, { message: `Flow saved to .4ge/assets/flows/${flags.id}.json` }));
+            }
+        }
+        catch (err) {
+            this.handleError(`Failed to pull flow: ${flags.id}`, err);
+        }
+    }
+    async saveToFile(filePath, data) {
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        await fs.writeFile(filePath, JSON.stringify(data, null, 2), 'utf-8');
+    }
+}

package/dist/commands/flow/show.js

@@ -0,0 +1,58 @@
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { getFlow } from '../../generated/api/sdk.gen.js';
+import { zGetFlowResponse } from '../../generated/api/zod.gen.js';
+import { validateResponse } from '../../core/api/index.js';
+export default class FlowShow extends BaseCommand {
+    static description = 'Show detailed information for a specific flow';
+    static examples = [
+        '<%= config.bin %> flow:show --id <uuid>',
+        '<%= config.bin %> flow:show --id <uuid> --json',
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        id: Flags.string({
+            description: 'Flow ID',
+            required: true,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(FlowShow);
+        const client = await this.getClient();
+        const projectId = await this.getProjectIdOrExit();
+        await this.renderHeader('ready', 'compact');
+        const response = await this.withSpinner(`Fetching flow ${flags.id}...`, () => getFlow({
+            client,
+            path: {
+                projectId,
+                flowId: flags.id,
+            },
+        }));
+        const { data, error } = response;
+        try {
+            const validated = validateResponse(data, error, zGetFlowResponse);
+            const payload = validated.data;
+            const metadata = validated.metadata;
+            if (this.isJsonMode) {
+                this.outputJson(payload, { source: 'flow show' });
+            }
+            else {
+                this.log(`\nFlow: ${payload.label}`);
+                this.log(`ID:     ${payload.id}`);
+                this.log(`Status: ${payload.status}`);
+                this.log(`Roadmap: ${payload.roadmap_status ?? 'None'}`);
+                this.log(`Feature ID: ${payload.parent_feature_id ?? payload.parent_id ?? 'None'}`);
+                this.log(`Steps:  ${payload.step_count}`);
+                if (payload.description) {
+                    this.log(`\nDescription:\n${payload.description}\n`);
+                }
+                if (this.isInteractiveMode && metadata?.action_hints) {
+                    await this.handleActionHints(metadata.action_hints);
+                }
+            }
+        }
+        catch (err) {
+            this.handleError(`Failed to fetch flow detail for ID: ${flags.id}`, err);
+        }
+    }
+}

package/dist/commands/flow/update.js

@@ -0,0 +1,105 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { updateFlow } from '../../generated/api/sdk.gen.js';
+import { zUpdateFlowResponse } from '../../generated/api/zod.gen.js';
+import { validateResponse } from '../../core/api/index.js';
+import { SuccessMessage } from '../../ui/index.js';
+export default class FlowUpdate extends BaseCommand {
+    static description = 'Update a flow';
+    static examples = [
+        '<%= config.bin %> flow:update --id <uuid> --status IN_DEVELOPMENT',
+        '<%= config.bin %> flow:update --id <uuid> --status COMPLETE --title "New Title"',
+        '<%= config.bin %> flow:update --id <uuid> --roadmap-status next --priority MUST_HAVE',
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        id: Flags.string({
+            description: 'Flow ID (UUID)',
+            required: true,
+        }),
+        status: Flags.string({
+            description: 'New status (BACKLOG|NOT_STARTED|IN_PLANNING|READY_FOR_DEVELOPMENT|IN_DEVELOPMENT|BLOCKED|REVIEW|COMPLETE)',
+            options: ['BACKLOG', 'NOT_STARTED', 'IN_PLANNING', 'READY_FOR_DEVELOPMENT', 'IN_DEVELOPMENT', 'BLOCKED', 'REVIEW', 'COMPLETE'],
+        }),
+        title: Flags.string({
+            description: 'New title',
+        }),
+        description: Flags.string({
+            description: 'New description',
+        }),
+        priority: Flags.string({
+            description: 'New priority (MUST_HAVE|SHOULD_HAVE|BACKLOG)',
+            options: ['MUST_HAVE', 'SHOULD_HAVE', 'BACKLOG'],
+        }),
+        'roadmap-status': Flags.string({
+            description: 'New roadmap status (now|next|later)',
+            options: ['now', 'next', 'later'],
+        }),
+        force: Flags.boolean({
+            description: 'Skip confirmation prompt',
+            default: false,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(FlowUpdate);
+        const projectId = await this.getProjectIdOrExit();
+        await this.renderHeader('ready', 'compact');
+        const body = {};
+        if (flags.status !== undefined)
+            body.status = flags.status;
+        if (flags.title !== undefined)
+            body.label = flags.title;
+        if (flags.description !== undefined)
+            body.description = flags.description;
+        if (flags.priority !== undefined)
+            body.priority = flags.priority;
+        if (flags['roadmap-status'] !== undefined)
+            body.roadmap_status = flags['roadmap-status'];
+        if (Object.keys(body).length === 0) {
+            const message = 'At least one field must be provided to update (--status, --title, --description, --priority, --roadmap-status)';
+            if (this.isJsonMode) {
+                this.outputErrorAndExit({ message, code: 'MISSING_INPUT' });
+            }
+            else {
+                this.error(message);
+            }
+        }
+        const confirmed = await this.confirmAction(`Update flow ${flags.id}?`, flags.force, { headerVariant: 'compact' });
+        if (!confirmed)
+            return;
+        const payload = {
+            path: {
+                projectId,
+                flowId: flags.id,
+            },
+            body,
+        };
+        if (this.isDryRun) {
+            await this.handleDryRun(payload);
+            return;
+        }
+        const client = await this.getClient();
+        const { data, error } = await this.withSpinner(`Updating flow ${flags.id}...`, () => updateFlow({
+            client,
+            ...payload,
+        }));
+        try {
+            const validated = validateResponse(data, error, zUpdateFlowResponse);
+            const flow = validated.data;
+            const metadata = validated.metadata;
+            if (this.isJsonMode) {
+                this.outputJson(flow, { source: 'flow update', ...metadata });
+            }
+            else {
+                await this.renderInk(_jsx(SuccessMessage, { message: `Flow ${flags.id} updated successfully!` }));
+                if (this.isInteractiveMode && metadata?.action_hints) {
+                    await this.handleActionHints(metadata.action_hints);
+                }
+            }
+        }
+        catch (err) {
+            this.handleError(`Failed to update flow: ${flags.id}`, err);
+        }
+    }
+}

package/dist/commands/idea/graduate.js

@@ -74,8 +74,8 @@ export default class IdeaGraduate extends BaseCommand {
                 if (this.isInteractiveMode) {
                     const { default: chalk } = await import('chalk');
                     this.log(`\n  🚀 Next steps:`);
-                    this.log(`  - Project info: ${chalk.cyan(`4ge project info --id ${result.id}`)}`);
-                    this.log(`  - Pull plan:    ${chalk.cyan(`4ge plan pull --project ${result.id}`)}`);
+                    this.log(`  - Project info: ${chalk.cyan(`4ge project:info --id ${result.id}`)}`);
+                    this.log(`  - Pull plan:    ${chalk.cyan(`4ge plan:pull --project ${result.id}`)}`);
                     if (metadata?.action_hints) {
                         await this.handleActionHints(metadata.action_hints);
                     }

package/dist/commands/init.js

@@ -326,7 +326,7 @@ export default class Init extends BaseCommand {
                     this.log(`Skill installed at: ${skillPath}`);
                     this.log(chalk.dim('Reload your AI agent to pick up the new skill.'));
                 }
-                this.log(chalk.dim('\nConfigure additional settings with: 4ge config manage'));
+                this.log(chalk.dim('\nConfigure additional settings with: 4ge config:manage'));
                 this.log(chalk.dim('Available: default mode, hierarchy settings, pull settings\n'));
             }
         }

package/dist/commands/login.js

@@ -1,5 +1,5 @@
 import AuthLogin from './auth/login.js';
 export default class Login extends AuthLogin {
-    static description = 'Alias for `4ge auth login`';
+    static description = 'Alias for `4ge auth:login`';
     static hidden = false;
 }

package/dist/commands/project/index.js

@@ -4,6 +4,6 @@ export default class Project extends BaseCommand {
     static hidden = true;
     async run() {
         await this.renderHeader('ready', 'compact');
-        this.log('Use `4ge project list` to list projects.');
+        this.log('Use `4ge project:list` to list projects.');
     }
 }

package/dist/commands/project/list.js

@@ -62,7 +62,7 @@ export default class ProjectList extends BaseCommand {
                         const selectedId = await this.selectOption('Select a project for details:', options, { headerVariant: 'compact' });
                         if (selectedId) {
                             const { default: chalk } = await import('chalk');
-                            this.log(`\n  🚀 Run: ${chalk.cyan(`4ge project show ${selectedId}`)}\n`);
+                            this.log(`\n  🚀 Run: ${chalk.cyan(`4ge project:show ${selectedId}`)}\n`);
                         }
                     }
                     if (metadata?.action_hints) {

package/dist/commands/story/list.js

@@ -65,7 +65,7 @@ export default class StoryList extends BaseCommand {
                         const selectedId = await this.selectOption('Select a story for details:', options, { headerVariant: 'compact' });
                         if (selectedId) {
                             const { default: chalk } = await import('chalk');
-                            this.log(`\n  🚀 Run: ${chalk.cyan(`4ge story show ${selectedId}`)}\n`);
+                            this.log(`\n  🚀 Run: ${chalk.cyan(`4ge story:show ${selectedId}`)}\n`);
                         }
                     }
                     if (metadata?.action_hints) {

package/dist/commands/template/list.js

@@ -5,6 +5,8 @@ import { listTemplates } from '../../generated/api/sdk.gen.js';
 import { zListTemplatesResponse } from '../../generated/api/zod.gen.js';
 import { validateResponse } from '../../core/api/index.js';
 import { DataTable } from '../../ui/index.js';
+/** Render a boolean as a checkmark or empty string. Pure — extracted from the DataTable column def so it's unit-testable. */
+export const formatCheckmark = (v) => (v ? '✓' : '');
 export default class TemplateList extends BaseCommand {
     static description = 'List all available project templates';
     static flags = {
@@ -52,7 +54,7 @@ export default class TemplateList extends BaseCommand {
                     { key: 'framework', header: 'Framework' },
                     { key: 'author', header: 'Author' },
                     { key: 'featuresCount', header: 'Features' },
-                    { key: 'isOfficial', header: 'Official', format: (v) => (v ? '✓' : '') },
+                    { key: 'isOfficial', header: 'Official', format: formatCheckmark },
                 ], title: "Available Templates", emptyMessage: flags.workspace ? `No templates found for workspace: ${flags.workspace}` : 'No templates found.' }));
             if (this.isInteractiveMode) {
                 if (filteredTemplates.length > 0) {
@@ -64,7 +66,7 @@ export default class TemplateList extends BaseCommand {
                     const selectedId = await this.selectOption('Select a template for details:', options, { headerVariant: 'compact' });
                     if (selectedId) {
                         const { default: chalk } = await import('chalk');
-                        this.log(`\n  🚀 Run: ${chalk.cyan(`4ge template info --id ${selectedId}`)}\n`);
+                        this.log(`\n  🚀 Run: ${chalk.cyan(`4ge template:info --id ${selectedId}`)}\n`);
                     }
                 }
                 if (metadata?.action_hints) {

package/dist/commands/template/pull.js

@@ -87,8 +87,8 @@ export default class TemplatePull extends BaseCommand {
         }
         if (this.isInteractiveMode) {
             await this.handleActionHints([
-                { label: 'List template features', command: `4ge template feature list ${templateId}` },
-                { label: 'Project info', command: '4ge project info' },
+                { label: 'List template features', command: `4ge template:feature:list ${templateId}` },
+                { label: 'Project info', command: '4ge project:info' },
             ]);
         }
     }

package/dist/commands/whoami.js

@@ -1,5 +1,5 @@
 import AuthStatus from './auth/status.js';
 export default class Whoami extends AuthStatus {
-    static description = 'Alias for `4ge auth status`';
+    static description = 'Alias for `4ge auth:status`';
     static hidden = false;
 }

package/dist/core/auth/api-client.js

@@ -16,7 +16,7 @@ export function isAuthError(error) {
  */
 export function getAuthErrorHint(error) {
     if (error?.code === 'TOKEN_EXPIRED') {
-        return "Run '4ge auth login' to re-authenticate";
+        return "Run '4ge auth:login' to re-authenticate";
     }
     if (error?.code === 'INVALID_API_KEY') {
         return 'Check your 4GE_API_KEY environment variable';
@@ -146,7 +146,7 @@ export function createApiClient(opts) {
                 code: isPatAuth ? 'INVALID_API_KEY' : 'TOKEN_EXPIRED',
                 hint: isPatAuth
                     ? 'Check your 4GE_API_KEY environment variable'
-                    : "Run '4ge auth login' to re-authenticate",
+                    : "Run '4ge auth:login' to re-authenticate",
             };
             return authError;
         }

package/dist/core/auth/token-refresh.js

@@ -66,7 +66,7 @@ export async function ensureFreshToken() {
     }
     if (result.error || !result.data) {
         // Server is reachable and explicitly rejected the refresh token.
-        throw new Error(`Session expired. Please re-authenticate: run '4ge auth login'\n` +
+        throw new Error(`Session expired. Please re-authenticate: run '4ge auth:login'\n` +
             `Details: ${result.error?.message || 'Refresh token is invalid or expired'}`);
     }
     try {

package/dist/core/project/markdown.js

@@ -33,5 +33,5 @@ export function generateReadmeMd(project, filesGenerated) {
 ${fileLinks}
 
 ---
-*Generated by \`4ge project pull\` on ${date}*`;
+*Generated by \`4ge project:pull\` on ${date}*`;
 }

package/dist/generated/api/index.js

@@ -1,2 +1,2 @@
 // This file is auto-generated by @hey-api/openapi-ts
-export { cliAuthCallback, cliAuthEmailLogin, cliAuthLogin, cliAuthRefresh, cliAuthStatus, createIdea, createProject, createTemplate, createTemplateFeature, deleteTemplate, deleteTemplateFeature, getEpicDetail, getEpicTree, getFeatureDetail, getFeatureTree, getLatestPlanVersion, getPlanMetadata, getPlanTree, getPlanVersionDetail, getPlanVersions, getProjectDetail, getStoryDetail, getStoryTree, getTemplateDetail, graduateIdea, listEpics, listFeatures, listIdeas, listProjects, listStories, listTemplateFeatures, listTemplates, listWorkspaces, updateEpic, updateFeature, updateIdea, updateProject, updateStory, updateTemplate, updateTemplateFeature, } from "./sdk.gen.js";
+export { cliAuthCallback, cliAuthEmailLogin, cliAuthLogin, cliAuthRefresh, cliAuthStatus, createIdea, createProject, createTemplate, createTemplateFeature, deleteTemplate, deleteTemplateFeature, getEpicDetail, getEpicTree, getFeatureDetail, getFeatureTree, getFlow, getFlowTree, getLatestPlanVersion, getPlanMetadata, getPlanTree, getPlanVersionDetail, getPlanVersions, getProjectDetail, getStoryDetail, getStoryTree, getTemplateDetail, graduateIdea, listEpics, listFeatures, listFlows, listIdeas, listProjects, listStories, listTemplateFeatures, listTemplates, listWorkspaces, updateEpic, updateFeature, updateFlow, updateIdea, updateProject, updateStory, updateTemplate, updateTemplateFeature, } from "./sdk.gen.js";

package/dist/generated/api/sdk.gen.js

@@ -301,6 +301,62 @@ export const getFeatureTree = (options) => (options.client ?? client).get({
     url: "/api/cli/v1/projects/{projectId}/features/{featureId}/tree",
     ...options,
 });
+/**
+ * list-flows
+ *
+ * List flows under a feature. A feature owns one implied flow (its ordered useraction/systemresponse/conditional steps), so this returns a 1-element array. roadmap/status filters apply at the feature level.
+ */
+export const listFlows = (options) => (options.client ?? client).get({
+    security: [
+        { scheme: "bearer", type: "http" },
+        { name: "Authorization", type: "apiKey" },
+    ],
+    url: "/api/cli/v1/projects/{projectId}/features/{featureId}/flows",
+    ...options,
+});
+/**
+ * get-flow
+ *
+ * Get a flow summary. flowId is the owning feature id (a flow is the implied collection of steps attached to a feature via parent_feature_id).
+ */
+export const getFlow = (options) => (options.client ?? client).get({
+    security: [
+        { scheme: "bearer", type: "http" },
+        { name: "Authorization", type: "apiKey" },
+    ],
+    url: "/api/cli/v1/projects/{projectId}/flows/{flowId}",
+    ...options,
+});
+/**
+ * update-flow
+ *
+ * Update a flow. flowId is the owning feature id; flow-level metadata IS the feature metadata (status/label/description/roadmap/priority). Invalid enums return 422.
+ */
+export const updateFlow = (options) => (options.client ?? client).patch({
+    security: [
+        { scheme: "bearer", type: "http" },
+        { name: "Authorization", type: "apiKey" },
+    ],
+    url: "/api/cli/v1/projects/{projectId}/flows/{flowId}",
+    ...options,
+    headers: {
+        "Content-Type": "application/json",
+        ...options.headers,
+    },
+});
+/**
+ * get-flow-tree
+ *
+ * Get a flow with its ordered step tree. Steps are topologically sorted over project_plan_edges; conditional branches nest via parent_id.
+ */
+export const getFlowTree = (options) => (options.client ?? client).get({
+    security: [
+        { scheme: "bearer", type: "http" },
+        { name: "Authorization", type: "apiKey" },
+    ],
+    url: "/api/cli/v1/projects/{projectId}/flows/{flowId}/tree",
+    ...options,
+});
 /**
  * list-stories
  *

package/dist/generated/api/zod.gen.js

@@ -748,6 +748,173 @@ export const zGetFeatureTreeResponse = z.object({
         action_hints: z.array(z.unknown()).optional(),
     }),
 });
+export const zListFlowsPath = z.object({
+    projectId: z.uuid(),
+    featureId: z.uuid(),
+});
+export const zListFlowsQuery = z.object({
+    roadmap: z.enum(["now", "next", "later"]).optional(),
+    status: z.string().optional(),
+});
+/**
+ * Successful response
+ */
+export const zListFlowsResponse = z.object({
+    data: z.array(z.object({
+        id: z.uuid(),
+        label: z.string(),
+        description: z.string().nullable(),
+        node_type: z.enum(["flow"]),
+        status: z.enum([
+            "BACKLOG",
+            "NOT_STARTED",
+            "IN_PLANNING",
+            "READY_FOR_DEVELOPMENT",
+            "IN_DEVELOPMENT",
+            "BLOCKED",
+            "REVIEW",
+            "COMPLETE",
+        ]),
+        priority: z.string().nullable(),
+        roadmap_status: z
+            .enum(["now", "next", "later", "someday", "released"])
+            .optional(),
+        parent_id: z.uuid().nullable(),
+        parent_feature_id: z.uuid().nullish(),
+        project_id: z.uuid(),
+        workspace_id: z.uuid(),
+        position_x: z.number().optional(),
+        position_y: z.number().optional(),
+        step_count: z.int().gte(0),
+    })),
+    error: z.unknown(),
+    metadata: z.object({
+        timestamp: z.string(),
+        request_id: z.string(),
+        action_hints: z.array(z.unknown()).optional(),
+    }),
+});
+export const zGetFlowPath = z.object({
+    projectId: z.uuid(),
+    flowId: z.uuid(),
+});
+/**
+ * Successful response
+ */
+export const zGetFlowResponse = z.object({
+    data: z.object({
+        id: z.uuid(),
+        label: z.string(),
+        description: z.string().nullable(),
+        node_type: z.enum(["flow"]),
+        status: z.enum([
+            "BACKLOG",
+            "NOT_STARTED",
+            "IN_PLANNING",
+            "READY_FOR_DEVELOPMENT",
+            "IN_DEVELOPMENT",
+            "BLOCKED",
+            "REVIEW",
+            "COMPLETE",
+        ]),
+        priority: z.string().nullable(),
+        roadmap_status: z
+            .enum(["now", "next", "later", "someday", "released"])
+            .optional(),
+        parent_id: z.uuid().nullable(),
+        parent_feature_id: z.uuid().nullish(),
+        project_id: z.uuid(),
+        workspace_id: z.uuid(),
+        position_x: z.number().optional(),
+        position_y: z.number().optional(),
+        step_count: z.int().gte(0),
+    }),
+    error: z.unknown(),
+    metadata: z.object({
+        timestamp: z.string(),
+        request_id: z.string(),
+        action_hints: z.array(z.unknown()).optional(),
+    }),
+});
+export const zUpdateFlowBody = z.object({
+    label: z.string().min(1).optional(),
+    description: z.string().optional(),
+    status: z
+        .enum([
+        "BACKLOG",
+        "NOT_STARTED",
+        "IN_PLANNING",
+        "READY_FOR_DEVELOPMENT",
+        "IN_DEVELOPMENT",
+        "BLOCKED",
+        "REVIEW",
+        "COMPLETE",
+    ])
+        .optional(),
+    priority: z.enum(["MUST_HAVE", "SHOULD_HAVE", "BACKLOG"]).optional(),
+    roadmap_status: z
+        .enum(["now", "next", "later", "someday", "released"])
+        .optional(),
+    parent_id: z.uuid().optional(),
+});
+export const zUpdateFlowPath = z.object({
+    projectId: z.uuid(),
+    flowId: z.uuid(),
+});
+/**
+ * Successful response
+ */
+export const zUpdateFlowResponse = z.object({
+    data: z.object({
+        id: z.uuid(),
+        label: z.string(),
+        description: z.string().nullable(),
+        node_type: z.enum(["flow"]),
+        status: z.enum([
+            "BACKLOG",
+            "NOT_STARTED",
+            "IN_PLANNING",
+            "READY_FOR_DEVELOPMENT",
+            "IN_DEVELOPMENT",
+            "BLOCKED",
+            "REVIEW",
+            "COMPLETE",
+        ]),
+        priority: z.string().nullable(),
+        roadmap_status: z
+            .enum(["now", "next", "later", "someday", "released"])
+            .optional(),
+        parent_id: z.uuid().nullable(),
+        parent_feature_id: z.uuid().nullish(),
+        project_id: z.uuid(),
+        workspace_id: z.uuid(),
+        position_x: z.number().optional(),
+        position_y: z.number().optional(),
+        step_count: z.int().gte(0),
+    }),
+    error: z.unknown(),
+    metadata: z.object({
+        timestamp: z.string(),
+        request_id: z.string(),
+        action_hints: z.array(z.unknown()).optional(),
+    }),
+});
+export const zGetFlowTreePath = z.object({
+    projectId: z.uuid(),
+    flowId: z.uuid(),
+});
+/**
+ * Successful response
+ */
+export const zGetFlowTreeResponse = z.object({
+    data: z.unknown().optional(),
+    error: z.unknown(),
+    metadata: z.object({
+        timestamp: z.string(),
+        request_id: z.string(),
+        action_hints: z.array(z.unknown()).optional(),
+    }),
+});
 export const zListStoriesPath = z.object({
     projectId: z.uuid(),
 });

package/dist/ui/components/cli-header.js

@@ -23,8 +23,9 @@ const COMPACT_ART = [
 ];
 const START_COLOR = { r: 0, g: 229, b: 255 }; // #00e5ff
 const END_COLOR = { r: 224, g: 64, b: 251 }; // #e040fb
-const lerp = (start, end, t) => Math.round(start + (end - start) * t);
-const applyGradient = (text, width) => {
+export const lerp = (start, end, t) => Math.round(start + (end - start) * t);
+/** Apply a linear RGB gradient over a single-line string. Pure. */
+export const applyGradient = (text, width) => {
     return text
         .split('')
         .map((char, i) => {
@@ -37,14 +38,16 @@ const applyGradient = (text, width) => {
         .join('');
 };
 const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
-const STATUS_CONFIG = {
+export const STATUS_CONFIG = {
     'checking-connectivity': { label: 'Checking Connectivity', icon: SPINNER_FRAMES, color: 'yellow' },
     'refreshing-token': { label: 'Refreshing Token', icon: SPINNER_FRAMES, color: 'yellow' },
     ready: { label: 'Ready', icon: '✓', color: 'green' },
     'no-connection': { label: 'No Connection', icon: '✗', color: 'red' },
     'update-required': { label: 'Update Required', icon: '⚠', color: 'magenta' },
 };
-const getArt = (variant) => {
+/** Resolve the status config (label/icon/color) for a CliStatus. Pure. */
+export const getStatusConfig = (status) => STATUS_CONFIG[status];
+export const getArt = (variant) => {
     const art = variant === 'compact' ? MIDDY_ART : ART;
     const width = Math.max(...art.map((line) => line.length));
     return { art, width };
@@ -59,7 +62,7 @@ export function renderHeaderString(version, status = 'ready', headerVariant = 'f
         return `${chalk.dim('║ ')}${applyGradient(line + padding, width)}${chalk.dim(' ║')}`;
     })
         .join('\n');
-    const currentStatus = STATUS_CONFIG[status];
+    const currentStatus = getStatusConfig(status);
     const icon = Array.isArray(currentStatus.icon) ? currentStatus.icon[0] : currentStatus.icon;
     const statusLabel = chalk[currentStatus.color](`${currentStatus.label} ${icon}`);
     const statusBar = chalk.dim(`[ 4ge CLI | v${version} | Status: ${statusLabel} ]`);
@@ -82,7 +85,7 @@ export default function CliHeader({ version, status = 'ready', headerVariant = '
     const { art, width } = getArt(headerVariant);
     const borderTop = `╔${'═'.repeat(width + 2)}╗`;
     const borderBottom = `╚${'═'.repeat(width + 2)}╝`;
-    const currentStatus = STATUS_CONFIG[status];
+    const currentStatus = getStatusConfig(status);
     const icon = Array.isArray(currentStatus.icon) ? currentStatus.icon[frame] : currentStatus.icon;
     return (_jsxs(Box, { flexDirection: "column", marginY: 1, children: [_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { dimColor: true, children: borderTop }), art.map((line, i) => {
                         const padding = ' '.repeat(width - line.length);

package/dist/ui/components/data-table.js

@@ -1,6 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Box, Text } from 'ink';
-const getStatusColor = (value) => {
+/**
+ * Map a status value to a chalk/ink color token.
+ * Pure: given a value, returns 'green' | 'yellow' | 'red' | undefined.
+ * Exported for unit testing — the mapping is logic, the JSX is wiring.
+ */
+export const getStatusColor = (value) => {
     if (typeof value !== 'string')
         return undefined;
     const upper = value.toUpperCase();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4ge/cli",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "4ge Service Architecture Bridge & CLI",
   "main": "dist/index.js",
   "bin": {
@@ -38,6 +38,7 @@
     "dev": "node --env-file=.env.local ./bin/dev.js",
     "test": "node --env-file=.env.test ./node_modules/vitest/vitest.mjs run",
     "test:watch": "node --env-file=.env.test ./node_modules/vitest/vitest.mjs",
+    "test:coverage": "node --env-file=.env.test ./node_modules/vitest/vitest.mjs run --coverage",
     "lint": "eslint src/ --ext .ts",
     "format": "prettier --write \"src/**/*.ts\"",
     "sync-api": "openapi-ts && prettier --write \"src/generated/api/**/*.ts\"",

package/skills/4ge-cli.md

@@ -13,15 +13,30 @@ Before using this CLI, the user **MUST** have completed:
 The CLI is already installed and configured in this project.
 
 ## ⌨️ Command Syntax
-All interactions follow this structure:
+
+**Convention (hard rule):** commands are `4ge <namespace>:<command> [--params]` —
+a colon between namespace and command, **never a space**.
+
+| Correct | Wrong |
+|---|---|
+| `4ge epic:list` | ~~`4ge epic list`~~ |
+| `4ge project:pull --json` | ~~`4ge project pull --json`~~ |
+| `4ge flow:show --id <id>` | ~~`4ge flow show --id <id>`~~ |
+| `4ge auth:status` | ~~`4ge auth status`~~ |
+
+Nested commands chain with more colons: `4ge template:feature:list`.
+A few root commands take no colon (`4ge init`, `4ge whoami`, `4ge login`) —
+single words with no nested command.
+
+Full form:
 
 ```bash
 4ge <namespace>:<command> [options] --json
 ```
 
-- **Namespace:Command**: Colon-separated (e.g. `epic:list`, `story:show`, `auth:status`).
-- **Required flag**: `--json` is **mandatory** in agent mode for machine-readable output.
-- **Positional arguments**: A few commands take a direct arg without a flag (e.g. `idea:show <ID>`).
+- **`--json` is mandatory** in agent mode for machine-readable output.
+- **Positional arguments**: a few commands take a direct arg without a flag
+  (e.g. `4ge idea:show <ID>`).
 
 ## 🛠 Usage Guidelines
 
@@ -80,6 +95,7 @@ Use it for network-flaky operations.
 |-----------|----------|-----------|
 | **project** | `create`, `info`, `list`, `pull`, `update` | `--workspace` (create), `--name`, `--description`, `--template`, `--force`, `--save`/`--stdout` (pull), `--dry-run`, `--retry` |
 | **epic** | `list`, `show`, `pull`, `update` | `--epic-id` / `--id` (pull), `--status`, `--title`, `--recursive` (pull), `--roadmap` (pull, with `--recursive`), `--save`/`--stdout` (pull), `--dry-run`, `--retry` |
+| **flow** | `list`, `show`, `pull`, `update` | `--id`, `--feature-id` (list), `--recursive` (pull — full flow step tree), `--status`, `--title` (update), `--description` (update), `--priority` (update), `--roadmap-status` (update), `--save`/`--stdout` (pull), `--dry-run`, `--retry` |
 | **story** | `list`, `show`, `pull`, `update` | `--story-id` / `--id` (pull), `--status`, `--title`, `--recursive` (pull), `--roadmap` (pull, with `--recursive`), `--save`/`--stdout` (pull), `--dry-run`, `--retry` |
 | **feature** | `list`, `show`, `pull`, `update` | `--feature-id` / `--id` (pull), `--status`, `--roadmap`, `--recursive` (pull), `--roadmap` (pull, with `--recursive`), `--save`/`--stdout` (pull), `--dry-run`, `--retry` |
 | **idea** | `create`, `graduate`, `list`, `show`, `update` | `<ID>` (positional for show), `--title`, `--workspace`, `--dry-run`, `--retry` |
@@ -102,6 +118,76 @@ No `--project-id` flag is needed for those namespaces.
 
 Flags always override config; bare `4ge <ns>:pull --id <id>` honours the config defaults.
 
+### Plan data model — parent-link semantics
+
+**Read this before reconstructing a hierarchy from `list`/`pull --json` output.
+A wrong field will falsely make everything look orphaned.**
+
+Each project plan node (epic / story / feature / flow step) carries TWO
+parent-link fields. They coexist by design — neither is legacy — and they
+serve different relationships:
+
+| Field | Meaning | Populated on |
+|---|---|---|
+| `parent_id` | The **hierarchy tree** edge. epic → story → feature, plus step → step containment inside flows. | epics, stories, features, flow steps |
+| `parent_feature_id` | A **flow-ownership** edge. Used ONLY by flow-step nodes (`node_type`: `useraction` / `systemresponse` / `conditional`) to attach to their owning feature. These steps deliberately have `parent_id` null (or pointing at another step). | flow steps only |
+
+**Canonical hierarchy is `epic → story → feature`** (parent points UP
+toward the epic), and the tree read bottom-up is:
+
+```
+feature.parent_id → a story id → (story.parent_id) → an epic
+```
+
+Not feature → epic directly — the story is the mandatory intermediate node.
+
+#### Rules agents must follow
+
+1. **For features and stories, `parent_feature_id` is null by design.**
+   Features and stories are never flow steps, so they use `parent_id`
+   exclusively. A null `parent_feature_id` on a feature/story is NOT a
+   broken link and NOT an orphan. Aggregating `parent_feature_id` to
+   reconstruct the tree will falsely report "orphans everywhere" — do
+   not do this.
+
+2. **To reconstruct the hierarchy from list output, use `parent_id`,
+   never `parent_feature_id`:**
+   - `feature.parent_id` → a story id (the story that owns the feature).
+   - `story.parent_id` → an epic id.
+   - Group features by epic: resolve `feature.parent_id` → story, then
+     `story.parent_id` → epic.
+
+3. **`children: []` under a filtered query on a flow-bearing feature is
+   a known, narrow bug — not proof of corruption.** Under an active
+   roadmap/status/priority filter, flow-step nodes linked ONLY via
+   `parent_feature_id` (no usable `parent_id`) can be pruned in the tree
+   builder and surface as `children: []` on their owning feature. This
+   affects **flow steps only** — never the `parent_id` epic→story→feature
+   backbone. If you see empty `children` only under a filtered query on a
+   feature that bears flows, cite this caveat before claiming the
+   hierarchy is broken.
+
+   *Contract:* the CLI surfaces the server's tree as-is. There is no CLI
+   flag to work around the flow-step pruning case; if you hit it, query
+   without the filter, or pull the flow's own step tree instead:
+   `flow:list --feature-id <featureId> --json` to resolve the flow id, then
+   `flow:pull --id <flowId> --recursive --json` (the flow step tree is not
+   subject to the same pruning).
+
+#### Quick check: is the hierarchy intact?
+
+```bash
+# Every feature's parent_id should resolve to a story id in story:list.
+4ge feature:list --json   # collect feature[*].parent_id
+4ge story:list --json     # every parent_id from above must appear here
+# Every story's parent_id should resolve to an epic id in epic:list.
+4ge story:list --json     # collect story[*].parent_id
+4ge epic:list --json      # every parent_id from above must appear here
+```
+
+If those joins are complete, the hierarchy is intact regardless of how
+many `parent_feature_id` fields are null.
+
 ## 🔄 Common Workflow Patterns
 
 1. **Explore projects**: `4ge project:list --json`