@aitherium/shell-cli 1.1.0 → 1.11.0

package/dist/commands.js

@@ -2,14 +2,17 @@
  * Built-in slash commands for AitherShell CLI.
  */
 import { execSync, spawn } from 'node:child_process';
-import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, statSync } from 'node:fs';
 import { resolve, join, dirname, basename, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline';
 import { homedir } from 'node:os';
 import chalk from 'chalk';
 import ora from 'ora';
-import { formatTable, getSessionArtifacts, clearSessionArtifacts, resolveImagePath } from './renderer.js';
+import { getActiveConfig } from './config.js';
+import { getRemoteMcpClient } from './mcp-client.js';
+import { formatTable, getSessionArtifacts, clearSessionArtifacts, resolveImagePath, osc8Link, addSessionArtifact } from './renderer.js';
+import { loadSession, saveSession, listSessions, deleteSession, transcriptMarkdown, sessionTokens, } from './session-store.js';
 import { loginWithPassword, verify2FA, register, logoutSession, validateToken, buildProfile, setProfile, clearProfile, getActiveProfile, getActiveUser, getActiveToken, requestEmailOTP, verifyEmailOTP, requestDeviceCode, pollDeviceToken, } from './auth.js';
 const ONBOARD_CODE_EXTENSIONS = new Set([
     '.py', '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.java', '.go', '.rs', '.cs',
@@ -216,13 +219,50 @@ function parseToolResponse(payload) {
     }
     return raw;
 }
-async function callMcpTool(client, tool, params) {
+/**
+ * Invoke an MCP tool, routing to the right transport:
+ *   - remote MCP gateway (config.mcpUrl, MCP protocol) when configured —
+ *     so AitherNode tools work against a cloud workspace; else
+ *   - the chat backend's REST /tools/call (local Genesis).
+ * Returns the parsed tool output, or `{ error, status }` on failure.
+ */
+export async function invokeMcpTool(client, tool, params) {
+    const remote = getRemoteMcpClient(getActiveConfig());
+    if (remote) {
+        try {
+            const result = await remote.callTool(tool, params);
+            const parsed = parseToolResponse(result);
+            if (result?.isError) {
+                return { error: typeof parsed === 'string' ? parsed : JSON.stringify(parsed), status: 0 };
+            }
+            return parsed;
+        }
+        catch (err) {
+            return { error: err?.message || 'MCP tool call failed', status: 0 };
+        }
+    }
     const response = await client.postDetailed('/tools/call', { tool, params });
     if (response?.error) {
         return { error: response.error, status: response.status || 0 };
     }
     return parseToolResponse(response);
 }
+async function callMcpTool(client, tool, params) {
+    return invokeMcpTool(client, tool, params);
+}
+/** Copy text to the OS clipboard (win32 clip / macOS pbcopy / Linux xclip|wl-copy). */
+function copyToClipboard(text) {
+    const plat = process.platform;
+    const cmd = plat === 'win32' ? 'clip'
+        : plat === 'darwin' ? 'pbcopy'
+            : 'xclip -selection clipboard';
+    const p = spawn(cmd, { shell: true });
+    p.on('error', () => { }); // don't crash if the clipboard tool is missing
+    // `end(text)` writes then closes in one shot — avoids a stdin backpressure
+    // hang on large/multiline content (a bare write+end can deadlock the pipe).
+    p.stdin.on('error', () => { });
+    p.stdin.end(text);
+}
 const COMMANDS = {
     help: {
         description: 'Show available commands',
@@ -239,6 +279,213 @@ const COMMANDS = {
             console.log();
         },
     },
+    // ── Conversation QoL (transcript-backed) ──
+    chats: {
+        description: 'List, resume, or delete saved chat conversations',
+        usage: '/chats [resume <id> | delete <id>]',
+        handler: async (_client, args, config) => {
+            const parts = args.trim().split(/\s+/);
+            const sub = parts[0] || '';
+            if (sub === 'resume' && parts[1]) {
+                const entry = loadSession(parts[1]);
+                if (!entry) {
+                    console.log(chalk.yellow(`  Session ${parts[1]} not found locally.`));
+                    return;
+                }
+                config.sessionId = entry.sessionId;
+                console.log(chalk.green(`  ↩ Switched to ${entry.sessionId.slice(0, 8)} (${entry.messages.length} msgs) — continues via session id.`));
+                console.log(chalk.dim(`  For a full replay, relaunch: aither --resume ${entry.sessionId}`));
+                return;
+            }
+            if (sub === 'delete' && parts[1]) {
+                console.log(deleteSession(parts[1]) ? chalk.green(`  Deleted ${parts[1]}.`) : chalk.yellow('  Not found.'));
+                return;
+            }
+            const list = listSessions(20);
+            if (!list.length) {
+                console.log(chalk.dim('  No saved chats yet.'));
+                return;
+            }
+            console.log();
+            console.log(formatTable(['  Session', 'Agent', 'Msgs', 'Updated'], list.map(s => [chalk.cyan(s.sessionId.slice(0, 8)), s.agent, String(s.messageCount), new Date(s.updatedAt).toLocaleString()])));
+            console.log(chalk.dim('\n  /chats resume <id>   ·   /chats delete <id>   ·   aither --continue'));
+            console.log();
+        },
+    },
+    export: {
+        description: 'Export the current conversation transcript to a file',
+        usage: '/export [path] [--json]',
+        handler: async (_client, args, config) => {
+            const entry = loadSession(config.sessionId);
+            if (!entry || !entry.messages.length) {
+                console.log(chalk.dim('  Nothing to export yet.'));
+                return;
+            }
+            const json = /--json\b/.test(args);
+            const pathArg = args.replace(/--json\b/, '').trim();
+            const file = pathArg || join(homedir(), '.aither', 'exports', `${config.sessionId.slice(0, 8)}.${json ? 'json' : 'md'}`);
+            try {
+                mkdirSync(dirname(file), { recursive: true });
+                writeFileSync(file, json ? JSON.stringify(entry, null, 2) : transcriptMarkdown(entry));
+                console.log(chalk.green(`  ✓ Exported ${entry.messages.length} messages → ${file}`));
+            }
+            catch (e) {
+                console.log(chalk.red(`  Export failed: ${e.message}`));
+            }
+        },
+    },
+    copy: {
+        description: 'Copy the last assistant answer to the clipboard',
+        handler: async (_client, _args, config) => {
+            const entry = loadSession(config.sessionId);
+            const last = entry?.messages.slice().reverse().find(m => m.role === 'assistant');
+            if (!last) {
+                console.log(chalk.dim('  No answer to copy yet.'));
+                return;
+            }
+            try {
+                copyToClipboard(last.content);
+                console.log(chalk.green(`  ✓ Copied ${last.content.length} chars to clipboard.`));
+            }
+            catch (e) {
+                console.log(chalk.yellow(`  Could not copy: ${e.message}`));
+            }
+        },
+    },
+    tokens: {
+        description: 'Show token usage for the current session',
+        handler: async (_client, _args, config) => {
+            const entry = loadSession(config.sessionId);
+            if (!entry) {
+                console.log(chalk.dim('  No usage recorded yet.'));
+                return;
+            }
+            const turns = entry.messages.filter(m => m.role === 'assistant').length;
+            console.log(chalk.bold(`\n  Session ${config.sessionId.slice(0, 8)}`));
+            console.log(`  Turns: ${turns}   ·   Tokens: ${sessionTokens(entry)}   ·   Messages: ${entry.messages.length}\n`);
+        },
+    },
+    rewind: {
+        description: 'Drop the last N turns from the conversation context',
+        usage: '/rewind [N]',
+        handler: async (_client, args, config) => {
+            const n = Math.max(1, Number(args.trim()) || 1);
+            const entry = loadSession(config.sessionId);
+            if (!entry || !entry.messages.length) {
+                console.log(chalk.dim('  Nothing to rewind.'));
+                return;
+            }
+            const removed = entry.messages.splice(-n * 2, n * 2);
+            saveSession(entry);
+            console.log(chalk.green(`  ↶ Rewound ${Math.floor(removed.length / 2)} turn(s). ${entry.messages.length} messages left.`));
+        },
+    },
+    compact: {
+        description: 'Summarize the conversation and compact the context',
+        handler: async (client, _args, config) => {
+            const entry = loadSession(config.sessionId);
+            if (!entry || entry.messages.length < 2) {
+                console.log(chalk.dim('  Not enough conversation to compact.'));
+                return;
+            }
+            const spinner = ora('Summarizing conversation...').start();
+            let summary = '';
+            try {
+                for await (const ev of client.streamChat('Summarize our conversation so far into a concise brief I can use as context to continue — key facts, decisions, and open threads.', { sessionId: config.sessionId, agent: config.defaultAgent, model: config.model })) {
+                    const d = ev.data || {};
+                    if (ev.type === 'token')
+                        summary += (d.t || d.token || '');
+                    else if ((ev.type === 'message' || ev.type === 'answer' || ev.type === 'final_answer') && !summary)
+                        summary = String(d.answer || d.content || d.message || '');
+                }
+            }
+            catch (e) {
+                spinner.stop();
+                console.log(chalk.yellow(`  Compact failed: ${e.message} — transcript kept.`));
+                return;
+            }
+            spinner.stop();
+            // Guard: never replace a real conversation with an empty/truncated summary.
+            if (summary.trim().length < 40) {
+                console.log(chalk.yellow('  Summary too short — transcript kept unchanged.'));
+                return;
+            }
+            entry.messages = [{ role: 'assistant', content: `[Conversation summary]\n${summary.trim()}`, timestamp: new Date().toISOString() }];
+            saveSession(entry);
+            console.log(chalk.green(`  ✓ Compacted to a ${summary.length}-char summary (kept as context).`));
+        },
+    },
+    trace: {
+        description: 'Replay the live trace (events + timing) of a recent turn',
+        usage: '/trace [N]   — show the last turn (or the N-th most recent)',
+        handler: async (_client, args) => {
+            const sessRoot = join(homedir(), '.aither', 'sessions');
+            if (!existsSync(sessRoot)) {
+                console.log(chalk.dim('  No traces recorded yet.'));
+                return;
+            }
+            // Gather all persisted turn profiles; filename is an ISO timestamp so a
+            // lexical sort gives recency without stat() calls.
+            const files = [];
+            for (const sid of readdirSync(sessRoot)) {
+                const dir = join(sessRoot, sid);
+                let entries = [];
+                try {
+                    entries = readdirSync(dir);
+                }
+                catch {
+                    continue;
+                }
+                for (const f of entries) {
+                    if (f.endsWith('.json'))
+                        files.push({ path: join(dir, f), name: f });
+                }
+            }
+            if (!files.length) {
+                console.log(chalk.dim('  No traces recorded yet.'));
+                return;
+            }
+            files.sort((a, b) => b.name.localeCompare(a.name));
+            const idx = Math.min(Math.max(0, (parseInt(args.trim(), 10) || 1) - 1), files.length - 1);
+            let profile;
+            try {
+                profile = JSON.parse(readFileSync(files[idx].path, 'utf8'));
+            }
+            catch (e) {
+                console.log(chalk.red(`  Failed to read trace: ${e}`));
+                return;
+            }
+            const events = profile.events || [];
+            console.log(chalk.bold(`\n  Trace — ${(profile.prompt || profile.session_id || '').slice(0, 60)} ` +
+                `(${events.length} events · ${((profile.duration_ms || 0) / 1000).toFixed(1)}s)\n`));
+            const t0 = events.length ? (events[0].data?._ts || 0) : 0;
+            let tokenRun = 0;
+            const flushTokens = () => {
+                if (tokenRun > 0) {
+                    console.log(chalk.dim(`           · ${tokenRun} token chunk(s) streamed`));
+                    tokenRun = 0;
+                }
+            };
+            for (const ev of events) {
+                if (ev.type === 'token') {
+                    tokenRun++;
+                    continue;
+                }
+                flushTokens();
+                if (ev.type === 'heartbeat')
+                    continue;
+                const ts = ev.data?._ts || 0;
+                const rel = t0 ? ((ts - t0) / 1000).toFixed(2).padStart(6) : '   ?  ';
+                const d = ev.data || {};
+                const detail = d.detail || d.substage || d.summary || d.step ||
+                    d.message || d.status || d.model || d.stage || '';
+                console.log(chalk.dim(`  +${rel}s `) + chalk.cyan(ev.type) +
+                    (detail ? chalk.dim(`  ${String(detail).slice(0, 90)}`) : ''));
+            }
+            flushTokens();
+            console.log(chalk.dim(`\n  (showing ${idx + 1}/${files.length} — /trace ${idx + 2} for older)\n`));
+        },
+    },
     status: {
         description: 'Show system status',
         handler: async (client) => {
@@ -360,6 +607,9 @@ const COMMANDS = {
             ]);
             console.log(formatTable(['  Agent', 'Role', 'Status'], rows));
             console.log();
+            console.log(chalk.dim('  Want more? 43 agents available — /explore agents'));
+            console.log(chalk.dim('  Try premium: @demiurge, @hydra, @athena, @lyra'));
+            console.log();
         },
     },
     services: {
@@ -461,6 +711,128 @@ const COMMANDS = {
             console.log();
         },
     },
+    lyra: {
+        description: 'Ask Lyra (the Research Librarian) to research a question',
+        usage: '/lyra "question" [--effort quick_glance|library_session|deep_dive|leave_no_stone|N]',
+        handler: async (client, args) => {
+            // Effort tiers map onto the platform 1-10 effort scale.
+            const TIERS = {
+                quick_glance: 3, library_session: 5, deep_dive: 7, leave_no_stone: 9,
+            };
+            let question = args;
+            let effort = TIERS.library_session;
+            const effortMatch = args.match(/--effort\s+(\S+)/);
+            if (effortMatch) {
+                const raw = effortMatch[1].toLowerCase();
+                effort = TIERS[raw] ?? (Number(raw) || effort);
+                question = question.replace(effortMatch[0], '');
+            }
+            question = question.replace(/^["']|["']$/g, '').trim();
+            if (!question) {
+                console.log(chalk.yellow(`  Usage: ${COMMANDS.lyra.usage}`));
+                return;
+            }
+            const tierName = Object.entries(TIERS).find(([, v]) => v === effort)?.[0] || `effort ${effort}`;
+            const spinner = ora(`Lyra is researching (${tierName})...`).start();
+            let result;
+            try {
+                result = await client.forgeDispatch(question, { agent: 'lyra', effort });
+            }
+            catch (err) {
+                spinner.stop();
+                console.log(chalk.red(`  Error: ${err.message}`));
+                return;
+            }
+            spinner.stop();
+            if (result?.error) {
+                console.log(chalk.red(`  Error: ${result.error}`));
+                return;
+            }
+            console.log();
+            const output = result?.response || result?.result || result?.output;
+            console.log(output || JSON.stringify(result, null, 2));
+            const sources = result?.sources || result?.citations;
+            if (Array.isArray(sources) && sources.length) {
+                console.log(chalk.dim('\n  Sources:'));
+                for (const s of sources.slice(0, 8)) {
+                    console.log(chalk.dim(`   - ${typeof s === 'string' ? s : s.url || s.title || JSON.stringify(s)}`));
+                }
+            }
+            console.log();
+        },
+    },
+    atlas: {
+        description: "Atlas PM board — latest cycle, in-flight items, or run a cycle",
+        usage: '/atlas [board|tick] [--items N] [--sync]',
+        handler: async (client, args) => {
+            const sub = (args.trim().split(/\s+/)[0] || 'board').toLowerCase();
+            if (sub === 'tick') {
+                const itemsMatch = args.match(/--items\s+(\d+)/);
+                const sync = /--sync\b/.test(args);
+                const body = { max_items: itemsMatch ? Number(itemsMatch[1]) : 1 };
+                if (sync)
+                    body.sync = true;
+                const spinner = ora(sync ? 'Running one Atlas PM cycle (sync)...' : 'Queuing an Atlas PM cycle...').start();
+                const result = await client.post('/spec/factory/pm-tick', body);
+                spinner.stop();
+                if (!result || result.error) {
+                    console.log(chalk.red(`  Error: ${result?.error || 'pm-tick failed (is Genesis up?)'}`));
+                    return;
+                }
+                console.log();
+                if (result.job_id) {
+                    console.log(`  Cycle queued: ${chalk.cyan(result.job_id)}`);
+                    console.log(chalk.dim('  Poll with /atlas board (or /spec status APIs) for results.'));
+                }
+                else {
+                    const picked = result.picked || [];
+                    console.log(`  Cycle ${chalk.cyan(result.cycle_id || '?')} — backlog ${result.backlog_size ?? '?'}, picked ${picked.length}`);
+                    for (const p of picked) {
+                        const pr = p.pr_number ? chalk.green(`PR #${p.pr_number}`) : chalk.dim(p.status || 'no PR');
+                        console.log(`   - ${p.title || p.item}: ${pr}`);
+                    }
+                }
+                console.log();
+                return;
+            }
+            // Default: the board — latest PM cycle summary + in-flight items.
+            const spinner = ora('Fetching the Atlas board...').start();
+            const result = await client.get('/spec/factory/pm-latest');
+            spinner.stop();
+            if (!result) {
+                console.log(chalk.red('  Could not reach the PM board (is Genesis up?)'));
+                return;
+            }
+            console.log();
+            const cycle = result.latest_cycle;
+            if (cycle) {
+                const summary = cycle.summary || cycle;
+                console.log(`  Latest cycle: ${chalk.cyan(cycle.cycle_id || summary.cycle_id || '?')} (${cycle.status || '?'})`);
+                const picked = summary.picked || [];
+                for (const p of picked) {
+                    const pr = p.pr_number ? chalk.green(`PR #${p.pr_number}`) : chalk.dim(p.status || '');
+                    console.log(`   - ${p.title || p.item}: ${pr} ${p.review ? chalk.dim(`[review: ${p.review}]`) : ''}`);
+                }
+            }
+            else {
+                console.log(chalk.dim('  No PM cycle has run yet — try /atlas tick'));
+            }
+            const inflight = result.in_flight || [];
+            if (inflight.length) {
+                console.log();
+                const rows = inflight.slice(0, 20).map((it) => [
+                    chalk.cyan((it.key || it.item || '?').slice(0, 28)),
+                    (it.title || '').slice(0, 44),
+                    it.status || '?',
+                    it.pr_number ? `#${it.pr_number}` : '',
+                ]);
+                console.log(formatTable(['  Item', 'Title', 'Status', 'PR'], rows));
+                if (inflight.length > 20)
+                    console.log(chalk.dim(`\n  ... and ${inflight.length - 20} more`));
+            }
+            console.log();
+        },
+    },
     logs: {
         description: 'Show recent log entries from Chronicle',
         usage: '/logs [--level error] [--limit 20] [--service name]',
@@ -1513,8 +1885,8 @@ const COMMANDS = {
      * NEW COMMANDS — wired to actual Genesis endpoints
      * ──────────────────────────────────────────────────────────────────── */
     memory: {
-        description: 'Recall or store a memory',
-        usage: '/memory recall <query>  |  /memory remember <text>',
+        description: 'Recall, store, or forget a memory',
+        usage: '/memory recall <query>  |  /memory remember <text>  |  /memory forget <text>',
         handler: async (client, args) => {
             const parts = args.trim().split(/\s+/);
             const sub = (parts[0] || '').toLowerCase();
@@ -1541,8 +1913,27 @@ const COMMANDS = {
                 }
                 console.log();
             }
+            else if (sub === 'forget' && text) {
+                // Cross-tier hard-delete: removes every copy of memories CONTAINING this
+                // phrase (Spirit, Nexus, WorkingMemory, graph). Be specific.
+                const spinner = ora('Forgetting...').start();
+                const result = await client.post('/external/memory/forget', { content_match: text });
+                spinner.stop();
+                if (result?.error || result?.detail) {
+                    console.log(chalk.yellow('  ' + (result.error || result.detail)));
+                    return;
+                }
+                const total = result?.total ?? 0;
+                console.log(total > 0
+                    ? chalk.green(`  Forgot ${total} ${total === 1 ? 'memory' : 'memories'} matching "${text}".`)
+                    : chalk.dim(`  No memories matched "${text}".`));
+                const tiers = ['spirit', 'nexus', 'workingmemory', 'graph']
+                    .filter((t) => result?.[t]).map((t) => `${t}:${result[t]}`);
+                if (tiers.length)
+                    console.log(chalk.dim('  ' + tiers.join('  ')));
+            }
             else {
-                console.log(chalk.dim('  Usage: /memory recall <query>  |  /memory remember <text>'));
+                console.log(chalk.dim('  Usage: /memory recall <query>  |  /memory remember <text>  |  /memory forget <text>'));
             }
         },
     },
@@ -1833,6 +2224,107 @@ const COMMANDS = {
             }
         },
     },
+    node: {
+        description: 'Onboard and manage mesh compute nodes',
+        usage: '/node [ls|enroll [--tenant <t>] [--ttl <hours>] [--label <l>]|rm <id>]',
+        handler: async (client, args) => {
+            const parts = parseQuotedArgs(args.trim());
+            const sub = (parts[0] || 'ls').toLowerCase();
+            const flag = (...names) => {
+                for (const n of names) {
+                    const i = parts.indexOf(n);
+                    if (i >= 0 && parts[i + 1])
+                        return parts[i + 1];
+                }
+                return undefined;
+            };
+            // The gateway node registry is reachable through the public Cloudflare
+            // tunnel; GET /nodes is open (no auth), so `ls` always works. Minting and
+            // removal are internal-key gated → routed server-side via the MCP tools.
+            const clusterUrl = (process.env.AITHER_CLUSTER_URL || 'https://cluster.aitherium.com').replace(/\/+$/, '');
+            if (sub === 'ls' || sub === 'list') {
+                const tenant = flag('--tenant', '-t') || '';
+                const spinner = ora('Listing mesh nodes...').start();
+                let nodes = [];
+                const ac = new AbortController();
+                const t = setTimeout(() => ac.abort(), 12000);
+                try {
+                    const r = await fetch(`${clusterUrl}/nodes${tenant ? `?tenant=${encodeURIComponent(tenant)}` : ''}`, { signal: ac.signal });
+                    if (r.ok)
+                        nodes = (await r.json())?.nodes || [];
+                    else {
+                        spinner.stop();
+                        console.log(chalk.red(`  Gateway returned ${r.status}`));
+                        return;
+                    }
+                }
+                catch (e) {
+                    spinner.stop();
+                    console.log(chalk.red(`  Gateway unreachable: ${e?.message || e}`));
+                    return;
+                }
+                finally {
+                    clearTimeout(t);
+                }
+                spinner.stop();
+                if (!nodes.length) {
+                    console.log(chalk.dim('  No mesh nodes registered.'));
+                    return;
+                }
+                console.log();
+                console.log(chalk.bold('  Mesh Nodes'));
+                for (const n of nodes) {
+                    const hw = n.hardware || {};
+                    const dot = n.status === 'online' ? chalk.green('●') : chalk.red('●');
+                    const gpu = hw.gpu || n.gpu || '—';
+                    const memVal = typeof hw.memory_gb === 'number' ? hw.memory_gb : n.memory_gb;
+                    const mem = typeof memVal === 'number' ? `${Math.round(memVal)}GB` : '—';
+                    const ctr = (n.services?.length ?? n.containers?.length ?? n.containers ?? 0);
+                    const ten = (n.tenant || n.labels?.tenant) ? chalk.dim(` tenant=${n.tenant || n.labels?.tenant}`) : '';
+                    console.log(`  ${dot} ${chalk.cyan(n.name || n.node_id)}  ${chalk.dim(gpu)}  ${mem}  ${ctr} ctr${ten}`);
+                }
+                console.log();
+            }
+            else if (sub === 'enroll' || sub === 'mint') {
+                const tenant = flag('--tenant', '-t') || '';
+                const ttlH = parseFloat(flag('--ttl') || '1') || 1;
+                const label = flag('--label', '-l') || '';
+                const spinner = ora('Minting enrollment token...').start();
+                const out = await invokeMcpTool(client, 'mint_node_token', {
+                    ttl_seconds: Math.round(ttlH * 3600), label, tenant,
+                });
+                spinner.stop();
+                if (out?.error || out?.success === false) {
+                    console.log(chalk.red('  ' + (out?.error || 'mint failed')));
+                    return;
+                }
+                console.log();
+                console.log(chalk.green('  ✓ Enrollment token minted') + chalk.dim(`  (single-use${tenant ? `, tenant=${tenant}` : ''})`));
+                console.log(chalk.bold('\n  Run this on the target node:'));
+                console.log('  ' + chalk.cyan(out.install_command || out.install || ''));
+                console.log(chalk.dim('\n  It registers through the tunnel, installs a reboot-safe service, and starts heartbeating.'));
+                console.log();
+            }
+            else if (sub === 'rm' || sub === 'remove') {
+                const id = parts[1];
+                if (!id) {
+                    console.log(chalk.dim('  Usage: /node rm <id|name>'));
+                    return;
+                }
+                const spinner = ora(`Removing ${id}...`).start();
+                const out = await invokeMcpTool(client, 'remove_cluster_node', { node_id: id });
+                spinner.stop();
+                if (out?.error || out?.success === false) {
+                    console.log(chalk.yellow('  ' + (out?.error || 'remove failed')));
+                    return;
+                }
+                console.log(chalk.green(`  ✓ Removed ${out.name || id}`) + chalk.dim(`  (${out.remaining ?? '?'} remaining)`));
+            }
+            else {
+                console.log(chalk.dim('  Usage: /node [ls | enroll [--tenant <t>] [--ttl <hours>] | rm <id>]'));
+            }
+        },
+    },
     workflow: {
         description: 'List or run workflows',
         usage: '/workflow [list|run <id>|create <yaml_path>]',
@@ -1944,6 +2436,495 @@ const COMMANDS = {
             }
         },
     },
+    grid: {
+        description: 'Manage grid distributed inference nodes',
+        usage: '/grid [status|add|remove|test|sync|pull]',
+        handler: async (client, args, config) => {
+            const parts = args.trim().split(/\s+/);
+            const sub = parts[0]?.toLowerCase() || 'status';
+            const configPath = join(homedir(), '.aither', 'config.json');
+            // Read shared ADK config
+            function readGridConfig() {
+                try {
+                    if (existsSync(configPath)) {
+                        return JSON.parse(readFileSync(configPath, 'utf-8'));
+                    }
+                }
+                catch { }
+                return {};
+            }
+            function writeGridConfig(data) {
+                const existing = readGridConfig();
+                Object.assign(existing, data);
+                const dir = join(homedir(), '.aither');
+                if (!existsSync(dir))
+                    mkdirSync(dir, { recursive: true });
+                writeFileSync(configPath, JSON.stringify(existing, null, 2), 'utf-8');
+            }
+            async function testNode(host, port) {
+                try {
+                    const r = await fetch(`http://${host}:${port}/v1/models`, {
+                        signal: AbortSignal.timeout(5000),
+                    });
+                    if (r.ok) {
+                        const data = await r.json();
+                        const models = (data?.data || []).map((m) => m.id).slice(0, 3);
+                        console.log(chalk.green(`  [+] ${host}:${port}`) + chalk.dim(` — models: ${models.join(', ') || 'default'}`));
+                        return true;
+                    }
+                }
+                catch { }
+                // Try /health as fallback
+                try {
+                    const r = await fetch(`http://${host}:${port}/health`, {
+                        signal: AbortSignal.timeout(3000),
+                    });
+                    if (r.ok) {
+                        console.log(chalk.yellow(`  [!] ${host}:${port}`) + chalk.dim(' — healthy but no /v1 API (missing --api-oai?)'));
+                        return false;
+                    }
+                }
+                catch { }
+                console.log(chalk.red(`  [x] ${host}:${port}`) + chalk.dim(' — unreachable'));
+                return false;
+            }
+            if (sub === 'status') {
+                const cfg = readGridConfig();
+                const nodes = cfg.grid_nodes || {};
+                console.log(chalk.bold('\n  Grid Topology'));
+                console.log('  ' + '='.repeat(55));
+                // GPU
+                if (cfg.backend) {
+                    console.log(`  ${chalk.cyan('[GPU]')}     ${(cfg.base_url || 'auto').padEnd(30)}  ${cfg.model || 'auto'}`);
+                }
+                else {
+                    console.log(`  ${chalk.dim('[GPU]     not configured (run: adk deploy grid)')}`);
+                }
+                // Reasoning
+                const rNode = nodes.reasoning;
+                if (rNode) {
+                    const display = `${rNode.host}:${rNode.port || 8121}`;
+                    console.log(`  ${chalk.magenta('[reason]')}  ${display.padEnd(30)}  ${rNode.model || cfg.reasoning_model || 'auto'}`);
+                }
+                else if (cfg.reasoning_url) {
+                    console.log(`  ${chalk.magenta('[reason]')}  ${cfg.reasoning_url.padEnd(30)}  ${cfg.reasoning_model || 'auto'}`);
+                }
+                else {
+                    console.log(`  ${chalk.dim('[reason]  not configured — /grid add reasoning <ip>')}`);
+                }
+                // Cluster
+                const cNodes = nodes.cluster || [];
+                if (cNodes.length > 0) {
+                    for (let i = 0; i < cNodes.length; i++) {
+                        const n = cNodes[i];
+                        const display = `${n.host}:${n.port || 8121}`;
+                        console.log(`  ${chalk.blue(`[cpu.${i}]`)}   ${display.padEnd(30)}  ${n.model || cfg.cluster_model || 'auto'}`);
+                    }
+                }
+                else if (cfg.cluster_url) {
+                    console.log(`  ${chalk.blue('[cpu.0]')}   ${cfg.cluster_url.padEnd(30)}  ${cfg.cluster_model || 'auto'}`);
+                }
+                else {
+                    console.log(`  ${chalk.dim('[cpu]     not configured — /grid add cluster <ip>')}`);
+                }
+                // Auth
+                console.log();
+                const token = config.authToken || cfg.api_key;
+                if (token) {
+                    console.log(chalk.dim(`  Auth: logged in — /grid sync to push config to workspace`));
+                }
+                else {
+                    console.log(chalk.dim('  Auth: not logged in — /login to enable cloud sync'));
+                }
+                // Health
+                console.log(chalk.bold('\n  Health'));
+                console.log('  ' + '-'.repeat(55));
+                let checked = false;
+                if (rNode) {
+                    await testNode(rNode.host, rNode.port || 8121);
+                    checked = true;
+                }
+                for (const n of cNodes) {
+                    await testNode(n.host, n.port || 8121);
+                    checked = true;
+                }
+                if (!checked)
+                    console.log(chalk.dim('  No remote nodes configured'));
+                console.log();
+            }
+            else if (sub === 'add') {
+                const role = parts[1]?.toLowerCase();
+                const host = parts[2];
+                const portStr = parts.find(p => p.startsWith('--port='))?.split('=')[1];
+                const port = portStr ? parseInt(portStr) : 8121;
+                const modelStr = parts.find(p => p.startsWith('--model='))?.split('=')[1];
+                if (!role || !host || !['reasoning', 'cluster'].includes(role)) {
+                    console.log(chalk.dim('  Usage: /grid add reasoning <ip> [--port=8121] [--model=name]'));
+                    console.log(chalk.dim('         /grid add cluster <ip> [--port=8121] [--model=name]'));
+                    return;
+                }
+                const cfg = readGridConfig();
+                const nodes = cfg.grid_nodes || {};
+                const entry = { host, port };
+                if (modelStr)
+                    entry.model = modelStr;
+                if (role === 'reasoning') {
+                    nodes.reasoning = entry;
+                    writeGridConfig({
+                        reasoning_backend: 'openai',
+                        reasoning_url: `http://${host}:${port}/v1`,
+                        reasoning_model: modelStr || 'deepseek-r1-8b',
+                        grid_nodes: nodes,
+                    });
+                }
+                else {
+                    const cluster = (nodes.cluster || []).filter((n) => n.host !== host);
+                    cluster.push(entry);
+                    nodes.cluster = cluster;
+                    const first = cluster[0];
+                    writeGridConfig({
+                        cluster_backend: 'openai',
+                        cluster_url: `http://${first.host}:${first.port || 8121}/v1`,
+                        cluster_model: modelStr || 'qwen2.5-32b',
+                        grid_nodes: nodes,
+                    });
+                }
+                console.log(chalk.green(`  Added ${role} node: ${host}:${port}`));
+                await testNode(host, port);
+                console.log(chalk.dim('  Sync to cloud: /grid sync'));
+            }
+            else if (sub === 'remove') {
+                const host = parts[1];
+                if (!host) {
+                    console.log(chalk.dim('  Usage: /grid remove <ip>'));
+                    return;
+                }
+                const cfg = readGridConfig();
+                const nodes = cfg.grid_nodes || {};
+                let removed = false;
+                if (nodes.reasoning?.host === host) {
+                    delete nodes.reasoning;
+                    writeGridConfig({ reasoning_backend: '', reasoning_url: '', reasoning_model: '', grid_nodes: nodes });
+                    removed = true;
+                }
+                if (nodes.cluster) {
+                    const before = nodes.cluster.length;
+                    nodes.cluster = nodes.cluster.filter((n) => n.host !== host);
+                    if (nodes.cluster.length < before) {
+                        const update = { grid_nodes: nodes };
+                        if (nodes.cluster.length === 0) {
+                            update.cluster_backend = '';
+                            update.cluster_url = '';
+                            update.cluster_model = '';
+                        }
+                        else {
+                            const first = nodes.cluster[0];
+                            update.cluster_url = `http://${first.host}:${first.port || 8121}/v1`;
+                        }
+                        writeGridConfig(update);
+                        removed = true;
+                    }
+                }
+                console.log(removed ? chalk.green(`  Removed: ${host}`) : chalk.yellow(`  No node found: ${host}`));
+            }
+            else if (sub === 'test') {
+                const target = parts[1];
+                const cfg = readGridConfig();
+                const nodes = cfg.grid_nodes || {};
+                console.log(chalk.bold('\n  Grid Node Tests'));
+                console.log('  ' + '='.repeat(50));
+                let checked = false;
+                const rNode = nodes.reasoning;
+                if (rNode && (!target || target === rNode.host)) {
+                    await testNode(rNode.host, rNode.port || 8121);
+                    checked = true;
+                }
+                for (const n of (nodes.cluster || [])) {
+                    if (!target || target === n.host) {
+                        await testNode(n.host, n.port || 8121);
+                        checked = true;
+                    }
+                }
+                if (!checked)
+                    console.log(chalk.dim(target ? `  No node found: ${target}` : '  No nodes configured'));
+                console.log();
+            }
+            else if (sub === 'sync') {
+                const cfg = readGridConfig();
+                const token = config.authToken || cfg.api_key;
+                if (!token) {
+                    console.log(chalk.yellow('  Not logged in. Run: /login'));
+                    return;
+                }
+                const spinner = ora('Syncing grid config to workspace...').start();
+                try {
+                    // Try Genesis Strata endpoint first
+                    const result = await client.post('/strata/write', {
+                        path: 'grid/config.json',
+                        data: JSON.stringify({
+                            profile: cfg.profile, backend: cfg.backend, base_url: cfg.base_url,
+                            model: cfg.model, reasoning_backend: cfg.reasoning_backend,
+                            reasoning_url: cfg.reasoning_url, reasoning_model: cfg.reasoning_model,
+                            cluster_backend: cfg.cluster_backend, cluster_url: cfg.cluster_url,
+                            cluster_model: cfg.cluster_model, grid_nodes: cfg.grid_nodes,
+                        }, null, 2),
+                    });
+                    spinner.stop();
+                    if (result?.success) {
+                        console.log(chalk.green('  Grid config synced to workspace'));
+                        console.log(chalk.dim('  Pull on another machine: /grid pull'));
+                    }
+                    else {
+                        // Fallback: try gateway directly
+                        const gateway = cfg.gateway_url || 'https://gateway.aitherium.com';
+                        const r = await fetch(`${gateway}/api/v1/config/grid`, {
+                            method: 'PUT',
+                            headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` },
+                            body: JSON.stringify(cfg.grid_nodes || {}),
+                            signal: AbortSignal.timeout(10000),
+                        });
+                        spinner.stop();
+                        if (r.ok) {
+                            console.log(chalk.green('  Grid config synced via gateway'));
+                        }
+                        else {
+                            console.log(chalk.yellow('  Sync failed — config saved locally only'));
+                        }
+                    }
+                }
+                catch (e) {
+                    spinner.stop();
+                    console.log(chalk.yellow(`  Sync failed: ${e.message || e}`));
+                    console.log(chalk.dim('  Config is saved locally at ~/.aither/config.json'));
+                }
+            }
+            else if (sub === 'pull') {
+                const cfg = readGridConfig();
+                const token = config.authToken || cfg.api_key;
+                if (!token) {
+                    console.log(chalk.yellow('  Not logged in. Run: /login'));
+                    return;
+                }
+                const spinner = ora('Pulling grid config from workspace...').start();
+                try {
+                    const result = await client.get('/strata/read?path=grid/config.json');
+                    spinner.stop();
+                    if (result?.data) {
+                        const gridData = typeof result.data === 'string' ? JSON.parse(result.data) : result.data;
+                        writeGridConfig(gridData);
+                        console.log(chalk.green('  Grid config pulled and saved locally'));
+                        console.log(chalk.dim('  Run: /grid status'));
+                    }
+                    else {
+                        // Fallback: gateway
+                        const gateway = cfg.gateway_url || 'https://gateway.aitherium.com';
+                        const r = await fetch(`${gateway}/api/v1/config/grid`, {
+                            headers: { 'Authorization': `Bearer ${token}` },
+                            signal: AbortSignal.timeout(10000),
+                        });
+                        spinner.stop();
+                        if (r.ok) {
+                            const gridData = await r.json();
+                            writeGridConfig(gridData);
+                            console.log(chalk.green('  Grid config pulled from gateway'));
+                        }
+                        else {
+                            console.log(chalk.yellow('  No grid config found in workspace'));
+                            console.log(chalk.dim('  Run /grid sync from your configured machine first'));
+                        }
+                    }
+                }
+                catch (e) {
+                    spinner.stop();
+                    console.log(chalk.yellow(`  Pull failed: ${e.message || e}`));
+                }
+            }
+            else {
+                console.log(chalk.bold('\n  /grid — Manage distributed inference nodes\n'));
+                console.log('  Commands:');
+                console.log(chalk.dim('    /grid status              Show topology + health'));
+                console.log(chalk.dim('    /grid add reasoning <ip>  Add Mac reasoning node'));
+                console.log(chalk.dim('    /grid add cluster <ip>    Add CPU cluster node'));
+                console.log(chalk.dim('    /grid remove <ip>         Remove a node'));
+                console.log(chalk.dim('    /grid test                Test all nodes'));
+                console.log(chalk.dim('    /grid test <ip>           Test specific node'));
+                console.log(chalk.dim('    /grid sync                Push config to workspace'));
+                console.log(chalk.dim('    /grid pull                Pull config from workspace'));
+                console.log();
+            }
+        },
+    },
+    explore: {
+        description: 'Browse packs, agents, and skills available for your setup',
+        usage: '/explore [agents|tools|skills|grid|all] [--free]',
+        handler: async (client, args, config) => {
+            const filter = args.trim().toLowerCase() || 'all';
+            const freeOnly = filter.includes('--free') || filter.includes('free');
+            const category = filter.replace('--free', '').replace('free', '').trim() || 'all';
+            // Fetch catalog from Genesis, fall back to local
+            let catalog = [];
+            try {
+                const result = await client.get('/api/v1/catalog/packs');
+                if (result?.packs)
+                    catalog = result.packs;
+            }
+            catch { }
+            // Fallback: try bundled catalog
+            if (catalog.length === 0) {
+                try {
+                    const catalogPath = join(homedir(), '.aitheros', 'packs_catalog.json');
+                    if (existsSync(catalogPath)) {
+                        catalog = JSON.parse(readFileSync(catalogPath, 'utf-8')).packs || [];
+                    }
+                }
+                catch { }
+            }
+            // Second fallback: ADK package data
+            if (catalog.length === 0) {
+                try {
+                    // Try common ADK install locations
+                    const paths = [
+                        join(homedir(), '.local', 'lib', 'python3.12', 'site-packages', 'adk', 'data', 'packs_catalog.json'),
+                        join(homedir(), '.local', 'lib', 'python3.11', 'site-packages', 'adk', 'data', 'packs_catalog.json'),
+                    ];
+                    for (const p of paths) {
+                        if (existsSync(p)) {
+                            catalog = JSON.parse(readFileSync(p, 'utf-8')).packs || [];
+                            break;
+                        }
+                    }
+                }
+                catch { }
+            }
+            if (catalog.length === 0) {
+                console.log(chalk.yellow('\n  No catalog available. Install aither-adk or connect to Genesis.\n'));
+                return;
+            }
+            // Filter
+            let filtered = catalog;
+            if (category === 'agents')
+                filtered = catalog.filter((p) => p.type === 'agent_pack');
+            else if (category === 'tools')
+                filtered = catalog.filter((p) => p.type === 'tool_pack');
+            else if (category === 'grid')
+                filtered = catalog.filter((p) => (p.tags || []).some((t) => t === 'grid' || t === 'distributed'));
+            else if (category === 'skills')
+                filtered = catalog.filter((p) => p.type === 'skill_pack');
+            if (freeOnly)
+                filtered = filtered.filter((p) => p.tier === 'free');
+            // Check installed
+            const packsDir = join(homedir(), '.aitheros', 'packs');
+            const installedIds = new Set();
+            try {
+                if (existsSync(packsDir)) {
+                    for (const d of readdirSync(packsDir)) {
+                        if (existsSync(join(packsDir, d, '.toolpack.yaml')))
+                            installedIds.add(d);
+                    }
+                }
+            }
+            catch { }
+            // Group by type
+            const groups = {};
+            for (const p of filtered) {
+                const type = (p.type || 'other').replace('_pack', '').replace('_', ' ');
+                if (!groups[type])
+                    groups[type] = [];
+                groups[type].push(p);
+            }
+            console.log(chalk.bold('\n  Aitherium Marketplace'));
+            console.log('  ' + '='.repeat(60));
+            for (const [type, packs] of Object.entries(groups).sort()) {
+                console.log(chalk.bold(`\n  ${type.charAt(0).toUpperCase() + type.slice(1)} Packs`));
+                for (const p of packs) {
+                    const installed = installedIds.has(p.id);
+                    const icon = installed ? chalk.green('✓') : chalk.dim('○');
+                    const tier = p.tier === 'free' ? chalk.green('free') : chalk.yellow(p.tier);
+                    const pricing = p.pricing || {};
+                    let price = '';
+                    if (pricing.subscription_cents)
+                        price = `$${(pricing.subscription_cents / 100).toFixed(0)}/mo`;
+                    else if (pricing.one_time_cents)
+                        price = `$${(pricing.one_time_cents / 100).toFixed(0)}`;
+                    else
+                        price = 'free';
+                    console.log(`  ${icon} ${p.name || p.id}`);
+                    console.log(chalk.dim(`    ${p.description || ''}`));
+                    console.log(chalk.dim(`    ${tier} ${price !== 'free' ? '· ' + price : ''}${installed ? ' · installed' : ''}`));
+                }
+            }
+            console.log(chalk.bold('\n  Quick Actions'));
+            console.log('  ' + '-'.repeat(60));
+            console.log(chalk.dim('    /explore agents              Browse agent packs'));
+            console.log(chalk.dim('    /explore tools --free         Free tool packs only'));
+            console.log(chalk.dim('    /explore grid                 Grid infrastructure'));
+            console.log();
+            const token = config.authToken;
+            if (token) {
+                console.log(chalk.dim('  Full catalog: https://portal.aitherium.com/marketplace'));
+            }
+            else {
+                console.log(chalk.dim('  Full catalog: https://portal.aitherium.com/marketplace'));
+                console.log(chalk.dim('  Sign up free: https://portal.aitherium.com/signup'));
+            }
+            console.log();
+        },
+    },
+    upgrade: {
+        description: 'Open upgrade/checkout page for a pack or plan',
+        usage: '/upgrade [pack-id|managed|setup]',
+        handler: async (_client, args) => {
+            const target = args.trim().toLowerCase();
+            const URLS = {
+                'managed': { url: 'https://portal.aitherium.com/marketplace/grid?sku=grid_managed_monthly', label: 'Grid Managed ($49/mo)' },
+                'setup': { url: 'https://portal.aitherium.com/marketplace/grid?sku=grid_setup_onetime', label: 'Grid Setup Call ($199)' },
+                'grid': { url: 'https://portal.aitherium.com/marketplace/grid', label: 'Grid Distributed Inference' },
+                'demiurge': { url: 'https://portal.aitherium.com/marketplace/agent.demiurge', label: 'Demiurge — Code Architect' },
+                'hydra': { url: 'https://portal.aitherium.com/marketplace/agent.hydra', label: 'Hydra — Code Guardian' },
+                'athena': { url: 'https://portal.aitherium.com/marketplace/agent.athena', label: 'Athena — Security Oracle' },
+                'lyra': { url: 'https://portal.aitherium.com/marketplace/agent.lyra', label: 'Lyra — Research Muse' },
+                'pro': { url: 'https://portal.aitherium.com/pricing', label: 'Professional Plan' },
+            };
+            if (!target) {
+                console.log(chalk.bold('\n  Upgrade Options\n'));
+                for (const [key, info] of Object.entries(URLS)) {
+                    console.log(`  ${chalk.cyan(key.padEnd(15))} ${info.label}`);
+                }
+                console.log();
+                console.log(chalk.dim('  Usage: /upgrade managed'));
+                console.log(chalk.dim('         /upgrade demiurge'));
+                console.log(chalk.dim('         /upgrade pro'));
+                console.log();
+                return;
+            }
+            const match = URLS[target];
+            if (match) {
+                console.log(`\n  Opening: ${match.label}`);
+                console.log(chalk.cyan(`  ${match.url}\n`));
+                try {
+                    const { execSync } = await import('node:child_process');
+                    const cmd = process.platform === 'win32' ? 'start' : process.platform === 'darwin' ? 'open' : 'xdg-open';
+                    execSync(`${cmd} "${match.url}"`, { stdio: 'ignore' });
+                }
+                catch {
+                    console.log(chalk.dim('  (Could not open browser — copy the URL above)'));
+                }
+            }
+            else {
+                // Try as a generic pack/agent ID
+                const url = `https://portal.aitherium.com/marketplace/${target}`;
+                console.log(`\n  Opening: ${url}\n`);
+                try {
+                    const { execSync } = await import('node:child_process');
+                    const cmd = process.platform === 'win32' ? 'start' : process.platform === 'darwin' ? 'open' : 'xdg-open';
+                    execSync(`${cmd} "${url}"`, { stdio: 'ignore' });
+                }
+                catch {
+                    console.log(chalk.dim('  (Could not open browser — copy the URL above)'));
+                }
+            }
+        },
+    },
     deploy: {
         description: 'Deploy a service',
         usage: '/deploy <service_name>',
@@ -2124,9 +3105,9 @@ const COMMANDS = {
                     console.log(chalk.bold('  🔐 Browser Authentication'));
                     console.log();
                     console.log(`  Open this URL in your browser:`);
-                    console.log(chalk.cyan(`  ${dc.verification_uri_complete}`));
+                    console.log(`  ${osc8Link(dc.verification_uri_complete)}`);
                     console.log();
-                    console.log(`  Or go to ${chalk.cyan(dc.verification_uri)} and enter code:`);
+                    console.log(`  Or go to ${osc8Link(dc.verification_uri)} and enter code:`);
                     console.log(chalk.bold.yellow(`  ${dc.user_code}`));
                     console.log();
                     console.log(chalk.dim(`  Waiting for authorization (expires in ${Math.round(dc.expires_in / 60)}m)...`));
@@ -2495,18 +3476,21 @@ const COMMANDS = {
         handler: async (_client, args) => {
             const __dirname = dirname(fileURLToPath(import.meta.url));
             const repoRoot = resolve(__dirname, '..', '..', '..', '..', '..');
-            const composeFile = join(repoRoot, 'docker-compose.demo.yml');
-            const fullCompose = join(repoRoot, 'docker-compose.aitheros.yml');
+            const composeFile = join(repoRoot, '.DEPLOYMENT', 'compose', 'docker-compose.demo.yml');
+            const fullCompose = join(repoRoot, '.DEPLOYMENT', 'compose', 'docker-compose.aitheros.yml');
             const target = existsSync(composeFile) ? composeFile : fullCompose;
+            // Compose files live under .DEPLOYMENT/; --project-directory keeps their
+            // relative build contexts / volume mounts resolving against the repo root.
+            const pd = `--project-directory "${repoRoot}"`;
             const sub = args.trim().toLowerCase().split(/\s+/)[0] || 'status';
             const cmdMap = {
-                start: `docker compose -f "${target}" up -d`,
-                up: `docker compose -f "${target}" up -d`,
-                stop: `docker compose -f "${target}" down --timeout 10`,
-                down: `docker compose -f "${target}" down --timeout 10`,
-                status: `docker compose -f "${target}" ps`,
-                ps: `docker compose -f "${target}" ps`,
-                logs: `docker compose -f "${target}" logs --tail 30`,
+                start: `docker compose -f "${target}" ${pd} up -d`,
+                up: `docker compose -f "${target}" ${pd} up -d`,
+                stop: `docker compose -f "${target}" ${pd} down --timeout 10`,
+                down: `docker compose -f "${target}" ${pd} down --timeout 10`,
+                status: `docker compose -f "${target}" ${pd} ps`,
+                ps: `docker compose -f "${target}" ${pd} ps`,
+                logs: `docker compose -f "${target}" ${pd} logs --tail 30`,
             };
             if (!cmdMap[sub]) {
                 console.log(chalk.bold('\n  /demo — Manage the minimal demo stack\n'));
@@ -3719,6 +4703,37 @@ const COMMANDS = {
                             console.log(`    ${chalk.dim(k)}: ${v}`);
                         }
                     }
+                    // ── Effort → tier → model routing table ──
+                    // Surfaces exactly which model serves each effort level so a misroute
+                    // (e.g. a chat turn going straight to a DGX/reasoning model instead of
+                    // the orchestrator) is obvious at a glance. DOCTRINE: every chat tier
+                    // should serve from aither-orchestrator; the DGX is only the `reason` tool.
+                    const routing = result?.routing || result?.info?.routing || {};
+                    const e2t = routing.effort_to_tier || {};
+                    const tb = routing.tier_backends || {};
+                    if (Object.keys(e2t).length) {
+                        console.log();
+                        console.log(chalk.bold('  Effort → tier → model (what serves each turn):'));
+                        for (let e = 1; e <= 10; e++) {
+                            const tier = e2t[String(e)] || e2t[e];
+                            if (!tier)
+                                continue;
+                            const cfg = tb[tier] || {};
+                            const model = cfg.model || '(default)';
+                            // Flag anything that is NOT the orchestrator serving a chat turn.
+                            const offOrch = model && !String(model).startsWith('aither-orchestrator') && tier !== 'vision';
+                            const line = `    effort ${String(e).padStart(2)} → ${String(tier).padEnd(10)} → ${model}`;
+                            console.log(offOrch ? chalk.yellow(line + '  ⚠ not orchestrator') : chalk.dim(line));
+                            if (cfg.reasoning_model) {
+                                console.log(chalk.dim(`                 ↳ reason tool → ${cfg.reasoning_model}`));
+                            }
+                        }
+                    }
+                    const reasonTool = result?.info?.tools?.reason;
+                    if (reasonTool?.model) {
+                        console.log();
+                        console.log(`  reason tool: ${chalk.cyan(reasonTool.model)} ${chalk.dim('(' + (reasonTool.invoked_when || 'orchestrator-invoked') + ')')}`);
+                    }
                     console.log();
                 }
                 catch (e) {
@@ -3793,6 +4808,151 @@ const COMMANDS = {
             console.log(chalk.cyan(`  ${config.imageAttachments.length} image(s) queued for next message.`));
         },
     },
+    imagine: {
+        description: 'Generate an image (Sana / ComfyUI / Gemini / OpenAI)',
+        usage: '/imagine <prompt> [--backend sana|comfyui|gemini|openai] [--model <name>] [-w 1024] [-h 1024] [-o out.png]  |  /imagine backends  |  /imagine models',
+        handler: async (client, args, config) => {
+            const BACKENDS = ['sana', 'comfyui', 'gemini', 'openai'];
+            const LABELS = {
+                sana: 'Local · Sana (fast Linear DiT, keyless)',
+                comfyui: 'Local · ComfyUI (full SDXL workflows)',
+                gemini: 'Cloud · Gemini / Imagen (BYOK)',
+                openai: 'Cloud · OpenAI gpt-image-1 / DALL·E (BYOK)',
+            };
+            const trimmed = args.trim();
+            // The image API (/api/canvas/generate, /api/canvas/models) is a VEIL route
+            // (port 3000), NOT Genesis (8001) which `client` is bound to. Derive the
+            // Veil base from the Genesis URL (swap port → 3000) with env override.
+            const veilBase = (process.env.AITHER_VEIL_URL
+                || client.baseUrl.replace(/:\d+($|\/)/, ':3000$1')
+                || 'http://127.0.0.1:3000').replace(/\/+$/, '');
+            const authToken = config.authToken;
+            const veilFetch = async (path, init = {}) => {
+                const headers = {
+                    'Content-Type': 'application/json',
+                    ...(authToken ? { Authorization: `Bearer ${authToken}` } : {}),
+                    ...(init.headers || {}),
+                };
+                return fetch(`${veilBase}${path}`, { ...init, headers });
+            };
+            if (trimmed === 'backends') {
+                console.log(chalk.bold('\nImage generation backends:\n'));
+                for (const b of BACKENDS) {
+                    const def = b === 'sana' ? chalk.green('  (default)') : '';
+                    console.log(`  ${chalk.cyan(b.padEnd(8))} ${LABELS[b]}${def}`);
+                }
+                console.log(chalk.dim('\n  Use:  /imagine a fox --backend sana\n'));
+                return;
+            }
+            if (trimmed === 'models') {
+                const spinner = ora('Fetching installed image models...').start();
+                try {
+                    const res = await veilFetch('/api/canvas/models');
+                    const data = await res.json().catch(() => ({}));
+                    const allCkpts = (data?.models || []).filter((m) => m.type === 'checkpoint');
+                    // Hide NSFW-flagged models unless the session safety level explicitly allows it.
+                    const allowNsfw = ['explicit', 'unrestricted'].includes((config.safetyLevel || '').toLowerCase());
+                    const ckpts = allowNsfw ? allCkpts : allCkpts.filter((m) => !m.nsfw);
+                    const hidden = allCkpts.length - ckpts.length;
+                    spinner.succeed(`${ckpts.length} installed checkpoint(s):`);
+                    for (const m of ckpts)
+                        console.log(`  ${chalk.cyan(m.id)}${m.nsfw ? chalk.dim(' (nsfw)') : ''}`);
+                    if (hidden > 0)
+                        console.log(chalk.dim(`  (${hidden} NSFW model(s) hidden — set safety to explicit to show)`));
+                    console.log(chalk.dim('\n  Use:  /imagine a fox --backend comfyui --model <name>'));
+                    console.log(chalk.dim('  (Sana: --model sprint for one-step fast mode)\n'));
+                }
+                catch (err) {
+                    spinner.fail(`Failed to list models: ${err.message}`);
+                }
+                return;
+            }
+            const flag = (re, def) => {
+                const m = args.match(re);
+                return m ? m[1] : def;
+            };
+            const backend = (flag(/--backend\s+(\S+)/) || flag(/-b\s+(\S+)/) || 'sana').toLowerCase();
+            const model = flag(/--model\s+(\S+)/) || flag(/-m\s+(\S+)/);
+            const width = parseInt(flag(/--width\s+(\d+)/) || flag(/-w\s+(\d+)/) || '1024');
+            const height = parseInt(flag(/--height\s+(\d+)/) || flag(/-h\s+(\d+)/) || '1024');
+            const steps = parseInt(flag(/--steps\s+(\d+)/) || '20');
+            const output = flag(/--output\s+(\S+)/) || flag(/-o\s+(\S+)/);
+            const negative = flag(/--negative\s+"([^"]+)"/) || flag(/--negative\s+(\S+)/);
+            const prompt = args
+                .replace(/--(backend|model|width|height|steps|output|negative)\s+("[^"]+"|\S+)/g, '')
+                .replace(/-[bmwho]\s+\S+/g, '')
+                .replace(/^["']|["']$/g, '')
+                .trim();
+            if (!prompt) {
+                console.log(chalk.yellow('  Usage: /imagine <prompt> [--backend sana|comfyui|gemini|openai] [--model <name>] [-w 1024] [-h 1024] [-o out.png]'));
+                console.log(chalk.dim('         /imagine backends   — list backends'));
+                console.log(chalk.dim('         /imagine models     — list installed ComfyUI checkpoints'));
+                return;
+            }
+            if (!BACKENDS.includes(backend)) {
+                console.log(chalk.red(`  Unknown backend "${backend}". Choose: ${BACKENDS.join(', ')}`));
+                return;
+            }
+            const spinner = ora(`Generating via ${chalk.cyan(backend)} (${veilBase})...`).start();
+            try {
+                const res = await veilFetch('/api/canvas/generate', {
+                    method: 'POST',
+                    body: JSON.stringify({
+                        prompt,
+                        provider: backend,
+                        negative_prompt: negative || '',
+                        width, height, steps,
+                        preferred_model: model || undefined,
+                        model: model || undefined,
+                        batch_size: 1,
+                        safety_level: config.safetyLevel || 'OFF',
+                    }),
+                });
+                const data = await res.json().catch(() => ({}));
+                if (!res.ok || data?.success === false) {
+                    const hint = data?.needsKey ? ` — add a ${backend} key under Settings → Integrations` : '';
+                    spinner.fail(`Generation failed (HTTP ${res.status}): ${data?.error || 'unknown'}${hint}`);
+                    return;
+                }
+                const images = data?.images || (data?.image ? [data.image] : []);
+                if (!images.length) {
+                    spinner.fail(`No image returned by ${backend}. (Is the Veil API at ${veilBase}? Override with AITHER_VEIL_URL.)`);
+                    return;
+                }
+                spinner.succeed(`Image generated via ${backend}${data?.model ? ` (${data.model})` : ''}!`);
+                const { resolve: resolvePath } = await import('node:path');
+                for (let i = 0; i < images.length; i++) {
+                    const img = images[i];
+                    const base = (output || `aither-image-${Date.now()}.png`).replace(/\.png$/i, '');
+                    const outPath = images.length > 1 ? `${base}-${i}.png` : `${base}.png`;
+                    if (img.startsWith('data:') || /^[A-Za-z0-9+/=]{40,}/.test(img)) {
+                        writeFileSync(outPath, Buffer.from(img.replace(/^data:image\/\w+;base64,/, ''), 'base64'));
+                    }
+                    else {
+                        // http(s) URL or a Veil-relative path (e.g. /api/canvas/image?...)
+                        const imgRes = img.startsWith('http')
+                            ? await fetch(img)
+                            : await veilFetch(img);
+                        writeFileSync(outPath, Buffer.from(await imgRes.arrayBuffer()));
+                    }
+                    // Absolute path + clickable link, and register as a session artifact so
+                    // /get and /artifacts can find it (matches how chat-generated images work).
+                    const absPath = resolvePath(outPath);
+                    let sz = 0;
+                    try {
+                        sz = statSync(absPath).size;
+                    }
+                    catch { /* size optional */ }
+                    const idx = addSessionArtifact({ path: absPath, size: sz, language: 'image' });
+                    console.log(chalk.green(`  Saved: ${osc8Link(`file://${absPath.replace(/\\/g, '/')}`, absPath)}`));
+                    console.log(chalk.dim(`  Artifact #${idx} — /get ${idx} to copy it here`));
+                }
+            }
+            catch (err) {
+                spinner.fail(`Error: ${err.message}`);
+            }
+        },
+    },
     speak: {
         description: 'Text-to-speech via Lyra',
         usage: '/speak <text> [--voice <name>]',
@@ -4161,48 +5321,103 @@ COMMANDS['artifacts'] = {
             console.log(chalk.dim('  No artifacts produced yet. Run a code generation task first.'));
             return;
         }
-        console.log(chalk.bold(`\n  📦 Artifact Mailbox (${artifacts.length} items)\n`));
+        console.log(chalk.bold(`\n  📦 Artifacts (${artifacts.length})\n`));
         for (let i = 0; i < artifacts.length; i++) {
             const art = artifacts[i];
             const sizeStr = art.size > 1024
                 ? `${(art.size / 1024).toFixed(1)} KB`
                 : `${art.size} bytes`;
-            console.log(`  ${chalk.cyan(`#${i + 1}`)} ${chalk.white.bold(art.filename)} ${chalk.dim(`(${sizeStr})`)}`);
-            if (art.retrieve_cmd) {
-                console.log(chalk.dim(`     ${art.retrieve_cmd}`));
+            const timeStr = new Date(art.timestamp).toLocaleTimeString();
+            console.log(`  ${chalk.cyan(`#${i + 1}`)} ${chalk.white.bold(art.filename)} ${chalk.dim(`(${sizeStr})`)} ${chalk.dim(timeStr)}`);
+        }
+        console.log(chalk.cyan(`\n  /get <N>`) + chalk.dim(` to download  ·  `) + chalk.cyan(`/get all`) + chalk.dim(` to download all\n`));
+    },
+};
+// ── /get command ──
+COMMANDS['get'] = {
+    description: 'Download an artifact by number or "all" (from /artifacts list)',
+    usage: '/get <number|all> [dest_path]',
+    handler: async (client, args) => {
+        const artifacts = getSessionArtifacts();
+        if (artifacts.length === 0) {
+            console.log(chalk.dim('  No artifacts to download.'));
+            return;
+        }
+        const parts = args.trim().split(/\s+/);
+        const selector = parts[0] || '';
+        const customDest = parts.slice(1).join(' ');
+        // Determine which artifacts to download
+        let indices;
+        if (selector === 'all') {
+            indices = artifacts.map((_, i) => i);
+        }
+        else {
+            const num = parseInt(selector, 10);
+            if (isNaN(num) || num < 1 || num > artifacts.length) {
+                console.log(chalk.red(`  Usage: /get <1-${artifacts.length}|all> [dest_path]`));
+                return;
             }
-            console.log(chalk.dim(`     ${art.timestamp}`));
+            indices = [num - 1];
+        }
+        for (const idx of indices) {
+            const art = artifacts[idx];
+            const dest = customDest || `./${art.filename}`;
+            await _downloadArtifact(client, art, idx + 1, dest);
         }
-        console.log(chalk.dim(`\n  Use /get <number> to download an artifact to current directory.\n`));
     },
 };
-// ── /get command ──
-COMMANDS['get'] = {
-    description: 'Download an artifact by number (from /artifacts list)',
-    usage: '/get <number>',
-    handler: async (_client, args) => {
-        const num = parseInt(args.trim(), 10);
-        const artifacts = getSessionArtifacts();
-        if (isNaN(num) || num < 1 || num > artifacts.length) {
-            console.log(chalk.red(`  Invalid artifact number. Use /artifacts to see available items (1-${artifacts.length}).`));
-            return;
+/** Download a single artifact — HTTP first, docker cp fallback. */
+async function _downloadArtifact(client, art, num, dest) {
+    const filename = basename(dest) || art.filename;
+    const destPath = resolve(dest);
+    console.log(chalk.dim(`  Downloading #${num}: ${art.filename}...`));
+    // 1) Try HTTP download via Genesis /files/ endpoint
+    if (art.download_url || art.path) {
+        try {
+            let url = art.download_url || '';
+            if (!url && art.path) {
+                // Build from absolute container path
+                let rel = art.path;
+                for (const prefix of ['/app/AitherOS/', '/app/']) {
+                    if (rel.startsWith(prefix)) {
+                        rel = rel.slice(prefix.length);
+                        break;
+                    }
+                }
+                url = `/files/${rel}`;
+            }
+            const fullUrl = `${client.baseUrl}${url}`;
+            const resp = await fetch(fullUrl, { signal: AbortSignal.timeout(60000) });
+            if (resp.ok) {
+                const buf = Buffer.from(await resp.arrayBuffer());
+                writeFileSync(destPath, buf);
+                // OSC 8 clickable hyperlink for terminals that support it
+                const fileUri = `file://${destPath.replace(/\\/g, '/')}`;
+                const link = `\x1b]8;;${fileUri}\x1b\\${destPath}\x1b]8;;\x1b\\`;
+                console.log(chalk.green(`  ✓ Saved: ${link}`));
+                return;
+            }
+            // Non-ok — fall through to docker cp
         }
-        const art = artifacts[num - 1];
-        if (!art.retrieve_cmd) {
-            console.log(chalk.red(`  No retrieve command available for artifact #${num}.`));
-            return;
+        catch {
+            // HTTP failed — fall through to docker cp
         }
-        console.log(chalk.dim(`  Retrieving ${art.filename}...`));
+    }
+    // 2) Fallback: docker cp
+    if (art.retrieve_cmd) {
         try {
-            execSync(art.retrieve_cmd, { stdio: 'inherit' });
-            console.log(chalk.green(`  ✓ Downloaded: ./${art.filename}`));
+            execSync(art.retrieve_cmd, { stdio: 'pipe' });
+            const fileUri = `file://${destPath.replace(/\\/g, '/')}`;
+            const link = `\x1b]8;;${fileUri}\x1b\\${destPath}\x1b]8;;\x1b\\`;
+            console.log(chalk.green(`  ✓ Saved: ${link}`));
         }
         catch (err) {
             console.log(chalk.red(`  ✗ Download failed: ${err.message || err}`));
-            console.log(chalk.dim(`     Manual: ${art.retrieve_cmd}`));
         }
-    },
-};
+        return;
+    }
+    console.log(chalk.red(`  ✗ No download path available for artifact #${num}.`));
+}
 // ═══════════════════════════════════════════════════════════════════════════════
 // Sandbox + IDE commands
 // ═══════════════════════════════════════════════════════════════════════════════
@@ -5295,7 +6510,490 @@ COMMANDS.v4 = {
     },
 };
 COMMANDS.elevate = COMMANDS.v4;
-COMMANDS.deepseek = COMMANDS.v4;
+// ── /deepseek — interactive wizard: route the live orchestrator to DeepSeek ──
+// Drives the REAL lever (model stack switch), NOT the reasoning profile (which
+// only affects MCTS / one-shot /v4 and does nothing for normal chat turns).
+// Flow: ensure DEEPSEEK_API_KEY → switch model stack to a DeepSeek stack →
+// live test turn that PROVES generation actually came from DeepSeek.
+// The stack whose tier_backends route effort>=5 to backend: deepseek_cloud.
+const _DEEPSEEK_STACK = 'cloud-dsv4';
+// Remembered so `/deepseek off` can revert to whatever was active before.
+let _deepseekPrevStack = null;
+/** Resolve the active model stack + whether it routes any tier to DeepSeek. */
+async function _dsActiveStack(client) {
+    const data = await client.get('/model-stacks/active');
+    const stack = data?.stack || '(unknown)';
+    const tb = (data?.routing?.tier_backends || {});
+    const tiers = {};
+    let routesDeepseek = false;
+    for (const [tier, cfg] of Object.entries(tb)) {
+        const backend = cfg?.backend || '';
+        const model = cfg?.model || '';
+        tiers[tier] = `${model} (${backend})`;
+        if (/deepseek/i.test(backend) || /deepseek/i.test(model))
+            routesDeepseek = true;
+    }
+    return { stack, routesDeepseek, tiers };
+}
+/** True if a DEEPSEEK_API_KEY value is present in the vault. */
+async function _dsKeyPresent(client) {
+    const r = await client.getDetailed('/secrets/DEEPSEEK_API_KEY');
+    const val = r?.value ?? r?.secret ?? '';
+    return Boolean(val && String(val).trim());
+}
+/** Live test turn — proves generation actually came from DeepSeek (not local). */
+async function _dsSelfTest(client, config) {
+    let model = '';
+    let gotContent = false;
+    let error = '';
+    try {
+        for await (const ev of client.streamChat('Reply with exactly the three words: DEEPSEEK ROUTE OK', {
+            effort: 8, // effort 8 → 'deep' tier → deepseek_cloud in cloud-dsv4
+            maxEffort: 8,
+            agent: config.defaultAgent,
+            sessionId: `deepseek-selftest-${Date.now()}`,
+            priority: 'user',
+        })) {
+            const d = ev.data || {};
+            if (d.model && typeof d.model === 'string')
+                model = d.model;
+            if (ev.type === 'token' || d.t)
+                gotContent = true;
+            if (d.via_cloud || d.via_bridge)
+                gotContent = true;
+            if (ev.type === 'error' || d.error)
+                error = d.error || d.message || 'stream error';
+            if (ev.type === 'stream_timeout')
+                error = error || 'timed out waiting for tokens';
+        }
+    }
+    catch (e) {
+        error = e?.message || String(e);
+    }
+    // Definitive PASS = the served model name is a DeepSeek model.
+    // Soft PASS = content streamed with no error (model name not surfaced by SSE).
+    const ok = /deepseek/i.test(model) || (gotContent && !error);
+    return { ok, model, gotContent, error };
+}
+COMMANDS.deepseek = {
+    description: 'Route the live orchestrator to DeepSeek (interactive setup + self-test)',
+    usage: '/deepseek [on|off|status|test]',
+    handler: async (client, args, config) => {
+        const sub = (args.trim().split(/\s+/)[0] || 'on').toLowerCase();
+        // ── status ──────────────────────────────────────────────────────────
+        if (sub === 'status') {
+            const spinner = ora('Reading routing...').start();
+            const st = await _dsActiveStack(client);
+            const hasKey = await _dsKeyPresent(client);
+            spinner.stop();
+            console.log();
+            console.log(chalk.bold('  Active stack: ') + chalk.cyan(st.stack));
+            console.log(chalk.bold('  DeepSeek routed: ') + (st.routesDeepseek ? chalk.green('yes') : chalk.yellow('no — chatting against local/other')));
+            console.log(chalk.bold('  API key stored:  ') + (hasKey ? chalk.green('yes') : chalk.red('no — run /deepseek on')));
+            console.log();
+            console.log(chalk.bold('  Effort tiers:'));
+            for (const [tier, val] of Object.entries(st.tiers)) {
+                const ds = /deepseek/i.test(val);
+                console.log(`    ${tier.padEnd(10)} ${ds ? chalk.green(val) : chalk.dim(val)}`);
+            }
+            console.log();
+            return;
+        }
+        // ── off / revert ────────────────────────────────────────────────────
+        if (sub === 'off' || sub === 'revert' || sub === 'local') {
+            let target = _deepseekPrevStack;
+            if (!target) {
+                // Fall back to the stack marked default.
+                const list = await client.get('/model-stacks');
+                const def = (list?.stacks || []).find((s) => s.default);
+                target = def?.name || 'dgx-hybrid';
+            }
+            const spinner = ora(`Reverting to ${target}...`).start();
+            const res = await client.postDetailed('/model-stacks/switch', { stack: target });
+            spinner.stop();
+            if (res?.error) {
+                console.log(chalk.red(`  Revert failed: ${res.error}`));
+                return;
+            }
+            _deepseekPrevStack = null;
+            console.log(chalk.green(`  Reverted — orchestrator back on '${target}'.`));
+            return;
+        }
+        // ── test only ───────────────────────────────────────────────────────
+        if (sub === 'test') {
+            const spinner = ora('Running live DeepSeek test turn...').start();
+            const t = await _dsSelfTest(client, config);
+            spinner.stop();
+            if (t.ok) {
+                console.log(chalk.green(`  ✓ DeepSeek answered${t.model ? ` (model: ${t.model})` : ''}.`));
+            }
+            else {
+                console.log(chalk.red(`  ✗ Test failed${t.model ? ` (served: ${t.model})` : ''}${t.error ? ` — ${t.error}` : ''}.`));
+                if (!/deepseek/i.test(t.model) && t.model) {
+                    console.log(chalk.yellow(`  The turn was served by '${t.model}', not DeepSeek — stack may not be switched.`));
+                }
+            }
+            return;
+        }
+        // ── on (default): full interactive wizard ───────────────────────────
+        console.log();
+        console.log(chalk.bold.cyan('  DeepSeek orchestrator setup'));
+        console.log(chalk.dim('  Routes the model you chat with to the DeepSeek API (V4). Reversible with /deepseek off.'));
+        console.log();
+        // 1. Show where we are.
+        let spinner = ora('Checking current routing...').start();
+        const before = await _dsActiveStack(client);
+        const hasKey = await _dsKeyPresent(client);
+        spinner.stop();
+        console.log(chalk.dim(`  Current stack: ${before.stack}${before.routesDeepseek ? ' (already routes DeepSeek)' : ''}`));
+        // 2. Ensure the API key exists (prompt if missing).
+        if (!hasKey) {
+            console.log();
+            console.log(chalk.yellow('  No DEEPSEEK_API_KEY found in the vault.'));
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            const ask = (q) => new Promise(resolve => rl.question(q, resolve));
+            let key = '';
+            try {
+                key = (await ask(chalk.cyan('  Paste your DeepSeek API key (or blank to cancel): '))).trim();
+            }
+            finally {
+                rl.close();
+            }
+            if (!key) {
+                console.log(chalk.yellow('  Cancelled — no key entered.'));
+                return;
+            }
+            spinner = ora('Storing key in vault...').start();
+            const sres = await client.postDetailed('/secrets', { key: 'DEEPSEEK_API_KEY', value: key });
+            spinner.stop();
+            if (sres?.error) {
+                console.log(chalk.red(`  Failed to store key: ${sres.error}`));
+                return;
+            }
+            console.log(chalk.green('  ✓ Key stored.'));
+        }
+        else {
+            console.log(chalk.dim('  DEEPSEEK_API_KEY already in vault — reusing it.'));
+        }
+        // 3. Switch the model stack (the real lever) unless already there.
+        if (before.stack !== _DEEPSEEK_STACK) {
+            _deepseekPrevStack = before.stack;
+            spinner = ora(`Switching model stack → ${_DEEPSEEK_STACK}...`).start();
+            const swres = await client.postDetailed('/model-stacks/switch', { stack: _DEEPSEEK_STACK });
+            spinner.stop();
+            if (swres?.error) {
+                console.log(chalk.red(`  Stack switch failed: ${swres.error}`));
+                console.log(chalk.dim('  (Need execute permission, and Genesis + MicroScheduler must be up.)'));
+                return;
+            }
+            console.log(chalk.green(`  ✓ Stack switched to ${_DEEPSEEK_STACK} (effort 5+ → DeepSeek).`));
+        }
+        else {
+            console.log(chalk.dim(`  Already on ${_DEEPSEEK_STACK}.`));
+        }
+        // 4. Prove it: live test turn.
+        spinner = ora('Verifying with a live DeepSeek turn...').start();
+        const t = await _dsSelfTest(client, config);
+        spinner.stop();
+        console.log();
+        if (t.ok) {
+            console.log(chalk.green.bold(`  ✓ Working — DeepSeek served the turn${t.model ? ` (model: ${t.model})` : ''}.`));
+            console.log(chalk.dim('  Effort 5+ chat now routes to DeepSeek. Low-effort reflex stays local.'));
+            console.log(chalk.dim('  Revert anytime:  /deepseek off    •    Re-check:  /deepseek status'));
+        }
+        else {
+            console.log(chalk.red.bold('  ✗ Stack switched but the test turn did NOT confirm DeepSeek.'));
+            if (t.model)
+                console.log(chalk.yellow(`    Served by: ${t.model}`));
+            if (t.error)
+                console.log(chalk.yellow(`    Error: ${t.error}`));
+            console.log(chalk.dim('    Likely causes: bad/missing key, V4 model name not allowed for your key,'));
+            console.log(chalk.dim('    or MicroScheduler down. Check: /deepseek status  and  /secrets get DEEPSEEK_API_KEY'));
+        }
+        console.log();
+    },
+};
+// ── /gateway — provision an ACTA gateway key for a deployment (the provision_gateway_key tool) ──
+COMMANDS.gateway = {
+    description: 'Provision a scoped ACTA gateway key (aither_sk_live_*) for a deployment',
+    usage: '/gateway mint <tenant> [scopes] [days]',
+    handler: async (client, args, _config) => {
+        const parts = args.trim().split(/\s+/).filter(Boolean);
+        if (parts[0] !== 'mint' || !parts[1]) {
+            console.log(chalk.yellow('  usage: /gateway mint <tenant> [scopes] [days]'));
+            console.log(chalk.dim('  e.g.   /gateway mint daoos-usb-demo  chat,agent:ask  30'));
+            return;
+        }
+        const tenant = parts[1];
+        const scopes = parts[2] || 'chat,agent:ask,agent:read';
+        const days = parseInt(parts[3] || '30', 10) || 30;
+        console.log(chalk.cyan(`  minting gateway key for ${tenant} (${scopes}, ${days}d)…`));
+        const res = await invokeMcpTool(client, 'provision_gateway_key', { tenant, scopes, expires_in_days: days });
+        if (res?.error) {
+            console.log(chalk.red('  ✗ ' + res.error));
+            return;
+        }
+        const key = res?.api_key || res?.key || '';
+        if (key) {
+            console.log(chalk.green(`  ✓ minted: ${String(key).slice(0, 18)}…${String(key).slice(-4)}`));
+            console.log(chalk.dim('  Save it to your deployment .env as AITHER_GATEWAY_KEY — shown once, never commit it.'));
+        }
+        else {
+            console.log(chalk.dim('  ' + JSON.stringify(res)));
+        }
+    },
+};
+// ── /panel — interactive dev control panel (secrets/env • routing • MCP • status) ──
+// A pop-up console you drive with the keyboard — no memorizing commands. Uses the
+// proven rl.question loop (same input path as /login and /deepseek), so it works in
+// both plain and TUI modes. Authenticated as the active shell user.
+COMMANDS.panel = {
+    description: 'Dev control panel — routing/DeepSeek, MCP tools, secrets/env, status',
+    usage: '/panel',
+    handler: async (client, _args, config) => {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        const ask = (q) => new Promise(resolve => rl.question(q, resolve));
+        const pause = async () => { await ask(chalk.dim('\n  ↵ enter to continue ')); };
+        const rule = (w = 58) => chalk.dim('  ' + '─'.repeat(w));
+        const header = (title) => {
+            console.clear();
+            console.log();
+            console.log(chalk.bold.cyan(`  AitherOS Dev Panel`) + chalk.dim(`  ·  ${title}`));
+            const who = config.authUser?.email || config.authUser?.username || 'local';
+            console.log(chalk.dim(`  ${who}  ·  ${config.genesisUrl}`));
+            console.log(rule());
+        };
+        // ── Section: Model routing & DeepSeek ──────────────────────────────
+        const routingMenu = async () => {
+            let back = false;
+            while (!back) {
+                header('Model routing & DeepSeek');
+                const spin = ora('Reading routing...').start();
+                const st = await _dsActiveStack(client).catch(() => null);
+                const hasKey = await _dsKeyPresent(client).catch(() => false);
+                spin.stop();
+                if (!st) {
+                    console.log(chalk.red('  Could not read /model-stacks/active (Genesis down?).'));
+                    await pause();
+                    return;
+                }
+                console.log(chalk.bold('  Active stack:    ') + chalk.cyan(st.stack));
+                console.log(chalk.bold('  DeepSeek routed: ') + (st.routesDeepseek ? chalk.green('yes (effort 5+)') : chalk.yellow('no')));
+                console.log(chalk.bold('  DeepSeek key:    ') + (hasKey ? chalk.green('stored') : chalk.red('missing')));
+                console.log();
+                for (const [tier, val] of Object.entries(st.tiers)) {
+                    const ds = /deepseek/i.test(val);
+                    console.log(`    ${tier.padEnd(10)} ${ds ? chalk.green(val) : chalk.dim(val)}`);
+                }
+                console.log(rule());
+                console.log('  [d] route orchestrator → DeepSeek    [l] revert to local/previous');
+                console.log('  [t] live self-test                   [r] refresh        [b] back');
+                const c = (await ask('\n  > ')).trim().toLowerCase();
+                if (c === 'b' || c === '') {
+                    back = true;
+                }
+                else if (c === 'r') { /* loop re-reads */ }
+                else if (c === 'd') {
+                    if (st.stack !== _DEEPSEEK_STACK)
+                        _deepseekPrevStack = st.stack;
+                    const s2 = ora(`Switching → ${_DEEPSEEK_STACK}...`).start();
+                    const res = await client.postDetailed('/model-stacks/switch', { stack: _DEEPSEEK_STACK });
+                    s2.stop();
+                    console.log(res?.error ? chalk.red(`  Failed: ${res.error}`) : chalk.green(`  ✓ Switched to ${_DEEPSEEK_STACK}.`));
+                    await pause();
+                }
+                else if (c === 'l') {
+                    const target = _deepseekPrevStack || 'dgx-hybrid';
+                    const s2 = ora(`Reverting → ${target}...`).start();
+                    const res = await client.postDetailed('/model-stacks/switch', { stack: target });
+                    s2.stop();
+                    if (!res?.error)
+                        _deepseekPrevStack = null;
+                    console.log(res?.error ? chalk.red(`  Failed: ${res.error}`) : chalk.green(`  ✓ Reverted to ${target}.`));
+                    await pause();
+                }
+                else if (c === 't') {
+                    const s2 = ora('Live DeepSeek test turn...').start();
+                    const t = await _dsSelfTest(client, config);
+                    s2.stop();
+                    console.log(t.ok ? chalk.green(`  ✓ Served by ${t.model || 'model'} — working.`)
+                        : chalk.red(`  ✗ ${t.error || 'no DeepSeek response'}${t.model ? ` (served: ${t.model})` : ''}`));
+                    await pause();
+                }
+            }
+        };
+        // ── Section: MCP tools ─────────────────────────────────────────────
+        const mcpMenu = async () => {
+            header('MCP tools');
+            const spin = ora('Loading tools...').start();
+            let tools = [];
+            try {
+                const remote = getRemoteMcpClient(config);
+                if (remote) {
+                    await remote.connect();
+                    tools = await remote.listTools();
+                }
+                else {
+                    const r = await client.get('/tools');
+                    tools = r?.tools || [];
+                }
+            }
+            catch (e) {
+                spin.stop();
+                console.log(chalk.red(`  Could not list tools: ${e?.message || e}`));
+                await pause();
+                return;
+            }
+            spin.stop();
+            if (!tools.length) {
+                console.log(chalk.yellow('  No MCP tools available (is the MCP gateway connected?).'));
+                await pause();
+                return;
+            }
+            let back = false;
+            let filter = '';
+            while (!back) {
+                header('MCP tools');
+                const shown = (filter ? tools.filter(t => (t.name || '').toLowerCase().includes(filter)) : tools).slice(0, 30);
+                shown.forEach((t, i) => {
+                    const desc = (t.description || '').split('\n')[0].slice(0, 60);
+                    console.log(`  ${String(i + 1).padStart(2)}. ${chalk.cyan((t.name || '').padEnd(28))} ${chalk.dim(desc)}`);
+                });
+                console.log(rule());
+                console.log(chalk.dim(`  ${shown.length} of ${tools.length} shown.  Type a number to run, /<text> to filter, b to go back.`));
+                const c = (await ask('\n  > ')).trim();
+                if (c.toLowerCase() === 'b' || c === '') {
+                    back = true;
+                }
+                else if (c.startsWith('/')) {
+                    filter = c.slice(1).toLowerCase();
+                }
+                else {
+                    const idx = parseInt(c, 10) - 1;
+                    const tool = shown[idx];
+                    if (!tool) {
+                        console.log(chalk.yellow('  No such number.'));
+                        await pause();
+                        continue;
+                    }
+                    console.log(chalk.dim(`\n  Args for ${tool.name} — JSON object, or k=v space-separated, or blank for none:`));
+                    const raw = (await ask('  args> ')).trim();
+                    let params = {};
+                    if (raw) {
+                        try {
+                            params = raw.startsWith('{') ? JSON.parse(raw)
+                                : Object.fromEntries(raw.split(/\s+/).map(p => { const i = p.indexOf('='); return [p.slice(0, i), p.slice(i + 1)]; }));
+                        }
+                        catch (e) {
+                            console.log(chalk.red(`  Bad args: ${e?.message || e}`));
+                            await pause();
+                            continue;
+                        }
+                    }
+                    const s2 = ora(`Running ${tool.name}...`).start();
+                    const res = await invokeMcpTool(client, tool.name, params);
+                    s2.stop();
+                    console.log(rule());
+                    if (res?.error)
+                        console.log(chalk.red(`  Error: ${res.error}`));
+                    else
+                        console.log('  ' + (typeof res === 'string' ? res : JSON.stringify(res, null, 2)).split('\n').join('\n  '));
+                    await pause();
+                }
+            }
+        };
+        // ── Section: Secrets & env ─────────────────────────────────────────
+        const secretsMenu = async () => {
+            header('Secrets & env');
+            const spin = ora('Reading vault...').start();
+            // Genesis has no /secrets route on all deployments; probe and degrade honestly.
+            const listing = await client.getDetailed('/secrets');
+            spin.stop();
+            const keys = listing?.keys || listing?.secrets;
+            if (Array.isArray(keys)) {
+                console.log(chalk.bold(`  ${keys.length} secret(s):`));
+                for (const k of keys)
+                    console.log(`    ${chalk.cyan(typeof k === 'string' ? k : (k.key || k.name))}`);
+                console.log(rule());
+                console.log('  [s] set a secret   [d] delete   [b] back');
+                const c = (await ask('\n  > ')).trim().toLowerCase();
+                if (c === 's') {
+                    const k = (await ask('  key:   ')).trim();
+                    const v = (await ask('  value: ')).trim();
+                    if (k && v) {
+                        const r = await client.postDetailed('/secrets', { key: k, value: v });
+                        console.log(r?.error ? chalk.red(`  Failed: ${r.error}`) : chalk.green(`  ✓ ${k} stored.`));
+                    }
+                    await pause();
+                }
+                else if (c === 'd') {
+                    const k = (await ask('  key to delete: ')).trim();
+                    if (k) {
+                        const r = await client.postDetailed(`/secrets/${k}/delete`, {});
+                        console.log(r?.error ? chalk.red(`  Failed: ${r.error}`) : chalk.green(`  ✓ ${k} deleted.`));
+                    }
+                    await pause();
+                }
+            }
+            else {
+                console.log(chalk.yellow('  The secrets vault is not exposed through Genesis on this deployment.'));
+                console.log(chalk.dim('  (GET /secrets → 404. The vault at :8111 rejects unauthenticated writes by design.)'));
+                console.log();
+                console.log(chalk.dim('  To make this section live, a small owner-gated Genesis route is needed that'));
+                console.log(chalk.dim('  proxies reads/writes to AitherSecrets using Genesis’s in-cluster credential.'));
+                console.log(chalk.dim('  Routing, MCP tools, and status below work without it.'));
+                await pause();
+            }
+        };
+        // ── Section: Service status ────────────────────────────────────────
+        const statusView = async () => {
+            header('Service status');
+            const spin = ora('Querying Genesis...').start();
+            const st = await client.get('/status').catch(() => null);
+            spin.stop();
+            if (!st) {
+                console.log(chalk.red('  /status unavailable.'));
+                await pause();
+                return;
+            }
+            const tracked = st.tracked_services ?? st.count ?? '?';
+            const healthy = st.healthy ?? st.healthy_count ?? '?';
+            console.log(chalk.bold('  Tracked services: ') + tracked);
+            console.log(chalk.bold('  Healthy:          ') + healthy);
+            if (st.generation_ready !== undefined)
+                console.log(chalk.bold('  Generation ready: ') + (st.generation_ready ? chalk.green('yes') : chalk.yellow('no')));
+            await pause();
+        };
+        // ── Main loop ──────────────────────────────────────────────────────
+        try {
+            let running = true;
+            while (running) {
+                header('main');
+                console.log('  1) Model routing & DeepSeek');
+                console.log('  2) MCP tools');
+                console.log('  3) Secrets & env');
+                console.log('  4) Service status');
+                console.log('  q) Quit');
+                const c = (await ask('\n  > ')).trim().toLowerCase();
+                if (c === 'q' || c === 'quit' || c === 'exit')
+                    running = false;
+                else if (c === '1')
+                    await routingMenu();
+                else if (c === '2')
+                    await mcpMenu();
+                else if (c === '3')
+                    await secretsMenu();
+                else if (c === '4')
+                    await statusView();
+            }
+        }
+        finally {
+            rl.close();
+            console.clear();
+            console.log(chalk.dim('  Dev panel closed.'));
+        }
+    },
+};
 COMMANDS['pool'] = {
     description: 'LLM pool management — check status or reset stuck slots',
     usage: '/pool [status|reset]',
@@ -5351,12 +7049,43 @@ COMMANDS['pool'] = {
     },
 };
 // ═══════════════════════════════════════════════════════════════════════════
+// FLEET — rebuild every lib-baking Python image + safe rolling recreate onto current code
+// ═══════════════════════════════════════════════════════════════════════════
+COMMANDS['fleet'] = {
+    description: 'Fleet refresh — rebuild all lib-baking Python images + safe rolling recreate',
+    usage: '/fleet refresh [--build-only|--recreate-only|--dry-run]',
+    handler: async (_client, args, _config) => {
+        const __dirname = dirname(fileURLToPath(import.meta.url));
+        const repoRoot = resolve(__dirname, '..', '..', '..', '..', '..');
+        const script = join(repoRoot, '.DEPLOYMENT', 'scripts', 'fleet-refresh.sh');
+        if (!existsSync(script)) {
+            console.log(chalk.red(`  fleet-refresh.sh not found: ${script}`));
+            return;
+        }
+        const parts = args.trim().split(/\s+/).filter(Boolean);
+        if (parts[0] !== 'refresh') {
+            console.log(chalk.yellow('  Usage: /fleet refresh [--build-only|--recreate-only|--dry-run]'));
+            return;
+        }
+        const allowed = ['--build-only', '--recreate-only', '--dry-run'];
+        const flags = parts.slice(1).filter((f) => allowed.includes(f));
+        console.log(chalk.cyan(`  Running fleet-refresh ${flags.join(' ')} ...`));
+        try {
+            execSync(`bash "${script}" ${flags.join(' ')}`, { stdio: 'inherit', cwd: repoRoot });
+        }
+        catch (e) {
+            console.log(chalk.red(`  fleet-refresh failed: ${e?.message || e}`));
+        }
+    },
+};
+// ═══════════════════════════════════════════════════════════════════════════
 // DOCKER — Container lifecycle management
 // ═══════════════════════════════════════════════════════════════════════════
 COMMANDS['docker'] = {
-    description: 'Manage Docker containers (up/down/status/build/restart/logs/ps)',
-    usage: '/docker <up|down|status|restart|build|logs|ps> [--build] [service]',
+    description: 'Manage Docker containers (up/down/status/build/restart/logs/ps/recover)',
+    usage: '/docker <up|down|status|restart|build|logs|ps|recover> [--build] [service]',
     handler: async (_client, args, _config) => {
+        const __dirname = dirname(fileURLToPath(import.meta.url));
         const repoRoot = resolve(__dirname, '..', '..', '..', '..', '..');
         const composeFile = join(repoRoot, 'docker-compose.aitheros.yml');
         if (!existsSync(composeFile)) {
@@ -5517,9 +7246,109 @@ COMMANDS['docker'] = {
                 });
                 break;
             }
+            case 'recover': {
+                // Recover Docker Desktop from WSL2 500-error hang (no reboot needed)
+                console.log();
+                const isHealthy = (() => {
+                    try {
+                        const r = execSync('docker info 2>&1', { encoding: 'utf-8', timeout: 10000 });
+                        return !r.includes('500 Internal Server Error');
+                    }
+                    catch {
+                        return false;
+                    }
+                })();
+                if (isHealthy && !rest.includes('--force')) {
+                    console.log(chalk.green('  Docker engine is healthy. Use --force to recover anyway.'));
+                    break;
+                }
+                console.log(chalk.red('  Docker engine is DOWN. Starting recovery...'));
+                const recoverSteps = [
+                    ['[1/5] Killing Docker Desktop...', [
+                            'taskkill /F /IM "Docker Desktop.exe" 2>NUL',
+                            'taskkill /F /IM "com.docker.backend.exe" 2>NUL',
+                            'taskkill /F /IM "com.docker.build.exe" 2>NUL',
+                            'taskkill /F /IM "docker-agent.exe" 2>NUL',
+                            'taskkill /F /IM "docker-sandbox.exe" 2>NUL',
+                        ]],
+                    ['[2/5] Shutting down WSL...', ['wsl --shutdown']],
+                    ['[3/5] Cleaning up zombie processes...', [
+                            'taskkill /F /IM vmmem 2>NUL',
+                            'taskkill /F /IM wslservice.exe 2>NUL',
+                        ]],
+                    ['[4/5] Restarting Docker service...', [
+                            'net stop com.docker.service 2>NUL',
+                            'net start com.docker.service 2>NUL',
+                        ]],
+                ];
+                for (const [label, shellCmds] of recoverSteps) {
+                    console.log(chalk.yellow(`  ${label}`));
+                    for (const c of shellCmds) {
+                        try {
+                            execSync(c, { encoding: 'utf-8', timeout: 15000, stdio: 'pipe' });
+                        }
+                        catch { }
+                    }
+                    await new Promise(r => setTimeout(r, 2000));
+                }
+                console.log(chalk.yellow('  [5/5] Starting Docker Desktop...'));
+                spawn('C:\\Program Files\\Docker\\Docker\\Docker Desktop.exe', [], {
+                    detached: true, stdio: 'ignore',
+                }).unref();
+                // Wait for engine to come back
+                const recoverSpinner = ora('  Waiting for Docker engine...').start();
+                let recovered = false;
+                for (let elapsed = 5; elapsed <= 90; elapsed += 5) {
+                    await new Promise(r => setTimeout(r, 5000));
+                    try {
+                        const info = execSync('docker info 2>&1', { encoding: 'utf-8', timeout: 10000 });
+                        if (!info.includes('500 Internal Server Error')) {
+                            recoverSpinner.succeed(chalk.green(`  Docker recovered in ${elapsed}s!`));
+                            recovered = true;
+                            break;
+                        }
+                    }
+                    catch { }
+                }
+                if (!recovered) {
+                    recoverSpinner.fail(chalk.red('  Recovery failed after 90s. You may need to reboot.'));
+                    break;
+                }
+                // Clean up dead containers
+                try {
+                    const deadContainers = execSync('docker ps -a --filter status=dead --format "{{.Names}}"', {
+                        encoding: 'utf-8', timeout: 10000,
+                    }).trim();
+                    for (const name of deadContainers.split('\n').filter(Boolean)) {
+                        console.log(chalk.dim(`  Removing dead: ${name}`));
+                        try {
+                            execSync(`docker rm -f ${name}`, { timeout: 10000, stdio: 'pipe' });
+                        }
+                        catch { }
+                    }
+                }
+                catch { }
+                // Restart exited containers
+                try {
+                    const exitedContainers = execSync('docker ps -a --filter status=exited --format "{{.Names}}"', {
+                        encoding: 'utf-8', timeout: 10000,
+                    }).trim();
+                    for (const name of exitedContainers.split('\n').filter(Boolean)) {
+                        console.log(chalk.dim(`  Restarting: ${name}`));
+                        try {
+                            execSync(`docker start ${name}`, { timeout: 10000, stdio: 'pipe' });
+                        }
+                        catch { }
+                    }
+                }
+                catch { }
+                const finalCount = execSync('docker ps -q', { encoding: 'utf-8', timeout: 5000 }).trim().split('\n').filter(Boolean).length;
+                console.log(chalk.green(`  ${finalCount} containers running`));
+                break;
+            }
             default:
                 console.log(chalk.yellow('  Unknown subcommand: ' + subcmd));
-                console.log(chalk.dim('  Available: up [--build], down, restart, build, status, ps, logs <service>'));
+                console.log(chalk.dim('  Available: up [--build], down, restart, build, status, ps, logs <service>, recover [--force]'));
         }
     },
 };
@@ -6659,7 +8488,7 @@ COMMANDS['ingest'] = {
 // ── Sovereign Install (standalone binary entry point) ──────────────────────
 COMMANDS['install'] = {
     description: 'Full AitherOS sovereign install — auth, Docker, pull, boot, extensions',
-    usage: '/install [--profile chat-minimal] [--with node,connect] [--non-interactive]',
+    usage: '/install [--profile chat-minimal|personal] [--with node,connect] [--non-interactive]',
     handler: async (_client, args, config) => {
         const flags = args.split(/\s+/).filter(Boolean);
         let profile = 'chat-minimal';
@@ -6676,6 +8505,29 @@ COMMANDS['install'] = {
                 nonInteractive = true;
             }
         }
+        // Auto-resolve "personal" to sub-profile based on GPU
+        if (profile === 'personal') {
+            try {
+                const gpuOut = execSync('nvidia-smi --query-gpu=memory.total --format=csv,noheader,nounits', { timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] }).toString().trim();
+                const vramMb = parseInt(gpuOut.split('\n')[0], 10);
+                if (vramMb >= 7500) {
+                    profile = 'personal-gpu';
+                    console.log(chalk.cyan(`  GPU detected (${vramMb}MB) -> vLLM AWQ profile`));
+                }
+                else if (vramMb >= 5500) {
+                    profile = 'personal-ollama';
+                    console.log(chalk.cyan(`  GPU detected (${vramMb}MB) -> Ollama GPU profile`));
+                }
+                else {
+                    profile = 'personal-cpu';
+                    console.log(chalk.yellow(`  GPU too small (${vramMb}MB) -> CPU profile`));
+                }
+            }
+            catch {
+                profile = 'personal-cpu';
+                console.log(chalk.yellow('  No GPU detected -> CPU inference profile'));
+            }
+        }
         const spinner = ora('Starting AitherOS sovereign install...').start();
         // Step 1: Auth check
         const token = getActiveToken();
@@ -6748,6 +8600,20 @@ COMMANDS['install'] = {
         else {
             spinner.warn('Genesis did not become healthy in 90s (services may still be starting)');
         }
+        // Step 6b: Pull Nemotron model for Ollama profiles
+        if (profile === 'personal-ollama' || profile === 'personal-cpu') {
+            spinner.start('Pulling Nemotron-Orchestrator-8B model...');
+            const container = profile === 'personal-cpu'
+                ? 'aither-ollama-personal-cpu'
+                : 'aither-ollama-personal';
+            try {
+                execSync(`docker exec ${container} ollama pull nemotron-orchestrator:8b-q4_K_M`, { timeout: 600_000, stdio: 'pipe' });
+                spinner.succeed('Model downloaded');
+            }
+            catch {
+                spinner.warn('Model will download on first use');
+            }
+        }
         // Step 7: Install extensions via API
         if (extensions.length > 0 && healthy) {
             spinner.start('Installing extensions...');
@@ -6773,10 +8639,164 @@ COMMANDS['install'] = {
         if (extensions.length) {
             console.log(`  Extensions: ${chalk.dim(extensions.join(', '))}`);
         }
+        if (profile.startsWith('personal')) {
+            console.log(`  Feedback:   ${chalk.dim('/feedback in AitherShell')}`);
+            console.log(`  Support:    ${chalk.cyan('https://demo.aitherium.com/support')}`);
+            console.log(`  Bug Report: ${chalk.dim('/report-bug in AitherShell')}`);
+        }
         console.log('');
         console.log(chalk.dim('Run "aither status" to check service health.'));
     },
 };
+// =============================================================================
+// Feedback, Support & Bug Reporting (Personal Agent)
+// =============================================================================
+COMMANDS['feedback'] = {
+    description: 'Submit feedback on your agent experience',
+    usage: '/feedback [thumbs-up | thumbs-down | "comment text"]',
+    handler: async (client, args, config) => {
+        const token = getActiveToken();
+        if (!token) {
+            console.log(chalk.red('  Not logged in. Run: /login'));
+            return;
+        }
+        const trimmed = args.trim();
+        let rating = 0;
+        let comment = '';
+        let category = '';
+        if (!trimmed) {
+            // Interactive mode
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            const ask = (q) => new Promise(r => rl.question(q, r));
+            console.log(chalk.bold('\n  Submit Feedback\n'));
+            const ratingStr = await ask('  Rating (1=bad, 3=ok, 5=great): ');
+            rating = Math.max(-1, Math.min(1, Math.round((parseInt(ratingStr, 10) || 3) / 2.5 - 1)));
+            comment = await ask('  Comment (optional): ');
+            const catStr = await ask('  Category (bug/feature/performance/other): ');
+            category = catStr.trim() || 'other';
+            rl.close();
+        }
+        else if (trimmed === 'thumbs-up' || trimmed === '+1' || trimmed === 'up') {
+            rating = 1;
+            comment = 'Thumbs up';
+        }
+        else if (trimmed === 'thumbs-down' || trimmed === '-1' || trimmed === 'down') {
+            rating = -1;
+            comment = 'Thumbs down';
+        }
+        else {
+            comment = trimmed;
+        }
+        try {
+            const resp = await client.post('/feedback', {
+                rating,
+                comment,
+                category,
+                metadata: { source: 'aithershell', plan: 'personal' },
+            });
+            const fid = resp?.feedback_id || 'submitted';
+            console.log(chalk.green(`  Feedback received (${fid}). Thank you!`));
+        }
+        catch (err) {
+            console.log(chalk.red(`  Failed to submit feedback: ${err.message || err}`));
+            console.log(chalk.dim('  You can also submit at: https://demo.aitherium.com/support'));
+        }
+    },
+};
+COMMANDS['support'] = {
+    description: 'Open support page or show support options',
+    usage: '/support [docs | contact | status]',
+    handler: async (_client, args) => {
+        const sub = args.trim().toLowerCase() || '';
+        const urls = {
+            '': { url: 'https://demo.aitherium.com/support', label: 'Support Portal' },
+            docs: { url: 'https://docs.aitherium.com', label: 'Documentation' },
+            contact: { url: 'https://demo.aitherium.com/support', label: 'Contact Support' },
+            status: { url: 'https://status.aitherium.com', label: 'System Status' },
+            community: { url: 'https://github.com/Aitherium/aither-adk/discussions', label: 'Community' },
+        };
+        const entry = urls[sub];
+        if (!entry) {
+            console.log(chalk.red(`  Unknown option: ${sub}`));
+            console.log(chalk.dim('  Options: docs, contact, status, community'));
+            return;
+        }
+        console.log(chalk.bold(`\n  Opening ${entry.label}...`));
+        console.log(chalk.cyan(`  ${entry.url}\n`));
+        try {
+            const platform = process.platform;
+            const cmd = platform === 'win32' ? 'start' : platform === 'darwin' ? 'open' : 'xdg-open';
+            // Use start "" "url" on Windows to handle URLs with special chars
+            const shellCmd = platform === 'win32' ? `start "" "${entry.url}"` : `${cmd} "${entry.url}"`;
+            execSync(shellCmd, { stdio: 'ignore' });
+        }
+        catch {
+            console.log(chalk.dim('  Could not open browser. Visit the URL above manually.'));
+        }
+    },
+};
+COMMANDS['report-bug'] = {
+    description: 'Report a bug with structured details',
+    usage: '/report-bug [--title "..."] [--severity low|medium|high]',
+    handler: async (client, args) => {
+        const token = getActiveToken();
+        if (!token) {
+            console.log(chalk.red('  Not logged in. Run: /login'));
+            return;
+        }
+        let title = '';
+        let description = '';
+        let severity = 'medium';
+        const trimmed = args.trim();
+        if (!trimmed) {
+            // Interactive mode
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            const ask = (q) => new Promise(r => rl.question(q, r));
+            console.log(chalk.bold('\n  Report a Bug\n'));
+            title = await ask('  Bug title: ');
+            if (!title.trim()) {
+                console.log(chalk.red('  Title is required.'));
+                rl.close();
+                return;
+            }
+            description = await ask('  Description: ');
+            const sevStr = await ask('  Severity (low/medium/high) [medium]: ');
+            severity = ['low', 'medium', 'high'].includes(sevStr.trim()) ? sevStr.trim() : 'medium';
+            rl.close();
+        }
+        else {
+            // Parse flags: --title "..." --severity low
+            const titleMatch = trimmed.match(/--title\s+"([^"]+)"/);
+            const sevMatch = trimmed.match(/--severity\s+(\w+)/);
+            title = titleMatch?.[1] || trimmed.replace(/--\w+\s+"[^"]*"/g, '').replace(/--\w+\s+\w+/g, '').trim();
+            severity = sevMatch?.[1] || 'medium';
+        }
+        try {
+            const resp = await client.post('/feedback', {
+                rating: -1,
+                comment: `[BUG] ${title}\n\n${description}`,
+                category: 'Bug',
+                metadata: {
+                    source: 'aithershell',
+                    plan: 'personal',
+                    severity,
+                    type: 'bug_report',
+                },
+            });
+            const fid = resp?.feedback_id || 'submitted';
+            console.log(chalk.green(`\n  Bug report submitted (${fid}).`));
+            console.log(chalk.dim('  Our team will review this. Track progress at:'));
+            console.log(chalk.cyan('  https://demo.aitherium.com/support\n'));
+        }
+        catch (err) {
+            console.log(chalk.red(`  Failed to submit: ${err.message || err}`));
+            console.log(chalk.dim('  Submit directly at: https://demo.aitherium.com/support'));
+        }
+    },
+};
+COMMANDS['bug'] = COMMANDS['report-bug'];
+COMMANDS['draw'] = COMMANDS['imagine'];
+COMMANDS['gen'] = COMMANDS['imagine'];
 export function getCommand(name) {
     return COMMANDS[name.toLowerCase()];
 }