ucn 4.2.3 → 5.0.2

package/cli/index.js

@@ -14,22 +14,24 @@ const { detectLanguage } = require('../core/parser');
 const { ProjectIndex } = require('../core/project');
 const { expandGlob, findProjectRoot } = require('../core/discovery');
 const output = require('../core/output');
-const { getCliCommandSet, resolveCommand, FLAG_APPLICABILITY, toCliName, FILE_LOCAL_COMMANDS } = require('../core/registry');
-const { looksLikeHandle, parseSymbolHandle } = require('../core/shared');
-
-/**
- * Convert a CLI argument that may be a stable handle into the symbol name
- * that's appropriate for headers / "Usages of X" / "find Y" displays.
- * Plain names pass through unchanged.
- */
-function nameForDisplay(arg) {
-    if (typeof arg !== 'string') return arg;
-    if (!looksLikeHandle(arg)) return arg;
-    const h = parseSymbolHandle(arg);
-    return h && h.name ? h.name : arg;
-}
+const {
+    getCliCommandSet,
+    resolveCommand,
+    suggestCommand,
+    v4MigrationHint,
+    FLAG_APPLICABILITY,
+    toCliName,
+    FILE_LOCAL_COMMANDS,
+    formatSurfaceMessage,
+    getCliFlagsForCommand,
+    getCliAcceptedFlags,
+} = require('../core/registry');
+const { buildPublicParams, isPublicCommand } = require('../core/public-command');
 const { execute } = require('../core/execute');
-const { ExpandCache } = require('../core/expand-cache');
+const { applyOutputBudget, MAX_OUTPUT_CHARS } = require('../core/output-budget');
+const { clearAllCaches } = require('../core/cache');
+
+let activeCanonicalCommand = null;
 
 // Sentinel error for command failures that have already printed their message.
 // Thrown instead of process.exit(1) so finally blocks can run (cache save).
@@ -42,6 +44,35 @@ class FlagValidationError extends Error {
     constructor(msg) { super(msg); this.name = 'FlagValidationError'; }
 }
 
+function unknownCommandMessage(command, { interactive = false } = {}) {
+    const migration = v4MigrationHint(command, 'cli');
+    if (migration) return `Unknown command: ${command}. ${migration}`;
+    const suggestion = suggestCommand(command, 'cli');
+    const correction = suggestion ? ` Did you mean "${suggestion}"?` : '';
+    const help = !suggestion
+        ? (interactive
+            ? ' Type "help" for available commands.'
+            : ' Run "ucn --help" for available commands.')
+        : '';
+    return `Unknown command: ${command}.${correction}${help}`;
+}
+
+function resultExitCode(command, result) {
+    if (result && result.ok === false) return 2;
+    if (command !== 'check' || !result) return 0;
+    if (result.trust) {
+        // Target-less pre-commit check distinguishes advisory review from a
+        // blocking validation failure. Export/reference review remains
+        // machine-readable in trust.status but does not make every ordinary
+        // body edit fail CI; incomplete accounts and signature drift do.
+        return result.trust.status === 'BLOCKED' ? 1 : 0;
+    }
+    // Symbol-mode check (verify): a mismatch or unresolved call-site tier is
+    // review-required and must fail a CI gate.
+    return (Number(result.mismatches || 0) > 0 ||
+        Number(result.unverifiedCount || 0) > 0) ? 1 : 0;
+}
+
 /**
  * Validate that a raw flag value is a positive integer. Returns the parsed
  * number when valid, or throws FlagValidationError. Callers pass `null`/`undefined`
@@ -61,6 +92,13 @@ function validatePositiveInt(raw, flagName, { allowZero = false, cap = 10000000
     if (trimmed === '') {
         throw new FlagValidationError(`Invalid ${flagName} value: must be a ${label} (got "${raw}")`);
     }
+    // CLI integer flags use canonical base-10 spelling. Number()/parseInt()
+    // accept exponent, decimal and hexadecimal forms (`1e1`, `2.5`, `0x10`),
+    // which is especially dangerous for source-line identity because a
+    // malformed pin can accidentally select a real definition.
+    if (!/^\d+$/.test(trimmed)) {
+        throw new FlagValidationError(`Invalid ${flagName} value: must be a ${label} (got "${raw}")`);
+    }
     const n = Number(trimmed);
     if (!isFinite(n) || isNaN(n)) {
         throw new FlagValidationError(`Invalid ${flagName} value: must be a ${label} (got "${raw}")`);
@@ -90,7 +128,7 @@ function validatePositiveInt(raw, flagName, { allowZero = false, cap = 10000000
  * Throws FlagValidationError on the first invalid flag.
  */
 function validateNumericFlags(flags) {
-    // --top: positive integer, no zero. Used by stats/find/context/etc.
+    // --top: positive integer, no zero. Used by show/find/repo/etc.
     if (flags.topRaw != null) {
         flags.top = validatePositiveInt(flags.topRaw, '--top');
     }
@@ -102,7 +140,10 @@ function validateNumericFlags(flags) {
     if (flags.maxFilesRaw != null) {
         flags.maxFiles = validatePositiveInt(flags.maxFilesRaw, '--max-files');
     }
-    // --max-lines: positive integer, no zero. Used by class command.
+    if (flags.lineRaw != null) {
+        flags.line = validatePositiveInt(flags.lineRaw, '--line');
+    }
+    // --max-lines: positive integer, no zero. Used by source.
     if (flags.maxLinesRaw != null) {
         flags.maxLines = validatePositiveInt(flags.maxLinesRaw, '--max-lines');
     }
@@ -118,22 +159,62 @@ function validateNumericFlags(flags) {
     if (flags.workersRaw != null) {
         flags.workers = validatePositiveInt(flags.workersRaw, '--workers', { allowZero: true });
     }
+    if (flags.maxCharsRaw != null) {
+        flags.maxChars = validatePositiveInt(flags.maxCharsRaw, '--max-chars', {
+            cap: MAX_OUTPUT_CHARS,
+        });
+    }
+    // --min-confidence: number in [0,1] (ordinal evidence weight). Anything
+    // else used to coerce to 0 silently — "abc" behaved like no filter.
+    if (flags.minConfidenceRaw != null) {
+        const value = Number(flags.minConfidenceRaw);
+        if (flags.minConfidenceRaw === '' || !Number.isFinite(value) ||
+            value < 0 || value > 1) {
+            throw new FlagValidationError(
+                `Invalid --min-confidence value: "${flags.minConfidenceRaw}" — must be a number between 0 and 1.`);
+        }
+        flags.minConfidence = value;
+    }
 }
 
-/**
- * Print an error message and abort. When `--json` is in effect, write a JSON
- * error envelope to stdout (so JSON-consuming pipelines see structured output)
- * and write the same plain message to stderr (for humans piping to a TTY).
- */
-function fail(msg) {
-    // This helper can run before parsed flags exist, so raw argv is the single
-    // reliable source for the output mode.
+/** Emit the one CLI error contract, including failures before main dispatch. */
+function emitCliError(msg, command = activeCanonicalCommand) {
     const wantsJson = process.argv.includes('--json');
+    const error = typeof msg === 'string' ? msg : String(msg);
     if (wantsJson) {
-        const env = { meta: { ok: false }, error: typeof msg === 'string' ? msg : String(msg) };
+        const canonical = command && isPublicCommand(command)
+            ? command
+            : resolveCommand(command, 'cli');
+        const surfaceCommand = canonical
+            ? toCliName(canonical)
+            : (command ? String(command) : null);
+        const env = {
+            meta: {
+                ok: false,
+                ...(surfaceCommand && {
+                    command: surfaceCommand,
+                    ...(canonical && surfaceCommand !== canonical && {
+                        canonicalCommand: canonical,
+                    }),
+                    ...(canonical && {
+                        contract: output.contractMeta(canonical),
+                    }),
+                }),
+            },
+            data: null,
+            error,
+        };
         try { process.stdout.write(JSON.stringify(env) + '\n'); } catch (_) { /* stdout may be closed */ }
     }
-    console.error(msg);
+    console.error(error);
+}
+
+/**
+ * Print an error message and abort command execution. Throw instead of calling
+ * process.exit so index/cache finally blocks still run.
+ */
+function fail(msg, command = activeCanonicalCommand) {
+    emitCliError(msg, command);
     throw new CommandError();
 }
 
@@ -191,7 +272,6 @@ function parseFlags(tokens) {
         excludeTests: tokens.includes('--exclude-tests') ? true : undefined,
         includeExported: tokens.includes('--include-exported') || undefined,
         includeDecorated: tokens.includes('--include-decorated') || undefined,
-        includeUncertain: tokens.includes('--include-uncertain') || undefined,
         expandUnverified: tokens.includes('--expand-unverified') || undefined,
         includeMethods: tokens.some(a => a === '--include-methods=false' || a === '--no-include-methods') ? false : tokens.some(a => a === '--include-methods' || (a.startsWith('--include-methods=') && a !== '--include-methods=false')) ? true : undefined,
         detailed: tokens.includes('--detailed') || undefined,
@@ -202,7 +282,8 @@ function parseFlags(tokens) {
         codeOnly: tokens.includes('--code-only') || undefined,
         caseSensitive: tokens.includes('--case-sensitive') || undefined,
         withTypes: tokens.includes('--with-types') || undefined,
-        expand: tokens.includes('--expand') || undefined,
+        withSource: tokens.includes('--with-source') || undefined,
+        cycles: tokens.includes('--cycles') || undefined,
         depth: getValueFlag('--depth'),
         depthRaw: getValueFlag('--depth'),
         // `top` is the parsed numeric value (NaN/0 default → falsy). `topRaw`
@@ -213,6 +294,9 @@ function parseFlags(tokens) {
         context: parseInt(getValueFlag('--context') || '0'),
         contextRaw: getValueFlag('--context'),
         direction: getValueFlag('--direction'),
+        to: getValueFlag('--to'),
+        sections: getValueFlag('--sections'),
+        range: getValueFlag('--range'),
         addParam: getValueFlag('--add-param'),
         removeParam: getValueFlag('--remove-param'),
         renameTo: getValueFlag('--rename-to'),
@@ -220,10 +304,14 @@ function parseFlags(tokens) {
         base: getValueFlag('--base'),
         staged: tokens.includes('--staged') || undefined,
         deep: tokens.includes('--deep') || undefined,
-        compact: tokens.includes('--compact') || undefined,
+        compact: tokens.includes('--no-compact')
+            ? false
+            : (tokens.includes('--compact') ? true : undefined),
         maxLines: getValueFlag('--max-lines') || null,
         maxLinesRaw: getValueFlag('--max-lines'),
-        regex: tokens.includes('--no-regex') ? false : undefined,
+        regex: tokens.includes('--regex')
+            ? true
+            : (tokens.includes('--no-regex') ? false : undefined),
         functions: tokens.includes('--functions') || undefined,
         hot: tokens.includes('--hot') || undefined,
         diverse: tokens.includes('--diverse') || undefined,
@@ -232,10 +320,13 @@ function parseFlags(tokens) {
         // Explicit line pin (fix #249: our own disambiguation notes advertise
         // line= but no surface accepted it).
         line: parseInt(getValueFlag('--line') || '0', 10) || undefined,
+        lineRaw: getValueFlag('--line'),
         limit: parseInt(getValueFlag('--limit') || '0') || undefined,
         limitRaw: getValueFlag('--limit'),
         maxFiles: parseInt(getValueFlag('--max-files') || '0') || undefined,
         maxFilesRaw: getValueFlag('--max-files'),
+        maxChars: parseInt(getValueFlag('--max-chars') || '0') || undefined,
+        maxCharsRaw: getValueFlag('--max-chars'),
         // Structural search flags
         type: getValueFlag('--type'),
         param: getValueFlag('--param'),
@@ -244,8 +335,10 @@ function parseFlags(tokens) {
         decorator: getValueFlag('--decorator'),
         exported: tokens.includes('--exported') || undefined,
         unused: tokens.includes('--unused') || undefined,
-        showConfidence: (tokens.includes('--hide-confidence') || tokens.includes('--no-confidence')) ? false : undefined,
-        minConfidence: parseFloat(getValueFlag('--min-confidence') || '0') || 0,
+        showConfidence: (tokens.includes('--hide-confidence') || tokens.includes('--no-confidence')) ? false
+            : tokens.includes('--show-confidence') ? true : undefined,
+        minConfidence: 0,
+        minConfidenceRaw: getValueFlag('--min-confidence'),
         unreachableOnly: tokens.includes('--unreachable-only') || undefined,
         framework: getValueFlag('--framework'),
         // endpoints command flags
@@ -277,24 +370,7 @@ flags.interactive = args.includes('--interactive') || args.includes('-i');
 flags.followSymlinks = !args.includes('--no-follow-symlinks');
 
 // Known flags for validation
-const knownFlags = new Set([
-    '--help', '-h', '--version', '-v', '--mcp',
-    '--json', '--verbose', '--no-quiet', '--quiet',
-    '--code-only', '--with-types', '--top-level', '--exact', '--case-sensitive',
-    '--no-cache', '--clear-cache', '--include-tests', '--exclude-tests',
-    '--include-exported', '--include-decorated', '--expand', '--interactive', '-i', '--all', '--include-methods', '--no-include-methods', '--include-uncertain', '--expand-unverified', '--detailed', '--calls-only',
-    '--file', '--context', '--exclude', '--not', '--in',
-    '--depth', '--direction', '--add-param', '--remove-param', '--rename-to', '--default-value',
-    '--default', '--top', '--no-follow-symlinks',
-    '--base', '--staged', '--stack',
-    '--regex', '--no-regex', '--functions', '--hot', '--diverse', '--git',
-    '--max-lines', '--class-name', '--line', '--limit', '--max-files',
-    '--type', '--param', '--receiver', '--returns', '--decorator', '--exported', '--unused',
-    '--hide-confidence', '--no-confidence', '--min-confidence', '--unreachable-only',
-    '--framework', '--workers', '--deep', '--compact',
-    '--bridge', '--server-only', '--client-only', '--unmatched',
-    '--method', '--prefix', '--hide-uncertain', '--no-uncertain'
-]);
+const knownFlags = getCliAcceptedFlags();
 
 // Handle help flag
 if (args.includes('--help') || args.includes('-h')) {
@@ -317,8 +393,9 @@ const unknownFlags = args.filter(a => {
 });
 
 if (unknownFlags.length > 0) {
-    console.error(`Unknown flag(s): ${unknownFlags.join(', ')}`);
-    console.error('Use --help to see available flags');
+    emitCliError(
+        `Unknown flag(s): ${unknownFlags.join(', ')}. Use --help to see available flags.`,
+    );
     process.exit(1);
 }
 
@@ -329,11 +406,7 @@ try {
     validateNumericFlags(flags);
 } catch (e) {
     if (e instanceof FlagValidationError) {
-        if (flags.json) {
-            const env = { meta: { ok: false }, error: e.message };
-            try { process.stdout.write(JSON.stringify(env) + '\n'); } catch (_) { /* stdout may be closed */ }
-        }
-        console.error(e.message);
+        emitCliError(e.message);
         process.exit(1);
     }
     throw e;
@@ -341,11 +414,11 @@ try {
 
 // Value flags that consume the next token (space form: --flag value)
 const VALUE_FLAGS = new Set([
-    '--file', '--depth', '--top', '--context', '--direction',
+    '--file', '--depth', '--top', '--context', '--direction', '--to', '--sections', '--range',
     '--add-param', '--remove-param', '--rename-to', '--default', '--default-value',
     '--base', '--exclude', '--not', '--in', '--max-lines', '--class-name', '--line',
     '--type', '--param', '--receiver', '--returns', '--decorator',
-    '--limit', '--max-files', '--min-confidence', '--stack', '--framework',
+    '--limit', '--max-files', '--max-chars', '--min-confidence', '--stack', '--framework',
     '--workers', '--method', '--prefix'
 ]);
 
@@ -378,58 +451,18 @@ function requireArg(arg, usage) {
     }
 }
 
-/**
- * Print result in JSON or text format based on --json flag
- * @param {*} result - The result data
- * @param {Function} jsonFn - Function to format as JSON (receives result)
- * @param {Function} textFn - Function to format as text (receives result)
- */
-function printOutput(result, jsonFn, textFn) {
-    if (flags.json) {
-        console.log(jsonFn(result));
-    } else {
-        const text = textFn(result);
-        if (text !== undefined) {
-            console.log(text);
-        }
-    }
-}
-
-/**
- * Print inline 3-line code previews for context items (--expand support).
- * Used by context in project, interactive, and glob modes. Previews both
- * directions with attribution headers (fix #252: callees only — the flag
- * was a silent no-op for caller-only contexts, and the unlabeled preview
- * rendered detached from the item it expanded).
- */
-function printInlineExpand(ctx, root) {
-    if (!root || !ctx) return;
-    const preview = (c, label) => {
-        // Caller entries locate the enclosing FUNCTION via callerStartLine;
-        // callee entries are definitions with startLine.
-        const startLine = label === 'caller' ? c.callerStartLine : c.startLine;
-        const endLine = label === 'caller'
-            ? (c.callerEndLine || (startLine ? startLine + 5 : null))
-            : (c.endLine || (startLine ? startLine + 5 : null));
-        if (!c.relativePath || !startLine) return;
-        try {
-            const filePath = path.join(root, c.relativePath);
-            const content = fs.readFileSync(filePath, 'utf-8');
-            const codeLines = content.split('\n');
-            console.log(`      ┌ ${label}: ${c.name || c.callerName || '(anonymous)'} — ${c.relativePath}:${startLine}`);
-            const previewLines = Math.min(3, endLine - startLine + 1);
-            for (let i = 0; i < previewLines && startLine - 1 + i < codeLines.length; i++) {
-                console.log(`      │ ${codeLines[startLine - 1 + i]}`);
-            }
-            if (endLine - startLine + 1 > 3) {
-                console.log(`      │ ... (${endLine - startLine - 2} more lines)`);
-            }
-        } catch (e) {
-            // Skip on error
-        }
-    };
-    for (const c of ctx.callers || []) preview(c, 'caller');
-    for (const c of ctx.callees || []) preview(c, 'callee');
+function formatCliText(command, result, params, execution, displayFlags) {
+    const text = output.formatPublicText(command, result, params, {
+        ...execution,
+        surface: 'cli',
+    });
+    return applyOutputBudget(text, {
+        command,
+        maxChars: displayFlags?.maxChars,
+        all: !!displayFlags?.all,
+        surface: 'cli',
+        params,
+    }).text;
 }
 
 // ============================================================================
@@ -444,18 +477,36 @@ function main() {
     let target, command, arg;
 
     if (positionalArgs.length === 0) {
+        // Standalone `ucn --clear-cache` (the form SKILL.md and README
+        // document) clears the current project's cache — falling through to
+        // the help banner made it a silent no-op.
+        if (flags.clearCache) {
+            if (flags.all) {
+                const removed = clearAllCaches();
+                console.log(removed.length > 0
+                    ? 'All UCN user caches cleared'
+                    : 'No UCN user caches to clear');
+                process.exit(0);
+            }
+            const index = new ProjectIndex('.');
+            const removed = index.clearCache();
+            console.log(removed.length > 0
+                ? `Cache cleared (${index.root})`
+                : `No cache to clear (${index.root})`);
+            process.exit(0);
+        }
         // No args: show help
         printUsage();
         process.exit(0);
     } else if (positionalArgs.length === 1) {
-        // One arg: could be a command (use . as target) or a target (use toc as command)
+        // One arg: could be a command (use . as target) or a target (use repo as command)
         if (COMMANDS.has(positionalArgs[0])) {
             target = '.';
             command = positionalArgs[0];
             arg = undefined;
         } else {
             target = positionalArgs[0];
-            command = 'toc';
+            command = 'repo';
             arg = undefined;
         }
     } else if (COMMANDS.has(positionalArgs[0])) {
@@ -466,12 +517,10 @@ function main() {
     } else {
         // First arg is a target (path/glob)
         target = positionalArgs[0];
-        command = positionalArgs[1] || 'toc';
+        command = positionalArgs[1] || 'repo';
         arg = positionalArgs[2];
-        // lines takes `<file> <range>` as two positionals (fix #252 —
-        // the extra token was silently dropped and the command then
-        // demanded a --file the user had plainly given).
-        if (command === 'lines' && positionalArgs.length > 3) {
+        // source accepts `<file> <range>` as two positionals.
+        if (command === 'source' && positionalArgs.length > 3) {
             arg = positionalArgs.slice(2).join(' ');
         }
     }
@@ -491,54 +540,62 @@ function main() {
             // Single file mode
             runFileCommand(target, command, arg);
         } else {
-            console.error(`Error: "${target}" not found`);
-            process.exit(1);
+            // `ucn missing-dir repo` is a target error. Any other two-token
+            // form whose first token is not a path is an unknown command.
+            const targetInvocation = positionalArgs.length > 1 &&
+                COMMANDS.has(positionalArgs[1]);
+            fail(
+                targetInvocation
+                    ? `Error: "${target}" not found`
+                    : unknownCommandMessage(target),
+                targetInvocation ? null : target,
+            );
         }
     } catch (e) {
         if (!(e instanceof CommandError)) {
-            console.error(`Error: ${e.message}`);
+            emitCliError(`Error: ${e.message}`);
         }
         process.exitCode = 1;
     }
 }
 
 /**
- * Parse the lines command's target forms (fix #252: `lines main.ts 1-10`
- * silently dropped the second positional and demanded a --file that was
- * plainly given): `<range>` (+ --file), `<file> <range>`, `<file>:<range>`.
- */
-function parseLinesTarget(arg, fileFlag) {
-    let file = fileFlag;
-    let range = arg;
-    const parts = String(arg || '').trim().split(/\s+/);
-    if (parts.length === 2 && /^\d+(-\d+)?$/.test(parts[1])) {
-        file = parts[0];
-        range = parts[1];
-    } else if (!/^\d+(-\d+)?$/.test(range)) {
-        const m = String(range).match(/^(.+):(\d+(?:-\d+)?)$/);
-        if (m) { file = m[1]; range = m[2]; }
-    }
-    return { file, range };
-}
-
-/**
- * Tiered-output contract notes: unverified callers are always shown for
- * these commands, so the legacy reveal flags are implied no-ops. Shared by
- * one-shot and interactive mode (fix #250 — interactive printed nothing).
+ * Tiered-output contract notes shared by one-shot and interactive mode.
  */
 function printTieredNoOpNotes(canonical, flags, print) {
-    if (!['about', 'context', 'impact', 'trace', 'blast', 'reverseTrace', 'affectedTests', 'verify', 'smart'].includes(canonical)) return;
-    if (flags.includeUncertain) {
-        print(`Note: --include-uncertain has no effect on '${toCliName(canonical)}' — unverified candidates are always shown (tiered).`);
-    }
-    if (['impact', 'verify', 'blast', 'reverseTrace', 'affectedTests'].includes(canonical) && flags.includeMethods) {
+    if (!['show', 'impact', 'trace', 'tests', 'check'].includes(canonical)) return;
+    if (['impact', 'trace', 'tests', 'check'].includes(canonical) && flags.includeMethods) {
         print(`Note: --include-methods has no effect on '${toCliName(canonical)}' — method calls are always tiered by receiver evidence.`);
     }
-    if (['about', 'context', 'smart'].includes(canonical) && flags.includeMethods) {
+    if (canonical === 'show' && flags.includeMethods) {
         print(`Note: --include-methods on '${toCliName(canonical)}' affects only method-callee display for standalone-function targets — caller tiers are always evidence-based, and method targets analyze method calls by default.`);
     }
 }
 
+const GLOBAL_FLAG_KEYS = new Set([
+    'json', 'quiet', 'cache', 'clearCache', 'followSymlinks', 'maxFiles',
+    'verbose', 'interactive', '_fileFromFileMode', 'topRaw',
+    'limitRaw', 'maxFilesRaw', 'maxLinesRaw', 'depthRaw', 'contextRaw',
+    'workers', 'workersRaw', 'lineRaw', 'maxChars', 'maxCharsRaw', 'minConfidenceRaw',
+]);
+
+/** Apply one command/flag policy across project, file, glob, and REPL modes. */
+function warnInapplicableFlags(canonical, parsedFlags, print) {
+    const applicableFlags = FLAG_APPLICABILITY[canonical];
+    if (!applicableFlags) return;
+    const flagToCli = (flag) => '--' + flag.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+    for (const [key, value] of Object.entries(parsedFlags)) {
+        if (GLOBAL_FLAG_KEYS.has(key)) continue;
+        if (value === undefined || value === null || value === 0 ||
+            (Array.isArray(value) && value.length === 0)) continue;
+        if (key === 'file' && parsedFlags._fileFromFileMode) continue;
+        if (!applicableFlags.includes(key)) {
+            print(`Warning: ${flagToCli(key)} has no effect on '${toCliName(canonical)}'.`);
+        }
+    }
+    printTieredNoOpNotes(canonical, parsedFlags, print);
+}
+
 // ============================================================================
 // FILE MODE
 // ============================================================================
@@ -546,11 +603,11 @@ function printTieredNoOpNotes(canonical, flags, print) {
 function runFileCommand(filePath, command, arg) {
     const language = detectLanguage(filePath);
     if (!language) {
-        console.error(`Unsupported file type: ${filePath}`);
-        process.exit(1);
+        fail(`Unsupported file type: ${filePath}`, command);
     }
 
     const canonical = resolveCommand(command, 'cli') || command;
+    activeCanonicalCommand = canonical;
 
     // Commands that need full project index — auto-route to project mode
     const fileLocalCommands = FILE_LOCAL_COMMANDS;
@@ -559,7 +616,7 @@ function runFileCommand(filePath, command, arg) {
         // Auto-detect project root and route to project mode
         const projectRoot = findProjectRoot(path.dirname(filePath));
         let effectiveArg = arg;
-        if (['imports', 'exporters', 'fileExports', 'graph'].includes(canonical) && !arg) {
+        if (canonical === 'deps' && !arg) {
             effectiveArg = filePath;
         }
         // Scope to the target file unless an explicit --file was provided
@@ -572,78 +629,47 @@ function runFileCommand(filePath, command, arg) {
         return;
     }
 
-    // Require arg for commands that need it
-    const needsArg = { fn: 'fn <name>', class: 'class <name>', find: 'find <name>', usages: 'usages <name>', search: 'search <term>', lines: 'lines <start-end>', typedef: 'typedef <name>' };
+    if (!isPublicCommand(canonical)) {
+        fail(unknownCommandMessage(command));
+    }
+
+    // Require arg for commands that need it.
+    const needsArg = {
+        show: 'show <name>', find: 'find <name>', usages: 'usages <name>',
+        search: 'search <term>', source: 'source <name|range>', trace: 'trace <name>',
+        tests: 'tests <name>', plan: 'plan <name>',
+    };
     // Structural search doesn't require term
     const isStructural = flags.type || flags.param || flags.receiver || flags.returns || flags.decorator || flags.exported || flags.unused;
-    if (needsArg[canonical] && !(canonical === 'search' && isStructural)) {
+    const hasFlagTarget = canonical === 'source' && flags.range;
+    if (needsArg[canonical] && !(canonical === 'search' && isStructural) && !hasFlagTarget) {
         requireArg(arg, `Usage: ucn <file> ${needsArg[canonical]}`);
     }
 
-    // Build single-file index and route through execute()
+    // Build single-file index and route through the same public executor and
+    // formatter used by project/glob/MCP modes.
     const index = new ProjectIndex(path.dirname(filePath));
     index.buildSingleFile(filePath);
     const relativePath = path.relative(index.root, path.resolve(filePath));
 
-    // Map command args to execute() params
-    const paramsByCommand = {
-        toc:     { ...flags },
-        fn:      { name: arg, file: relativePath, ...flags },
-        class:   { name: arg, file: relativePath, ...flags },
-        find:    { name: arg, file: relativePath, ...flags },
-        usages:  { name: arg, file: relativePath, ...flags },
-        search:  { term: arg, ...flags },
-        lines:   { file: relativePath, range: arg },
-        typedef: { name: arg, file: relativePath, ...flags },
-        api:     { file: relativePath, limit: flags.limit },
-    };
-
-    const { ok, result, error, note } = execute(index, canonical, paramsByCommand[canonical]);
-    if (!ok) fail(error);
-    if (note) console.error(note);
-
-    // Format output using same formatters as project mode
-    switch (canonical) {
-        case 'toc':
-            printOutput(result, output.formatTocJson, r => output.formatToc(r, {
-                detailedHint: 'Add --detailed to list all functions, or "ucn . about <name>" for full details on a symbol',
-                uncertainHint: 'run "ucn . about <name>" for tiered detail on a specific symbol'
-            }));
-            break;
-        case 'find':
-            printOutput(result,
-                r => output.formatSymbolJson(r, arg),
-                r => output.formatFindDetailed(r, arg, { depth: flags.depth, top: flags.top, all: flags.all })
-            );
-            break;
-        case 'fn':
-            printOutput(result, output.formatFnResultJson, output.formatFnResult);
-            break;
-        case 'class':
-            printOutput(result, output.formatClassResultJson, output.formatClassResult);
-            break;
-        case 'lines':
-            printOutput(result, output.formatLinesJson, r => output.formatLines(r));
-            break;
-        case 'usages':
-            printOutput(result, r => output.formatUsagesJson(r, arg), r => output.formatUsages(r, arg));
-            break;
-        case 'search':
-            if (result && result.meta && result.meta.mode === 'structural') {
-                printOutput(result, output.formatStructuralSearchJson, output.formatStructuralSearch);
-            } else {
-                printOutput(result, r => output.formatSearchJson(r, arg), r => output.formatSearch(r, arg));
-            }
-            break;
-        case 'typedef':
-            printOutput(result, r => output.formatTypedefJson(r, arg), r => output.formatTypedef(r, arg));
-            break;
-        case 'api': {
-            const apiFile = relativePath;
-            printOutput(result, r => output.formatApiJson(r, apiFile), r => output.formatApi(r, apiFile));
-            break;
-        }
+    const scopedFlags = { ...flags };
+    if (['show', 'find', 'usages', 'source', 'api'].includes(canonical) && !scopedFlags.file) {
+        scopedFlags.file = relativePath;
     }
+    if (canonical === 'source' && /^\d+(?:-\d+)?$/.test(String(arg || ''))) {
+        scopedFlags.range = arg;
+        arg = undefined;
+    }
+    warnInapplicableFlags(canonical, scopedFlags, (message) => console.error(message));
+    const params = buildPublicParams(canonical, arg, scopedFlags);
+    const execution = execute(index, canonical, params);
+    const { ok, result, error } = execution;
+    if (!ok) fail(formatSurfaceMessage(error, 'cli'));
+    console.log(flags.json
+        ? output.formatPublicJson(canonical, result, params, {
+            ...execution, surface: 'cli',
+        })
+        : formatCliText(canonical, result, params, execution, scopedFlags));
 }
 
 // ============================================================================
@@ -662,12 +688,9 @@ function runProjectCommand(rootDir, command, arg) {
 
     // Clear cache if requested
     if (flags.clearCache) {
-        const cacheDir = path.join(index.root, '.ucn-cache');
-        if (fs.existsSync(cacheDir)) {
-            fs.rmSync(cacheDir, { recursive: true, force: true });
-            if (!flags.quiet) {
-                console.error('Cache cleared');
-            }
+        const removed = index.clearCache();
+        if (removed.length > 0 && !flags.quiet) {
+            console.error('Cache cleared');
         }
     }
 
@@ -676,8 +699,8 @@ function runProjectCommand(rootDir, command, arg) {
     let cacheWasLoaded = false;
     if (flags.cache && !flags.clearCache) {
         const loaded = index.loadCache();
-        if (loaded) {
-            cacheWasLoaded = true;
+        cacheWasLoaded = !!loaded;
+        if (loaded && !flags.maxFiles) {
             if (!index.isCacheStale()) {
                 usedCache = true;
                 if (!flags.quiet) {
@@ -693,516 +716,39 @@ function runProjectCommand(rootDir, command, arg) {
     if (!usedCache) {
         index.build(null, { quiet: flags.quiet, forceRebuild: cacheWasLoaded, followSymlinks: flags.followSymlinks, maxFiles: flags.maxFiles, workers: flags.workers });
         needsCacheSave = flags.cache;
-        // Clear stale expand cache — line ranges may have shifted after rebuild
-        try {
-            const expandPath = path.join(index.root, '.ucn-cache', 'expandable.json');
-            if (fs.existsSync(expandPath)) fs.unlinkSync(expandPath);
-        } catch (_) { /* best-effort */ }
     }
 
     try {
-    // Resolve CLI aliases to canonical command names — dispatch on canonical
+    // Resolve CLI spelling to the canonical command ID.
     const canonical = resolveCommand(command, 'cli') || command;
+    activeCanonicalCommand = canonical;
 
-    // Warn about flags that don't apply to this command
-    const applicableFlags = FLAG_APPLICABILITY[canonical];
-    if (applicableFlags) {
-        // Map from camelCase flag name to CLI flag string
-        const flagToCli = (f) => '--' + f.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
-        // Flags that are global (not command-specific) — skip warning for these
-        const globalFlags = new Set(['json', 'quiet', 'cache', 'clearCache', 'followSymlinks', 'maxFiles', 'verbose', 'expand', 'interactive', '_fileFromFileMode', 'topRaw', 'limitRaw', 'maxFilesRaw', 'maxLinesRaw', 'depthRaw', 'contextRaw', 'workersRaw']);
-        for (const [key, value] of Object.entries(flags)) {
-            if (globalFlags.has(key)) continue;
-            // Skip unset values (undefined, null, 0, empty array) — but NOT false (explicit negation)
-            if (value === undefined || value === null || value === 0 || (Array.isArray(value) && value.length === 0)) continue;
-            // Skip --file when it was injected by file-mode routing, not user input
-            if (key === 'file' && flags._fileFromFileMode) continue;
-            if (!applicableFlags.includes(key)) {
-                console.error(`Warning: ${flagToCli(key)} has no effect on '${toCliName(canonical)}'.`);
-            }
-        }
-        // Tiered-output contract notes (shared with interactive mode).
-        printTieredNoOpNotes(canonical, flags, (m) => console.error(m));
+    if (!isPublicCommand(canonical)) {
+        fail(unknownCommandMessage(command));
     }
+    warnInapplicableFlags(canonical, flags, (message) => console.error(message));
 
-    switch (canonical) {
-        // ── Commands using shared executor ───────────────────────────────
-
-        case 'toc': {
-            const { ok, result, error, note } = execute(index, 'toc', flags);
-            if (!ok) fail(error);
-            if (note) console.error(note);
-            printOutput(result, output.formatTocJson, r => output.formatToc(r, {
-                detailedHint: 'Add --detailed to list all functions, or "ucn . about <name>" for full details on a symbol',
-                uncertainHint: 'run "ucn . about <name>" for tiered detail on a specific symbol'
-            }));
-            break;
-        }
-
-        case 'find': {
-            const { ok, result, error, note } = execute(index, 'find', { name: arg, ...flags });
-            if (!ok) fail(error);
-            if (note) console.error(note);
-            printOutput(result,
-                r => output.formatSymbolJson(r, arg),
-                r => output.formatFindDetailed(r, arg, { depth: flags.depth, top: flags.top, all: flags.all, compact: flags.compact })
-            );
-            break;
-        }
-
-        case 'usages': {
-            const { ok, result, error, note } = execute(index, 'usages', { name: arg, ...flags });
-            if (!ok) fail(error);
-            if (note) console.error(note);
-            const displayName = nameForDisplay(arg);
-            printOutput(result,
-                r => output.formatUsagesJson(r, displayName),
-                r => output.formatUsages(r, displayName, { compact: flags.compact })
-            );
-            break;
-        }
-
-        case 'example': {
-            const { ok, result, error, note } = execute(index, 'example', {
-                name: arg,
-                file: flags.file,
-                className: flags.className,
-                diverse: flags.diverse,
-                top: flags.top || undefined,
-                includeTests: flags.includeTests,
-            });
-            if (!ok) fail(error);
-            if (note) console.error(note);
-            const displayName = nameForDisplay(arg);
-            printOutput(result,
-                r => output.formatExampleJson(r, displayName),
-                r => output.formatExample(r, displayName)
-            );
-            break;
-        }
-
-        case 'context': {
-            const { ok, result: ctx, error, note } = execute(index, 'context', { name: arg, ...flags });
-            if (!ok) fail(error);
-            if (flags.json) {
-                console.log(output.formatContextJson(ctx));
-            } else {
-                const { text, expandable } = output.formatContext(ctx, {
-                    expandHint: 'Use "expand <N>" or --expand to see code for items',
-                    showConfidence: flags.showConfidence !== false,
-                    compact: !!flags.compact,
-                });
-                console.log(text);
-
-                // Inline expansion of callees when --expand flag is set
-                if (flags.expand) {
-                    printInlineExpand(ctx, index.root);
-                }
-
-                // Save expandable items to cache for 'expand' command
-                saveExpandableItems(expandable, index.root);
-                if (note) console.error(note);
-            }
-            break;
-        }
-
-        case 'expand': {
-            requireArg(arg, 'Usage: ucn . expand <N>\nFirst run "ucn . context <name>" to get numbered items');
-            // Whole-token integers only (fix #248: parseInt truncation made
-            // `expand 1abc` and `expand 2.5` silently expand items 1 and 2).
-            if (!/^\d+$/.test(String(arg).trim())) {
-                fail(`Invalid item number: "${arg}"`);
-            }
-            const expandNum = parseInt(arg, 10);
-            const cached = loadExpandableItems(index.root);
-            const items = cached?.items || [];
-            const match = items.find(i => i.num === expandNum);
-            const { ok, result, error } = execute(index, 'expand', {
-                match, itemNum: expandNum, itemCount: items.length, validateRoot: true
-            });
-            if (!ok) fail(error);
-            if (flags.json) {
-                // Honor --json: structured output with the expanded code + metadata.
-                const env = {
-                    meta: { command: 'expand', item: expandNum },
-                    data: {
-                        item: expandNum,
-                        ...(match && {
-                            name: match.name,
-                            type: match.type,
-                            file: match.relativePath || match.file,
-                            startLine: match.startLine,
-                            endLine: match.endLine,
-                            handle: match.relativePath && match.startLine && match.name
-                                ? `${match.relativePath}:${match.startLine}:${match.name}`
-                                : null,
-                        }),
-                        text: result.text,
-                    },
-                };
-                console.log(JSON.stringify(env, null, 2));
-            } else {
-                console.log(result.text);
-            }
-            break;
-        }
-
-        case 'smart': {
-            const { ok, result, error, note } = execute(index, 'smart', { name: arg, ...flags });
-            if (!ok) fail(error);
-            printOutput(result, output.formatSmartJson, r => output.formatSmart(r, {
-                uncertainHint: 'unverified callees are listed below with reasons'
-            }));
-            if (note) console.error(note);
-            break;
-        }
-
-        case 'about': {
-            const { ok, result, error, note } = execute(index, 'about', { name: arg, ...flags });
-            if (!ok) fail(error);
-            printOutput(result,
-                output.formatAboutJson,
-                r => output.formatAbout(r, { expand: flags.expand, root: index.root, depth: flags.depth, showConfidence: flags.showConfidence !== false, compact: !!flags.compact, git: !!flags.git })
-            );
-            if (note) console.error(note);
-            break;
-        }
-
-        case 'impact': {
-            const { ok, result, error, note } = execute(index, 'impact', { name: arg, ...flags });
-            if (!ok) fail(error);
-            printOutput(result, output.formatImpactJson, r => output.formatImpact(r, { compact: flags.compact }));
-            if (note) console.error(note);
-            break;
-        }
-
-        case 'blast': {
-            const { ok, result, error, note } = execute(index, 'blast', { name: arg, ...flags });
-            if (!ok) fail(error);
-            printOutput(result, output.formatBlastJson, output.formatBlast);
-            if (note) console.error(note);
-            break;
-        }
-
-        case 'plan': {
-            const { ok, result, error } = execute(index, 'plan', { name: arg, ...flags });
-            if (!ok) fail(error);
-            printOutput(result, output.formatPlanJson, output.formatPlan);
-            break;
-        }
-
-        case 'trace': {
-            const { ok, result, error, note } = execute(index, 'trace', { name: arg, ...flags });
-            if (!ok) fail(error);
-            printOutput(result, output.formatTraceJson, output.formatTrace);
-            if (note) console.error(note);
-            break;
-        }
-
-        case 'reverseTrace': {
-            const { ok, result, error, note } = execute(index, 'reverseTrace', { name: arg, ...flags });
-            if (!ok) fail(error);
-            printOutput(result, output.formatReverseTraceJson, output.formatReverseTrace);
-            if (note) console.error(note);
-            break;
-        }
-
-        case 'stacktrace': {
-            const { ok, result, error } = execute(index, 'stacktrace', { stack: flags.stack || arg });
-            if (!ok) fail(error);
-            printOutput(result, output.formatStackTraceJson, output.formatStackTrace);
-            break;
-        }
-
-        case 'verify': {
-            const { ok, result, error } = execute(index, 'verify', { name: arg, ...flags });
-            if (!ok) fail(error);
-            printOutput(result, output.formatVerifyJson, output.formatVerify);
-            break;
-        }
-
-        case 'related': {
-            const { ok, result, error, note } = execute(index, 'related', { name: arg, ...flags });
-            if (!ok) fail(error);
-            printOutput(result, output.formatRelatedJson, r => output.formatRelated(r, { all: flags.all, top: flags.top }));
-            if (note) console.error(note);
-            break;
-        }
-
-        case 'brief': {
-            requireArg(arg, 'Usage: ucn . brief <name>');
-            const { ok, result, error } = execute(index, 'brief', { name: arg, file: flags.file, className: flags.className, line: flags.line, git: flags.git });
-            if (!ok) fail(error);
-            printOutput(result, output.formatBriefJson, output.formatBrief);
-            break;
-        }
-
-        case 'doctor': {
-            const { ok, result, error } = execute(index, 'doctor', {
-                file: flags.file, in: flags.in,
-                limit: flags.limit, deep: flags.deep,
-            });
-            if (!ok) fail(error);
-            printOutput(result, output.formatDoctorJson, output.formatDoctor);
-            break;
-        }
-
-        case 'orient': {
-            const topVal = flags.topRaw != null ? flags.topRaw : (flags.top || undefined);
-            const { ok, result, error } = execute(index, 'orient', { top: topVal });
-            if (!ok) fail(error);
-            printOutput(result, output.formatOrientJson, output.formatOrient);
-            break;
-        }
-
-        case 'check': {
-            const { ok, result, error } = execute(index, 'check', {
-                base: flags.base, staged: flags.staged,
-                file: flags.file, limit: flags.limit,
-            });
-            if (!ok) fail(error);
-            printOutput(result, output.formatCheckJson, output.formatCheck);
-            break;
-        }
-
-        // ── Extraction commands (via execute) ────────────────────────────
-
-        case 'fn': {
-            requireArg(arg, 'Usage: ucn . fn <name>');
-            const { ok, result, error, note } = execute(index, 'fn', { name: arg, file: flags.file, all: flags.all, className: flags.className, line: flags.line });
-            if (!ok) fail(error);
-            if (note) console.error(note);
-            printOutput(result, output.formatFnResultJson, output.formatFnResult);
-            break;
-        }
-
-        case 'class': {
-            requireArg(arg, 'Usage: ucn . class <name>');
-            const { ok, result, error, note } = execute(index, 'class', { name: arg, file: flags.file, all: flags.all, maxLines: flags.maxLines, line: flags.line });
-            if (!ok) fail(error);
-            if (note) console.error(note);
-            printOutput(result, output.formatClassResultJson, output.formatClassResult);
-            break;
-        }
-
-        case 'lines': {
-            requireArg(arg, 'Usage: ucn . lines <range> --file <path> (or: lines <file> <range>)');
-            const linesTarget = parseLinesTarget(arg, flags.file);
-            const { ok, result, error, note } = execute(index, 'lines', { file: linesTarget.file, range: linesTarget.range });
-            if (!ok) fail(error);
-            if (note) console.error(note);
-            printOutput(result, output.formatLinesJson, r => output.formatLines(r));
-            break;
-        }
-
-        // ── File dependency commands ────────────────────────────────────
-
-        case 'imports': {
-            const filePath = arg || flags.file;
-            const { ok, result, error } = execute(index, 'imports', { file: filePath });
-            if (!ok) fail(error);
-            printOutput(result,
-                r => output.formatImportsJson(r, filePath),
-                r => output.formatImports(r, filePath)
-            );
-            break;
-        }
-
-        case 'exporters': {
-            const filePath = arg || flags.file;
-            const { ok, result, error } = execute(index, 'exporters', { file: filePath });
-            if (!ok) fail(error);
-            printOutput(result,
-                r => output.formatExportersJson(r, filePath),
-                r => output.formatExporters(r, filePath)
-            );
-            break;
-        }
-
-        case 'fileExports': {
-            const filePath = arg || flags.file;
-            const { ok, result, error } = execute(index, 'fileExports', { file: filePath });
-            if (!ok) fail(error);
-            printOutput(result,
-                r => output.formatFileExportsJson(r, filePath),
-                r => output.formatFileExports(r, filePath)
-            );
-            break;
-        }
-
-        case 'graph': {
-            const filePath = arg || flags.file;
-            const { ok, result, error } = execute(index, 'graph', { file: filePath, direction: flags.direction, depth: flags.depth, all: flags.all });
-            if (!ok) fail(error);
-            printOutput(result,
-                output.formatGraphJson,
-                r => output.formatGraph(r, { showAll: flags.all || flags.depth != null, maxDepth: flags.depth != null ? parseInt(flags.depth, 10) : 2, file: filePath })
-            );
-            break;
-        }
-
-        case 'circularDeps': {
-            const { ok, result, error } = execute(index, 'circularDeps', { file: flags.file, exclude: flags.exclude });
-            if (!ok) fail(error);
-            printOutput(result, output.formatCircularDepsJson, output.formatCircularDeps);
-            break;
-        }
-
-        // ── Remaining commands ──────────────────────────────────────────
-
-        case 'typedef': {
-            const { ok, result, error } = execute(index, 'typedef', { name: arg, exact: flags.exact, file: flags.file, className: flags.className });
-            if (!ok) fail(error);
-            printOutput(result,
-                r => output.formatTypedefJson(r, arg),
-                r => output.formatTypedef(r, arg)
-            );
-            break;
-        }
-
-        case 'tests': {
-            const { ok, result, error } = execute(index, 'tests', { name: arg, callsOnly: flags.callsOnly, className: flags.className, file: flags.file, exclude: flags.exclude });
-            if (!ok) fail(error);
-            const displayName = nameForDisplay(arg);
-            printOutput(result,
-                r => output.formatTestsJson(r, displayName),
-                r => output.formatTests(r, displayName)
-            );
-            break;
-        }
-
-        case 'affectedTests': {
-            const { ok, result, error, note } = execute(index, 'affectedTests', { name: arg, ...flags });
-            if (!ok) fail(error);
-            printOutput(result, output.formatAffectedTestsJson, r => output.formatAffectedTests(r, { all: flags.all }));
-            if (note) console.error(note);
-            break;
-        }
-
-        case 'api': {
-            const filePath = arg || flags.file;
-            const { ok, result, error, note } = execute(index, 'api', { file: filePath, limit: flags.limit });
-            if (!ok) fail(error);
-            if (note) console.error(note);
-            printOutput(result,
-                r => output.formatApiJson(r, filePath),
-                r => output.formatApi(r, filePath)
-            );
-            break;
-        }
-
-        case 'search': {
-            const { ok, result, error, structural } = execute(index, 'search', { term: arg, ...flags });
-            if (!ok) fail(error);
-            if (structural) {
-                printOutput(result, output.formatStructuralSearchJson, output.formatStructuralSearch);
-            } else {
-                printOutput(result,
-                    r => output.formatSearchJson(r, arg),
-                    r => output.formatSearch(r, arg)
-                );
-            }
-            break;
-        }
-
-        case 'deadcode': {
-            const { ok, result, error, note } = execute(index, 'deadcode', { ...flags, in: flags.in || subdirScope });
-            if (!ok) fail(error);
-            if (note) console.error(note);
-            printOutput(result,
-                output.formatDeadcodeJson,
-                r => output.formatDeadcode(r, {
-                    top: flags.top,
-                    decoratedHint: !flags.includeDecorated && result.excludedDecorated > 0 ? `${result.excludedDecorated} decorated/annotated symbol(s) hidden (framework-registered). Use --include-decorated to include them.` : undefined,
-                    exportedHint: !flags.includeExported && result.excludedExported > 0 ? `${result.excludedExported} exported symbol(s) excluded from the audit (public API may have external callers). Use --include-exported to audit them.` : undefined,
-                    externalContractHint: !flags.includeExported && result.excludedExternalContract > 0 ? `${result.excludedExternalContract} symbol(s) hidden (override an out-of-tree base class — reachable via external contract, not dead). Use --include-exported to include them.` : undefined
-                })
-            );
-            break;
-        }
-
-        case 'entrypoints': {
-            const { ok, result, error, note } = execute(index, 'entrypoints', { type: flags.type, framework: flags.framework, file: flags.file, exclude: flags.exclude, includeTests: flags.includeTests, excludeTests: flags.excludeTests, limit: flags.limit });
-            if (!ok) fail(error);
-            if (note) console.error(note);
-            printOutput(result,
-                output.formatEntrypointsJson,
-                r => output.formatEntrypoints(r)
-            );
-            break;
-        }
-
-        case 'endpoints': {
-            const { ok, result, error, note } = execute(index, 'endpoints', {
-                file: flags.file,
-                exclude: flags.exclude,
-                limit: flags.limit,
-                framework: flags.framework,
-                bridge: flags.bridge,
-                serverOnly: flags.serverOnly,
-                clientOnly: flags.clientOnly,
-                unmatched: flags.unmatched,
-                method: flags.method,
-                prefix: flags.prefix,
-                hideUncertain: flags.hideUncertain,
-            });
-            if (!ok) fail(error);
-            if (note) console.error(note);
-            printOutput(result,
-                output.formatEndpointsJson,
-                r => output.formatEndpoints(r, { bridge: r._bridge, unmatched: r._unmatched })
-            );
-            break;
-        }
-
-        case 'stats': {
-            // MEDIUM-7: pass the raw --top value when present so the executor
-            // can validate it and surface "Invalid --top" errors. Without
-            // this, --top=abc is silently coerced to NaN → undefined and
-            // the user gets the default (10) with no warning.
-            const topVal = flags.topRaw != null ? flags.topRaw : (flags.top || undefined);
-            const { ok, result, error, note } = execute(index, 'stats', {
-                functions: flags.functions,
-                hot: flags.hot,
-                top: topVal,
-            });
-            if (!ok) fail(error);
-            if (note) console.error(note);
-            printOutput(result,
-                output.formatStatsJson,
-                r => output.formatStats(r, { top: flags.top })
-            );
-            break;
-        }
-
-        case 'diffImpact': {
-            const { ok, result, error, note } = execute(index, 'diffImpact', { base: flags.base, staged: flags.staged, file: flags.file, limit: flags.limit, all: flags.all });
-            if (!ok) fail(error);
-            if (note) console.error(note);
-            printOutput(result, output.formatDiffImpactJson, r => output.formatDiffImpact(r, { all: flags.all }));
-            break;
-        }
-
-        case 'auditAsync': {
-            const { ok, result, error, note } = execute(index, 'auditAsync', {
-                file: flags.file,
-                exclude: flags.exclude,
-                limit: flags.limit,
-            });
-            if (!ok) fail(error);
-            if (note) console.error(note);
-            printOutput(result, output.formatAuditAsyncJson, output.formatAuditAsync);
-            break;
-        }
-
-        default:
-            console.error(`Unknown command: ${canonical}`);
-            printUsage();
-            throw new CommandError();
+    // Public commands share one argument builder, executor, and formatter.
+    const publicParams = buildPublicParams(canonical, arg, {
+        ...flags,
+        ...(subdirScope && !flags.in ? { in: subdirScope } : {}),
+    });
+    const publicExecution = execute(index, canonical, publicParams);
+    if (!publicExecution.ok) {
+        fail(formatSurfaceMessage(publicExecution.error, 'cli'));
     }
+    console.log(flags.json
+        ? output.formatPublicJson(canonical, publicExecution.result, publicParams, {
+            ...publicExecution, surface: 'cli',
+        })
+        : formatCliText(canonical, publicExecution.result, publicParams, publicExecution, flags));
+    // A gate that could not run (check outside git / bad base ref) must not
+    // exit 0 — CI gating on the exit code would read "could not run" as "passed".
+    process.exitCode = Math.max(process.exitCode || 0,
+        resultExitCode(canonical, publicExecution.result));
     } catch (e) {
         if (!(e instanceof CommandError)) {
-            console.error(`Error: ${e.message}`);
+            emitCliError(`Error: ${e.message}`);
         }
         process.exitCode = 1;
     } finally {
@@ -1211,57 +757,12 @@ function runProjectCommand(rootDir, command, arg) {
         // On cache-hit runs, only re-save if callsCache was mutated OR
         // reachability was computed (MED-1: persists the BFS result so
         // subsequent cold invocations don't repeat the 7-11s tax).
-        if (flags.cache && (needsCacheSave || index.callsCacheDirty || index.reachabilityDirty)) {
+        if (flags.cache && (needsCacheSave || index.callsCacheDirty || index.reachabilityDirty || index.computedDispatchDirty)) {
             try { index.saveCache(); } catch (e) { /* best-effort */ }
         }
     }
 }
 
-// extractFunctionFromProject and extractClassFromProject removed —
-// all surfaces now use execute(index, 'fn'/'class', params) from core/execute.js
-
-
-/**
- * Save expandable items to cache file
- */
-function saveExpandableItems(items, root) {
-    try {
-        const cacheDir = path.join(root || '.', '.ucn-cache');
-        if (!fs.existsSync(cacheDir)) {
-            fs.mkdirSync(cacheDir, { recursive: true });
-        }
-        fs.writeFileSync(
-            path.join(cacheDir, 'expandable.json'),
-            JSON.stringify({ items, root, timestamp: Date.now() }, null, 2)
-        );
-    } catch (e) {
-        // Silently fail - expand feature is optional
-    }
-}
-
-/**
- * Load expandable items from cache
- */
-function loadExpandableItems(root) {
-    try {
-        const cachePath = path.join(root || '.', '.ucn-cache', 'expandable.json');
-        if (fs.existsSync(cachePath)) {
-            return JSON.parse(fs.readFileSync(cachePath, 'utf-8'));
-        }
-    } catch (e) {
-        // Return null on error
-    }
-    return null;
-}
-
-/**
- * Print expanded code for a cached item
- */
-// printExpandedItem removed — all surfaces now use execute(index, 'expand', ...)
-
-
-
-
 // ============================================================================
 // GLOB MODE
 // ============================================================================
@@ -1270,11 +771,11 @@ function runGlobCommand(pattern, command, arg) {
     const files = expandGlob(pattern);
 
     if (files.length === 0) {
-        console.error(`No files match pattern: ${pattern}`);
-        process.exit(1);
+        fail(`No files match pattern: ${pattern}`, command);
     }
 
     const canonical = resolveCommand(command, 'cli') || command;
+    activeCanonicalCommand = canonical;
 
     // Build a temporary index over the matched files and route through execute().
     // This gives glob mode the same semantics as project mode: test exclusions,
@@ -1283,223 +784,22 @@ function runGlobCommand(pattern, command, arg) {
     const index = new ProjectIndex(rootDir);
     index.build(files, { quiet: true });
 
-    // Supported commands — anything that works with an index.
-    // All execute() commands are supported; only expand (requires cached state)
-    // and interactive-only commands are excluded.
-    const unsupportedGlobCommands = new Set(['expand']);
-    if (unsupportedGlobCommands.has(canonical)) {
-        console.error(`Command "${command}" not supported in glob mode.`);
-        process.exit(1);
-    }
-
-    // Build params — same as project mode
-    const params = {};
-    const needsName = new Set(['find', 'usages', 'fn', 'class', 'typedef', 'about', 'context',
-        'smart', 'impact', 'trace', 'blast', 'reverseTrace', 'tests', 'affectedTests',
-        'example', 'verify', 'plan', 'related']);
-    if (needsName.has(canonical)) {
-        if (!arg) {
-            console.error(`Usage: ucn "pattern" ${command} <name>`);
-            process.exit(1);
-        }
-        params.name = arg;
-    }
-    if (canonical === 'search' || canonical === 'structuralSearch') {
-        if (!arg && !flags.type) {
-            console.error('Usage: ucn "pattern" search <term>');
-            process.exit(1);
-        }
-        params.term = arg;
-    }
-    // Merge flags first, then set positional overrides so they aren't wiped
-    Object.assign(params, flags);
-
-    // Warn about inapplicable flags (same check as project/interactive mode)
-    const applicableFlags = FLAG_APPLICABILITY[canonical];
-    if (applicableFlags) {
-        const flagToCli = (f) => '--' + f.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
-        const globalFlags = new Set(['json', 'quiet', 'cache', 'clearCache', 'followSymlinks', 'maxFiles', 'verbose', 'expand', 'interactive', '_fileFromFileMode', 'topRaw', 'limitRaw', 'maxFilesRaw', 'maxLinesRaw', 'depthRaw', 'contextRaw', 'workersRaw']);
-        for (const [key, value] of Object.entries(flags)) {
-            if (globalFlags.has(key)) continue;
-            if (value === undefined || value === null || value === 0 || (Array.isArray(value) && value.length === 0)) continue;
-            if (!applicableFlags.includes(key)) {
-                console.error(`Warning: ${flagToCli(key)} has no effect on '${toCliName(canonical)}'.`);
-            }
-        }
-    }
-    if (canonical === 'stacktrace' && arg) {
-        params.stack = arg;
+    if (!isPublicCommand(canonical)) {
+        fail(unknownCommandMessage(command));
     }
-    if (canonical === 'lines' && arg) {
-        params.range = arg;
-    }
-    if (['imports', 'exporters', 'fileExports', 'graph', 'api'].includes(canonical)) {
-        if (arg) params.file = arg;
-    }
-
-    const { ok, result, error, note, structural } = execute(index, canonical, params);
-    if (!ok) fail(error);
-    if (note) console.error(note);
-
-    // Format output — same formatters as project mode
-    switch (canonical) {
-        case 'toc':
-            printOutput(result, output.formatTocJson, r => output.formatToc(r, {
-                detailedHint: 'Add --detailed to list all functions, or "ucn . about <name>" for full details on a symbol'
-            }));
-            break;
-        case 'find':
-            printOutput(result,
-                r => output.formatSymbolJson(r, arg),
-                r => output.formatFindDetailed(r, arg, { depth: flags.depth, top: flags.top, all: flags.all })
-            );
-            break;
-        case 'search':
-            if (structural) {
-                printOutput(result, output.formatStructuralSearchJson, output.formatStructuralSearch);
-            } else {
-                printOutput(result,
-                    r => output.formatSearchJson(r, arg),
-                    r => output.formatSearch(r, arg)
-                );
-            }
-            break;
-        case 'fn':
-            printOutput(result, output.formatFnResultJson, output.formatFnResult);
-            break;
-        case 'class':
-            printOutput(result, output.formatClassResultJson, output.formatClassResult);
-            break;
-        case 'usages':
-            printOutput(result, r => output.formatUsagesJson(r, arg), r => output.formatUsages(r, arg));
-            break;
-        case 'deadcode':
-            printOutput(result, output.formatDeadcodeJson, r => output.formatDeadcode(r, { top: flags.top }));
-            break;
-        case 'typedef':
-            printOutput(result, r => output.formatTypedefJson(r, arg), r => output.formatTypedef(r, arg));
-            break;
-        case 'stats':
-            printOutput(result, output.formatStatsJson, r => output.formatStats(r, { top: flags.top }));
-            break;
-        case 'about':
-            printOutput(result, output.formatAboutJson,
-                r => output.formatAbout(r, { expand: flags.expand, root: index.root, depth: flags.depth, showConfidence: flags.showConfidence !== false, compact: !!flags.compact }));
-            break;
-        case 'context':
-            if (flags.json) {
-                console.log(output.formatContextJson(result));
-            } else {
-                const { text } = output.formatContext(result, {
-                    expandHint: 'Use --expand to see inline callee previews',
-                    showConfidence: flags.showConfidence !== false,
-                    compact: !!flags.compact,
-                });
-                console.log(text);
-                if (flags.expand) {
-                    printInlineExpand(result, index.root);
-                }
-            }
-            break;
-        case 'smart':
-            printOutput(result, output.formatSmartJson, output.formatSmart);
-            break;
-        case 'impact':
-            printOutput(result, output.formatImpactJson, output.formatImpact);
-            break;
-        case 'related':
-            printOutput(result, output.formatRelatedJson,
-                r => output.formatRelated(r, { all: flags.all, top: flags.top }));
-            break;
-        case 'brief':
-            printOutput(result, output.formatBriefJson, output.formatBrief);
-            break;
-        case 'doctor':
-            printOutput(result, output.formatDoctorJson, output.formatDoctor);
-            break;
-        case 'check':
-            printOutput(result, output.formatCheckJson, output.formatCheck);
-            break;
-        case 'trace':
-            printOutput(result, output.formatTraceJson, output.formatTrace);
-            break;
-        case 'blast':
-            printOutput(result, output.formatBlastJson, output.formatBlast);
-            break;
-        case 'reverseTrace':
-            printOutput(result, output.formatReverseTraceJson, output.formatReverseTrace);
-            break;
-        case 'tests':
-            printOutput(result, r => output.formatTestsJson(r, arg), r => output.formatTests(r, arg));
-            break;
-        case 'affectedTests':
-            printOutput(result, output.formatAffectedTestsJson,
-                r => output.formatAffectedTests(r, { all: flags.all }));
-            break;
-        case 'example':
-            printOutput(result, r => output.formatExampleJson(r, arg), r => output.formatExample(r, arg));
-            break;
-        case 'verify':
-            printOutput(result, output.formatVerifyJson, output.formatVerify);
-            break;
-        case 'plan':
-            printOutput(result, output.formatPlanJson, output.formatPlan);
-            break;
-        case 'imports': {
-            const filePath = params.file;
-            printOutput(result, r => output.formatImportsJson(r, filePath), r => output.formatImports(r, filePath));
-            break;
-        }
-        case 'exporters': {
-            const filePath = params.file;
-            printOutput(result, r => output.formatExportersJson(r, filePath), r => output.formatExporters(r, filePath));
-            break;
-        }
-        case 'fileExports': {
-            const filePath = params.file;
-            printOutput(result, r => output.formatFileExportsJson(r, filePath), r => output.formatFileExports(r, filePath));
-            break;
-        }
-        case 'api': {
-            const filePath = params.file;
-            printOutput(result, r => output.formatApiJson(r, filePath), r => output.formatApi(r, filePath));
-            break;
-        }
-        case 'graph':
-            printOutput(result, output.formatGraphJson,
-                r => output.formatGraph(r, { showAll: flags.all || flags.depth != null, maxDepth: flags.depth }));
-            break;
-        case 'circularDeps':
-            printOutput(result, output.formatCircularDepsJson, output.formatCircularDeps);
-            break;
-        case 'entrypoints':
-            printOutput(result, output.formatEntrypointsJson, output.formatEntrypoints);
-            break;
-        case 'endpoints':
-            printOutput(result, output.formatEndpointsJson, r => output.formatEndpoints(r, { bridge: r._bridge, unmatched: r._unmatched }));
-            break;
-        case 'diffImpact':
-            printOutput(result, output.formatDiffImpactJson, output.formatDiffImpact);
-            break;
-        case 'auditAsync':
-            printOutput(result, output.formatAuditAsyncJson, output.formatAuditAsync);
-            break;
-        case 'stacktrace':
-            printOutput(result, output.formatStackTraceJson, output.formatStackTrace);
-            break;
-        case 'lines':
-            printOutput(result, output.formatLinesJson, output.formatLines);
-            break;
-        default: {
-            // Fallback: output JSON for any command without a dedicated formatter
-            if (flags.json) {
-                console.log(JSON.stringify({ meta: {}, data: result }, null, 2));
-            } else {
-                console.log(JSON.stringify(result, null, 2));
-            }
-            break;
-        }
+    warnInapplicableFlags(canonical, flags, (message) => console.error(message));
+    const publicParams = buildPublicParams(canonical, arg, flags);
+    const publicExecution = execute(index, canonical, publicParams);
+    if (!publicExecution.ok) {
+        fail(formatSurfaceMessage(publicExecution.error, 'cli'));
     }
+    console.log(flags.json
+        ? output.formatPublicJson(canonical, publicExecution.result, publicParams, {
+            ...publicExecution, surface: 'cli',
+        })
+        : formatCliText(canonical, publicExecution.result, publicParams, publicExecution, flags));
+    process.exitCode = Math.max(process.exitCode || 0,
+        resultExitCode(canonical, publicExecution.result));
 }
 
 // ============================================================================
@@ -1510,153 +810,93 @@ function runGlobCommand(pattern, command, arg) {
 // Single source of truth for the public CLI help. README points here ("Run `ucn --help`")
 // rather than carrying a copy — keep it that way.
 function printUsage() {
+    const perCommandFlags = [...getCliCommandSet()].map(command => {
+        const flags = getCliFlagsForCommand(command);
+        return `  ${command.padEnd(14)} ${flags.join(' ')}`;
+    }).join('\n');
     console.log(`UCN - Universal Code Navigator
 
-Supported: JavaScript, TypeScript, Python, Go, Rust, Java, HTML
+Supported: JavaScript/TypeScript, Python, Go, Rust, Java, C, C++, C#, HTML
 
 Usage:
-  ucn [command] [args]            Project mode (current directory)
-  ucn <file> [command] [args]     Single file mode
-  ucn <dir> [command] [args]      Project mode (specific directory)
-  ucn "pattern" [command] [args]  Glob pattern mode
-  (Default output is text; add --json for machine-readable JSON)
-
-═══════════════════════════════════════════════════════════════════════════════
-UNDERSTAND CODE
-═══════════════════════════════════════════════════════════════════════════════
-  about <name>        Full picture (definition, callers, callees, tests, code)
-  brief <name>        One-screen summary (signature, docstring, side effects, complexity)
-  context <name>      Who calls this + what it calls (numbered for expand)
-  smart <name>        Function + all dependencies inline
-  impact <name>       What breaks if changed (call sites grouped by file)
-  blast <name>        Transitive blast radius (callers of callers, --depth=N)
-  trace <name>        Call tree visualization (--depth=N expands all children)
-  reverse-trace <name> Upward call chain to entry points (--depth=N, default 5)
-  related <name>      Find similar functions (same file, shared deps)
-  example <name>      Best usage example with context
-
-═══════════════════════════════════════════════════════════════════════════════
-FIND CODE
-═══════════════════════════════════════════════════════════════════════════════
-  find <name>         Find symbol definitions (supports glob: find "handle*")
-  usages <name>       All usages grouped: definitions, calls, imports, references
-  toc                 Table of contents (compact; --detailed lists all symbols)
-  search <term>       Text search (regex default, --context=N, --exclude=, --in=)
-                      Structural: --type=function|class|call --param= --returns= --decorator= --exported --unused
-  tests <name>        Find test files for a function (--file, --class-name, --exclude, --calls-only)
-  affected-tests <n>  Tests affected by a change (blast + test detection, --depth=N)
-
-═══════════════════════════════════════════════════════════════════════════════
-EXTRACT CODE
-═══════════════════════════════════════════════════════════════════════════════
-  fn <name>[,n2,...]  Extract function(s) (comma-separated for bulk, --file)
-  class <name>        Extract class
-  lines <range>       Extract line range (e.g., lines 50-100)
-  expand <N>          Show code for item N from context output
-
-═══════════════════════════════════════════════════════════════════════════════
-FILE DEPENDENCIES
-═══════════════════════════════════════════════════════════════════════════════
-  imports <file>      What does file import
-  exporters <file>    Who imports this file
-  file-exports <file> What does file export
-  graph <file>        Full dependency tree (--depth=N, --direction=imports|importers|both)
-  circular-deps       Detect circular import chains (--file=, --exclude=)
-
-═══════════════════════════════════════════════════════════════════════════════
-REFACTORING HELPERS
-═══════════════════════════════════════════════════════════════════════════════
-  plan <name>         Preview refactoring (--add-param, --remove-param, --rename-to, --default-value)
-  verify <name>       Check all call sites match signature
-  diff-impact         What changed in git diff and who calls it (--base, --staged)
-  check               Pre-commit summary: diff-impact + verify + affected-tests in one shot
-  deadcode            Unreferenced-symbol candidates (review before deletion)
-  entrypoints         Detect framework entry points (routes, DI, tasks)
-  endpoints           HTTP API: list server routes + client requests; --bridge to match
-                        --bridge --server-only --client-only --unmatched
-                        --method=GET --prefix=/api --hide-uncertain
-
-═══════════════════════════════════════════════════════════════════════════════
-OTHER
-═══════════════════════════════════════════════════════════════════════════════
-  api                 Show exported/public symbols
-  typedef <name>      Find type definitions
-  stats               Project statistics (--functions for per-function line counts, --hot for top callers)
-  doctor              Parse health, blind spots, command proofs, and task readiness (--deep adds evidence profile)
-  orient              One-screen repo map: size, top dirs, hot functions, entry points, readiness (--top=N)
-  stacktrace <text>   Parse stack trace, show code at each frame (alias: stack)
-  audit-async         Find calls in async functions that are likely missing await (JS/TS/Python)
-
-Common Flags:
-  --file <pattern>    Filter by file path (e.g., --file=routes)
-  --exclude=a,b       Exclude patterns (e.g., --exclude=test,mock)
-  --in=<path>         Only in path (e.g., --in=src/core)
-  --depth=N           Max depth: blast=3, trace=3, reverse-trace=5, graph=2, affected-tests=3
-  --direction=X       Graph direction: imports, importers, or both (default: both)
-  --all               Show full results: all callers/callees + unverified (about/context), full tree (trace/blast),
-                        all names (related/find/fn/class/toc), all changed (diff-impact)
-  --top=N             Limit callers/callees (about), similar functions (related), search results
-  --limit=N           Limit result count (find, usages, search, deadcode, api, toc, entrypoints, diff-impact)
-  --max-files=N       Max files to index (large projects)
-  --context=N         Lines of context around matches (search, usages)
-  --json              Machine-readable output
-  --compact           Token-efficient about/context/impact output
-  --code-only         Filter out comments/strings (search, usages)
-  --with-types        Include type definitions (about, smart)
-  --detailed          Show all symbols in toc (not just counts)
-  --include-tests     Include test files in usage counts (about) and results (find, usages, deadcode)
-  --exclude-tests     Exclude test files (entrypoints includes tests by default)
-  --class-name=X      Scope to specific class (e.g., --class-name=Repository)
-  --include-methods   Include method-call (obj.fn) callee expansion in trace/smart
-                        (no effect on caller-direction commands: about/context/impact/verify/
-                        blast/reverse-trace/affected-tests always tier method calls by evidence)
-  --include-uncertain No effect on tiered commands; unverified candidates are always
-                        shown in their own section with reasons
-  --expand-unverified Follow unverified caller edges in blast/reverse-trace trees
-                        (downstream nodes marked as possible, not confirmed, impact chains)
-  --hide-confidence   Hide confidence scores (shown by default in about, context)
-  --min-confidence=N  Filter low-confidence edges (about, context, blast, trace,
-                        reverse-trace, smart, affected-tests)
-  --unreachable-only  Show only callers/callees that are unreachable from entry points (about, context, impact)
-  --include-exported  Include exported symbols in deadcode
-  --no-regex          Force plain text search (regex is default)
-  --functions         Show per-function line counts (stats command)
-  --hot               Show top N most-called functions (stats command, pair with --top=N)
-  --diverse           Cluster call sites by argument shape (example command, pair with --top=N)
-  --git               Attach git enrichment (last modified, author, recent commits) to about/brief
-  --include-decorated Include decorated/annotated symbols in deadcode
-  --deep              Add a stratified evidence profile to doctor (not measured accuracy)
-  --framework=X       Filter entrypoints by framework (e.g., --framework=express,spring)
-  --bridge            Match server routes to client requests (endpoints command).
-                        Confidence tiers: EXACT, PARTIAL, UNCERTAIN
-  --server-only       Only list server routes (endpoints command)
-  --client-only       Only list client requests (endpoints command)
-  --unmatched         Only show routes/requests with no match (endpoints, pair with --bridge)
-  --method=X          Filter by HTTP method (endpoints, e.g., --method=POST)
-  --prefix=X          Filter routes/requests by path prefix (endpoints, e.g., --prefix=/api)
-  --hide-uncertain    Hide UNCERTAIN-confidence bridges (endpoints command)
-  --exact             Exact name match only (find, typedef)
-  --calls-only        Only show call/test-case matches (tests)
-  --case-sensitive    Case-sensitive text search (search)
-  --top-level         Show only top-level functions in toc
-  --max-lines=N       Max source lines for class (large classes show summary)
-  --workers=N         Parallel build workers (auto-detect; 0 to disable, env: UCN_WORKERS)
-  --no-cache          Disable caching
-  --clear-cache       Clear cache before running
-  --base=<ref>        Git ref for diff-impact (default: HEAD)
-  --staged            Analyze staged changes (diff-impact)
-  --no-follow-symlinks  Don't follow symbolic links
-  --mcp               Start the MCP stdio server
-  -i, --interactive   Keep index in memory for multiple queries
-  -v, --version       Print the UCN version and exit
-
-Quick Start:
-  ucn orient                          # First look at a new repo
-  ucn toc                             # See project structure
-  ucn about handleRequest             # Understand a function
-  ucn impact handleRequest            # Before modifying
-  ucn fn handleRequest --file api     # Extract specific function
-  ucn --interactive                   # Multiple queries`);
+  ucn [command] [args]            Current project
+  ucn <file|dir|glob> <command>   Explicit target
+  Add --json for a stable { meta, data } envelope.
+
+Commands:
+  repo                            Repository overview
+    --sections=summary,files,stats,health  Select repository sections
+    --deep                         Include deep readiness evidence
+  show <symbol>                   Symbol summary and relationships
+    --sections=summary,callers,callees,source,dependencies,tests,types,example,related
+  find <name>                     Definitions; --type=type, --with-source
+  usages <name>                   Calls, imports, definitions, references
+  search [term]                   Text or structural search
+    literal text by default; --regex enables regular-expression syntax
+  source <symbol|file:range>      Exact function, class, or line extraction
+  trace <symbol>                  Call graph
+    --direction=callees|callers   Downstream or upstream (default: callees)
+    --to=entrypoints              Follow callers toward entry points
+  impact [symbol]                 Symbol impact; without symbol, Git-diff impact
+  tests <symbol>                  Direct tests; --depth=N adds transitive impact
+  deps <file>                     File graph; --direction=imports|importers|both
+    --detailed                     Include import declarations
+  deps --cycles                   Report circular dependencies (no file target)
+  api [file]                      Project or file public API
+  check [symbol]                  Signature check; without symbol, precommit check
+  plan <symbol>                   Preview rename or parameter edits
+  entrypoints                     Runtime and framework entry points
+  endpoints                       Server/client HTTP surface
+  deadcode                        Conservative unreachable-symbol candidates
+  audit-async                     Likely missing-await sites
+  stacktrace <text>               Resolve runtime frames to source
+
+Common flags:
+  --file=PATH --exclude=a,b --in=PATH --depth=N --top=N --limit=N
+  --all --compact --no-compact --json --include-tests --class-name=X --line=N
+  --range=N-M (source with --file=PATH)
+  --base=REF --staged --no-cache --clear-cache [--all] --max-files=N --workers=N
+  --max-chars=N (text output; default 10K targeted / 3K broad, ceiling 100K)
+  Cache: per-user by default; set UCN_CACHE_DIR to override the cache root.
+
+Accepted flags by command:
+${perCommandFlags}
+
+Global/build/output flags:
+  --help -h --version -v --mcp --json --verbose --no-quiet --quiet
+  --interactive -i --no-cache --clear-cache --no-follow-symlinks
+  --max-files=N --max-chars=N --workers=N
+  --clear-cache --all clears every bounded per-user UCN project cache.
+
+Exit codes:
+  0  Command completed successfully; check found no blocking issues.
+  1  Findings, unsafe changes, validation failures, or invalid user input.
+  2  Command could not run (operational/environment failure).
+
+Boolean aliases:
+  --no-include-methods --no-regex --show-confidence --hide-confidence
+  --no-confidence --hide-uncertain --no-uncertain --compact --no-compact
+
+Value aliases:
+  --not=PATTERN (alias of --exclude) --default=VALUE (alias of --default-value)
+
+Trust:
+  CONFIRMED means target-identity evidence exists. UNVERIFIED means possible and
+  requires review. ACCOUNT conserves observed text lines; it never proves full
+  runtime semantics or safe deletion.
+
+UCN vs grep:
+  Use UCN for definitions, callers/callees, impact, tests, dependencies, APIs,
+  entry points, and audits. Use grep/ripgrep for simple literals, messages,
+  configuration, filenames, Markdown, and unsupported languages.
+
+Quick start:
+  ucn repo
+  ucn show handleRequest
+  ucn trace handleRequest --direction=callers
+  ucn impact handleRequest
+  ucn tests handleRequest --depth=3
+  ucn source handleRequest`);
 }
 
 // ============================================================================
@@ -1669,12 +909,18 @@ function runInteractive(rootDir) {
 
     console.log('Building index...');
     const index = new ProjectIndex(rootDir);
+    if (flags.clearCache) {
+        const removed = index.clearCache();
+        if (removed.length > 0 && !flags.quiet) {
+            console.error('Cache cleared');
+        }
+    }
     // Same cache discipline as one-shot mode (fix #250: the REPL fully
     // re-parsed every session and never consumed cache-persisted state —
     // the divergence mechanism behind the relocation P1).
     let iCacheFresh;
-    if (flags.cache && !flags.clearCache) {
-        const loaded = index.loadCache();
+    if (flags.cache) {
+        const loaded = !flags.clearCache && index.loadCache();
         iCacheFresh = loaded && !index.isCacheStale();
         if (!iCacheFresh && loaded) {
             index.build(null, { quiet: true, forceRebuild: true, workers: flags.workers });
@@ -1687,9 +933,8 @@ function runInteractive(rootDir) {
     } else {
         index.build(null, { quiet: true, workers: flags.workers });
     }
-    const iExpandCache = new ExpandCache({ maxSize: 20 });
     console.log(`Index ready: ${index.files.size} files, ${index.symbols.size} unique symbol names`);
-    console.log('Type commands (e.g., "find parseFile", "about main", "toc")');
+    console.log('Type commands (e.g., "find parseFile", "show main", "repo")');
     console.log('Type "help" for commands, "quit" to exit\n');
 
     const rl = readline.createInterface({
@@ -1716,50 +961,29 @@ function runInteractive(rootDir) {
         if (input === 'help') {
             console.log(`
 Commands:
-  toc                    Project overview (--detailed)
-  find <name>            Find symbol (--exact, glob: "handle*")
-  brief <name>           Signature, docs, side effects, and complexity
-  about <name>           Everything about a symbol
+  repo                   Repository overview (--sections=files,stats,health)
+  show <name>            Symbol summary + relationships (--sections=...)
+  find <name>            Find definitions (--type=type, --with-source)
   usages <name>          All usages grouped by type
-  context <name>         Callers + callees
-  expand <N>             Show code for item N from context
-  smart <name>           Function + dependencies
-  impact <name>          What breaks if changed
-  blast <name>           Transitive blast radius (--depth=N)
-  trace <name>           Call tree (--depth=N)
-  reverse-trace <name>   Upward to entry points (--depth=N)
-  example <name>         Best usage example
-  related <name>         Sibling functions
-  fn <name>[,n2,...]     Extract function(s) (--file=)
-  class <name>           Extract class code (--file=)
-  lines <range>          Extract lines (--file= required)
-  graph <file>           File dependency tree (--direction=, --depth=)
-  circular-deps          Circular import chains (--file=, --exclude=)
-  file-exports <file>    File's exported symbols
-  imports <file>         What file imports
-  exporters <file>       Who imports file
-  tests <name>           Find tests (--file, --class-name, --exclude, --calls-only)
-  affected-tests <n>     Tests affected by a change (--depth=N)
+  source <target>        Extract a symbol or file:line-range
+  trace <name>           Call tree (--direction=callees|callers, --to=entrypoints)
+  impact [name]          Symbol impact, or Git diff impact without a name
+  tests <name>           Direct tests; --depth=N includes transitive impact
+  deps <file>            File graph (--direction=, --depth=, --detailed, --cycles)
   search <term>          Text search (--context=N, --exclude=, --in=)
                          Structural: --type= --param= --returns= --decorator= --exported --unused
-  typedef <name>         Find type definitions
   deadcode               Unreferenced-symbol candidates (review before deletion)
   entrypoints            Detect runtime, framework, task, and test entry points
   endpoints              List server/client HTTP endpoints (--bridge to match)
-  verify <name>          Check call sites match signature
+  check [name]           Symbol signature check, or pre-commit check without a name
   plan <name>            Preview refactoring (--add-param=, --remove-param=, --rename-to=, --default-value=)
-  check                  Pre-commit diff, signature, and affected-test checks
   stacktrace <text>      Parse a stack trace
   api                    Show public symbols
-  diff-impact            What changed and who's affected
-  stats                  Index statistics
-  doctor                 Parse health, blind spots, command proofs, and task readiness
-  orient                 Repository map and readiness summary
-  audit-async            Find likely missing-await calls (JS/TS/Python)
+  audit-async            Find likely missing-await calls (JS/TS/Python/C#)
   rebuild                Rebuild index
   quit                   Exit
 
-Flags can be added per-command: context myFunc --include-methods
+Flags can be added per-command: show myFunc --sections=source,callers
 `);
             rl.prompt();
             return;
@@ -1768,8 +992,6 @@ Flags can be added per-command: context myFunc --include-methods
         if (input === 'rebuild') {
             console.log('Rebuilding index...');
             index.build(null, { quiet: true, forceRebuild: true, workers: flags.workers });
-            // Clear expand cache — stale line ranges after rebuild
-            if (iExpandCache) iExpandCache.clearForRoot(index.root);
             console.log(`Index ready: ${index.files.size} files, ${index.symbols.size} unique symbol names`);
             rl.prompt();
             return;
@@ -1779,7 +1001,7 @@ Flags can be added per-command: context myFunc --include-methods
         const tokens = input.split(/\s+/);
         const command = tokens[0];
         // Flags that take a space-separated value (--flag value)
-        const valueFlagNames = new Set(['--file', '--in', '--base', '--add-param', '--remove-param', '--rename-to', '--default', '--depth', '--top', '--context', '--max-lines', '--direction', '--exclude', '--not', '--stack', '--type', '--param', '--receiver', '--returns', '--decorator', '--limit', '--max-files', '--min-confidence', '--class-name', '--line', '--framework', '--method', '--prefix']);
+        const valueFlagNames = new Set(['--file', '--in', '--base', '--add-param', '--remove-param', '--rename-to', '--default', '--depth', '--top', '--context', '--max-lines', '--direction', '--to', '--sections', '--range', '--exclude', '--not', '--stack', '--type', '--param', '--receiver', '--returns', '--decorator', '--limit', '--max-files', '--max-chars', '--min-confidence', '--class-name', '--line', '--framework', '--method', '--prefix']);
         const flagTokens = [];
         const argTokens = [];
         const skipNext = new Set();
@@ -1798,9 +1020,8 @@ Flags can be added per-command: context myFunc --include-methods
         }
         const arg = argTokens.join(' ');
 
-        // Unknown flags error instead of folding their VALUE into the
-        // symbol name (fix #250: `about AddTask --bogus 5` searched for
-        // "AddTask 5"). Same vocabulary as one-shot mode.
+        // Unknown flags error instead of folding their value into the symbol
+        // name. Same vocabulary as one-shot mode.
         const unknown = flagTokens.filter(t =>
             t.startsWith('--') && !knownFlags.has(t.split('=')[0]));
         if (unknown.length > 0) {
@@ -1820,8 +1041,28 @@ Flags can be added per-command: context myFunc --include-methods
             // global CLI mode. MED-2/MED-3/MED-5: bad values are rejected with
             // a helpful message instead of being silently coerced.
             validateNumericFlags(iflags);
+            // The REPL is an edit/query loop, not a frozen snapshot. Keep the
+            // symbol table and call cache on the same generation by checking
+            // source staleness before every command. getCachedCalls already
+            // refreshes individual call records lazily; without this matching
+            // rebuild a newly added definition was invisible while its calls
+            // appeared in neighbouring answers (UCN5-044).
+            if (index.isCacheStale()) {
+                console.log('Source changed; rebuilding index...');
+                index.build(null, {
+                    quiet: true,
+                    forceRebuild: true,
+                    followSymlinks: flags.followSymlinks,
+                    maxFiles: flags.maxFiles,
+                    workers: flags.workers,
+                });
+                if (flags.cache) {
+                    try { index.saveCache(); } catch (_) { /* best-effort */ }
+                }
+                console.log(`Index ready: ${index.files.size} files, ${index.symbols.size} unique symbol names`);
+            }
             const iCanonical = resolveCommand(command, 'cli') || command;
-            executeInteractiveCommand(index, iCanonical, arg, iflags, iExpandCache);
+            executeInteractiveCommand(index, iCanonical, arg, iflags);
         } catch (e) {
             if (e instanceof FlagValidationError) {
                 console.log(e.message);
@@ -1838,222 +1079,26 @@ Flags can be added per-command: context myFunc --include-methods
     });
 }
 
-// parseInteractiveFlags removed — both global and interactive mode now use parseFlags()
-
-// ── Data-driven interactive command dispatch ─────────────────────────────
-//
-// Each entry maps a canonical command name to:
-//   params: (arg, iflags) => execute() params object
-//   format: (result, arg, iflags, index) => formatted string
-//
-// The generic handler calls execute(), checks errors, prints notes, and
-// formats the result. Only commands with truly unique behavior (expand
-// cache save, file writing, conditional formatters) keep explicit cases.
-
-const INTERACTIVE_DISPATCH = {
-    // ── Understanding Code ───────────────────────────────────────────
-    about:        { params: 'name', format: (r, _a, f, idx) => output.formatAbout(r, { expand: f.expand, root: idx.root, showAll: f.all, depth: f.depth, showConfidence: f.showConfidence !== false, compact: !!f.compact, git: !!f.git }) },
-    smart:        { params: 'name', format: (r) => output.formatSmart(r, { uncertainHint: 'unverified callees are listed below with reasons' }) },
-    impact:       { params: 'name', format: (r, _a, f) => output.formatImpact(r, { compact: !!f.compact }) },
-    blast:        { params: 'name', format: (r) => output.formatBlast(r) },
-    trace:        { params: 'name', format: (r) => output.formatTrace(r) },
-    reverseTrace: { params: 'name', format: (r) => output.formatReverseTrace(r) },
-    related:      { params: 'name', format: (r, _a, f) => output.formatRelated(r, { all: f.all, top: f.top }) },
-    example:      { params: (a, f) => ({ name: a, file: f.file, className: f.className, diverse: f.diverse, top: f.top || undefined, includeTests: f.includeTests }), format: (r, a) => output.formatExample(r, a) },
-    brief:        { params: 'name', format: (r) => output.formatBrief(r) },
-
-    // ── Finding Code ─────────────────────────────────────────────────
-    find:          { params: 'name', format: (r, a, f) => output.formatFindDetailed(r, a, { depth: f.depth, top: f.top, all: f.all }) },
-    usages:        { params: 'name', format: (r, a, f) => output.formatUsages(r, a, { compact: !!f.compact }) },
-    toc:           { params: 'flags', format: (r) => output.formatToc(r, { detailedHint: 'Add --detailed to list all functions, or "about <name>" for full details on a symbol', uncertainHint: 'run "about <name>" for tiered detail on a specific symbol' }) },
-    tests:         { params: 'name', format: (r, a) => output.formatTests(r, a) },
-    affectedTests: { params: 'name', format: (r, _a, f) => output.formatAffectedTests(r, { all: f.all }) },
-    typedef:       { params: 'name', format: (r, a) => output.formatTypedef(r, a) },
-
-    // ── File Dependencies ────────────────────────────────────────────
-    imports:      { params: 'file', format: (r, a, f) => output.formatImports(r, a || f.file) },
-    exporters:    { params: 'file', format: (r, a, f) => output.formatExporters(r, a || f.file) },
-    fileExports:  { params: 'file', format: (r, a, f) => output.formatFileExports(r, a || f.file) },
-    graph:        { params: (a, f) => ({ file: a || f.file, direction: f.direction, depth: f.depth, all: f.all }), format: (r, a, f) => { const d = f.depth ? parseInt(f.depth) : 2; return output.formatGraph(r, { showAll: f.all || !!f.depth, maxDepth: d, file: a || f.file }); } },
-    circularDeps: { params: (a, f) => ({ file: f.file, exclude: f.exclude }), format: (r) => output.formatCircularDeps(r) },
-
-    // ── Refactoring Helpers ──────────────────────────────────────────
-    plan:         { params: 'name', format: (r) => output.formatPlan(r) },
-    verify:       { params: 'name', format: (r) => output.formatVerify(r) },
-    diffImpact:   { params: (a, f) => ({ base: f.base, staged: f.staged, file: f.file, limit: f.limit, all: f.all }), format: (r, _a, f) => output.formatDiffImpact(r, { all: f.all }) },
-    check:        { params: (a, f) => ({ base: f.base, staged: f.staged, file: f.file, limit: f.limit }), format: (r) => output.formatCheck(r) },
-    entrypoints:  { params: (a, f) => ({ type: f.type, framework: f.framework, file: f.file, exclude: f.exclude, includeTests: f.includeTests, excludeTests: f.excludeTests, limit: f.limit }), format: (r) => output.formatEntrypoints(r) },
-    endpoints:    { params: (a, f) => ({ file: f.file, exclude: f.exclude, limit: f.limit, framework: f.framework, bridge: f.bridge, serverOnly: f.serverOnly, clientOnly: f.clientOnly, unmatched: f.unmatched, method: f.method, prefix: f.prefix, hideUncertain: f.hideUncertain }), format: (r) => output.formatEndpoints(r, { bridge: r._bridge, unmatched: r._unmatched }) },
-
-    // ── Other ────────────────────────────────────────────────────────
-    api:          { params: (a, f) => ({ file: a || f.file, limit: f.limit }), format: (r, a, f) => output.formatApi(r, a || f.file) },
-    stacktrace:   { params: (a, f) => ({ stack: f.stack || a }), format: (r) => output.formatStackTrace(r) },
-    doctor:       { params: (a, f) => ({ file: f.file, in: f.in, limit: f.limit, deep: f.deep }), format: (r) => output.formatDoctor(r) },
-    orient:       { params: (a, f) => ({ top: f.topRaw != null ? f.topRaw : (f.top || undefined) }), format: (r) => output.formatOrient(r) },
-    // MED-2: stats handler in execute.js rejects top<=0; without explicit
-    // coercion, parseFlags's `top: 0` default would surface as
-    // "Invalid --top value" on bare `stats`. Mirror the project-mode top
-    // coercion (topRaw when present, else undefined for default-10).
-    stats:        { params: (a, f) => ({ functions: f.functions, hot: f.hot, top: f.topRaw != null ? f.topRaw : (f.top || undefined) }), format: (r, _a, f) => output.formatStats(r, { top: f.top }) },
-    auditAsync:   { params: (a, f) => ({ file: f.file, exclude: f.exclude, limit: f.limit }), format: (r) => output.formatAuditAsync(r) },
-};
-
-/**
- * Build execute() params from a dispatch entry's params descriptor.
- *   'name'  → { name: arg, ...iflags }
- *   'file'  → { file: arg }
- *   'flags' → iflags (no arg)
- *   function → custom builder
- */
-function buildInteractiveParams(descriptor, arg, iflags) {
-    if (typeof descriptor === 'function') return descriptor(arg, iflags);
-    switch (descriptor) {
-        case 'name':  return { name: arg, ...iflags };
-        case 'file':  return { file: arg || iflags.file };
-        case 'flags': return iflags;
-        default:      return { name: arg, ...iflags };
-    }
-}
+function executeInteractiveCommand(index, command, arg, iflags = {}) {
+    warnInapplicableFlags(command, iflags, (message) => console.log(message));
 
-function executeInteractiveCommand(index, command, arg, iflags = {}, cache = null) {
-    // Warn about inapplicable flags (same check as project mode)
-    const applicableFlags = FLAG_APPLICABILITY[command];
-    if (applicableFlags) {
-        const flagToCli = (f) => '--' + f.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
-        const globalFlags = new Set(['json', 'quiet', 'cache', 'clearCache', 'followSymlinks', 'maxFiles', 'verbose', 'expand', 'interactive', '_fileFromFileMode', 'topRaw', 'limitRaw', 'maxFilesRaw', 'maxLinesRaw', 'depthRaw', 'contextRaw', 'workersRaw']);
-        for (const [key, value] of Object.entries(iflags)) {
-            if (globalFlags.has(key)) continue;
-            if (value === undefined || value === null || value === 0 || (Array.isArray(value) && value.length === 0)) continue;
-            if (!applicableFlags.includes(key)) {
-                console.log(`Warning: ${flagToCli(key)} has no effect on '${command}'.`);
-            }
-        }
-        // Tiered-output contract notes (fix #250 — one-shot mode printed
-        // these; interactive silently accepted the flags).
-        printTieredNoOpNotes(command, iflags, (m) => console.log(m));
+    if (!isPublicCommand(command)) {
+        console.log(unknownCommandMessage(command, { interactive: true }));
+        return;
     }
-
-    // ── Commands with unique behavior (not data-driven) ──────────────
-    switch (command) {
-
-        case 'fn': {
-            if (!arg) { console.log('Usage: fn <name>[,name2,...] [--file=<pattern>] [--class-name=<class>]'); return; }
-            const { ok, result, error, note } = execute(index, 'fn', { name: arg, file: iflags.file, all: iflags.all, className: iflags.className, line: iflags.line });
-            if (!ok) { console.log(error); return; }
-            console.log(output.formatFnResult(result));
-            if (note) console.log(note);
-            break;
-        }
-
-        case 'class': {
-            if (!arg) { console.log('Usage: class <name> [--file=<pattern>]'); return; }
-            const { ok, result, error, note } = execute(index, 'class', { name: arg, file: iflags.file, all: iflags.all, maxLines: iflags.maxLines, line: iflags.line });
-            if (!ok) { console.log(error); return; }
-            console.log(output.formatClassResult(result));
-            if (note) console.log(note);
-            break;
-        }
-
-        case 'lines': {
-            if (!arg) { console.log('Usage: lines <range> --file=<file> (or: lines <file> <range>)'); return; }
-            const iLinesTarget = parseLinesTarget(arg, iflags.file);
-            const { ok, result, error } = execute(index, 'lines', { file: iLinesTarget.file, range: iLinesTarget.range });
-            if (!ok) { console.log(error); return; }
-            console.log(output.formatLines(result));
-            break;
-        }
-
-        case 'expand': {
-            if (!arg) {
-                console.log('Usage: expand <number>');
-                return;
-            }
-            // Whole-token integers only (fix #248: parseInt truncation).
-            if (!/^\d+$/.test(String(arg).trim())) {
-                console.log(`Invalid item number: "${arg}"`);
-                return;
-            }
-            const expandNum = parseInt(arg, 10);
-            let match, itemCount, symbolName;
-            if (cache) {
-                const lookup = cache.lookup(index.root, expandNum);
-                match = lookup.match;
-                itemCount = lookup.itemCount;
-                symbolName = lookup.symbolName;
-            } else {
-                const cached = loadExpandableItems(index.root);
-                const items = cached?.items || [];
-                match = items.find(i => i.num === expandNum);
-                itemCount = items.length;
-            }
-            const { ok, result, error } = execute(index, 'expand', {
-                match, itemNum: expandNum, itemCount, symbolName, validateRoot: true
-            });
-            if (!ok) { console.log(error); return; }
-            console.log(result.text);
-            break;
-        }
-
-        case 'context': {
-            const { ok, result, error, note } = execute(index, 'context', { name: arg, ...iflags });
-            if (!ok) { console.log(error); return; }
-            const { text, expandable } = output.formatContext(result, {
-                expandHint: 'Use "expand <N>" to see code for item N',
-                showConfidence: iflags.showConfidence !== false,
-                compact: !!iflags.compact,
-            });
-            console.log(text);
-            if (iflags.expand) {
-                printInlineExpand(result, index.root);
-            }
-            if (note) console.log(note);
-            if (cache) {
-                cache.save(index.root, arg, iflags.file, expandable);
-            } else {
-                saveExpandableItems(expandable, index.root);
-            }
-            break;
-        }
-
-        case 'deadcode': {
-            const { ok, result, error, note } = execute(index, 'deadcode', iflags);
-            if (!ok) { console.log(error); return; }
-            console.log(output.formatDeadcode(result, {
-                top: iflags.top,
-                decoratedHint: !iflags.includeDecorated && result.excludedDecorated > 0 ? `${result.excludedDecorated} decorated/annotated symbol(s) hidden (framework-registered). Use --include-decorated to include them.` : undefined,
-                exportedHint: !iflags.includeExported && result.excludedExported > 0 ? `${result.excludedExported} exported symbol(s) excluded from the audit (public API may have external callers). Use --include-exported to audit them.` : undefined,
-                externalContractHint: !iflags.includeExported && result.excludedExternalContract > 0 ? `${result.excludedExternalContract} symbol(s) hidden (override an out-of-tree base class — reachable via external contract, not dead). Use --include-exported to include them.` : undefined
-            }));
-            if (note) console.log(note);
-            break;
-        }
-
-        case 'search': {
-            const { ok, result, error, structural, note } = execute(index, 'search', { term: arg, ...iflags });
-            if (!ok) { console.log(error); return; }
-            if (structural) {
-                console.log(output.formatStructuralSearch(result));
-            } else {
-                console.log(output.formatSearch(result, arg));
-            }
-            if (note) console.log(note);
-            break;
-        }
-
-        default: {
-            // ── Data-driven dispatch for standard commands ────────────
-            const entry = INTERACTIVE_DISPATCH[command];
-            if (!entry) {
-                console.log(`Unknown command: ${command}. Type "help" for available commands.`);
-                return;
-            }
-            const params = buildInteractiveParams(entry.params, arg, iflags);
-            const { ok, result, error, note } = execute(index, command, params);
-            if (!ok) { console.log(error); return; }
-            console.log(entry.format(result, arg, iflags, index));
-            if (note) console.log(note);
-        }
+    const publicParams = buildPublicParams(command, arg, iflags);
+    const publicExecution = execute(index, command, publicParams);
+    if (!publicExecution.ok) {
+        console.log(formatSurfaceMessage(publicExecution.error, 'cli'));
+        return;
     }
+    console.log(formatCliText(
+        command,
+        publicExecution.result,
+        publicParams,
+        publicExecution,
+        iflags,
+    ));
 }
 
 // ============================================================================