@4ge/cli 0.2.0 → 0.2.2

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

@@ -3,6 +3,8 @@ import { resolveCredential } from '../../core/auth/resolution.js';
 import { createApiClient, ConnectivityError } from '../../core/auth/api-client.js';
 import { ensureFreshToken } from '../../core/auth/token-refresh.js';
 import { cliAuthStatus } from '../../generated/api/sdk.gen.js';
+import { zCliAuthStatusResponse } from '../../generated/api/zod.gen.js';
+import { validateResponse } from '../../core/api/index.js';
 export default class AuthStatus extends BaseCommand {
     static description = 'Check authentication status';
     async run() {
@@ -12,7 +14,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 +39,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 +49,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 +67,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 +79,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.`);
@@ -85,8 +87,15 @@ export default class AuthStatus extends BaseCommand {
                 }
                 return;
             }
+            // Validate the envelope against the generated schema and extract the
+            // typed user. Uses the same boundary-validation seam as every other
+            // command (the generated zCliAuthStatusResponse now types data.user,
+            // data.workspaces, and the authenticated_as enum in lockstep with the
+            // app's CLIAuthStatusSchema — see docs/cli-api-contract.pin.md).
+            const validated = validateResponse(data, null, zCliAuthStatusResponse);
+            const user = validated.data?.user;
             if (this.isJsonMode) {
-                this.outputJson({ source: activeCredential.source, profile: activeCredential.profile, user: data });
+                this.outputJson({ source: activeCredential.source, profile: activeCredential.profile, user });
             }
             else {
                 if (activeCredential.source === 'environment') {
@@ -96,8 +105,9 @@ export default class AuthStatus extends BaseCommand {
                 this.log(`Source:  ${activeCredential.source}`);
                 if (activeCredential.profile)
                     this.log(`Profile: ${activeCredential.profile}`);
-                if (data)
-                    this.log(`User:    ${data.email || data.id || 'Unknown'}`);
+                // Display precedence per contract §5.8: full_name → username → email → id.
+                if (user)
+                    this.log(`User:    ${user.full_name || user.username || user.email || user.id || 'Unknown'}`);
             }
         }
         catch (error) {

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/list.js

@@ -69,7 +69,7 @@ export default class FlowList extends BaseCommand {
                         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`);
+                            this.log(`\n  🚀 Run: ${chalk.cyan(`4ge flow:show ${selectedId}`)}\n`);
                         }
                     }
                     if (metadata?.action_hints) {

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

@@ -66,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/realtime.js

@@ -66,17 +66,18 @@ export async function subscribeForTokens(opts) {
     };
 }
 /**
- * Get the Supabase URL and anon key from environment variables.
- * Throws if either is missing.
+ * Get the Supabase URL and anon key.
+ *
+ * The anon key is public by design (RLS enforces all security), so the
+ * production values are baked in as defaults — a globally-installed CLI has
+ * no `.env.local` and must still support the OAuth browser flow with zero
+ * user configuration. `SUPABASE_URL` / `SUPABASE_ANON_KEY` env vars override
+ * the defaults (used by `4ge/app` for local dev against a local Supabase).
  */
 export function getSupabaseConfig() {
-    const supabaseUrl = process.env.SUPABASE_URL;
-    const supabaseAnonKey = process.env.SUPABASE_ANON_KEY;
-    if (!supabaseUrl) {
-        throw new Error('SUPABASE_URL environment variable is required for OAuth login. Set it in your .env file or environment.');
-    }
-    if (!supabaseAnonKey) {
-        throw new Error('SUPABASE_ANON_KEY environment variable is required for OAuth login. Set it in your .env file or environment.');
-    }
+    // Production Supabase project backing app.4ge.dev.
+    const supabaseUrl = process.env.SUPABASE_URL || 'https://ujhqusbkvaaczncgzsyo.supabase.co';
+    const supabaseAnonKey = process.env.SUPABASE_ANON_KEY ||
+        'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InVqaHF1c2JrdmFhY3puY2d6c3lvIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NTU4NTQ1OTAsImV4cCI6MjA3MTQzMDU5MH0.A0c0oG-Dj0EvEuH8eNOa8y0o81uCNPkjlOFqoUMx170';
     return { supabaseUrl, supabaseAnonKey };
 }

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/core/version-check.js

@@ -0,0 +1,134 @@
+/**
+ * Best-effort npm registry update check for the 4ge CLI.
+ *
+ * Design constraints:
+ * - Never throws. A failed/timeout/missing registry response is a no-op.
+ * - Never blocks the user: hits the registry at most once per `cacheTtlMs`
+ *   (default 24h), persisting the result in a cache file alongside the
+ *   credentials directory.
+ * - Silent in machine/JSON contexts — the caller (the postrun hook) is
+ *   responsible for suppressing output in `--json` mode.
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+export const DEFAULT_CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+export const DEFAULT_REGISTRY_TIMEOUT_MS = 3_000;
+export const NPM_REGISTRY_URL = 'https://registry.npmjs.org';
+export const PACKAGE_NAME = '@4ge/cli';
+/**
+ * Default cache path: `~/.4ge/.update-check.json` (sibling of credentials.json).
+ */
+export function getDefaultCachePath() {
+    return join(homedir(), '.4ge', '.update-check.json');
+}
+/**
+ * Compare two semver strings by their numeric major.minor.patch components.
+ * Prerelease suffixes are ignored (treated as equal to the release).
+ *
+ * @returns -1 if `a < b`, 0 if equal, 1 if `a > b`. Non-parseable parts are
+ *          treated as 0.
+ */
+export function compareVersions(a, b) {
+    const pa = parseSemver(a);
+    const pb = parseSemver(b);
+    for (let i = 0; i < 3; i++) {
+        const x = pa[i];
+        const y = pb[i];
+        if (x < y)
+            return -1;
+        if (x > y)
+            return 1;
+    }
+    return 0;
+}
+function parseSemver(v) {
+    const m = /(\d+)\.(\d+)\.(\d+)/.exec(v ?? '');
+    return [
+        m ? Number(m[1]) : 0,
+        m ? Number(m[2]) : 0,
+        m ? Number(m[3]) : 0,
+    ];
+}
+/**
+ * Check the npm registry for a newer published version of the package.
+ *
+ * @returns an {@link UpdateInfo} when an update is available, otherwise `null`.
+ *          Always resolves (never rejects) — safe to call fire-and-forget.
+ */
+export async function checkForUpdate(opts) {
+    const { currentVersion, packageName = PACKAGE_NAME, cachePath = getDefaultCachePath(), cacheTtlMs = DEFAULT_CACHE_TTL_MS, timeoutMs = DEFAULT_REGISTRY_TIMEOUT_MS, registryUrl = NPM_REGISTRY_URL, fetchImpl = globalThis.fetch, } = opts;
+    if (!currentVersion)
+        return null;
+    // 1. Try the cache first.
+    let cached = null;
+    try {
+        const raw = await readFile(cachePath, 'utf-8');
+        cached = JSON.parse(raw);
+    }
+    catch {
+        // Missing or corrupt cache is fine — fall through to a live fetch.
+        cached = null;
+    }
+    const now = Date.now();
+    // "Fresh" means we checked recently, regardless of whether we learned a
+    // version. This gives us negative caching: a failed/offline check is retried
+    // at most once per TTL window instead of adding a network timeout to every
+    // subsequent command.
+    const cacheFresh = cached && typeof cached.lastCheck === 'number' &&
+        (now - cached.lastCheck) < cacheTtlMs;
+    let latest;
+    if (cacheFresh) {
+        // Either reuse a cached version, or (if the last check found nothing)
+        // honour the negative cache and skip a redundant fetch.
+        latest = cached.latest;
+    }
+    else {
+        latest = await fetchLatestVersion(packageName, registryUrl, timeoutMs, fetchImpl);
+        // Persist for next time — including a negative cache entry when fetch
+        // returned nothing, so we don't hammer the registry while offline.
+        await safeWriteCache(cachePath, { lastCheck: now, latest });
+        if (!latest)
+            return null;
+    }
+    if (!latest)
+        return null;
+    const updateAvailable = compareVersions(currentVersion, latest) < 0;
+    if (!updateAvailable)
+        return null;
+    return { current: currentVersion, latest, updateAvailable };
+}
+async function fetchLatestVersion(packageName, registryUrl, timeoutMs, fetchImpl) {
+    if (typeof fetchImpl !== 'function')
+        return undefined;
+    const encoded = encodeURIComponent(packageName);
+    const url = `${registryUrl}/${encoded}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetchImpl(url, {
+            signal: controller.signal,
+            headers: { accept: 'application/json' },
+        });
+        if (!res.ok)
+            return undefined;
+        const body = (await res.json());
+        return body?.['dist-tags']?.latest;
+    }
+    catch {
+        // Network error, timeout, malformed JSON — all treated as "no info".
+        return undefined;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function safeWriteCache(cachePath, data) {
+    try {
+        await mkdir(dirname(cachePath), { recursive: true });
+        await writeFile(cachePath, JSON.stringify(data), 'utf-8');
+    }
+    catch {
+        // Cache write is best-effort; never propagate.
+    }
+}

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

@@ -57,7 +57,20 @@ export const zCliAuthCallbackResponse = z.object({
  * Successful response
  */
 export const zCliAuthStatusResponse = z.object({
-    data: z.unknown(),
+    data: z.object({
+        user: z.object({
+            id: z.uuid(),
+            email: z.email().nullable(),
+            full_name: z.string().nullish(),
+            username: z.string().nullish(),
+        }),
+        workspaces: z.array(z.object({
+            id: z.uuid(),
+            name: z.string(),
+            role: z.enum(["OWNER", "MEMBER"]),
+        })),
+        authenticated_as: z.enum(["session", "api_key"]),
+    }),
     error: z.unknown(),
     metadata: z.object({
         timestamp: z.string(),

package/dist/hooks/postrun.js

@@ -0,0 +1,25 @@
+import { checkForUpdate } from '../core/version-check.js';
+const hook = async (options) => {
+    const { argv, config } = options;
+    // Silence in JSON / machine mode so stdout stays clean.
+    if (argv.includes('--json') || argv.includes('-j'))
+        return;
+    // Unlikely for a published CLI, but don't attempt without a version.
+    const currentVersion = config.version;
+    if (!currentVersion)
+        return;
+    try {
+        const info = await checkForUpdate({ currentVersion });
+        if (info?.updateAvailable) {
+            // Write directly to stderr — oclif's context.warn() also emits a stack
+            // trace via the logger, which is noisy for an advisory notice.
+            const chalk = (await import('chalk')).default;
+            process.stderr.write(chalk.yellow(`\nUpdate available: ${info.current} → ${info.latest}\n` +
+                `  Run \`npm i -g @4ge/cli\` to update.\n`));
+        }
+    }
+    catch {
+        // Never let an update check interfere with the user's command.
+    }
+};
+export default hook;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4ge/cli",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "4ge Service Architecture Bridge & CLI",
   "main": "dist/index.js",
   "bin": {
@@ -26,6 +26,9 @@
     "plugins": [
       "@oclif/plugin-help"
     ],
+    "hooks": {
+      "postrun": "./dist/hooks/postrun.js"
+    },
     "flexibleTaxonomy": true
   },
   "type": "module",

package/skills/4ge-cli.md

@@ -1,3 +1,19 @@
+---
+name: 4ge-cli
+description: >
+  Instructions for AI agents to interact with the 4ge Product Management
+  Platform via the `4ge` CLI. Covers command syntax (namespace:command with a
+  colon), mandatory `--json` agent mode, the response envelope, error handling,
+  discovery, dry-run previews, retry, and the full command reference for the
+  project / epic / story / feature / flow / idea / template / plan / auth /
+  config / skill namespaces. Use when an agent needs to read or mutate 4ge plan
+  assets, work with pull/list/show/update commands, or install the 4ge CLI skill
+  for an agent harness.
+user-invocable: true
+risk: safe
+source: https://github.com/Conflate-AI/4ge-cli/blob/main/skills/4ge-cli.md
+---
+
 # 4ge CLI Skill
 
 This document provides instructions for AI agents to interact with the 4ge
@@ -13,15 +29,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