@cleocode/cleo 2026.4.158 → 2026.5.0

package/dist/cli/commands/nexus.js

@@ -0,0 +1,3377 @@
+/**
+ * CLI nexus command group - Cross-project NEXUS operations.
+ *
+ * Thin CLI wrappers routing through the dispatch layer.
+ * All business logic lives in src/dispatch/domains/nexus.ts.
+ *
+ * `nexus analyze` is implemented directly here because it requires
+ * `@cleocode/nexus` pipeline access and `@cleocode/core` DB access together,
+ * and routing through the dispatch layer would create awkward coupling.
+ *
+ * @task T4554, T5323, T5330, T481, T534
+ * @epic T4545
+ */
+import path from 'node:path';
+import { generateGexf, getSymbolImpact } from '@cleocode/core/nexus';
+import { defineCommand, showUsage } from 'citty';
+import { dispatchFromCli, dispatchRaw } from '../../dispatch/adapters/cli.js';
+// ── Subcommand definitions ───────────────────────────────────────────────────
+/** cleo nexus init — initialize NEXUS directory structure and registry */
+const initCommand = defineCommand({
+    meta: { name: 'init', description: 'Initialize NEXUS directory structure and registry' },
+    async run() {
+        await dispatchFromCli('mutate', 'nexus', 'init', {}, { command: 'nexus' });
+    },
+});
+/** cleo nexus register — register a project in the global registry */
+const registerCommand = defineCommand({
+    meta: { name: 'register', description: 'Register a project in the global registry' },
+    args: {
+        path: {
+            type: 'positional',
+            description: 'Path to the project directory',
+            required: true,
+        },
+        name: {
+            type: 'string',
+            description: 'Custom project name (default: directory name)',
+        },
+        permissions: {
+            type: 'string',
+            description: 'Permissions: read|write|execute',
+            default: 'read',
+        },
+    },
+    async run({ args }) {
+        await dispatchFromCli('mutate', 'nexus', 'register', {
+            path: args.path,
+            name: args.name,
+            permission: args.permissions,
+        }, { command: 'nexus' });
+    },
+});
+/** cleo nexus unregister — remove a project from the registry */
+const unregisterCommand = defineCommand({
+    meta: { name: 'unregister', description: 'Remove a project from the registry' },
+    args: {
+        nameOrHash: {
+            type: 'positional',
+            description: 'Project name or hash to unregister',
+            required: true,
+        },
+    },
+    async run({ args }) {
+        await dispatchFromCli('mutate', 'nexus', 'unregister', { name: args.nameOrHash }, { command: 'nexus' });
+    },
+});
+/** cleo nexus list — list all registered projects */
+const listCommand = defineCommand({
+    meta: { name: 'list', description: 'List all registered projects' },
+    async run() {
+        await dispatchFromCli('query', 'nexus', 'list', {}, { command: 'nexus' });
+    },
+});
+/** cleo nexus status — show code intelligence index freshness */
+const statusCommand = defineCommand({
+    meta: {
+        name: 'status',
+        description: 'Show code intelligence index freshness: file count, node/relation counts, last indexed time, stale files. Falls back to NEXUS registry status if code-intelligence index is unavailable.',
+    },
+    args: {
+        path: {
+            type: 'positional',
+            description: 'Path to the project directory (default: cwd)',
+            required: false,
+        },
+        'project-id': {
+            type: 'string',
+            description: 'Override the project ID (default: auto-detected from path)',
+        },
+        json: {
+            type: 'boolean',
+            description: 'Output as JSON (LAFS envelope format)',
+        },
+    },
+    async run({ args }) {
+        const jsonOutput = !!args.json;
+        const projectIdOverride = args['project-id'];
+        const repoPath = args.path ? path.resolve(args.path) : process.cwd();
+        const startTime = Date.now();
+        try {
+            // SSoT-EXEMPT:status-index-stats — getIndexStats requires direct pipeline access
+            // with db handle + table refs; no dispatch op exposes this level of detail.
+            // Dispatch 'nexus.status' is used as fallback on error (see catch block).
+            const [{ getNexusDb, nexusSchema }, { getIndexStats }] = await Promise.all([
+                import('@cleocode/core/store/nexus-sqlite'),
+                import('@cleocode/nexus/pipeline'),
+            ]);
+            const projectId = projectIdOverride ?? Buffer.from(repoPath).toString('base64url').slice(0, 32);
+            const db = await getNexusDb();
+            const tables = {
+                nexusNodes: nexusSchema.nexusNodes,
+                nexusRelations: nexusSchema.nexusRelations,
+            };
+            const stats = await getIndexStats(projectId, repoPath, db, tables);
+            const durationMs = Date.now() - startTime;
+            if (jsonOutput) {
+                const envelope = {
+                    success: true,
+                    data: { projectId, repoPath, ...stats },
+                    meta: {
+                        operation: 'nexus.status',
+                        duration_ms: durationMs,
+                        timestamp: new Date().toISOString(),
+                    },
+                };
+                process.stdout.write(JSON.stringify(envelope, null, 2) + '\n');
+            }
+            else if (!stats.indexed) {
+                process.stdout.write(`[nexus] Index status for: ${repoPath}\n` +
+                    `  Status:     NOT INDEXED\n` +
+                    `  Run 'cleo nexus analyze' to build the index.\n`);
+            }
+            else {
+                const staleLabel = stats.staleFileCount < 0
+                    ? 'unknown'
+                    : stats.staleFileCount === 0
+                        ? 'up to date'
+                        : `${stats.staleFileCount} stale`;
+                process.stdout.write(`[nexus] Index status for: ${repoPath}\n` +
+                    `  Project ID:   ${projectId}\n` +
+                    `  Nodes:        ${stats.nodeCount}\n` +
+                    `  Relations:    ${stats.relationCount}\n` +
+                    `  Files:        ${stats.fileCount}\n` +
+                    `  Last indexed: ${stats.lastIndexedAt ?? 'never'}\n` +
+                    `  Staleness:    ${staleLabel}\n`);
+            }
+        }
+        catch (err) {
+            // Fall back to NEXUS registry status on error
+            const msg = err instanceof Error ? err.message : String(err);
+            if (jsonOutput) {
+                process.stdout.write(JSON.stringify({
+                    success: false,
+                    error: { code: 'E_STATUS_FAILED', message: msg },
+                    meta: {
+                        operation: 'nexus.status',
+                        duration_ms: Date.now() - startTime,
+                        timestamp: new Date().toISOString(),
+                    },
+                }, null, 2) + '\n');
+            }
+            else {
+                process.stderr.write(`[nexus] Error: ${msg}\n`);
+                await dispatchFromCli('query', 'nexus', 'status', {}, { command: 'nexus' });
+            }
+            process.exitCode = 1;
+        }
+    },
+});
+/** cleo nexus show — show details for a registered project by name */
+const showCommand = defineCommand({
+    meta: { name: 'show', description: 'Show details for a registered project by name' },
+    args: {
+        name: {
+            type: 'positional',
+            description: 'Project name',
+            required: true,
+        },
+    },
+    async run({ args }) {
+        await dispatchFromCli('query', 'nexus', 'show', { name: args.name }, { command: 'nexus' });
+    },
+});
+/** cleo nexus resolve — resolve a task reference across projects */
+const resolveCommand = defineCommand({
+    meta: {
+        name: 'resolve',
+        description: 'Resolve a task reference across projects (project:T### or T###)',
+    },
+    args: {
+        taskRef: {
+            type: 'positional',
+            description: 'Task reference to resolve',
+            required: true,
+        },
+    },
+    async run({ args }) {
+        await dispatchFromCli('query', 'nexus', 'resolve', { query: args.taskRef }, { command: 'nexus' });
+    },
+});
+/** cleo nexus discover — find related tasks across projects */
+const discoverCommand = defineCommand({
+    meta: { name: 'discover', description: 'Find related tasks across projects' },
+    args: {
+        taskQuery: {
+            type: 'positional',
+            description: 'Task query string',
+            required: true,
+        },
+        method: {
+            type: 'string',
+            description: 'Discovery method: labels|description|files|auto',
+            default: 'auto',
+        },
+        limit: {
+            type: 'string',
+            description: 'Max results',
+            default: '10',
+        },
+    },
+    async run({ args }) {
+        await dispatchFromCli('query', 'nexus', 'discover', {
+            query: args.taskQuery,
+            method: args.method,
+            limit: parseInt(args.limit, 10),
+        }, { command: 'nexus' });
+    },
+});
+/**
+ * cleo nexus augment — Symbol context augmentation for PreToolUse hooks.
+ *
+ * BM25-only search against nexus_nodes for pattern, returns top N symbols
+ * with callers/callees/community metadata as plain text suitable for hook injection.
+ *
+ * @task T1061
+ * @epic T1042
+ */
+const augmentCommand = defineCommand({
+    meta: {
+        name: 'augment',
+        description: 'Augment symbol pattern with code context (for PreToolUse hooks)',
+    },
+    args: {
+        pattern: {
+            type: 'positional',
+            description: 'Symbol name or file pattern to search',
+            required: true,
+        },
+        limit: {
+            type: 'string',
+            description: 'Max results to return (default: 5)',
+            default: '5',
+        },
+    },
+    async run({ args }) {
+        const pattern = args.pattern;
+        const limit = parseInt(args.limit, 10) || 5;
+        await dispatchFromCli('query', 'nexus', 'augment', {
+            pattern,
+            limit,
+        }, { command: 'nexus' });
+    },
+});
+/**
+ * cleo nexus setup — Install PreToolUse hook augmenter
+ *
+ * Writes ~/.cleo/hooks/nexus-augment.sh and registers it in CAAMP config.
+ *
+ * @task T1061
+ * @epic T1042
+ */
+const setupCommand = defineCommand({
+    meta: {
+        name: 'setup',
+        description: 'Install Nexus PreToolUse hook augmenter',
+    },
+    args: {},
+    async run() {
+        try {
+            // SSoT-EXEMPT:cli-install — installs filesystem hook, not a domain operation.
+            // Hook installation writes shell scripts to disk and cannot be a LAFS dispatch op.
+            const { homedir } = await import('node:os');
+            const { installNexusAugmentHook } = await import('@cleocode/core/internal');
+            const homeDir = homedir();
+            installNexusAugmentHook(homeDir);
+            process.stdout.write(`[nexus] Installed PreToolUse hook at ${homeDir}/.cleo/hooks/nexus-augment.sh\n`);
+            process.stdout.write(`[nexus] Hook will inject symbol context into Grep/Glob/Read tool calls\n`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[nexus setup] Error: ${msg}\n`);
+            process.exitCode = 1;
+        }
+    },
+});
+/** cleo nexus search — search tasks across projects by pattern */
+const searchCommand = defineCommand({
+    meta: { name: 'search', description: 'Search tasks across projects by pattern' },
+    args: {
+        pattern: {
+            type: 'positional',
+            description: 'Search pattern',
+            required: true,
+        },
+        project: {
+            type: 'string',
+            description: 'Limit search to specific project',
+        },
+        limit: {
+            type: 'string',
+            description: 'Max results',
+            default: '20',
+        },
+    },
+    async run({ args }) {
+        await dispatchFromCli('query', 'nexus', 'search', {
+            pattern: args.pattern,
+            project: args.project,
+            limit: parseInt(args.limit, 10),
+        }, { command: 'nexus' });
+    },
+});
+/** cleo nexus deps — show cross-project dependencies */
+const depsCommand = defineCommand({
+    meta: { name: 'deps', description: 'Show cross-project dependencies' },
+    args: {
+        taskQuery: {
+            type: 'positional',
+            description: 'Task query string',
+            required: true,
+        },
+        reverse: {
+            type: 'boolean',
+            description: 'Show reverse dependencies (what depends on this)',
+        },
+    },
+    async run({ args }) {
+        await dispatchFromCli('query', 'nexus', 'deps', {
+            query: args.taskQuery,
+            direction: args.reverse ? 'reverse' : 'forward',
+        }, { command: 'nexus' });
+    },
+});
+/** cleo nexus critical-path — show global critical path across all registered projects */
+const criticalPathCommand = defineCommand({
+    meta: {
+        name: 'critical-path',
+        description: 'Show global critical path across all registered projects',
+    },
+    async run() {
+        await dispatchFromCli('query', 'nexus', 'path.show', {}, { command: 'nexus' });
+    },
+});
+/** cleo nexus blocking — show blocking impact analysis for a task */
+const blockingCommand = defineCommand({
+    meta: { name: 'blocking', description: 'Show blocking impact analysis for a task' },
+    args: {
+        taskQuery: {
+            type: 'positional',
+            description: 'Task query string',
+            required: true,
+        },
+    },
+    async run({ args }) {
+        await dispatchFromCli('query', 'nexus', 'blockers.show', { query: args.taskQuery }, { command: 'nexus' });
+    },
+});
+/** cleo nexus orphans — detect broken cross-project dependency references */
+const orphansCommand = defineCommand({
+    meta: { name: 'orphans', description: 'Detect broken cross-project dependency references' },
+    async run() {
+        await dispatchFromCli('query', 'nexus', 'orphans.list', {}, { command: 'nexus' });
+    },
+});
+/** cleo nexus sync — sync project metadata (task count, labels) */
+const syncCommand = defineCommand({
+    meta: { name: 'sync', description: 'Sync project metadata (task count, labels)' },
+    args: {
+        project: {
+            type: 'positional',
+            description: 'Project name to sync (default: all)',
+            required: false,
+        },
+    },
+    async run({ args }) {
+        if (args.project) {
+            await dispatchFromCli('mutate', 'nexus', 'sync', { name: args.project }, { command: 'nexus' });
+        }
+        else {
+            await dispatchFromCli('mutate', 'nexus', 'sync', {}, { command: 'nexus' });
+        }
+    },
+});
+/** cleo nexus reconcile — reconcile current project with NEXUS registry */
+const reconcileCommand = defineCommand({
+    meta: {
+        name: 'reconcile',
+        description: 'Reconcile current project with NEXUS registry (auto-register if new, update path if moved)',
+    },
+    args: {
+        path: {
+            type: 'string',
+            description: 'Project path (default: current directory)',
+        },
+    },
+    async run({ args }) {
+        await dispatchFromCli('mutate', 'nexus', 'reconcile', { projectRoot: args.path }, { command: 'nexus' });
+    },
+});
+/** cleo nexus graph — show full dependency graph across all registered projects */
+const graphCommand = defineCommand({
+    meta: { name: 'graph', description: 'Show full dependency graph across all registered projects' },
+    async run() {
+        await dispatchFromCli('query', 'nexus', 'graph', {}, { command: 'nexus' });
+    },
+});
+/** cleo nexus share-status — show multi-contributor sharing status */
+const shareStatusCommand = defineCommand({
+    meta: {
+        name: 'share-status',
+        description: 'Show multi-contributor sharing status for the current project',
+    },
+    async run() {
+        await dispatchFromCli('query', 'nexus', 'share.status', {}, { command: 'nexus' });
+    },
+});
+/** cleo nexus transfer-preview — preview a task transfer between projects */
+const transferPreviewCommand = defineCommand({
+    meta: {
+        name: 'transfer-preview',
+        description: 'Preview a task transfer between projects (dry-run, no changes made)',
+    },
+    args: {
+        taskIds: {
+            type: 'positional',
+            description: 'Task IDs to preview transfer for',
+            required: true,
+        },
+        from: {
+            type: 'string',
+            description: 'Source project name',
+            required: true,
+        },
+        to: {
+            type: 'string',
+            description: 'Target project name',
+            required: true,
+        },
+        mode: {
+            type: 'string',
+            description: 'Transfer mode: copy|move',
+            default: 'copy',
+        },
+        scope: {
+            type: 'string',
+            description: 'Transfer scope: single|subtree',
+            default: 'subtree',
+        },
+    },
+    async run({ args }) {
+        await dispatchFromCli('query', 'nexus', 'transfer.preview', {
+            taskIds: args.taskIds.split(',').map((s) => s.trim()),
+            sourceProject: args.from,
+            targetProject: args.to,
+            mode: args.mode,
+            scope: args.scope,
+        }, { command: 'nexus' });
+    },
+});
+/** cleo nexus transfer — transfer tasks from one project to another */
+const transferCommand = defineCommand({
+    meta: { name: 'transfer', description: 'Transfer tasks from one project to another' },
+    args: {
+        taskIds: {
+            type: 'positional',
+            description: 'Task IDs to transfer',
+            required: true,
+        },
+        from: {
+            type: 'string',
+            description: 'Source project name',
+            required: true,
+        },
+        to: {
+            type: 'string',
+            description: 'Target project name',
+            required: true,
+        },
+        mode: {
+            type: 'string',
+            description: 'Transfer mode: copy|move',
+            default: 'copy',
+        },
+        scope: {
+            type: 'string',
+            description: 'Transfer scope: single|subtree',
+            default: 'subtree',
+        },
+        'on-conflict': {
+            type: 'string',
+            description: 'Conflict strategy: rename|skip|duplicate|fail',
+            default: 'rename',
+        },
+        'transfer-brain': {
+            type: 'boolean',
+            description: 'Also transfer associated brain memory entries',
+        },
+    },
+    async run({ args }) {
+        await dispatchFromCli('mutate', 'nexus', 'transfer', {
+            taskIds: args.taskIds.split(',').map((s) => s.trim()),
+            sourceProject: args.from,
+            targetProject: args.to,
+            mode: args.mode,
+            scope: args.scope,
+            onConflict: args['on-conflict'],
+            transferBrain: args['transfer-brain'],
+        }, { command: 'nexus' });
+    },
+});
+/** cleo nexus permission set — set permission level for a registered project */
+const permissionSetCommand = defineCommand({
+    meta: {
+        name: 'set',
+        description: 'Set permission level for a registered project (read|write|execute)',
+    },
+    args: {
+        name: {
+            type: 'positional',
+            description: 'Project name',
+            required: true,
+        },
+        level: {
+            type: 'positional',
+            description: 'Permission level: read|write|execute',
+            required: true,
+        },
+    },
+    async run({ args }) {
+        await dispatchFromCli('mutate', 'nexus', 'permission.set', { name: args.name, level: args.level }, { command: 'nexus' });
+    },
+});
+/** cleo nexus permission — manage permissions for registered projects */
+const permissionCommand = defineCommand({
+    meta: { name: 'permission', description: 'Manage permissions for registered projects' },
+    subCommands: {
+        set: permissionSetCommand,
+    },
+});
+/** cleo nexus share export — export a snapshot of current project state */
+const shareExportCommand = defineCommand({
+    meta: { name: 'export', description: 'Export a snapshot of current project state for sharing' },
+    args: {
+        output: {
+            type: 'string',
+            description: 'Output file path (default: auto-generated in current directory)',
+        },
+    },
+    async run({ args }) {
+        await dispatchFromCli('mutate', 'nexus', 'share.snapshot.export', { outputPath: args.output }, { command: 'nexus' });
+    },
+});
+/** cleo nexus share import — import a shared project snapshot */
+const shareImportCommand = defineCommand({
+    meta: { name: 'import', description: 'Import a shared project snapshot' },
+    args: {
+        file: {
+            type: 'positional',
+            description: 'Path to snapshot file',
+            required: true,
+        },
+    },
+    async run({ args }) {
+        await dispatchFromCli('mutate', 'nexus', 'share.snapshot.import', { inputPath: args.file }, { command: 'nexus' });
+    },
+});
+/** cleo nexus share — multi-contributor sharing operations */
+const shareCommand = defineCommand({
+    meta: { name: 'share', description: 'Multi-contributor sharing operations' },
+    subCommands: {
+        export: shareExportCommand,
+        import: shareImportCommand,
+    },
+});
+/** cleo nexus clusters — list all detected communities from the last analysis */
+const clustersCommand = defineCommand({
+    meta: {
+        name: 'clusters',
+        description: 'List all detected communities (Louvain clusters) from the last analysis',
+    },
+    args: {
+        path: {
+            type: 'positional',
+            description: 'Path to project directory (default: cwd)',
+            required: false,
+        },
+        json: {
+            type: 'boolean',
+            description: 'Output result as JSON (LAFS envelope format)',
+        },
+        'project-id': {
+            type: 'string',
+            description: 'Override the project ID (default: auto-detected from path)',
+        },
+    },
+    async run({ args }) {
+        const startTime = Date.now();
+        const jsonOutput = !!args.json;
+        const projectIdOverride = args['project-id'];
+        const repoPath = args.path ? path.resolve(args.path) : process.cwd();
+        const projectId = projectIdOverride ?? Buffer.from(repoPath).toString('base64url').slice(0, 32);
+        const response = await dispatchRaw('query', 'nexus', 'clusters', { projectId, repoPath });
+        const durationMs = Date.now() - startTime;
+        if (!response.success) {
+            const msg = response.error?.message ?? 'Unknown error';
+            if (jsonOutput) {
+                process.stdout.write(JSON.stringify({
+                    success: false,
+                    error: { code: response.error?.code ?? 'E_CLUSTERS_FAILED', message: msg },
+                    meta: {
+                        operation: 'nexus.clusters',
+                        duration_ms: durationMs,
+                        timestamp: new Date().toISOString(),
+                    },
+                }, null, 2) + '\n');
+            }
+            else {
+                process.stderr.write(`[nexus] Error: ${msg}\n`);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        const result = response.data;
+        if (jsonOutput) {
+            process.stdout.write(JSON.stringify({
+                success: true,
+                data: result,
+                meta: {
+                    operation: 'nexus.clusters',
+                    duration_ms: durationMs,
+                    timestamp: new Date().toISOString(),
+                },
+            }, null, 2) + '\n');
+        }
+        else if (result.communities.length === 0) {
+            process.stdout.write(`[nexus] No communities found for project ${projectId}.\n  Run 'cleo nexus analyze' first.\n`);
+        }
+        else {
+            process.stdout.write(`[nexus] Communities for project ${projectId} (${result.communities.length} total):\n`);
+            for (const c of result.communities) {
+                const cohesion = typeof c.cohesion === 'number' ? c.cohesion.toFixed(3) : '0.000';
+                process.stdout.write(`  ${String(c.id).padEnd(16)}  label=${String(c.label ?? '').padEnd(24)}  symbols=${String(c.symbolCount).padStart(5)}  cohesion=${cohesion}\n`);
+            }
+        }
+    },
+});
+/** cleo nexus flows — list all detected execution flows from the last analysis */
+const flowsCommand = defineCommand({
+    meta: {
+        name: 'flows',
+        description: 'List all detected execution flows (processes) from the last analysis',
+    },
+    args: {
+        path: {
+            type: 'positional',
+            description: 'Path to project directory (default: cwd)',
+            required: false,
+        },
+        json: { type: 'boolean', description: 'Output result as JSON (LAFS envelope format)' },
+        'project-id': {
+            type: 'string',
+            description: 'Override the project ID (default: auto-detected from path)',
+        },
+    },
+    async run({ args }) {
+        const startTime = Date.now();
+        const jsonOutput = !!args.json;
+        const projectIdOverride = args['project-id'];
+        const repoPath = args.path ? path.resolve(args.path) : process.cwd();
+        const projectId = projectIdOverride ?? Buffer.from(repoPath).toString('base64url').slice(0, 32);
+        const response = await dispatchRaw('query', 'nexus', 'flows', { projectId, repoPath });
+        const durationMs = Date.now() - startTime;
+        if (!response.success) {
+            const msg = response.error?.message ?? 'Unknown error';
+            if (jsonOutput) {
+                process.stdout.write(JSON.stringify({
+                    success: false,
+                    error: { code: response.error?.code ?? 'E_FLOWS_FAILED', message: msg },
+                    meta: {
+                        operation: 'nexus.flows',
+                        duration_ms: durationMs,
+                        timestamp: new Date().toISOString(),
+                    },
+                }, null, 2) + '\n');
+            }
+            else {
+                process.stderr.write(`[nexus] Error: ${msg}\n`);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        const result = response.data;
+        if (jsonOutput) {
+            process.stdout.write(JSON.stringify({
+                success: true,
+                data: result,
+                meta: {
+                    operation: 'nexus.flows',
+                    duration_ms: durationMs,
+                    timestamp: new Date().toISOString(),
+                },
+            }, null, 2) + '\n');
+        }
+        else if (result.flows.length === 0) {
+            process.stdout.write(`[nexus] No execution flows found for project ${projectId}.\n  Run 'cleo nexus analyze' first.\n`);
+        }
+        else {
+            process.stdout.write(`[nexus] Execution flows for project ${projectId} (${result.flows.length} total):\n`);
+            for (const p of result.flows) {
+                const processType = p.processType.replace('_community', '');
+                process.stdout.write(`  ${String(p.id).padEnd(30)}  steps=${String(p.stepCount).padStart(3)}  type=${processType.padEnd(12)}  ${String(p.label ?? '')}\n`);
+            }
+        }
+    },
+});
+/** cleo nexus context — show callers, callees, community membership, and process participation */
+const contextCommand = defineCommand({
+    meta: {
+        name: 'context',
+        description: 'Show callers, callees, community membership, and process participation for a code symbol',
+    },
+    args: {
+        symbol: { type: 'positional', description: 'Symbol name to look up', required: true },
+        json: { type: 'boolean', description: 'Output result as JSON (LAFS envelope format)' },
+        'project-id': {
+            type: 'string',
+            description: 'Override the project ID (default: auto-detected from cwd)',
+        },
+        limit: { type: 'string', description: 'Max callers/callees to show per side', default: '20' },
+        content: { type: 'boolean', description: 'Append source code content for the symbol' },
+    },
+    async run({ args }) {
+        const startTime = Date.now();
+        const jsonOutput = !!args.json;
+        const projectIdOverride = args['project-id'];
+        const repoPath = process.cwd();
+        const projectId = projectIdOverride ?? Buffer.from(repoPath).toString('base64url').slice(0, 32);
+        const limit = parseInt(args.limit, 10);
+        const symbolName = args.symbol;
+        const showContent = !!args.content;
+        const response = await dispatchRaw('query', 'nexus', 'context', {
+            symbol: symbolName,
+            projectId,
+            limit,
+            content: showContent,
+        });
+        const durationMs = Date.now() - startTime;
+        if (!response.success) {
+            const msg = response.error?.message ?? 'Unknown error';
+            if (jsonOutput) {
+                process.stdout.write(JSON.stringify({
+                    success: false,
+                    error: { code: response.error?.code ?? 'E_CONTEXT_FAILED', message: msg },
+                    meta: {
+                        operation: 'nexus.context',
+                        duration_ms: durationMs,
+                        timestamp: new Date().toISOString(),
+                    },
+                }, null, 2) + '\n');
+            }
+            else {
+                process.stderr.write(`[nexus] Error: ${msg}\n`);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        const result = response.data;
+        if (result.matchCount === 0) {
+            if (jsonOutput) {
+                process.stdout.write(JSON.stringify({
+                    success: false,
+                    error: {
+                        code: 'E_NOT_FOUND',
+                        message: `No symbol found matching '${symbolName}' in project ${projectId}`,
+                    },
+                    meta: {
+                        operation: 'nexus.context',
+                        duration_ms: durationMs,
+                        timestamp: new Date().toISOString(),
+                    },
+                }, null, 2) + '\n');
+            }
+            else {
+                process.stdout.write(`[nexus] No symbol found matching '${symbolName}'.\n  Run 'cleo nexus analyze' first, or check the symbol name.\n`);
+            }
+            process.exitCode = 4;
+            return;
+        }
+        if (jsonOutput) {
+            process.stdout.write(JSON.stringify({
+                success: true,
+                data: result,
+                meta: {
+                    operation: 'nexus.context',
+                    duration_ms: durationMs,
+                    timestamp: new Date().toISOString(),
+                },
+            }, null, 2) + '\n');
+        }
+        else {
+            process.stdout.write(`[nexus] Context for symbol '${symbolName}' (${result.matchCount} match${result.matchCount !== 1 ? 'es' : ''}):\n`);
+            for (const r of result.results) {
+                process.stdout.write(`\n  Symbol:   ${String(r.name)}  (${String(r.kind)})\n  File:     ${r.filePath ? String(r.filePath) : 'n/a'}${r.startLine ? `:${String(r.startLine)}` : ''}\n` +
+                    (r.docSummary ? `  Doc:      ${String(r.docSummary)}\n` : '') +
+                    (r.community ? `  Community: ${String(r.community.label ?? r.community.id)}\n` : '') +
+                    `  Callers (${r.callers.length}): ${r.callers.length === 0 ? 'none' : r.callers.map((c) => `${c.name}[${c.kind}]`).join(', ')}\n` +
+                    `  Callees (${r.callees.length}): ${r.callees.length === 0 ? 'none' : r.callees.map((c) => `${c.name}[${c.kind}]`).join(', ')}\n` +
+                    (r.processes.length > 0
+                        ? `  Processes: ${r.processes.map((p) => `${String(p.label)}(${p.role})`).join(', ')}\n`
+                        : ''));
+                if (r.source?.source) {
+                    const ext = String(r.filePath).split('.').pop() ?? 'txt';
+                    process.stdout.write(`\n  Source (lines ${r.source.startLine}-${r.source.endLine}):\n  \`\`\`${ext}\n${r.source.source
+                        .split('\n')
+                        .map((line) => `  ${line}`)
+                        .join('\n')}\n  \`\`\`\n`);
+                }
+                else if (r.source?.errors?.length) {
+                    process.stdout.write(`\n  [warning] Could not retrieve source: ${r.source.errors[0]}\n`);
+                }
+            }
+            if (result.matchCount > 5) {
+                process.stdout.write(`\n  (Showing 5 of ${result.matchCount} matches — use --json for full list)\n`);
+            }
+        }
+    },
+});
+/** cleo nexus impact — show blast radius for a code symbol */
+const impactCommand = defineCommand({
+    meta: {
+        name: 'impact',
+        description: 'Show blast radius for a code symbol — direct callers (d=1), indirect callers (d=2), transitive (d=3)',
+    },
+    args: {
+        symbol: { type: 'positional', description: 'Symbol name to analyze', required: true },
+        json: { type: 'boolean', description: 'Output result as JSON (LAFS envelope format)' },
+        'project-id': {
+            type: 'string',
+            description: 'Override the project ID (default: auto-detected from cwd)',
+        },
+        depth: { type: 'string', description: 'Maximum traversal depth (default: 3)', default: '3' },
+        why: { type: 'boolean', description: 'Append reasons[] path-strings for each affected symbol' },
+    },
+    async run({ args }) {
+        const startTime = Date.now();
+        const jsonOutput = !!args.json;
+        const whyFlag = !!args.why;
+        const projectIdOverride = args['project-id'];
+        const repoPath = process.cwd();
+        const projectId = projectIdOverride ?? Buffer.from(repoPath).toString('base64url').slice(0, 32);
+        const maxDepth = Math.min(parseInt(args.depth, 10), 5);
+        const symbolName = args.symbol;
+        try {
+            // SSoT-EXEMPT:shape-mismatch — core NexusImpactResult (targetName/impactByDepth)
+            // differs from contracts NexusImpactResult (targetNodeId/affected); routing through
+            // dispatch.impact would require changing the output format. Tracked in T1510.
+            const result = await getSymbolImpact(symbolName, projectId, repoPath, {
+                maxDepth,
+                why: whyFlag,
+            });
+            const durationMs = Date.now() - startTime;
+            if (jsonOutput) {
+                process.stdout.write(JSON.stringify({
+                    success: true,
+                    data: result,
+                    meta: {
+                        operation: 'nexus.impact',
+                        duration_ms: durationMs,
+                        timestamp: new Date().toISOString(),
+                    },
+                }, null, 2) + '\n');
+            }
+            else {
+                process.stdout.write(`[nexus] Impact analysis for '${symbolName}'\n  Target:  ${String(result.targetName)}  (${String(result.targetKind)})\n  File:    ${result.targetFilePath ? String(result.targetFilePath) : 'n/a'}\n  Risk:    ${result.riskLevel}  (${result.totalImpactedNodes} impacted node${result.totalImpactedNodes !== 1 ? 's' : ''})\n`);
+                if (result.totalImpactedNodes === 0) {
+                    process.stdout.write('  No callers found — safe to modify.\n');
+                }
+                else {
+                    for (let i = 0; i < result.impactByDepth.length; i++) {
+                        const layer = result.impactByDepth[i];
+                        if (!layer || layer.nodes.length === 0)
+                            continue;
+                        const label = i === 0 ? 'WILL BREAK' : i === 1 ? 'LIKELY AFFECTED' : 'MAY NEED TESTING';
+                        process.stdout.write(`\n  d=${i + 1} ${label} (${layer.nodes.length}):\n`);
+                        for (const node of layer.nodes.slice(0, 15)) {
+                            process.stdout.write(`    ${String(node.name).padEnd(36)}  ${String(node.kind).padEnd(12)}  ${node.filePath ?? ''}\n`);
+                            if (whyFlag && node.reasons.length > 0) {
+                                for (const reason of node.reasons) {
+                                    process.stdout.write(`      why: ${reason}\n`);
+                                }
+                            }
+                        }
+                        if (layer.nodes.length > 15) {
+                            process.stdout.write(`    ... and ${layer.nodes.length - 15} more\n`);
+                        }
+                    }
+                }
+            }
+        }
+        catch (err) {
+            const code = err instanceof Error && 'code' in err ? err.code : undefined;
+            const msg = err instanceof Error ? err.message : String(err);
+            const durationMs = Date.now() - startTime;
+            if (code === 'E_NOT_FOUND') {
+                if (jsonOutput) {
+                    process.stdout.write(JSON.stringify({
+                        success: false,
+                        error: { code: 'E_NOT_FOUND', message: msg },
+                        meta: {
+                            operation: 'nexus.impact',
+                            duration_ms: durationMs,
+                            timestamp: new Date().toISOString(),
+                        },
+                    }, null, 2) + '\n');
+                }
+                else {
+                    process.stdout.write(`[nexus] No symbol found matching '${symbolName}'.\n  Run 'cleo nexus analyze' first, or check the symbol name.\n`);
+                }
+                process.exitCode = 4;
+                return;
+            }
+            if (jsonOutput) {
+                process.stdout.write(JSON.stringify({
+                    success: false,
+                    error: { code: 'E_IMPACT_FAILED', message: msg },
+                    meta: {
+                        operation: 'nexus.impact',
+                        duration_ms: durationMs,
+                        timestamp: new Date().toISOString(),
+                    },
+                }, null, 2) + '\n');
+            }
+            else {
+                process.stderr.write(`[nexus] Error: ${msg}\n`);
+            }
+            process.exitCode = 1;
+        }
+    },
+});
+/** cleo nexus analyze — run code intelligence pipeline on a repository directory */
+const analyzeCommand = defineCommand({
+    meta: {
+        name: 'analyze',
+        description: 'Run code intelligence pipeline on a repository directory',
+    },
+    args: {
+        path: {
+            type: 'positional',
+            description: 'Path to repository directory (default: cwd)',
+            required: false,
+        },
+        json: {
+            type: 'boolean',
+            description: 'Output result as JSON (LAFS envelope format)',
+        },
+        'project-id': {
+            type: 'string',
+            description: 'Override the project ID (default: auto-detected)',
+        },
+        incremental: {
+            type: 'boolean',
+            description: 'Only re-index files that have changed since the last run (faster)',
+        },
+    },
+    async run({ args }) {
+        const startTime = Date.now();
+        const jsonOutput = !!args.json;
+        const projectIdOverride = args['project-id'];
+        const isIncremental = !!args.incremental;
+        // Resolve target path
+        const repoPath = args.path ? path.resolve(args.path) : process.cwd();
+        if (!jsonOutput) {
+            process.stderr.write(`[nexus] Analyzing: ${repoPath}${isIncremental ? ' (incremental)' : ''}\n`);
+        }
+        try {
+            // SSoT-EXEMPT:pipeline-progress — runPipeline requires a progress callback
+            // (CLI-only rendering concern) and direct DB handle access. No dispatch op
+            // can expose this without introducing CLI rendering concerns into the dispatch
+            // layer. The full analyze pipeline is fundamentally CLI-side-orchestrated.
+            // Lazy imports to avoid loading heavy dependencies until needed
+            const [{ getNexusDb, nexusSchema }, { runPipeline }, { getProjectRoot }, { eq }] = await Promise.all([
+                import('@cleocode/core/store/nexus-sqlite'),
+                import('@cleocode/nexus/pipeline'),
+                import('@cleocode/core/internal'),
+                import('drizzle-orm'),
+            ]);
+            // Determine project ID — use override or derive from path
+            const projectId = projectIdOverride ?? Buffer.from(repoPath).toString('base64url').slice(0, 32);
+            // Get DB and table references
+            const db = await getNexusDb();
+            const tables = {
+                nexusNodes: nexusSchema.nexusNodes,
+                nexusRelations: nexusSchema.nexusRelations,
+            };
+            // For full (non-incremental) runs: delete existing index first.
+            // NodeSQLiteDatabase uses sync Drizzle — no await, wrap in try-catch.
+            if (!isIncremental) {
+                if (!jsonOutput) {
+                    process.stderr.write('[nexus] Clearing existing index for project...\n');
+                }
+                try {
+                    db.delete(nexusSchema.nexusNodes)
+                        .where(eq(nexusSchema.nexusNodes.projectId, projectId))
+                        .run();
+                }
+                catch {
+                    // Table may not have rows — ignore
+                }
+                try {
+                    db.delete(nexusSchema.nexusRelations)
+                        .where(eq(nexusSchema.nexusRelations.projectId, projectId))
+                        .run();
+                }
+                catch {
+                    // Table may not have rows — ignore
+                }
+            }
+            // Run the pipeline (full or incremental)
+            const result = await runPipeline(repoPath, projectId, db, tables, jsonOutput
+                ? undefined
+                : (current, total, filePath) => {
+                    if (current % 50 === 0 || current === total) {
+                        const pct = total > 0 ? Math.round((current / total) * 100) : 100;
+                        process.stderr.write(`[nexus] Progress: ${current}/${total} files (${pct}%) — ${filePath}\n`);
+                    }
+                }, { incremental: isIncremental });
+            const durationMs = Date.now() - startTime;
+            // Write nexus-bridge.md after a successful pipeline run (best-effort)
+            try {
+                const { refreshNexusBridge } = await import('@cleocode/core/internal');
+                await refreshNexusBridge(repoPath, projectId);
+                if (!jsonOutput) {
+                    process.stderr.write(`[nexus] nexus-bridge.md refreshed at ${repoPath}/.cleo/nexus-bridge.md\n`);
+                }
+            }
+            catch {
+                // Non-fatal — bridge refresh failure should not fail the analyze command
+            }
+            // Auto-register project and update index stats in the multi-project registry (best-effort)
+            try {
+                const { nexusUpdateIndexStats } = await import('@cleocode/core/internal');
+                await nexusUpdateIndexStats(repoPath, {
+                    nodeCount: result.nodeCount,
+                    relationCount: result.relationCount,
+                    fileCount: result.fileCount,
+                });
+                if (!jsonOutput) {
+                    process.stderr.write('[nexus] Project registered/updated in multi-project registry.\n');
+                }
+            }
+            catch {
+                // Non-fatal — registry update must never fail the analyze command
+            }
+            // Post-hook: sweep git log and link task IDs to symbols (best-effort, idempotent)
+            try {
+                const { runGitLogTaskLinker } = await import('@cleocode/core/nexus');
+                const sweeperResult = await runGitLogTaskLinker(repoPath);
+                if (!jsonOutput && sweeperResult.commitsProcessed > 0) {
+                    process.stderr.write(`[nexus] Task-symbol sweep: ${sweeperResult.commitsProcessed} commit(s), ${sweeperResult.tasksFound} task(s), ${sweeperResult.linked} edge(s) linked.\n`);
+                }
+            }
+            catch {
+                // Non-fatal — task sweeper failure must never fail the analyze command
+            }
+            if (jsonOutput) {
+                const envelope = {
+                    success: true,
+                    data: {
+                        projectId,
+                        repoPath,
+                        incremental: isIncremental,
+                        nodeCount: result.nodeCount,
+                        relationCount: result.relationCount,
+                        fileCount: result.fileCount,
+                        durationMs,
+                    },
+                    meta: {
+                        operation: 'nexus.analyze',
+                        duration_ms: durationMs,
+                        timestamp: new Date().toISOString(),
+                    },
+                };
+                process.stdout.write(JSON.stringify(envelope, null, 2) + '\n');
+            }
+            else {
+                process.stdout.write(`[nexus] Analysis complete${isIncremental ? ' (incremental)' : ''}:\n` +
+                    `  Project ID: ${projectId}\n` +
+                    `  Files:      ${result.fileCount}\n` +
+                    `  Nodes:      ${result.nodeCount}\n` +
+                    `  Relations:  ${result.relationCount}\n` +
+                    `  Duration:   ${durationMs}ms\n`);
+            }
+            void getProjectRoot; // referenced to satisfy import
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (jsonOutput) {
+                const envelope = {
+                    success: false,
+                    error: { code: 'E_PIPELINE_FAILED', message: msg },
+                    meta: {
+                        operation: 'nexus.analyze',
+                        duration_ms: Date.now() - startTime,
+                        timestamp: new Date().toISOString(),
+                    },
+                };
+                process.stdout.write(JSON.stringify(envelope, null, 2) + '\n');
+            }
+            else {
+                process.stderr.write(`[nexus] Error: ${msg}\n`);
+            }
+            process.exitCode = 1;
+        }
+    },
+});
+// ── nexus projects subcommand group ──────────────────────────────────────────
+/** cleo nexus projects list — list all projects registered in the global nexus registry */
+const projectsListCommand = defineCommand({
+    meta: {
+        name: 'list',
+        description: 'List all projects registered in the global nexus registry',
+    },
+    args: {
+        json: {
+            type: 'boolean',
+            description: 'Output as JSON (LAFS envelope format)',
+        },
+    },
+    async run({ args }) {
+        const startTime = Date.now();
+        const jsonOutput = !!args.json;
+        const response = await dispatchRaw('query', 'nexus', 'projects.list', {});
+        const durationMs = Date.now() - startTime;
+        if (!response.success) {
+            process.stderr.write(`[nexus] Error: ${response.error?.message ?? 'Unknown error'}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        const data = response.data;
+        const list = data.projects;
+        if (jsonOutput) {
+            process.stdout.write(JSON.stringify({
+                success: true,
+                data,
+                meta: {
+                    operation: 'nexus.projects.list',
+                    duration_ms: durationMs,
+                    timestamp: new Date().toISOString(),
+                },
+            }, null, 2) + '\n');
+        }
+        else if (list.length === 0) {
+            process.stdout.write('[nexus] No projects registered. Run: cleo nexus projects register\n');
+        }
+        else {
+            process.stdout.write(`[nexus] Registered projects (${list.length}):\n\n`);
+            for (const p of list) {
+                const nodes = p.stats?.nodeCount ?? 0;
+                const rels = p.stats?.relationCount ?? 0;
+                const indexed = p.lastIndexed ? p.lastIndexed.slice(0, 10) : 'never';
+                process.stdout.write(`  ${p.name.padEnd(28)}  tasks=${String(p.taskCount).padStart(5)}  nodes=${String(nodes).padStart(6)}  relations=${String(rels).padStart(7)}  indexed=${indexed}\n` +
+                    `  ${''.padEnd(28)}  path=${p.path}\n`);
+            }
+        }
+    },
+});
+/** cleo nexus projects register — register a project in the global nexus registry */
+const projectsRegisterCommand = defineCommand({
+    meta: {
+        name: 'register',
+        description: 'Register a project in the global nexus registry (default: current directory)',
+    },
+    args: {
+        path: {
+            type: 'positional',
+            description: 'Path to the project directory (default: cwd)',
+            required: false,
+        },
+        name: {
+            type: 'string',
+            description: 'Custom project name (default: directory name)',
+        },
+        json: {
+            type: 'boolean',
+            description: 'Output as JSON (LAFS envelope format)',
+        },
+    },
+    async run({ args }) {
+        const startTime = Date.now();
+        const jsonOutput = !!args.json;
+        const repoPath = args.path ? path.resolve(args.path) : process.cwd();
+        const name = args.name;
+        const response = await dispatchRaw('mutate', 'nexus', 'projects.register', {
+            path: repoPath,
+            name,
+        });
+        const durationMs = Date.now() - startTime;
+        if (!response.success) {
+            const msg = response.error?.message ?? 'Unknown error';
+            if (jsonOutput) {
+                process.stdout.write(JSON.stringify({
+                    success: false,
+                    error: { code: response.error?.code ?? 'E_REGISTER_FAILED', message: msg },
+                    meta: {
+                        operation: 'nexus.projects.register',
+                        duration_ms: durationMs,
+                        timestamp: new Date().toISOString(),
+                    },
+                }, null, 2) + '\n');
+            }
+            else {
+                process.stderr.write(`[nexus] Error: ${msg}\n`);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        const data = response.data;
+        if (jsonOutput) {
+            process.stdout.write(JSON.stringify({
+                success: true,
+                data,
+                meta: {
+                    operation: 'nexus.projects.register',
+                    duration_ms: durationMs,
+                    timestamp: new Date().toISOString(),
+                },
+            }, null, 2) + '\n');
+        }
+        else {
+            process.stdout.write(`[nexus] Registered: ${data.path} (hash: ${data.hash})\n`);
+        }
+    },
+});
+/** cleo nexus projects remove — remove a project from the global nexus registry */
+const projectsRemoveCommand = defineCommand({
+    meta: {
+        name: 'remove',
+        description: 'Remove a project from the global nexus registry',
+    },
+    args: {
+        nameOrHash: {
+            type: 'positional',
+            description: 'Project name or hash to remove',
+            required: true,
+        },
+        json: {
+            type: 'boolean',
+            description: 'Output as JSON (LAFS envelope format)',
+        },
+    },
+    async run({ args }) {
+        const startTime = Date.now();
+        const jsonOutput = !!args.json;
+        const response = await dispatchRaw('mutate', 'nexus', 'projects.remove', {
+            nameOrHash: args.nameOrHash,
+        });
+        const durationMs = Date.now() - startTime;
+        if (!response.success) {
+            const msg = response.error?.message ?? 'Unknown error';
+            if (jsonOutput) {
+                process.stdout.write(JSON.stringify({
+                    success: false,
+                    error: { code: response.error?.code ?? 'E_REMOVE_FAILED', message: msg },
+                    meta: {
+                        operation: 'nexus.projects.remove',
+                        duration_ms: durationMs,
+                        timestamp: new Date().toISOString(),
+                    },
+                }, null, 2) + '\n');
+            }
+            else {
+                process.stderr.write(`[nexus] Error: ${msg}\n`);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        if (jsonOutput) {
+            process.stdout.write(JSON.stringify({
+                success: true,
+                data: response.data,
+                meta: {
+                    operation: 'nexus.projects.remove',
+                    duration_ms: durationMs,
+                    timestamp: new Date().toISOString(),
+                },
+            }, null, 2) + '\n');
+        }
+        else {
+            process.stdout.write(`[nexus] Removed: ${String(args.nameOrHash)}\n`);
+        }
+    },
+});
+/** cleo nexus projects scan — walk filesystem roots to discover .cleo/ directories */
+const projectsScanCommand = defineCommand({
+    meta: {
+        name: 'scan',
+        description: 'Walk filesystem roots to discover .cleo/ directories not registered in the global nexus registry',
+    },
+    args: {
+        roots: {
+            type: 'string',
+            description: 'Comma-separated search roots (default: ~/code,~/projects,/mnt/projects)',
+        },
+        'max-depth': {
+            type: 'string',
+            description: 'Maximum directory traversal depth (default: 4)',
+            default: '4',
+        },
+        'auto-register': {
+            type: 'boolean',
+            description: 'Register all discovered unregistered projects automatically',
+        },
+        'include-existing': {
+            type: 'boolean',
+            description: 'Also report projects that are already registered',
+        },
+        json: { type: 'boolean', description: 'Output as JSON (LAFS envelope format)' },
+    },
+    async run({ args }) {
+        const startTime = Date.now();
+        const jsonOutput = !!args.json;
+        const autoRegister = !!args['auto-register'];
+        const includeExisting = !!args['include-existing'];
+        const maxDepth = Math.max(1, Math.min(parseInt(args['max-depth'], 10), 20));
+        if (!jsonOutput) {
+            process.stdout.write(`[nexus] Scanning up to depth ${maxDepth} for .cleo/ project roots...\n`);
+        }
+        const response = await dispatchRaw('mutate', 'nexus', 'projects.scan', {
+            roots: args.roots,
+            maxDepth,
+            autoRegister,
+            includeExisting,
+        });
+        const durationMs = Date.now() - startTime;
+        if (!response.success) {
+            process.stderr.write(`[nexus] Error: ${response.error?.message ?? 'Unknown error'}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        const result = response.data;
+        if (!jsonOutput) {
+            process.stdout.write(`[nexus] Scanning ${result.roots.length} root(s) up to depth ${maxDepth}:\n${result.roots.map((r) => `  ${r}`).join('\n')}\n`);
+        }
+        if (jsonOutput) {
+            const data = {
+                roots: result.roots,
+                unregistered: result.unregistered,
+                tally: result.tally,
+            };
+            if (includeExisting)
+                data['registered'] = result.registered;
+            if (autoRegister) {
+                data['autoRegistered'] = result.autoRegistered;
+                data['autoRegisterErrors'] = result.autoRegisterErrors;
+            }
+            process.stdout.write(JSON.stringify({
+                success: true,
+                data,
+                meta: {
+                    operation: 'nexus.projects.scan',
+                    duration_ms: durationMs,
+                    timestamp: new Date().toISOString(),
+                },
+            }, null, 2) + '\n');
+        }
+        else {
+            process.stdout.write(`\n[nexus] Scan complete — ${result.tally.total} project(s) found (${result.tally.unregistered} unregistered, ${result.tally.registered} registered)\n`);
+            if (result.unregistered.length > 0) {
+                process.stdout.write('\n  Unregistered:\n');
+                for (const p of result.unregistered) {
+                    process.stdout.write(`    ${p}\n`);
+                }
+                if (!autoRegister) {
+                    process.stdout.write('\n  Tip: run with --auto-register to register all of the above.\n');
+                }
+            }
+            if (includeExisting && result.registered.length > 0) {
+                process.stdout.write('\n  Already registered:\n');
+                for (const p of result.registered) {
+                    process.stdout.write(`    ${p}\n`);
+                }
+            }
+            if (autoRegister) {
+                process.stdout.write(`\n  Auto-registered: ${result.autoRegistered.length} project(s)${result.autoRegisterErrors.length > 0 ? `, ${result.autoRegisterErrors.length} failed` : ''}\n`);
+                for (const e of result.autoRegisterErrors) {
+                    process.stdout.write(`    FAILED ${e.path}: ${e.error}\n`);
+                }
+            }
+        }
+    },
+});
+/** cleo nexus projects clean — bulk purge project_registry rows matching path criteria */
+const projectsCleanCommand = defineCommand({
+    meta: {
+        name: 'clean',
+        description: 'Bulk purge project_registry rows matching path criteria (requires at least one filter flag)',
+    },
+    args: {
+        'dry-run': {
+            type: 'boolean',
+            description: 'List matching projects without deleting anything',
+        },
+        pattern: {
+            type: 'string',
+            description: 'JS regex matched against project_path',
+        },
+        'include-temp': {
+            type: 'boolean',
+            description: 'Preset: match paths containing a .temp/ segment',
+        },
+        'include-tests': {
+            type: 'boolean',
+            description: 'Preset: match paths containing tmp/test/fixture/scratch/sandbox segments',
+        },
+        unhealthy: {
+            type: 'boolean',
+            description: 'Also match rows where health_status is "unhealthy"',
+        },
+        'never-indexed': {
+            type: 'boolean',
+            description: 'Also match rows where last_indexed IS NULL',
+        },
+        yes: {
+            type: 'boolean',
+            description: 'Skip confirmation prompt (still shows preview)',
+        },
+        json: {
+            type: 'boolean',
+            description: 'Output as JSON (LAFS envelope format)',
+        },
+    },
+    async run({ args }) {
+        const startTime = Date.now();
+        const jsonOutput = !!args.json;
+        const dryRun = !!args['dry-run'];
+        const skipPrompt = !!args.yes;
+        const cleanOpts = {
+            pattern: args.pattern,
+            includeTemp: !!args['include-temp'],
+            includeTests: !!args['include-tests'],
+            matchUnhealthy: !!args.unhealthy,
+            matchNeverIndexed: !!args['never-indexed'],
+        };
+        try {
+            // Preview phase via dispatch (always dry-run first to get counts)
+            const previewResp = await dispatchRaw('mutate', 'nexus', 'projects.clean', {
+                ...cleanOpts,
+                dryRun: true,
+            });
+            if (!previewResp.success) {
+                const code = previewResp.error?.code ?? 'E_CLEAN_FAILED';
+                const msg = previewResp.error?.message ?? 'Unknown error';
+                const exitCode = code === 'E_NO_CRITERIA' || code === 'E_INVALID_PATTERN' ? 6 : 1;
+                if (jsonOutput) {
+                    process.stdout.write(JSON.stringify({
+                        success: false,
+                        error: { code, message: msg },
+                        meta: {
+                            operation: 'nexus.projects.clean',
+                            duration_ms: Date.now() - startTime,
+                            timestamp: new Date().toISOString(),
+                        },
+                    }, null, 2) + '\n');
+                }
+                else {
+                    process.stderr.write(`[nexus] Error: ${msg}\n`);
+                }
+                process.exitCode = exitCode;
+                return;
+            }
+            const preview = previewResp.data;
+            const { matched: matchCount, totalCount, sample: samplePaths } = preview;
+            // Show preview in human mode
+            if (!jsonOutput) {
+                process.stdout.write(`[nexus] Clean preview — ${matchCount} project(s) of ${totalCount} total match criteria:\n`);
+                if (matchCount === 0) {
+                    process.stdout.write('  (no matches)\n');
+                }
+                else {
+                    for (const p of samplePaths) {
+                        process.stdout.write(`  ${p}\n`);
+                    }
+                    if (matchCount > 10) {
+                        process.stdout.write(`  ... and ${matchCount - 10} more\n`);
+                    }
+                }
+            }
+            if (matchCount === 0 || dryRun) {
+                const durationMs = Date.now() - startTime;
+                if (jsonOutput) {
+                    process.stdout.write(JSON.stringify({
+                        success: true,
+                        data: {
+                            dryRun: true,
+                            matched: matchCount,
+                            purged: 0,
+                            remaining: totalCount,
+                            sample: samplePaths,
+                        },
+                        meta: {
+                            operation: 'nexus.projects.clean',
+                            duration_ms: durationMs,
+                            timestamp: new Date().toISOString(),
+                        },
+                    }, null, 2) + '\n');
+                }
+                else if (dryRun && matchCount > 0) {
+                    process.stdout.write(`[nexus] Dry-run — ${matchCount} project(s) would be purged. Rerun without --dry-run to delete.\n`);
+                }
+                return;
+            }
+            // Confirmation prompt (skip with --yes) — CLI-side interactive stdin
+            if (!skipPrompt) {
+                const { createInterface } = await import('node:readline');
+                const rl = createInterface({ input: process.stdin, output: process.stdout });
+                const confirmed = await new Promise((resolve) => {
+                    rl.question(`\n[nexus] Delete ${matchCount} project(s) from the registry? [y/N] `, (answer) => {
+                        rl.close();
+                        resolve(answer.trim().toLowerCase() === 'y');
+                    });
+                });
+                if (!confirmed) {
+                    process.stdout.write('[nexus] Aborted — no projects deleted.\n');
+                    return;
+                }
+            }
+            // Actual delete via dispatch
+            const deleteResp = await dispatchRaw('mutate', 'nexus', 'projects.clean', {
+                ...cleanOpts,
+                dryRun: false,
+            });
+            const durationMs = Date.now() - startTime;
+            if (!deleteResp.success) {
+                const code = deleteResp.error?.code ?? 'E_CLEAN_FAILED';
+                const msg = deleteResp.error?.message ?? 'Unknown error';
+                const exitCode = code === 'E_NO_CRITERIA' || code === 'E_INVALID_PATTERN' ? 6 : 1;
+                if (jsonOutput) {
+                    process.stdout.write(JSON.stringify({
+                        success: false,
+                        error: { code, message: msg },
+                        meta: {
+                            operation: 'nexus.projects.clean',
+                            duration_ms: durationMs,
+                            timestamp: new Date().toISOString(),
+                        },
+                    }, null, 2) + '\n');
+                }
+                else {
+                    process.stderr.write(`[nexus] Error: ${msg}\n`);
+                }
+                process.exitCode = exitCode;
+                return;
+            }
+            const result = deleteResp.data;
+            if (jsonOutput) {
+                process.stdout.write(JSON.stringify({
+                    success: true,
+                    data: {
+                        dryRun: false,
+                        matched: result.matched,
+                        purged: result.purged,
+                        remaining: result.remaining,
+                        sample: result.sample,
+                    },
+                    meta: {
+                        operation: 'nexus.projects.clean',
+                        duration_ms: durationMs,
+                        timestamp: new Date().toISOString(),
+                    },
+                }, null, 2) + '\n');
+            }
+            else {
+                process.stdout.write(`[nexus] Purged ${result.purged} project(s). ${result.remaining} project(s) remaining in registry.\n`);
+            }
+        }
+        catch (err) {
+            const durationMs = Date.now() - startTime;
+            const msg = err instanceof Error ? err.message : String(err);
+            if (jsonOutput) {
+                process.stdout.write(JSON.stringify({
+                    success: false,
+                    error: { code: 'E_CLEAN_FAILED', message: msg },
+                    meta: {
+                        operation: 'nexus.projects.clean',
+                        duration_ms: durationMs,
+                        timestamp: new Date().toISOString(),
+                    },
+                }, null, 2) + '\n');
+            }
+            else {
+                process.stderr.write(`[nexus] Error: ${msg}\n`);
+            }
+            process.exitCode = 1;
+        }
+    },
+});
+/** cleo nexus projects — multi-project registry management */
+const projectsCommand = defineCommand({
+    meta: { name: 'projects', description: 'Multi-project registry management' },
+    subCommands: {
+        list: projectsListCommand,
+        register: projectsRegisterCommand,
+        remove: projectsRemoveCommand,
+        scan: projectsScanCommand,
+        clean: projectsCleanCommand,
+    },
+});
+/** cleo nexus refresh-bridge — regenerate .cleo/nexus-bridge.md from existing index */
+const refreshBridgeCommand = defineCommand({
+    meta: {
+        name: 'refresh-bridge',
+        description: 'Regenerate .cleo/nexus-bridge.md from the existing nexus.db index (does not re-index)',
+    },
+    args: {
+        path: {
+            type: 'positional',
+            description: 'Path to project directory (default: cwd)',
+            required: false,
+        },
+        json: {
+            type: 'boolean',
+            description: 'Output result as JSON (LAFS envelope format)',
+        },
+        'project-id': {
+            type: 'string',
+            description: 'Override the project ID (default: auto-detected from path)',
+        },
+    },
+    async run({ args }) {
+        const startTime = Date.now();
+        const jsonOutput = !!args.json;
+        const projectIdOverride = args['project-id'];
+        const repoPath = args.path ? path.resolve(args.path) : process.cwd();
+        const projectId = projectIdOverride ?? Buffer.from(repoPath).toString('base64url').slice(0, 32);
+        const response = await dispatchRaw('mutate', 'nexus', 'refresh-bridge', {
+            repoPath,
+            projectId,
+        });
+        const durationMs = Date.now() - startTime;
+        if (!response.success) {
+            const msg = response.error?.message ?? 'Unknown error';
+            if (jsonOutput) {
+                process.stdout.write(JSON.stringify({
+                    success: false,
+                    error: { code: response.error?.code ?? 'E_BRIDGE_FAILED', message: msg },
+                    meta: {
+                        operation: 'nexus.refresh-bridge',
+                        duration_ms: durationMs,
+                        timestamp: new Date().toISOString(),
+                    },
+                }, null, 2) + '\n');
+            }
+            else {
+                process.stderr.write(`[nexus] Error refreshing bridge: ${msg}\n`);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        const result = response.data;
+        if (jsonOutput) {
+            process.stdout.write(JSON.stringify({
+                success: true,
+                data: result,
+                meta: {
+                    operation: 'nexus.refresh-bridge',
+                    duration_ms: durationMs,
+                    timestamp: new Date().toISOString(),
+                },
+            }, null, 2) + '\n');
+        }
+        else if (result.written) {
+            process.stdout.write(`[nexus] nexus-bridge.md refreshed at ${result.path}\n`);
+        }
+        else {
+            process.stdout.write(`[nexus] nexus-bridge.md unchanged at ${result.path}\n`);
+        }
+    },
+});
+/**
+ * Export nexus graph to GEXF (Gephi) or JSON format.
+ *
+ * Queries graph_nodes and graph_edges from nexus.db and emits GEXF format
+ * suitable for visualization in Gephi. Supports optional project filtering.
+ *
+ * @task T626-M7
+ */
+const exportCommand = defineCommand({
+    meta: { name: 'export', description: 'Export nexus graph to GEXF (Gephi) or JSON format' },
+    args: {
+        format: {
+            type: 'string',
+            description: 'Output format: gexf, json',
+            default: 'gexf',
+        },
+        output: {
+            type: 'string',
+            description: 'Output file path (stdout if omitted)',
+        },
+        project: {
+            type: 'string',
+            description: 'Filter by project ID (exports all projects if omitted)',
+        },
+    },
+    async run({ args }) {
+        const startTime = Date.now();
+        const format = args.format ?? 'gexf';
+        const outputFile = args.output;
+        const projectFilter = args.project;
+        try {
+            // SSoT-EXEMPT:file-serialization — GEXF/JSON graph export writes raw bytes
+            // to stdout/file; requires direct nexus.db access for node/relation queries.
+            // Cannot be a standard LAFS dispatch envelope without binary data concerns.
+            const { getNexusDb, nexusSchema } = await import('@cleocode/core/store/nexus-sqlite');
+            const db = await getNexusDb();
+            // Load all nodes and relations
+            let allNodes = [];
+            let allRelations = [];
+            try {
+                allNodes = db.select().from(nexusSchema.nexusNodes).all();
+                allRelations = db.select().from(nexusSchema.nexusRelations).all();
+            }
+            catch {
+                // DB may be empty
+            }
+            // Filter by project if specified
+            const nodes = projectFilter
+                ? allNodes.filter((n) => n['projectId'] === projectFilter)
+                : allNodes;
+            const relations = projectFilter
+                ? allRelations.filter((r) => r['projectId'] === projectFilter)
+                : allRelations;
+            let output = '';
+            if (format === 'json') {
+                output = JSON.stringify({
+                    nodes: nodes.map((n) => ({
+                        id: n['id'],
+                        kind: n['kind'],
+                        label: n['label'],
+                        name: n['name'],
+                        filePath: n['filePath'],
+                        language: n['language'],
+                        isExported: n['isExported'],
+                        startLine: n['startLine'],
+                        endLine: n['endLine'],
+                        projectId: n['projectId'],
+                    })),
+                    edges: relations.map((r) => ({
+                        id: r['id'],
+                        source: r['sourceId'],
+                        target: r['targetId'],
+                        type: r['type'],
+                        confidence: r['confidence'],
+                        reason: r['reason'],
+                    })),
+                }, null, 2);
+            }
+            else if (format === 'gexf') {
+                // GEXF format (Gephi standard)
+                output = generateGexf(nodes, relations);
+            }
+            else {
+                process.stderr.write(`[nexus] Error: Unknown format '${format}'. Supported: gexf, json\n`);
+                process.exitCode = 1;
+                return;
+            }
+            if (outputFile) {
+                const { writeFileSync } = await import('node:fs');
+                writeFileSync(outputFile, output, 'utf-8');
+                process.stdout.write(`[nexus] Exported to ${outputFile} (${nodes.length} nodes, ${relations.length} edges)\n`);
+            }
+            else {
+                process.stdout.write(output);
+                if (!output.endsWith('\n'))
+                    process.stdout.write('\n');
+            }
+            const durationMs = Date.now() - startTime;
+            if (outputFile) {
+                process.stderr.write(`[nexus] Export completed in ${durationMs}ms\n`);
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[nexus] Error: ${msg}\n`);
+            process.exitCode = 1;
+        }
+    },
+});
+/**
+ * Compare NEXUS index state between two git commits.
+ * @task T625
+ */
+const diffCommand = defineCommand({
+    meta: {
+        name: 'diff',
+        description: 'Compare NEXUS index state between two git commits — shows new/removed relations and broken call chains',
+    },
+    args: {
+        before: {
+            type: 'string',
+            description: 'Git SHA or ref for the "before" snapshot (default: HEAD~1)',
+        },
+        after: {
+            type: 'string',
+            description: 'Git SHA or ref for the "after" snapshot (default: HEAD)',
+            default: 'HEAD',
+        },
+        path: { type: 'string', description: 'Repository directory to analyze (default: cwd)' },
+        json: { type: 'boolean', description: 'Output result as JSON (LAFS envelope format)' },
+        'project-id': {
+            type: 'string',
+            description: 'Override the project ID (default: auto-detected from path)',
+        },
+    },
+    async run({ args }) {
+        const startTime = Date.now();
+        const jsonOutput = !!args.json;
+        const repoPath = args.path ? path.resolve(args.path) : process.cwd();
+        const projectIdOverride = args['project-id'];
+        const beforeRef = args.before ?? 'HEAD~1';
+        const afterRef = args.after ?? 'HEAD';
+        if (!jsonOutput) {
+            process.stderr.write(`[nexus] Diffing relations: ${beforeRef}..${afterRef} in ${repoPath}\n`);
+        }
+        const response = await dispatchRaw('query', 'nexus', 'diff', {
+            repoPath,
+            beforeRef,
+            afterRef,
+            projectId: projectIdOverride,
+        });
+        const durationMs = Date.now() - startTime;
+        if (!response.success) {
+            const msg = response.error?.message ?? 'Unknown error';
+            if (jsonOutput) {
+                process.stdout.write(JSON.stringify({
+                    success: false,
+                    error: { code: response.error?.code ?? 'E_DIFF_FAILED', message: msg },
+                    meta: {
+                        operation: 'nexus.diff',
+                        duration_ms: durationMs,
+                        timestamp: new Date().toISOString(),
+                    },
+                }, null, 2) + '\n');
+            }
+            else {
+                process.stderr.write(`[nexus] Error running diff: ${msg}\n`);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        const result = response.data;
+        if (jsonOutput) {
+            process.stdout.write(JSON.stringify({
+                success: true,
+                data: result,
+                meta: {
+                    operation: 'nexus.diff',
+                    duration_ms: durationMs,
+                    timestamp: new Date().toISOString(),
+                },
+            }, null, 2) + '\n');
+        }
+        else {
+            process.stdout.write(`[nexus] Diff: ${result.beforeSha}..${result.afterSha}\n  Changed files: ${result.changedFiles.length > 0 ? result.changedFiles.join(', ') : 'n/a'}\n  Nodes:     before=${result.nodesBefore}  after=${result.nodesAfter}  new=+${result.newNodes}  removed=-${result.removedNodes}\n  Relations: before=${result.relationsBefore}  after=${result.relationsAfter}  new=+${result.newRelations}  removed=-${result.removedRelations}\n  Health:    ${result.healthStatus}\n`);
+            if (result.regressions.length > 0) {
+                process.stdout.write('\n  REGRESSIONS:\n');
+                for (const reg of result.regressions) {
+                    process.stdout.write(`    - ${reg}\n`);
+                }
+            }
+            else {
+                process.stdout.write('  No regressions detected.\n');
+            }
+        }
+    },
+});
+/**
+ * cleo nexus query — Execute recursive CTE queries against nexus.db
+ *
+ * Supports raw CTE syntax and 6 template aliases for common code intelligence patterns.
+ * Results returned as markdown table.
+ *
+ * @task T1057
+ */
+const queryCommand = defineCommand({
+    meta: {
+        name: 'query',
+        description: 'Execute recursive CTE queries against nexus.db',
+    },
+    args: {
+        cte: {
+            type: 'positional',
+            description: 'CTE SQL or template alias (callers-of, callees-of, co-changed, co-cited, path-between, community-members)',
+            required: true,
+        },
+        params: {
+            type: 'string',
+            description: 'Comma-separated parameters (e.g., "sym-id-1,sym-id-2")',
+        },
+    },
+    async run({ args }) {
+        const cteOrAlias = args.cte;
+        const paramsStr = args.params || '';
+        const params = paramsStr
+            .split(',')
+            .map((p) => p.trim())
+            .filter(Boolean);
+        const response = await dispatchRaw('query', 'nexus', 'query-cte', {
+            cte: cteOrAlias,
+            params,
+        });
+        if (!response.success) {
+            const code = response.error?.code;
+            const msg = response.error?.message ?? 'Unknown error';
+            const exitCode = code === 'E_INVALID_INPUT' ? 6 : 77;
+            process.stderr.write(`[nexus] Error: ${msg}\n`);
+            process.exitCode = exitCode;
+            return;
+        }
+        const result = response.data;
+        if (!result.success) {
+            process.stderr.write(`[nexus] Query error: ${result.error ?? 'Unknown'}\n`);
+            process.exitCode = 77;
+            return;
+        }
+        // Format as markdown table using the DSL formatter
+        const { formatCteResultAsMarkdown } = await import('@cleocode/core/nexus/query-dsl.js');
+        const markdown = formatCteResultAsMarkdown(result);
+        process.stdout.write(markdown + '\n');
+        process.stdout.write(`\n[nexus] ${result.row_count} rows in ${result.execution_time_ms.toFixed(2)}ms\n`);
+    },
+});
+/**
+ * cleo nexus route-map — Display all routes with their handlers and dependencies.
+ */
+const routeMapCommand = defineCommand({
+    meta: {
+        name: 'route-map',
+        description: 'Display all routes with their handlers and dependencies',
+    },
+    args: {
+        path: {
+            type: 'positional',
+            description: 'Path to project directory (default: cwd)',
+            required: false,
+        },
+        json: {
+            type: 'boolean',
+            description: 'Output result as JSON (LAFS envelope format)',
+        },
+        'project-id': {
+            type: 'string',
+            description: 'Override the project ID (default: auto-detected from path)',
+        },
+    },
+    async run({ args }) {
+        const startTime = Date.now();
+        const jsonOutput = !!args.json;
+        const projectIdOverride = args['project-id'];
+        const repoPath = args.path ? path.resolve(args.path) : process.cwd();
+        const projectId = projectIdOverride ?? Buffer.from(repoPath).toString('base64url').slice(0, 32);
+        const response = await dispatchRaw('query', 'nexus', 'route-map', { projectId });
+        const durationMs = Date.now() - startTime;
+        if (!response.success) {
+            const msg = response.error?.message ?? 'Unknown error';
+            if (jsonOutput) {
+                process.stdout.write(JSON.stringify({
+                    success: false,
+                    error: { code: response.error?.code ?? 'E_ROUTE_MAP_FAILED', message: msg },
+                    meta: {
+                        operation: 'nexus.route-map',
+                        duration_ms: durationMs,
+                        timestamp: new Date().toISOString(),
+                    },
+                }, null, 2) + '\n');
+            }
+            else {
+                process.stderr.write(`[nexus] Error running route-map: ${msg}\n`);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        const result = response.data;
+        if (jsonOutput) {
+            process.stdout.write(JSON.stringify({
+                success: true,
+                data: result,
+                meta: {
+                    operation: 'nexus.route-map',
+                    duration_ms: durationMs,
+                    timestamp: new Date().toISOString(),
+                },
+            }, null, 2) + '\n');
+        }
+        else {
+            if (result.routes.length === 0) {
+                process.stdout.write(`[nexus] No routes found for project ${projectId}.\n  Run 'cleo nexus analyze' first.\n`);
+            }
+            else {
+                process.stdout.write(`[nexus] Route Map for project ${projectId} (${result.routes.length} total):\n\n`);
+                process.stdout.write('| Route ID | Handler | Method | Path | Deps | Callers |\n');
+                process.stdout.write('|----------|---------|--------|------|------|----------|\n');
+                for (const route of result.routes) {
+                    const method = route.routeMeta['method'] ?? '—';
+                    const routePath = route.routeMeta['path'] ?? '—';
+                    const depCount = route.fetchedDeps.length;
+                    process.stdout.write(`| ${route.routeId} | ${route.handlerName} | ${method} | ${routePath} | ${depCount} | ${route.callerCount} |\n`);
+                }
+                process.stdout.write('\n');
+                if (result.distinctDeps.length > 0) {
+                    process.stdout.write(`External dependencies: ${result.distinctDeps.join(', ')}\n`);
+                }
+            }
+        }
+    },
+});
+/**
+ * cleo nexus shape-check — Check response shape compatibility for a route.
+ */
+const shapeCheckCommand = defineCommand({
+    meta: {
+        name: 'shape-check',
+        description: 'Check response shape compatibility for a route handler',
+    },
+    args: {
+        routeSymbol: {
+            type: 'positional',
+            description: 'Route symbol ID (format: <filePath>::<routeName>)',
+            required: true,
+        },
+        path: {
+            type: 'positional',
+            description: 'Path to project directory (default: cwd)',
+            required: false,
+        },
+        json: {
+            type: 'boolean',
+            description: 'Output result as JSON (LAFS envelope format)',
+        },
+        'project-id': {
+            type: 'string',
+            description: 'Override the project ID (default: auto-detected from path)',
+        },
+    },
+    async run({ args }) {
+        const startTime = Date.now();
+        const routeSymbol = args.routeSymbol;
+        const jsonOutput = !!args.json;
+        const projectIdOverride = args['project-id'];
+        const repoPath = args.path ? path.resolve(args.path) : process.cwd();
+        const projectId = projectIdOverride ?? Buffer.from(repoPath).toString('base64url').slice(0, 32);
+        const response = await dispatchRaw('query', 'nexus', 'shape-check', { routeSymbol, projectId });
+        const durationMs = Date.now() - startTime;
+        if (!response.success) {
+            const msg = response.error?.message ?? 'Unknown error';
+            if (jsonOutput) {
+                process.stdout.write(JSON.stringify({
+                    success: false,
+                    error: { code: response.error?.code ?? 'E_SHAPE_CHECK_FAILED', message: msg },
+                    meta: {
+                        operation: 'nexus.shape-check',
+                        duration_ms: durationMs,
+                        timestamp: new Date().toISOString(),
+                    },
+                }, null, 2) + '\n');
+            }
+            else {
+                process.stderr.write(`[nexus] Error running shape-check: ${msg}\n`);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        const result = response.data;
+        if (jsonOutput) {
+            process.stdout.write(JSON.stringify({
+                success: true,
+                data: result,
+                meta: {
+                    operation: 'nexus.shape-check',
+                    duration_ms: durationMs,
+                    timestamp: new Date().toISOString(),
+                },
+            }, null, 2) + '\n');
+        }
+        else {
+            process.stdout.write(`[nexus] Shape Check for route ${routeSymbol}\n\n`);
+            process.stdout.write(`Handler: ${result.handlerId}\n`);
+            process.stdout.write(`Declared Shape: ${result.declaredShape}\n`);
+            process.stdout.write(`Overall Status: ${result.overallStatus}\n`);
+            process.stdout.write(`Recommendation: ${result.recommendation}\n\n`);
+            if (result.callers.length === 0) {
+                process.stdout.write('No callers found.\n');
+            }
+            else {
+                process.stdout.write(`Callers (${result.callers.length} total):\n`);
+                process.stdout.write('| Caller | File | Expected Shape | Status |\n');
+                process.stdout.write('|--------|------|---------------|---------|\n');
+                for (const caller of result.callers) {
+                    process.stdout.write(`| ${caller.callerName} | ${caller.callerFile} | ${caller.expectedShape} | ${caller.status} |\n`);
+                }
+                if (result.callers.some((c) => c.status !== 'compatible')) {
+                    process.stdout.write('\nIncompatibilities:\n');
+                    for (const caller of result.callers) {
+                        if (caller.status !== 'compatible') {
+                            process.stdout.write(`  - ${caller.callerName}: ${caller.diagnosis}\n`);
+                        }
+                    }
+                }
+            }
+        }
+    },
+});
+/**
+ * Root nexus command group — registers all nexus subcommands.
+ *
+ * Dispatches to nexus domain registry operations.
+ * @task T4554
+ */
+// ---------------------------------------------------------------------------
+// Living Brain traversal commands (T1068)
+// ---------------------------------------------------------------------------
+/** cleo nexus full-context — show all 5-substrate context for a code symbol */
+const fullContextCommand = defineCommand({
+    meta: {
+        name: 'full-context',
+        description: 'Show full Living Brain context for a symbol: NEXUS callers/callees, BRAIN memories, TASKS, sentient proposals, conduit threads',
+    },
+    args: {
+        symbol: {
+            type: 'positional',
+            description: 'Symbol name or nexus node ID',
+            required: true,
+        },
+        json: {
+            type: 'boolean',
+            description: 'Output result as JSON (LAFS envelope format)',
+        },
+    },
+    async run({ args }) {
+        const startTime = Date.now();
+        const jsonOutput = !!args.json;
+        const symbolId = args.symbol;
+        const response = await dispatchRaw('query', 'nexus', 'full-context', { symbol: symbolId });
+        if (!response.success) {
+            process.stderr.write(`[nexus] Error running full-context: ${response.error?.message ?? 'Unknown error'}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        const result = response.data;
+        const durationMs = Date.now() - startTime;
+        if (jsonOutput) {
+            process.stdout.write(JSON.stringify({
+                success: true,
+                data: result,
+                meta: {
+                    operation: 'nexus.full-context',
+                    duration_ms: durationMs,
+                    timestamp: new Date().toISOString(),
+                },
+            }, null, 2) + '\n');
+            return;
+        }
+        process.stdout.write(`\n## Living Brain: ${result.symbolId}\n\n`);
+        process.stdout.write(`### NEXUS\n`);
+        if (!result.nexus) {
+            process.stdout.write(`  (no nexus data — run 'cleo nexus analyze' first)\n`);
+        }
+        else {
+            const n = result.nexus;
+            process.stdout.write(`  Kind: ${n.kind}  File: ${n.filePath ?? '—'}\n`);
+            process.stdout.write(`  Callers (${n.callers.length}): ${n.callers
+                .map((c) => c.name)
+                .slice(0, 10)
+                .join(', ') || '—'}\n`);
+            process.stdout.write(`  Callees (${n.callees.length}): ${n.callees
+                .map((c) => c.name)
+                .slice(0, 10)
+                .join(', ') || '—'}\n`);
+            process.stdout.write(`  Plasticity: w=${result.plasticityWeight.totalWeight.toFixed(2)} edges=${result.plasticityWeight.edgeCount}\n`);
+        }
+        process.stdout.write(`\n### BRAIN memories (${result.brainMemories.length})\n`);
+        for (const m of result.brainMemories.slice(0, 10)) {
+            process.stdout.write(`  [${m.nodeType}] ${m.label.slice(0, 80)} (edge=${m.edgeType} w=${m.weight.toFixed(2)})\n`);
+        }
+        if (result.brainMemories.length === 0)
+            process.stdout.write(`  (none)\n`);
+        process.stdout.write(`\n### TASKS (${result.tasks.length})\n`);
+        for (const t of result.tasks.slice(0, 10))
+            process.stdout.write(`  ${t.taskId}  w=${t.weight.toFixed(2)}\n`);
+        if (result.tasks.length === 0)
+            process.stdout.write(`  (none)\n`);
+        process.stdout.write(`\n### SENTIENT proposals (${result.sentientProposals.length})\n`);
+        for (const p of result.sentientProposals.slice(0, 5))
+            process.stdout.write(`  ${p.title.slice(0, 80)} (w=${p.weight.toFixed(2)})\n`);
+        if (result.sentientProposals.length === 0)
+            process.stdout.write(`  (none)\n`);
+        process.stdout.write(`\n### CONDUIT threads (${result.conduitThreads.length})\n`);
+        for (const c of result.conduitThreads.slice(0, 5))
+            process.stdout.write(`  ${c.nodeId}  w=${c.weight.toFixed(2)}\n`);
+        if (result.conduitThreads.length === 0)
+            process.stdout.write(`  (none)\n`);
+        process.stdout.write(`\n(${durationMs}ms)\n`);
+    },
+});
+/** cleo nexus task-footprint — show full code impact for a task */
+const taskFootprintCommand = defineCommand({
+    meta: {
+        name: 'task-footprint',
+        description: 'Show full code impact of a task: files, symbols, blast radius, brain observations, decisions, risk tier',
+    },
+    args: {
+        taskId: {
+            type: 'positional',
+            description: 'Task ID (e.g., T001)',
+            required: true,
+        },
+        json: {
+            type: 'boolean',
+            description: 'Output result as JSON (LAFS envelope format)',
+        },
+    },
+    async run({ args }) {
+        const startTime = Date.now();
+        const jsonOutput = !!args.json;
+        const taskId = args.taskId;
+        const response = await dispatchRaw('query', 'nexus', 'task-footprint', { taskId });
+        if (!response.success) {
+            process.stderr.write(`[nexus] Error running task-footprint: ${response.error?.message ?? 'Unknown error'}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        const result = response.data;
+        const durationMs = Date.now() - startTime;
+        if (jsonOutput) {
+            process.stdout.write(JSON.stringify({
+                success: true,
+                data: result,
+                meta: {
+                    operation: 'nexus.task-footprint',
+                    duration_ms: durationMs,
+                    timestamp: new Date().toISOString(),
+                },
+            }, null, 2) + '\n');
+            return;
+        }
+        process.stdout.write(`\n## Task Code Impact: ${result.taskId}\n\n`);
+        process.stdout.write(`**Risk Score**: ${result.riskScore}\n`);
+        process.stdout.write(`**Files** (${result.files.length}): ${result.files.slice(0, 10).join(', ') || '—'}\n\n`);
+        process.stdout.write(`### Symbols (${result.symbols.length})\n`);
+        for (const s of result.symbols.slice(0, 20)) {
+            process.stdout.write(`  [${s.riskLevel}] ${s.label} (${s.kind})  d1=${s.directCallers}  total=${s.totalAffected}\n`);
+        }
+        if (result.symbols.length === 0)
+            process.stdout.write(`  (none — run 'cleo nexus analyze' or link task to symbols first)\n`);
+        process.stdout.write(`\n### Blast Radius\n`);
+        process.stdout.write(`  analyzed=${result.blastRadius.symbolsAnalyzed}  total_affected=${result.blastRadius.totalAffected}  max_risk=${result.blastRadius.maxRisk}\n`);
+        process.stdout.write(`\n### Brain Observations (${result.brainObservations.length})\n`);
+        for (const o of result.brainObservations.slice(0, 5))
+            process.stdout.write(`  [${o.nodeType}] ${o.label.slice(0, 80)}\n`);
+        process.stdout.write(`\n### Decisions (${result.decisions.length})\n`);
+        for (const d of result.decisions.slice(0, 5))
+            process.stdout.write(`  [${d.linkType}] ${d.decision.slice(0, 80)}\n`);
+        process.stdout.write(`\n(${durationMs}ms)\n`);
+    },
+});
+/** cleo nexus brain-anchors — show code anchors for a brain memory entry */
+const brainAnchorsCommand = defineCommand({
+    meta: {
+        name: 'brain-anchors',
+        description: 'Show code anchors for a brain memory entry: linked nexus nodes, tasks that touched them, plasticity signal',
+    },
+    args: {
+        entryId: {
+            type: 'positional',
+            description: 'Brain entry node ID (e.g., observation:abc123)',
+            required: true,
+        },
+        json: {
+            type: 'boolean',
+            description: 'Output result as JSON (LAFS envelope format)',
+        },
+    },
+    async run({ args }) {
+        const startTime = Date.now();
+        const jsonOutput = !!args.json;
+        const entryId = args.entryId;
+        const response = await dispatchRaw('query', 'nexus', 'brain-anchors', { entryId });
+        if (!response.success) {
+            process.stderr.write(`[nexus] Error running brain-anchors: ${response.error?.message ?? 'Unknown error'}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        const result = response.data;
+        const durationMs = Date.now() - startTime;
+        if (jsonOutput) {
+            process.stdout.write(JSON.stringify({
+                success: true,
+                data: result,
+                meta: {
+                    operation: 'nexus.brain-anchors',
+                    duration_ms: durationMs,
+                    timestamp: new Date().toISOString(),
+                },
+            }, null, 2) + '\n');
+            return;
+        }
+        process.stdout.write(`\n## Brain Code Anchors: ${result.entryId}\n\n`);
+        process.stdout.write(`**Plasticity Signal**: ${result.plasticitySignal.toFixed(2)}\n\n`);
+        process.stdout.write(`### Nexus Nodes (${result.nexusNodes.length})\n`);
+        for (const n of result.nexusNodes.slice(0, 20)) {
+            process.stdout.write(`  [${n.kind}] ${n.label}  file=${n.filePath ?? '—'}  edge=${n.edgeType}  w=${n.weight.toFixed(2)}\n`);
+        }
+        if (result.nexusNodes.length === 0)
+            process.stdout.write(`  (none)\n`);
+        process.stdout.write(`\n### Tasks for Nodes (${result.tasksForNodes.length} nodes with task links)\n`);
+        for (const entry of result.tasksForNodes.slice(0, 10)) {
+            const taskList = entry.tasks.map((t) => t.taskId).join(', ');
+            process.stdout.write(`  ${entry.nexusNodeId}: ${taskList}\n`);
+        }
+        if (result.tasksForNodes.length === 0)
+            process.stdout.write(`  (none)\n`);
+        process.stdout.write(`\n(${durationMs}ms)\n`);
+    },
+});
+// ---------------------------------------------------------------------------
+// Extended Code Reasoning commands (T1069)
+// ---------------------------------------------------------------------------
+/** cleo nexus why <symbol> — trace why a code symbol is structured this way */
+const whyCommand = defineCommand({
+    meta: {
+        name: 'why',
+        description: 'Trace why a code symbol is structured this way: walks BRAIN decisions, observations, and tasks via code_reference+documents+applies_to edges',
+    },
+    args: {
+        symbol: {
+            type: 'positional',
+            description: 'Symbol name or nexus node ID to trace',
+            required: true,
+        },
+        json: {
+            type: 'boolean',
+            description: 'Output result as JSON (LAFS envelope format)',
+        },
+    },
+    async run({ args }) {
+        const startTime = Date.now();
+        const jsonOutput = !!args.json;
+        const symbolId = args.symbol;
+        const response = await dispatchRaw('query', 'nexus', 'why', { symbol: symbolId });
+        if (!response.success) {
+            process.stderr.write(`[nexus] Error running why: ${response.error?.message ?? 'Unknown error'}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        const result = response.data;
+        const durationMs = Date.now() - startTime;
+        if (jsonOutput) {
+            process.stdout.write(JSON.stringify({
+                success: true,
+                data: result,
+                meta: {
+                    operation: 'nexus.why',
+                    duration_ms: durationMs,
+                    timestamp: new Date().toISOString(),
+                },
+            }, null, 2) + '\n');
+            return;
+        }
+        process.stdout.write(`\n## Code Reasoning: ${result.symbolId}\n\n`);
+        process.stdout.write(`**Narrative**: ${result.narrative}\n\n`);
+        process.stdout.write(`### Trace Chain (${result.chain.length} steps)\n`);
+        if (result.chain.length === 0) {
+            process.stdout.write(`  (no trace — run 'cleo nexus analyze' and 'cleo memory code-links' first)\n`);
+        }
+        else {
+            for (const step of result.chain) {
+                const refsStr = step.refs.length > 0 ? `  refs=[${step.refs.join(', ')}]` : '';
+                process.stdout.write(`  [${step.type}] ${step.id}: ${step.title.slice(0, 80)}${refsStr}\n`);
+            }
+        }
+        process.stdout.write(`\n(${durationMs}ms)\n`);
+    },
+});
+/** cleo nexus impact-full <symbol> — merged structural + task + brain impact report */
+const impactFullCommand = defineCommand({
+    meta: {
+        name: 'impact-full',
+        description: 'Full merged impact report for a code symbol: structural blast radius + open tasks + brain risk notes',
+    },
+    args: {
+        symbol: {
+            type: 'positional',
+            description: 'Symbol name or nexus node ID to analyze',
+            required: true,
+        },
+        json: {
+            type: 'boolean',
+            description: 'Output result as JSON (LAFS envelope format)',
+        },
+    },
+    async run({ args }) {
+        const startTime = Date.now();
+        const jsonOutput = !!args.json;
+        const symbolId = args.symbol;
+        const response = await dispatchRaw('query', 'nexus', 'impact-full', { symbol: symbolId });
+        if (!response.success) {
+            process.stderr.write(`[nexus] Error running impact-full: ${response.error?.message ?? 'Unknown error'}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        const result = response.data;
+        const durationMs = Date.now() - startTime;
+        if (jsonOutput) {
+            process.stdout.write(JSON.stringify({
+                success: true,
+                data: result,
+                meta: {
+                    operation: 'nexus.impact-full',
+                    duration_ms: durationMs,
+                    timestamp: new Date().toISOString(),
+                },
+            }, null, 2) + '\n');
+            return;
+        }
+        process.stdout.write(`\n## Full Impact: ${result.symbolId}\n\n`);
+        process.stdout.write(`**Merged Risk Score**: ${result.mergedRiskScore}\n`);
+        process.stdout.write(`**Narrative**: ${result.narrative}\n\n`);
+        process.stdout.write(`### Structural Blast Radius\n`);
+        process.stdout.write(`  d=1 (will break)=${result.structural.directCallers}` +
+            `  d=2 (likely affected)=${result.structural.likelyAffected}` +
+            `  d=3 (may need testing)=${result.structural.mayNeedTesting}` +
+            `  total=${result.structural.totalAffected}` +
+            `  risk=${result.structural.riskLevel}\n`);
+        process.stdout.write(`\n### Open Tasks (${result.openTasks.length})\n`);
+        for (const t of result.openTasks.slice(0, 10)) {
+            process.stdout.write(`  ${t.taskId}  ${t.label.slice(0, 60)}  w=${t.weight.toFixed(2)}\n`);
+        }
+        if (result.openTasks.length === 0)
+            process.stdout.write(`  (none)\n`);
+        process.stdout.write(`\n### Brain Risk Notes (${result.brainRiskNotes.length})\n`);
+        for (const n of result.brainRiskNotes.slice(0, 10)) {
+            process.stdout.write(`  [${n.nodeType}] ${n.label.slice(0, 70)}  edge=${n.edgeType}  w=${n.weight.toFixed(2)}\n`);
+        }
+        if (result.brainRiskNotes.length === 0)
+            process.stdout.write(`  (none)\n`);
+        process.stdout.write(`\n(${durationMs}ms)\n`);
+    },
+});
+// ---------------------------------------------------------------------------
+// T1071 — conduit-scan: link conduit messages to nexus symbols
+// ---------------------------------------------------------------------------
+/**
+ * cleo nexus conduit-scan — Scan conduit messages and link them to nexus symbols.
+ *
+ * Writes `conduit_mentions_symbol` edges to brain_page_edges (idempotent).
+ * Gracefully no-ops when conduit.db or nexus.db is absent.
+ *
+ * @task T1071
+ * @epic T1042
+ */
+const conduitScanCommand = defineCommand({
+    meta: {
+        name: 'conduit-scan',
+        description: 'Scan conduit messages for symbol mentions and link them to nexus nodes (conduit_mentions_symbol edges)',
+    },
+    args: {
+        json: {
+            type: 'boolean',
+            description: 'Output result as JSON (LAFS envelope format)',
+        },
+    },
+    async run({ args }) {
+        const startTime = Date.now();
+        const jsonOutput = !!args.json;
+        const response = await dispatchRaw('mutate', 'nexus', 'conduit-scan', {});
+        const durationMs = Date.now() - startTime;
+        if (!response.success) {
+            const msg = response.error?.message ?? 'Unknown error';
+            if (jsonOutput) {
+                process.stdout.write(JSON.stringify({
+                    success: false,
+                    error: { code: response.error?.code ?? 'E_CONDUIT_SCAN_FAILED', message: msg },
+                    meta: {
+                        operation: 'nexus.conduit-scan',
+                        duration_ms: durationMs,
+                        timestamp: new Date().toISOString(),
+                    },
+                }, null, 2) + '\n');
+            }
+            else {
+                process.stderr.write(`[nexus] Error running conduit-scan: ${msg}\n`);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        const result = response.data;
+        if (jsonOutput) {
+            process.stdout.write(JSON.stringify({
+                success: true,
+                data: result,
+                meta: {
+                    operation: 'nexus.conduit-scan',
+                    duration_ms: durationMs,
+                    timestamp: new Date().toISOString(),
+                },
+            }, null, 2) + '\n');
+        }
+        else {
+            process.stdout.write(`[nexus] conduit-scan complete: scanned=${result.scanned} linked=${result.linked} (${durationMs}ms)\n`);
+        }
+    },
+});
+// ---------------------------------------------------------------------------
+// T1067 — task-symbols: show symbols touched by a task
+// ---------------------------------------------------------------------------
+/**
+ * cleo nexus task-symbols <taskId> — Show code symbols touched by a task.
+ *
+ * Forward-lookup (task → symbols) via task_touches_symbol edges.
+ *
+ * @task T1067
+ * @epic T1042
+ */
+const taskSymbolsCommand = defineCommand({
+    meta: {
+        name: 'task-symbols',
+        description: 'Show code symbols touched by a task (task_touches_symbol forward-lookup)',
+    },
+    args: {
+        taskId: {
+            type: 'positional',
+            description: 'Task ID (e.g., T001)',
+            required: true,
+        },
+        json: {
+            type: 'boolean',
+            description: 'Output result as JSON (LAFS envelope format)',
+        },
+    },
+    async run({ args }) {
+        const startTime = Date.now();
+        const jsonOutput = !!args.json;
+        const taskId = args.taskId;
+        const response = await dispatchRaw('query', 'nexus', 'task-symbols', { taskId });
+        const durationMs = Date.now() - startTime;
+        if (!response.success) {
+            const msg = response.error?.message ?? 'Unknown error';
+            if (jsonOutput) {
+                process.stdout.write(JSON.stringify({
+                    success: false,
+                    error: { code: response.error?.code ?? 'E_TASK_SYMBOLS_FAILED', message: msg },
+                    meta: {
+                        operation: 'nexus.task-symbols',
+                        duration_ms: durationMs,
+                        timestamp: new Date().toISOString(),
+                    },
+                }, null, 2) + '\n');
+            }
+            else {
+                process.stderr.write(`[nexus] Error running task-symbols: ${msg}\n`);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        const data = response.data;
+        const { symbols } = data;
+        if (jsonOutput) {
+            process.stdout.write(JSON.stringify({
+                success: true,
+                data: { taskId, count: symbols.length, symbols },
+                meta: {
+                    operation: 'nexus.task-symbols',
+                    duration_ms: durationMs,
+                    timestamp: new Date().toISOString(),
+                },
+            }, null, 2) + '\n');
+        }
+        else {
+            if (symbols.length === 0) {
+                process.stdout.write(`[nexus] No symbols found for task ${taskId}.\n  Run 'cleo nexus analyze' and ensure git history is available.\n`);
+            }
+            else {
+                process.stdout.write(`[nexus] Symbols touched by ${taskId} (${symbols.length} total):\n\n`);
+                for (const s of symbols) {
+                    process.stdout.write(`  [${s.kind.padEnd(12)}] ${s.label.padEnd(50)}  w=${s.weight.toFixed(2)}  via=${s.matchStrategy}\n`);
+                }
+            }
+            process.stdout.write(`\n(${durationMs}ms)\n`);
+        }
+    },
+});
+// ---------------------------------------------------------------------------
+// T1058 — search-code: BM25 code symbol search against nexus.db
+// ---------------------------------------------------------------------------
+/**
+ * cleo nexus search-code <query> — BM25 search of code symbols in nexus.db.
+ *
+ * Uses the same BM25 index as the augment hook. Returns symbol names, kinds,
+ * file paths, and relevance scores.
+ *
+ * @task T1058
+ * @epic T1042
+ */
+const searchCodeCommand = defineCommand({
+    meta: {
+        name: 'search-code',
+        description: 'BM25 search of code symbols in nexus.db (augment BM25 index)',
+    },
+    args: {
+        query: {
+            type: 'positional',
+            description: 'Search query (symbol name, file pattern, or keyword)',
+            required: true,
+        },
+        limit: {
+            type: 'string',
+            description: 'Max results (default: 10)',
+            default: '10',
+        },
+        json: {
+            type: 'boolean',
+            description: 'Output result as JSON (LAFS envelope format)',
+        },
+    },
+    async run({ args }) {
+        const startTime = Date.now();
+        const jsonOutput = !!args.json;
+        const query = args.query;
+        const limit = parseInt(args.limit, 10) || 10;
+        await dispatchFromCli('query', 'nexus', 'augment', { pattern: query, limit }, { command: 'nexus' });
+        const durationMs = Date.now() - startTime;
+        if (!jsonOutput) {
+            process.stdout.write(`\n(${durationMs}ms)\n`);
+        }
+    },
+});
+// ---------------------------------------------------------------------------
+// T1065 — contracts: contract extraction and compatibility commands
+// ---------------------------------------------------------------------------
+/** cleo nexus contracts sync — extract and store contracts from current project */
+const contractsSyncCommand = defineCommand({
+    meta: {
+        name: 'sync',
+        description: 'Extract contracts (HTTP/gRPC/topic) from the current project and store them',
+    },
+    args: {
+        path: {
+            type: 'positional',
+            description: 'Path to project directory (default: cwd)',
+            required: false,
+        },
+        json: {
+            type: 'boolean',
+            description: 'Output result as JSON (LAFS envelope format)',
+        },
+        'project-id': {
+            type: 'string',
+            description: 'Override the project ID (default: auto-detected)',
+        },
+    },
+    async run({ args }) {
+        const startTime = Date.now();
+        const jsonOutput = !!args.json;
+        const repoPath = args.path ? path.resolve(args.path) : process.cwd();
+        const projectIdOverride = args['project-id'];
+        const projectId = projectIdOverride ?? Buffer.from(repoPath).toString('base64url').slice(0, 32);
+        const response = await dispatchRaw('mutate', 'nexus', 'contracts-sync', {
+            projectId,
+            repoPath,
+        });
+        const durationMs = Date.now() - startTime;
+        if (!response.success) {
+            const msg = response.error?.message ?? 'Unknown error';
+            if (jsonOutput) {
+                process.stdout.write(JSON.stringify({
+                    success: false,
+                    error: { code: response.error?.code ?? 'E_CONTRACTS_SYNC_FAILED', message: msg },
+                    meta: {
+                        operation: 'nexus.contracts.sync',
+                        duration_ms: durationMs,
+                        timestamp: new Date().toISOString(),
+                    },
+                }, null, 2) + '\n');
+            }
+            else {
+                process.stderr.write(`[nexus] Error running contracts sync: ${msg}\n`);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        const result = response.data;
+        if (jsonOutput) {
+            process.stdout.write(JSON.stringify({
+                success: true,
+                data: result,
+                meta: {
+                    operation: 'nexus.contracts.sync',
+                    duration_ms: durationMs,
+                    timestamp: new Date().toISOString(),
+                },
+            }, null, 2) + '\n');
+        }
+        else {
+            process.stdout.write(`[nexus] Contracts extracted from ${projectId}:\n` +
+                `  HTTP:  ${result.http}\n` +
+                `  gRPC:  ${result.grpc}\n` +
+                `  Topic: ${result.topic}\n` +
+                `  Total: ${result.totalCount}\n` +
+                `  (${durationMs}ms)\n`);
+        }
+    },
+});
+/** cleo nexus contracts show — show contract compatibility between two projects */
+const contractsShowCommand = defineCommand({
+    meta: {
+        name: 'show',
+        description: 'Show contract compatibility matrix between two registered projects',
+    },
+    args: {
+        'project-a': {
+            type: 'string',
+            description: 'First project name or ID',
+            required: true,
+        },
+        'project-b': {
+            type: 'string',
+            description: 'Second project name or ID',
+            required: true,
+        },
+        json: {
+            type: 'boolean',
+            description: 'Output result as JSON (LAFS envelope format)',
+        },
+    },
+    async run({ args }) {
+        const startTime = Date.now();
+        const jsonOutput = !!args.json;
+        const projectA = args['project-a'];
+        const projectB = args['project-b'];
+        const response = await dispatchRaw('query', 'nexus', 'contracts-show', { projectA, projectB });
+        const durationMs = Date.now() - startTime;
+        if (!response.success) {
+            const msg = response.error?.message ?? 'Unknown error';
+            if (jsonOutput) {
+                process.stdout.write(JSON.stringify({
+                    success: false,
+                    error: { code: response.error?.code ?? 'E_CONTRACTS_SHOW_FAILED', message: msg },
+                    meta: {
+                        operation: 'nexus.contracts.show',
+                        duration_ms: durationMs,
+                        timestamp: new Date().toISOString(),
+                    },
+                }, null, 2) + '\n');
+            }
+            else {
+                process.stderr.write(`[nexus] Error running contracts show: ${msg}\n`);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        const result = response.data;
+        if (jsonOutput) {
+            process.stdout.write(JSON.stringify({
+                success: true,
+                data: result,
+                meta: {
+                    operation: 'nexus.contracts.show',
+                    duration_ms: durationMs,
+                    timestamp: new Date().toISOString(),
+                },
+            }, null, 2) + '\n');
+        }
+        else {
+            if (result.matches.length === 0) {
+                process.stdout.write(`[nexus] No contract matches found between ${projectA} and ${projectB}.\n  Run 'cleo nexus contracts sync' on both projects first.\n`);
+            }
+            else {
+                process.stdout.write(`[nexus] Contract compatibility: ${projectA} ↔ ${projectB}\n  Compatible: ${result.compatibleCount}  Incompatible: ${result.incompatibleCount}  Partial: ${result.partialCount}\n  Overall: ${result.overallCompatibility}%\n\n`);
+                for (const m of result.matches.slice(0, 20)) {
+                    process.stdout.write(`  [${m.compatibility.toUpperCase().padEnd(12)}] ${m.contractA.id} ↔ ${m.contractB.id}  score=${m.score.toFixed(2)}\n`);
+                }
+                if (result.matches.length > 20) {
+                    process.stdout.write(`  (showing 20 of ${result.matches.length} matches)\n`);
+                }
+            }
+            process.stdout.write(`\n(${durationMs}ms)\n`);
+        }
+    },
+});
+/** cleo nexus contracts link-tasks — link contracts to tasks via task_touches_symbol edges */
+const contractsLinkTasksCommand = defineCommand({
+    meta: {
+        name: 'link-tasks',
+        description: 'Link extracted contracts to tasks that touch their source symbols',
+    },
+    args: {
+        path: {
+            type: 'positional',
+            description: 'Path to project directory (default: cwd)',
+            required: false,
+        },
+        json: {
+            type: 'boolean',
+            description: 'Output result as JSON (LAFS envelope format)',
+        },
+    },
+    async run({ args }) {
+        const startTime = Date.now();
+        const jsonOutput = !!args.json;
+        const repoPath = args.path ? path.resolve(args.path) : process.cwd();
+        const projectId = Buffer.from(repoPath).toString('base64url').slice(0, 32);
+        const response = await dispatchRaw('mutate', 'nexus', 'contracts-link-tasks', {
+            projectId,
+            repoPath,
+        });
+        const durationMs = Date.now() - startTime;
+        if (!response.success) {
+            const msg = response.error?.message ?? 'Unknown error';
+            if (jsonOutput) {
+                process.stdout.write(JSON.stringify({
+                    success: false,
+                    error: { code: response.error?.code ?? 'E_CONTRACTS_LINK_FAILED', message: msg },
+                    meta: {
+                        operation: 'nexus.contracts.link-tasks',
+                        duration_ms: durationMs,
+                        timestamp: new Date().toISOString(),
+                    },
+                }, null, 2) + '\n');
+            }
+            else {
+                process.stderr.write(`[nexus] Error running contracts link-tasks: ${msg}\n`);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        const result = response.data;
+        if (jsonOutput) {
+            process.stdout.write(JSON.stringify({
+                success: true,
+                data: result,
+                meta: {
+                    operation: 'nexus.contracts.link-tasks',
+                    duration_ms: durationMs,
+                    timestamp: new Date().toISOString(),
+                },
+            }, null, 2) + '\n');
+        }
+        else {
+            process.stdout.write(`[nexus] contracts link-tasks:\n` +
+                `  Commits processed: ${result.commitsProcessed}\n` +
+                `  Tasks found:       ${result.tasksFound}\n` +
+                `  Edges linked:      ${result.linked}\n` +
+                `  Last commit:       ${result.lastCommitHash ?? '—'}\n` +
+                `  (${durationMs}ms)\n`);
+        }
+    },
+});
+/** cleo nexus contracts — contract extraction and compatibility operations */
+const contractsCommand = defineCommand({
+    meta: { name: 'contracts', description: 'Contract extraction and compatibility operations' },
+    subCommands: {
+        sync: contractsSyncCommand,
+        show: contractsShowCommand,
+        'link-tasks': contractsLinkTasksCommand,
+    },
+});
+/** cleo nexus group — alias for contracts subcommand (spec parity: T1114) */
+const groupCommand = defineCommand({
+    meta: {
+        name: 'group',
+        description: 'Contract extraction and compatibility operations (alias for contracts)',
+    },
+    subCommands: {
+        sync: contractsSyncCommand,
+        show: contractsShowCommand,
+        'link-tasks': contractsLinkTasksCommand,
+    },
+});
+/** cleo nexus wiki — community-grouped wiki index with optional LOOM LLM summaries */
+const wikiCommand = defineCommand({
+    meta: {
+        name: 'wiki',
+        description: 'Generate community-grouped wiki index from nexus code graph',
+    },
+    args: {
+        output: {
+            type: 'string',
+            description: 'Output directory for wiki files (default: .cleo/wiki)',
+            alias: 'o',
+        },
+        community: {
+            type: 'string',
+            description: 'Filter generation to a single community ID (e.g. "community:3")',
+            alias: 'c',
+        },
+        incremental: {
+            type: 'boolean',
+            description: 'Only regenerate communities whose symbols changed since last wiki run (uses .cleo/wiki-state.json)',
+        },
+        json: {
+            type: 'boolean',
+            description: 'Output result as JSON (LAFS envelope format)',
+        },
+    },
+    async run({ args }) {
+        const startTime = Date.now();
+        const jsonOutput = !!args.json;
+        const outputDir = args.output ?? path.join(process.cwd(), '.cleo', 'wiki');
+        const communityFilter = args.community ?? undefined;
+        const isIncremental = !!args.incremental;
+        // SSoT-EXEMPT:loom-provider — LLM backend resolution for wiki generation requires
+        // CLI-side async provider wiring that cannot be passed through the dispatch layer.
+        // The dispatch 'wiki' op always uses loomProvider=null (scaffold mode). CLI-side
+        // wiring enables real LLM narratives when a backend is available.
+        // Resolve LOOM provider via the existing LLM backend resolver (warm tier).
+        // Falls back gracefully — null means scaffold mode.
+        // The 'ai' package lives in @cleocode/core's deps; we load it transitively.
+        let loomProvider = null;
+        try {
+            const { resolveLlmBackend } = await import('@cleocode/core/memory/llm-backend-resolver.js');
+            const backend = await resolveLlmBackend('warm');
+            if (backend !== null && backend.name !== 'transformers') {
+                // Wire as a simple text-completion function using the 'ai' package
+                // loaded via @cleocode/core's node_modules (avoids duplicate dep in cleo).
+                loomProvider = async (prompt) => {
+                    // Dynamic import at call time to avoid top-level resolution in cleo
+                    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+                    const aiMod = await import('ai');
+                    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+                    const generateTextFn = aiMod.generateText;
+                    const { text } = await generateTextFn({
+                        model: backend.model,
+                        prompt,
+                        maxTokens: 256,
+                    });
+                    return text;
+                };
+            }
+        }
+        catch {
+            // LOOM unavailable — scaffold mode (logged inside generateNexusWikiIndex)
+            loomProvider = null;
+        }
+        try {
+            // SSoT-EXEMPT:loom-provider — must call generateNexusWikiIndex directly to pass
+            // loomProvider. The dispatch 'wiki' op does not accept a loomProvider param.
+            const { generateNexusWikiIndex } = await import('@cleocode/core/nexus/wiki-index.js');
+            const result = await generateNexusWikiIndex(outputDir, process.cwd(), {
+                communityFilter,
+                incremental: isIncremental,
+                loomProvider,
+                projectRoot: process.cwd(),
+            });
+            const durationMs = Date.now() - startTime;
+            if (jsonOutput) {
+                process.stdout.write(JSON.stringify({
+                    success: result.success,
+                    data: result,
+                    meta: {
+                        operation: 'nexus.wiki',
+                        duration_ms: durationMs,
+                        timestamp: new Date().toISOString(),
+                    },
+                }, null, 2) + '\n');
+            }
+            else {
+                if (result.success) {
+                    const skippedNote = result.skippedCommunities && result.skippedCommunities.length > 0
+                        ? `\n  Skipped:     ${result.skippedCommunities.length} unchanged communities`
+                        : '';
+                    const loomNote = result.loomEnabled ? ' (LOOM narratives enabled)' : ' (scaffold mode)';
+                    process.stdout.write(`[nexus] wiki generated${loomNote}:\n` +
+                        `  Communities: ${result.communityCount}\n` +
+                        `  Files:       ${result.fileCount}\n` +
+                        `  Output:      ${outputDir}` +
+                        skippedNote +
+                        `\n  (${durationMs}ms)\n`);
+                }
+                else {
+                    process.stderr.write(`[nexus] wiki generation failed: ${result.error}\n`);
+                    process.exitCode = 1;
+                }
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (jsonOutput) {
+                process.stdout.write(JSON.stringify({
+                    success: false,
+                    error: { code: 'E_WIKI_GENERATION_FAILED', message: msg },
+                    meta: {
+                        operation: 'nexus.wiki',
+                        duration_ms: Date.now() - startTime,
+                        timestamp: new Date().toISOString(),
+                    },
+                }, null, 2) + '\n');
+            }
+            else {
+                process.stderr.write(`[nexus] Error generating wiki: ${msg}\n`);
+            }
+            process.exitCode = 1;
+        }
+    },
+});
+// ---------------------------------------------------------------------------
+// T1108 — Plasticity Query Commands (hot-paths, hot-nodes, cold-symbols)
+// ---------------------------------------------------------------------------
+/**
+ * cleo nexus hot-paths — List highest-weight relation edges (Hebbian plasticity).
+ *
+ * Reads nexus_relations ORDER BY weight DESC, co_accessed_count DESC.
+ * If no dream cycle has run yet (all weights 0), prints an informational
+ * note and exits cleanly with an empty table.
+ *
+ * @task T1108
+ */
+const hotPathsCommand = defineCommand({
+    meta: {
+        name: 'hot-paths',
+        description: 'List highest-weight relation edges by Hebbian plasticity weight',
+    },
+    args: {
+        limit: {
+            type: 'string',
+            description: 'Maximum number of edges to return (default: 20)',
+            default: '20',
+        },
+        json: {
+            type: 'boolean',
+            description: 'Output raw JSON',
+            default: false,
+        },
+    },
+    async run({ args }) {
+        const limit = Number.parseInt(args.limit, 10) || 20;
+        const jsonOutput = args.json;
+        const startTime = Date.now();
+        const response = await dispatchRaw('query', 'nexus', 'hot-paths', { limit });
+        const durationMs = Date.now() - startTime;
+        if (!response.success) {
+            process.stderr.write(`[nexus hot-paths] Error: ${response.error?.message ?? 'Unknown error'}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        const result = response.data;
+        if (jsonOutput) {
+            process.stdout.write(JSON.stringify({
+                success: true,
+                data: result,
+                meta: {
+                    operation: 'nexus.hot-paths',
+                    duration_ms: durationMs,
+                    timestamp: new Date().toISOString(),
+                },
+            }, null, 2) + '\n');
+            return;
+        }
+        if (result.note) {
+            process.stdout.write(`[nexus] Note: ${result.note}\n`);
+        }
+        if (result.paths.length === 0) {
+            process.stdout.write('[nexus] No hot paths found.\n');
+            return;
+        }
+        process.stdout.write('| Source | Target | Edge Type | Weight | Co-Access |\n| --- | --- | --- | --- | --- |\n');
+        for (const p of result.paths) {
+            process.stdout.write(`| ${p.sourceId} | ${p.targetId} | ${p.type} | ${p.weight.toFixed(4)} | ${p.coAccessedCount} |\n`);
+        }
+        process.stdout.write(`\n${result.count} edge(s) shown.\n`);
+    },
+});
+/**
+ * cleo nexus hot-nodes — List nodes with the highest aggregate Hebbian weight.
+ *
+ * Aggregates SUM(weight) per source node in nexus_relations, then joins
+ * nexus_nodes for label/kind/file. If no dream cycle has run yet the table
+ * is empty and an informational note is printed.
+ *
+ * @task T1108
+ */
+const hotNodesCommand = defineCommand({
+    meta: {
+        name: 'hot-nodes',
+        description: 'List symbols with highest aggregate Hebbian weight',
+    },
+    args: {
+        limit: {
+            type: 'string',
+            description: 'Maximum number of nodes to return (default: 20)',
+            default: '20',
+        },
+        json: {
+            type: 'boolean',
+            description: 'Output raw JSON',
+            default: false,
+        },
+    },
+    async run({ args }) {
+        const limit = Number.parseInt(args.limit, 10) || 20;
+        const jsonOutput = args.json;
+        const startTime = Date.now();
+        const response = await dispatchRaw('query', 'nexus', 'hot-nodes', { limit });
+        const durationMs = Date.now() - startTime;
+        if (!response.success) {
+            process.stderr.write(`[nexus hot-nodes] Error: ${response.error?.message ?? 'Unknown error'}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        const result = response.data;
+        if (jsonOutput) {
+            process.stdout.write(JSON.stringify({
+                success: true,
+                data: result,
+                meta: {
+                    operation: 'nexus.hot-nodes',
+                    duration_ms: durationMs,
+                    timestamp: new Date().toISOString(),
+                },
+            }, null, 2) + '\n');
+            return;
+        }
+        if (result.note) {
+            process.stdout.write(`[nexus] Note: ${result.note}\n`);
+        }
+        if (result.nodes.length === 0) {
+            process.stdout.write('[nexus] No hot nodes found.\n');
+            return;
+        }
+        process.stdout.write('| Symbol | Total Weight | File | Kind |\n| --- | --- | --- | --- |\n');
+        for (const n of result.nodes) {
+            const file = n.filePath ?? '(unknown)';
+            process.stdout.write(`| ${n.label} | ${n.totalWeight.toFixed(4)} | ${file} | ${n.kind} |\n`);
+        }
+        process.stdout.write(`\n${result.count} node(s) shown.\n`);
+    },
+});
+/**
+ * cleo nexus cold-symbols — List symbols that have gone cold.
+ *
+ * Returns symbols whose most-recent access (max last_accessed_at across
+ * incident edges) is older than `--days` ago AND max weight < 0.1.
+ * If last_accessed_at is NULL for all incident edges (no dream cycle run)
+ * those symbols are included as infinitely cold.
+ *
+ * @task T1108
+ */
+const coldSymbolsCommand = defineCommand({
+    meta: {
+        name: 'cold-symbols',
+        description: 'List cold symbols (stale access + low weight) for pruning candidates',
+    },
+    args: {
+        days: {
+            type: 'string',
+            description: 'Age threshold in days (default: 30)',
+            default: '30',
+        },
+        json: {
+            type: 'boolean',
+            description: 'Output raw JSON',
+            default: false,
+        },
+    },
+    async run({ args }) {
+        const thresholdDays = Number.parseInt(args.days, 10) || 30;
+        const jsonOutput = args.json;
+        const startTime = Date.now();
+        const response = await dispatchRaw('query', 'nexus', 'cold-symbols', { days: thresholdDays });
+        const durationMs = Date.now() - startTime;
+        if (!response.success) {
+            process.stderr.write(`[nexus cold-symbols] Error: ${response.error?.message ?? 'Unknown error'}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        const result = response.data;
+        if (jsonOutput) {
+            process.stdout.write(JSON.stringify({
+                success: true,
+                data: result,
+                meta: {
+                    operation: 'nexus.cold-symbols',
+                    duration_ms: durationMs,
+                    timestamp: new Date().toISOString(),
+                },
+            }, null, 2) + '\n');
+            return;
+        }
+        if (result.note) {
+            process.stdout.write(`[nexus] Note: ${result.note}\n`);
+        }
+        if (result.symbols.length === 0) {
+            process.stdout.write(`[nexus] No cold symbols found (threshold: ${thresholdDays} days, weight < 0.1).\n`);
+            return;
+        }
+        process.stdout.write('| Symbol | Last Accessed | Weight | File |\n| --- | --- | --- | --- |\n');
+        for (const s of result.symbols) {
+            const lastAccessed = s.lastAccessed ?? '(never)';
+            const file = s.filePath ?? '(unknown)';
+            process.stdout.write(`| ${s.label} | ${lastAccessed} | ${s.maxWeight.toFixed(4)} | ${file} |\n`);
+        }
+        process.stdout.write(`\n${result.count} cold symbol(s) found (threshold: ${thresholdDays} days).\n`);
+    },
+});
+/**
+ * cleo nexus top-entries — List top-weighted symbols from nexus_relations.
+ *
+ * Returns the highest-weighted source nodes from the Hebbian plasticity
+ * relation graph (T998). Each entry is aggregated SUM(weight) per source_id
+ * joined with nexus_nodes for label / kind / file-path. Supports optional
+ * `--kind` filter (e.g. function, method, class) and `--limit` (default 20).
+ *
+ * Routes through the dispatch layer so all transports (CLI, TUI, agents) see
+ * the same LAFS envelope shape (see `handleTopEntries` in
+ * `packages/cleo/src/dispatch/domains/nexus.ts`).
+ *
+ * @task T1013
+ * @epic T1006
+ */
+// ── T1386: sigil sync + list ─────────────────────────────────────────
+/** cleo nexus sigil sync — populate sigils table from canonical CANT agents */
+const sigilSyncCommand = defineCommand({
+    meta: {
+        name: 'sync',
+        description: 'Populate the nexus.db sigils table with one row per canonical CANT agent (cleo-subagent + 5 seed roles + 2 meta agents). Idempotent.',
+    },
+    args: {
+        json: {
+            type: 'boolean',
+            description: 'Output as JSON (LAFS envelope format)',
+        },
+    },
+    async run() {
+        await dispatchFromCli('mutate', 'nexus', 'sigil.sync', {}, { command: 'nexus' });
+    },
+});
+/** cleo nexus sigil list — list every sigil currently stored in nexus.db */
+const sigilListCommand = defineCommand({
+    meta: {
+        name: 'list',
+        description: 'List every sigil currently stored in nexus.db, optionally filtered by role.',
+    },
+    args: {
+        role: {
+            type: 'string',
+            description: 'Filter by role (e.g. "orchestrator", "lead", "worker", "specialist", "subagent")',
+        },
+    },
+    async run({ args }) {
+        await dispatchFromCli('query', 'nexus', 'sigil.list', { role: args.role }, { command: 'nexus' });
+    },
+});
+/** cleo nexus sigil — group alias for `sync` and `list`. */
+const sigilCommand = defineCommand({
+    meta: {
+        name: 'sigil',
+        description: 'Sigil (peer-card) operations — sync from canonical CANT agents, list current rows',
+    },
+    subCommands: {
+        sync: sigilSyncCommand,
+        list: sigilListCommand,
+    },
+});
+const topEntriesCommand = defineCommand({
+    meta: {
+        name: 'top-entries',
+        description: 'List top-weighted symbols from nexus_relations by weight DESC',
+    },
+    args: {
+        limit: {
+            type: 'string',
+            description: 'Maximum number of entries to return (default: 20)',
+            default: '20',
+        },
+        kind: {
+            type: 'string',
+            description: 'Filter by nexus_nodes.kind (e.g. function, method, class, interface, type_alias)',
+        },
+        json: {
+            type: 'boolean',
+            description: 'Output result as JSON (LAFS envelope format)',
+        },
+    },
+    async run({ args }) {
+        const limit = Number.parseInt(args.limit, 10) || 20;
+        const kind = args.kind ?? undefined;
+        const jsonOutput = !!args.json;
+        const params = { limit };
+        if (kind !== undefined && kind.length > 0)
+            params.kind = kind;
+        await dispatchFromCli('query', 'nexus', 'top-entries', params, {
+            command: 'nexus',
+            operation: 'nexus.top-entries',
+            ...(jsonOutput ? { json: true } : {}),
+        });
+    },
+});
+export const nexusCommand = defineCommand({
+    meta: { name: 'nexus', description: 'Cross-project NEXUS operations' },
+    subCommands: {
+        init: initCommand,
+        register: registerCommand,
+        unregister: unregisterCommand,
+        list: listCommand,
+        status: statusCommand,
+        show: showCommand,
+        resolve: resolveCommand,
+        discover: discoverCommand,
+        search: searchCommand,
+        augment: augmentCommand,
+        setup: setupCommand,
+        deps: depsCommand,
+        'critical-path': criticalPathCommand,
+        blocking: blockingCommand,
+        orphans: orphansCommand,
+        sync: syncCommand,
+        reconcile: reconcileCommand,
+        graph: graphCommand,
+        'share-status': shareStatusCommand,
+        'transfer-preview': transferPreviewCommand,
+        transfer: transferCommand,
+        permission: permissionCommand,
+        share: shareCommand,
+        clusters: clustersCommand,
+        flows: flowsCommand,
+        context: contextCommand,
+        impact: impactCommand,
+        analyze: analyzeCommand,
+        query: queryCommand,
+        projects: projectsCommand,
+        'refresh-bridge': refreshBridgeCommand,
+        export: exportCommand,
+        diff: diffCommand,
+        'route-map': routeMapCommand,
+        'shape-check': shapeCheckCommand,
+        'full-context': fullContextCommand,
+        'task-footprint': taskFootprintCommand,
+        'brain-anchors': brainAnchorsCommand,
+        why: whyCommand,
+        'impact-full': impactFullCommand,
+        // T1071 — conduit scan
+        'conduit-scan': conduitScanCommand,
+        // T1067 — task symbols
+        'task-symbols': taskSymbolsCommand,
+        // T1058 — code symbol search
+        'search-code': searchCodeCommand,
+        // T1065 — contract registry
+        contracts: contractsCommand,
+        // T1114 — group alias for contracts
+        group: groupCommand,
+        // T1060 — wiki index
+        wiki: wikiCommand,
+        // T1108 — plasticity queries
+        'hot-paths': hotPathsCommand,
+        'hot-nodes': hotNodesCommand,
+        'cold-symbols': coldSymbolsCommand,
+        // T1013 / T1006 — top-weighted symbols by nexus_relations.weight
+        'top-entries': topEntriesCommand,
+        // T1386 — sigil sync + list (canonical CANT agent peer cards)
+        sigil: sigilCommand,
+    },
+    async run({ cmd, rawArgs }) {
+        const firstArg = rawArgs?.find((a) => !a.startsWith('-'));
+        if (firstArg && cmd.subCommands && firstArg in cmd.subCommands)
+            return;
+        await showUsage(cmd);
+    },
+});
+//# sourceMappingURL=nexus.js.map