kiku-agent 1.2.0 → 1.3.0

package/server/agent/commands.js

@@ -12,13 +12,47 @@ import { DebateOrchestrator } from './debate.js';
 import { timelineData } from '../../src/data/timelineData.js';
 import { COMMAND_NAMES, getCommandDetails, findCommandDefinition } from './commandRegistry.js';
 import { THEMES, THEME_NAMES, ansiBackground, ansiForeground, getThemeName, setTheme } from './theme.js';
-import { getGpuMetrics, formatProgressBar } from './gpuMetrics.js';
+import { getGpuMetrics, getSharedMemoryMetrics, formatProgressBar } from './gpuMetrics.js';
+import { computeVramEstimate, getHardwareTarget, probeLmStudioRuntime, resolveSystemHardwareTier } from './vramService.js';
+import { formatGb, bytesToGb, QUANT_BPW, classifyAllocation, QUANT_LADDER, parseBpw } from '../../src/lib/vram/estimator.js';
+import { matchModelIdentifier } from './config.js';
+import { MODEL_REGISTRY } from '../../src/lib/vram/modelRegistry.js';
+import { computePercentile } from './tokenTracker.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import http from 'node:http';
 import { PACKAGE_NAME, PACKAGE_VERSION } from './version.js';
 import { QUIZ_QUESTIONS, QUIZ_I18N, LETTER_LABELS, shuffleQuizQuestions } from './quizData.js';
 import crypto from 'node:crypto';
 import { isAbortError } from './errors.js';
 import { featureCommandHandlers, aiNarration, languageHint } from './commandFeatures.js';
 import { startWebChatServer, stopWebChatServer, getWebChatServerStatus, openBrowser } from '../webChatServer.js';
+import readline from 'node:readline';
+import {
+  resolveEnvTargets,
+  readEnvFile,
+  readMergedEnvMap,
+  upsertEnvKey,
+  removeEnvKey,
+  maskValue,
+  isSecretKey,
+  ENV_VAR_CATALOG,
+  describeGroup,
+  detectAutoDefaults,
+  generateEnvFile,
+} from './envManager.js';
+import { cleanUrl } from './research.js';
+
+function askEnvQuestion(question, defaultValue = '') {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: false });
+    const suffix = defaultValue ? ` ${C.dim}[${defaultValue}]${C.reset}` : '';
+    rl.question(`${C.cyberCyan}>${C.reset} ${question}${suffix}: `, (answer) => {
+      rl.close();
+      resolve(String(answer ?? '').trim());
+    });
+  });
+}
 
 function levenshteinDistance(a, b) {
   const matrix = Array.from({ length: a.length + 1 }, () => Array(b.length + 1).fill(0));
@@ -92,6 +126,228 @@ export function fuzzyMatchTools(query) {
     .sort((a, b) => b.score - a.score);
 }
 
+function parseVramArgs(tokens = []) {
+  const overrides = {};
+  const positional = [];
+  let force = false;
+  const num = (value) => {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  };
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    const nextVal = () => tokens[++i];
+    if (token === '--ctx') overrides.contextLength = num(nextVal());
+    else if (token === '--quant') overrides.quant = nextVal();
+    else if (token === '--params') overrides.paramsB = num(nextVal());
+    else if (token === '--layers') overrides.layers = num(nextVal());
+    else if (token === '--kv-heads') overrides.kvHeads = num(nextVal());
+    else if (token === '--head-dim') overrides.headDim = num(nextVal());
+    else if (token === '--cache-bits') overrides.cacheBits = num(nextVal());
+    else if (token === '--batch') overrides.batchSize = num(nextVal());
+    else if (token === '--force') force = true;
+    else positional.push(token);
+  }
+  return { overrides, positional, force };
+}
+
+function zoneBadge(zone) {
+  const color = zone === 'GREEN' ? C.emerald : zone === 'YELLOW' ? C.gold : zone === 'RED' ? C.roseGlow : C.slate;
+  return `${color}[${zone}]${C.reset}`;
+}
+
+function resolveVramModelTarget(ctx, positional = []) {
+  const target = positional.join(' ');
+  if (!target) return { modelName: ctx.agent?.client?.model || null, modelPath: null };
+  if (/\.gguf$/i.test(target)) return { modelName: null, modelPath: target };
+  return { modelName: target, modelPath: null };
+}
+
+/** `/vram live` — actual VRAM usage right now vs. the model's footprint. */
+async function printVramLivePanel(ctx, { overrides, positional }) {
+  const client = ctx.agent?.client || null;
+  const { modelName, modelPath } = resolveVramModelTarget(ctx, positional);
+
+  const [hw, runtime, shared] = await Promise.all([
+    getHardwareTarget(),
+    client?.baseUrl ? probeLmStudioRuntime(client.baseUrl) : Promise.resolve({ reachable: false }),
+    getSharedMemoryMetrics('lm'),
+  ]);
+
+  const result = await computeVramEstimate({ model: modelName, modelPath, ...overrides, includeHardware: false });
+  const est = result.estimate;
+
+  const lines = [];
+  let livePct = null;
+  let freeBytes = null;
+  if (hw.available && hw.freeBytes !== null && hw.freeBytes !== undefined) {
+    const usedBytes = Math.max(0, hw.totalBytes - hw.freeBytes);
+    freeBytes = hw.freeBytes;
+    const live = classifyAllocation({ totalBytes: usedBytes, availableBytes: hw.totalBytes });
+    livePct = live.usagePct;
+    const filled = Math.round((Math.min(100, live.usagePct) / 100) * 24);
+    const bar = `${C.gold}${'█'.repeat(filled)}${C.dim}${'░'.repeat(24 - filled)}${C.reset}`;
+    lines.push(`${C.gold}GPU (live):${C.reset} ${C.bold}${C.white}${hw.name}${C.reset} ${C.dim}via ${hw.source}${C.reset}`);
+    lines.push(`             ${bar} ${C.bold}${live.usagePct}%${C.reset} ${C.dim}(${formatGb(usedBytes)} / ${formatGb(hw.totalBytes)} used) ${zoneBadge(live.zone)}${C.reset}`);
+    lines.push(`${C.gold}Free VRAM:${C.reset}  ${C.emerald}${formatGb(freeBytes)}${C.reset}`);
+    if (shared?.available) {
+      if (shared.hasSpillover) {
+        lines.push(`${C.roseGlow}Shared GPU:${C.reset} ${C.bold}${C.roseGlow}${shared.sharedMemoryUsedMb} MB (SPILLOVER DETECTED — PCIe fallback degrades decoding speed)${C.reset}`);
+      } else {
+        lines.push(`${C.gold}Shared GPU:${C.reset} ${C.emerald}${shared.sharedMemoryUsedMb} MB (0% spillover — 100% Dedicated VRAM)${C.reset}`);
+      }
+    }
+  } else if (hw.available) {
+    lines.push(`${C.gold}GPU:${C.reset} ${C.white}${hw.name}${C.reset} ${C.dim}(total ${formatGb(hw.totalBytes)} — live usage unavailable)${C.reset}`);
+  } else {
+    lines.push(`${C.gold}GPU:${C.reset} ${C.dim}not detected — ${hw.reason || 'no queryable VRAM'}${C.reset}`);
+  }
+
+  lines.push(`${C.gold}Model:${C.reset}     ${C.bold}${C.white}${result.architecture.name || modelName || modelPath || 'unknown'}${C.reset}${result.approximate ? C.dim + ' (approx)' : ''}${C.reset} ${C.dim}[${result.configSource}]${C.reset}`);
+  if (runtime?.reachable) {
+    lines.push(`${C.gold}LM Studio:${C.reset} loaded ${C.white}${runtime.loadedModel || '?'}${C.reset}${runtime.loadedContextLength ? `${C.dim} @ ${runtime.loadedContextLength.toLocaleString('en-US')} ctx${runtime.quantization ? ` • ${runtime.quantization}` : ''}${C.reset}` : ''}`);
+  } else {
+    lines.push(`${C.gold}LM Studio:${C.reset} ${C.dim}not reachable — using checkpoint/registry context${C.reset}`);
+  }
+
+  const runtimeCtx = Number(overrides.contextLength) || runtime?.loadedContextLength || est.contextLength;
+  const estCls = hw.available ? classifyAllocation({ totalBytes: est.totalBytes, availableBytes: hw.totalBytes }) : null;
+  lines.push(`${C.gold}Estimate:${C.reset}   ${C.bold}${C.white}${formatGb(est.totalBytes)}${C.reset} @ ${C.white}${runtimeCtx ? runtimeCtx.toLocaleString('en-US') : '?'} ctx${C.reset}` +
+    ` ${C.dim}(weights ${formatGb(est.weightsBytes)} + KV ${formatGb(est.kvCacheBytes)} + fixed ${formatGb((est.activationBytes || 0) + (est.overheadBytes || 0))})${C.reset}` +
+    (estCls && estCls.zone !== 'UNKNOWN' ? ` ${zoneBadge(estCls.zone)}` : ''));
+
+  const loadedMatch = Boolean(runtime?.loadedModel && client?.model && matchModelIdentifier(client.model, runtime.loadedModel));
+  if (loadedMatch && livePct !== null) {
+    lines.push('',
+      livePct <= 80
+        ? `${C.emerald}${C.bold}Model already loaded & running at ${livePct}% VRAM — plenty of headroom.${C.reset}`
+        : `${C.gold}${C.bold}Model already loaded & running at ${livePct}% VRAM — it fits, but the card is tight.${C.reset}`,
+      `${C.dim}The naive full-attention estimate overstates sliding-window models (Gemma/Qwen); the live reading above is authoritative.${C.reset}`);
+  } else if (freeBytes !== null && est.totalBytes > 0) {
+    if (est.totalBytes <= freeBytes) {
+      lines.push('', `${C.emerald}${C.bold}Fits right now:${C.reset} ${C.emerald}free VRAM ${formatGb(freeBytes)} covers the ${formatGb(est.totalBytes)} estimate.${C.reset}`);
+    } else {
+      lines.push('', `${C.roseGlow}Does not fit right now:${C.reset} estimate ${formatGb(est.totalBytes)} vs ${formatGb(freeBytes)} free.`,
+        `${C.dim}Close other VRAM users, lower the context, or pick a lighter quant: /vram compare${C.reset}`);
+    }
+  } else if (estCls && estCls.zone !== 'UNKNOWN') {
+    lines.push('', `${C.dim}Live usage unavailable — estimate-only feasibility: ${estCls.zone}${C.reset}`);
+  }
+
+  printSolidPanel({
+    title: 'VRAM Live Status',
+    lines,
+    headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m'
+  });
+  return 'HANDLED';
+}
+
+/** `/vram compare` — every quantization for one model/context against the card. */
+async function printVramQuantCompare(ctx, { overrides, positional }) {
+  const client = ctx.agent?.client || null;
+  const { modelName, modelPath } = resolveVramModelTarget(ctx, positional);
+
+  const base = await computeVramEstimate({ model: modelName, modelPath, ...overrides, includeHardware: false });
+  const est = base.estimate;
+  if (!est.paramCount || !est.layers || !est.kvHeads || !est.headDim) {
+    console.log(`\n  ${C.amber}Insufficient architecture data for ${base.architecture.name || modelName || 'model'}.${C.reset}`);
+    console.log(`  ${C.dim}Pass explicit geometry: --params <B> --layers <n> --kv-heads <n> --head-dim <n> (or check /vram list).${C.reset}\n`);
+    return 'HANDLED';
+  }
+
+  const ctxLen = Number(overrides.contextLength) || est.contextLength || 16384;
+  const hw = await getHardwareTarget();
+  const fixed = (est.activationBytes || 0) + (est.overheadBytes || 0);
+  const visionBytes = est.visionEncoderBytes || 0;
+  const kvPerToken = est.kvBytesPerToken;
+
+  const rows = QUANT_LADDER.map((quant) => {
+    const bpw = parseBpw(quant);
+    const weights = Math.round(est.paramCount * bpw / 8) + visionBytes;
+    const kv = kvPerToken ? Math.round(kvPerToken * ctxLen) : 0;
+    const total = weights + kv + fixed;
+    const cls = hw.available ? classifyAllocation({ totalBytes: total, availableBytes: hw.totalBytes }) : null;
+    return { quant, weights, total, cls };
+  });
+
+  const lines = [
+    `${C.gold}Model:${C.reset} ${C.bold}${C.white}${base.architecture.name || modelName || 'model'}${C.reset} ${C.dim}(${(est.paramCount / 1e9).toFixed(1)}B • ${est.layers}L • GQA ${est.queryHeads}/${est.kvHeads} • d=${est.headDim}${visionBytes ? ' • VLM' : ''})${C.reset}`,
+    `${C.gold}Context:${C.reset} ${C.white}${ctxLen.toLocaleString('en-US')} tokens${C.reset}${hw.available ? ` ${C.dim}vs ${formatGb(hw.totalBytes)} card${C.reset}` : ` ${C.dim}(no GPU detected — zones unavailable)${C.reset}`}`,
+    '',
+    `${C.bold}${C.lavender}${'Quantization'.padEnd(13)}${'Weights'.padStart(10)}   ${'Total'.padStart(10)}   ${'vs Card'.padStart(9)}  Zone${C.reset}`,
+  ];
+  for (const row of rows) {
+    const marker = row.quant === est.quant ? `${C.cyberCyan}*${C.reset}` : ' ';
+    const zone = row.cls ? zoneBadge(row.cls.zone) : `${C.dim}—${C.reset}`;
+    const pct = row.cls ? `${row.cls.usagePct}%` : '—';
+    lines.push(`${marker} ${String(row.quant.toUpperCase()).padEnd(12)}${formatGb(row.weights).padStart(10)}   ${formatGb(row.total).padStart(10)}   ${String(pct).padStart(9)}  ${zone}`);
+  }
+  const firstGreen = rows.find(r => r.cls?.zone === 'GREEN');
+  if (firstGreen) {
+    lines.push('', `${C.dim}First GREEN at this context: ${C.reset}${C.emerald}${firstGreen.quant.toUpperCase()} → ${formatGb(firstGreen.total)}${C.reset}`);
+  }
+  lines.push(`${C.dim}Estimates assume full-attention KV caching; sliding-window models (Gemma, Qwen SWA layers) cache less.${C.reset}`);
+  printSolidPanel({
+    title: 'VRAM Quantization Compare',
+    lines,
+    headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m'
+  });
+  return 'HANDLED';
+}
+
+/** `/vram ctx` — how far the context ladder fits at the chosen quantization. */
+async function printVramContextLadder(ctx, { overrides, positional }) {
+  const client = ctx.agent?.client || null;
+  const { modelName, modelPath } = resolveVramModelTarget(ctx, positional);
+
+  const base = await computeVramEstimate({ model: modelName, modelPath, ...overrides, includeHardware: false });
+  const est = base.estimate;
+  if (!est.paramCount || !est.kvBytesPerToken) {
+    console.log(`\n  ${C.amber}Insufficient architecture data for ${base.architecture.name || modelName || 'model'} — pass --params/--layers/--kv-heads/--head-dim.${C.reset}\n`);
+    return 'HANDLED';
+  }
+
+  const quant = String(overrides.quant || est.quant || 'q4_k_m');
+  const bpw = parseBpw(quant) ?? 4.5;
+  const weights = Math.round(est.paramCount * bpw / 8) + (est.visionEncoderBytes || 0);
+  const fixed = (est.activationBytes || 0) + (est.overheadBytes || 0);
+  const kvPerToken = est.kvBytesPerToken;
+  const hw = await getHardwareTarget();
+  const ladder = [2048, 4096, 8192, 16384, 32768, 65536, 131072, 262144];
+
+  const rows = ladder.map((ctxTokens) => {
+    const total = weights + Math.round(kvPerToken * ctxTokens) + fixed;
+    const cls = hw.available ? classifyAllocation({ totalBytes: total, availableBytes: hw.totalBytes }) : null;
+    return { ctxTokens, total, cls };
+  });
+
+  const lines = [
+    `${C.gold}Model:${C.reset} ${C.bold}${C.white}${base.architecture.name || modelName || 'model'}${C.reset} ${C.dim}@ ${quant.toUpperCase()} (${(est.paramCount / 1e9).toFixed(1)}B • ${formatGb(weights)} weights + ${formatGb(fixed)} fixed)${C.reset}`,
+    '',
+    `${C.bold}${C.lavender}${'Context'.padStart(10)}   ${'KV Cache'.padStart(10)}   ${'Total'.padStart(10)}   ${'vs Card'.padStart(9)}  Zone${C.reset}`,
+  ];
+  for (const row of rows) {
+    const zone = row.cls ? zoneBadge(row.cls.zone) : `${C.dim}—${C.reset}`;
+    const pct = row.cls ? `${row.cls.usagePct}%` : '—';
+    lines.push(`${String(row.ctxTokens.toLocaleString('en-US')).padStart(10)}   ${formatGb(Math.round(kvPerToken * row.ctxTokens)).padStart(10)}   ${formatGb(row.total).padStart(10)}   ${String(pct).padStart(9)}  ${zone}`);
+  }
+  const maxGreen = [...rows].reverse().find(r => r.cls?.zone === 'GREEN');
+  if (maxGreen) {
+    lines.push('', `${C.dim}Largest GREEN context: ${C.reset}${C.emerald}${maxGreen.ctxTokens.toLocaleString('en-US')} tokens${C.reset}`);
+  } else {
+    lines.push('', `${C.amber}No ladder step fits this card — try a lighter quant: /vram compare${C.reset}`);
+  }
+  lines.push(`${C.dim}Estimates assume full-attention KV caching; sliding-window models (Gemma, Qwen SWA layers) cache less.${C.reset}`);
+  printSolidPanel({
+    title: 'VRAM Context Ladder',
+    lines,
+    headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m'
+  });
+  return 'HANDLED';
+}
+
+let lastLanScan = null;
+
 export const handlers = {
   ...featureCommandHandlers,
   '/exit': async (ctx) => {
@@ -100,6 +356,70 @@ export const handlers = {
     return 'EXIT';
   },
 
+  '/ingest': async (ctx) => {
+    const sub = (ctx.sub || '').toLowerCase().trim();
+    const rest = (ctx.extra || '').trim();
+    const { getDynamicCatalogStats, clearDynamicCatalog } = await import('./dynamicCatalog.js');
+    const { runIngestionScan, ingestRawEvent } = await import('./ingestionWorker.js');
+
+    if (!sub || sub === 'status') {
+      const stats = getDynamicCatalogStats();
+      console.log(`\n  ${C.bold}${C.lavender}Autonomous Dynamic Catalog Overlay Status:${C.reset}`);
+      console.log(`  ${C.dim}─────────────────────────────────────────────────${C.reset}`);
+      console.log(`  ${C.white}Total Ingested Entries:${C.reset} ${C.bold}${C.emerald}${stats.totalEntries}${C.reset}`);
+      console.log(`  ${C.dim}├─${C.reset} ${C.gold}Brands:${C.reset}     ${stats.brandsCount}`);
+      console.log(`  ${C.dim}├─${C.reset} ${C.cyberCyan}Timeline:${C.reset}   ${stats.timelineCount}`);
+      console.log(`  ${C.dim}├─${C.reset} ${C.sakura}Gallery:${C.reset}    ${stats.galleryCount}`);
+      console.log(`  ${C.dim}├─${C.reset} ${C.lavender}Works:${C.reset}      ${stats.worksCount}`);
+      console.log(`  ${C.dim}└─${C.reset} ${C.roseGlow}Events:${C.reset}     ${stats.eventsCount}`);
+      console.log(`  ${C.dim}Last Updated:${C.reset} ${stats.updatedAt}\n`);
+      return 'HANDLED';
+    }
+
+    if (sub === 'clear') {
+      clearDynamicCatalog();
+      console.log(`\n  ${C.emerald}✓ Dynamic catalog overlay cleared successfully.${C.reset}\n`);
+      return 'HANDLED';
+    }
+
+    if (sub === 'add') {
+      if (!rest) {
+        console.log(`\n  ${C.amber}Usage: /ingest add <event or live text>${C.reset}\n`);
+        return 'HANDLED';
+      }
+      console.log(`\n  ${C.cyberCyan}Ingesting event into dynamic catalog...${C.reset}`);
+      const client = ctx?.agent?.client || null;
+      const res = await ingestRawEvent(rest, { client, source: 'cli_manual', trustTier: 1 });
+      if (res.status === 'success') {
+        console.log(`  ${C.emerald}✓ Ingested successfully into category "${res.entry.category}":${C.reset}`);
+        console.log(`    ${C.white}Title/Brand:${C.reset} ${res.entry.title || res.entry.brand}`);
+        console.log(`    ${C.white}Year/Date:${C.reset}   ${res.entry.year} (${res.entry.date || 'N/A'})`);
+        console.log(`    ${C.white}Highlight:${C.reset}   ${res.entry.highlight || res.entry.summary}\n`);
+      } else if (res.status === 'duplicate') {
+        console.log(`  ${C.amber}[!] Skipped duplicate: ${res.message}${C.reset}\n`);
+      } else {
+        console.log(`  ${C.red}✗ Failed: ${res.reason || res.message}${C.reset}\n`);
+      }
+      return 'HANDLED';
+    }
+
+    if (sub === 'run') {
+      const topic = rest || 'Ju Jingyi 鞠婧祎';
+      console.log(`\n  ${C.cyberCyan}Scanning source-backed news & events for "${topic}"...${C.reset}`);
+      const client = ctx?.agent?.client || null;
+      const summary = await runIngestionScan({ topic, client });
+      console.log(`  ${C.emerald}✓ Scan complete:${C.reset}`);
+      console.log(`    Scanned: ${summary.totalScanned}`);
+      console.log(`    Ingested: ${C.bold}${C.emerald}${summary.ingestedCount}${C.reset}`);
+      console.log(`    Duplicates skipped: ${summary.skippedDuplicates}`);
+      console.log(`    Untrusted skipped: ${summary.skippedUntrusted}\n`);
+      return 'HANDLED';
+    }
+
+    console.log(`\n  ${C.amber}Unknown /ingest subcommand: "${sub}". Use status, run, add, or clear.${C.reset}\n`);
+    return 'HANDLED';
+  },
+
   '/help': async (ctx) => {
     const sub = (ctx.sub || ctx.extra || '').trim();
     if (typeof ctx.printHelp === 'function') {
@@ -145,7 +465,7 @@ export const handlers = {
 
   '/web': async (ctx) => {
     const rawAction = (ctx.sub || 'start').toLowerCase();
-    const extraPort = Number(ctx.extra || (ctx.sub && /^\d+$/.test(ctx.sub) ? ctx.sub : null)) || 3300;
+    const extraPort = Number(ctx.extra || (ctx.sub && /^\d+$/.test(ctx.sub) ? ctx.sub : null)) || 3002;
 
     if (rawAction === 'stop' || rawAction === 'close') {
       const stopped = await stopWebChatServer();
@@ -162,6 +482,7 @@ export const handlers = {
       const lines = [
         `• Status: ${status.running ? `${C.emerald}Running${C.reset}` : `${C.slate}Stopped${C.reset}`}`,
         `• URL: ${status.running ? `${C.cyberCyan}${status.url}${C.reset}` : `${C.dim}${status.url}${C.reset}`}`,
+        `• Tip: /portal chat also opens the chat URL on the dev server (port 3000)`,
         `• Port: ${status.port}`,
         `• Provider: ${status.provider || 'lmstudio'}`,
         `• Model: ${status.model || 'google/gemma-4-e4b'}`,
@@ -178,7 +499,7 @@ export const handlers = {
       await stopWebChatServer();
     }
 
-    const port = extraPort >= 1000 ? extraPort : 3300;
+    const port = extraPort >= 1000 ? extraPort : 3002;
     const res = await startWebChatServer({ port, agent: ctx.agent });
     openBrowser(res.url);
 
@@ -198,8 +519,6 @@ export const handlers = {
     return 'HANDLED';
   },
 
-  '/web-chat': async (ctx) => handlers['/web'](ctx),
-
   '/details': async (ctx) => {
     if (typeof ctx.printQueryDetails === 'function') {
       ctx.printQueryDetails([ctx.sub, ctx.extra].filter(Boolean).join(' '));
@@ -359,6 +678,14 @@ export const handlers = {
     const action = (ctx.sub || '').toLowerCase();
     const latest = ctx.agent.getResearchStatus().lastResult;
 
+    if (action === 'auto' || action === 'autoresearch') {
+      const autoParts = ['/autoresearch', ...(ctx.parts?.slice(2) || [])];
+      return handlers['/autoresearch']({ ...ctx, sub: autoParts[1] || 'status', parts: autoParts });
+    }
+    if (action === 'on' || action === 'off') {
+      return handlers['/autoresearch']({ ...ctx, sub: action, parts: ['/autoresearch', action, ...(ctx.parts?.slice(3) || [])] });
+    }
+
     if (action === 'status' || action === 'workers') {
       const status = ctx.agent.getResearchStatus();
       const lines = status.state === 'running'
@@ -376,23 +703,27 @@ export const handlers = {
     }
 
     if (action === 'cancel') {
-      console.log(ctx.agent.cancelResearch()
+      const cancelled = Boolean(ctx.agent?.cancelResearch?.() || ctx.cancelActiveQuery?.());
+      console.log(cancelled
         ? `\n  ${C.emerald}[OK] Research cancellation requested.${C.reset}\n`
         : `\n  ${C.amber}No research job is running.${C.reset}\n`);
       return 'HANDLED';
     }
 
     if (action === 'last') {
+      const cleanSources = (latest?.sources || [])
+        .map(s => cleanUrl(String(s)))
+        .filter(s => /^https?:\/\//i.test(s) && !s.includes('...') && !s.includes('…'));
       const lines = latest
         ? [
             `${C.bold}${C.cyberCyan}Research ID:${C.reset} ${latest.id}`,
-            `${C.bold}${C.slate}Sources Found:${C.reset} ${latest.sources?.length || 0}`,
+            `${C.bold}${C.slate}Sources Found:${C.reset} ${cleanSources.length}`,
             '',
             `${C.bold}${C.roseGlow}Synthesized Answer:${C.reset}`,
-            ...String(latest.answer).split('\n').map(l => `  ${l}`),
+            ...formatMarkdownLines(latest.answer || 'No findings recorded.').map(l => `  ${l}`),
             '',
             `${C.bold}${C.lavender}Sources Cited:${C.reset}`,
-            ...(latest.sources?.length ? latest.sources.map((s, i) => `  [${i + 1}] ${s}`) : [`  ${C.dim}None recorded.${C.reset}`])
+            ...(cleanSources.length ? cleanSources.map((s, i) => `  [${i + 1}] ${C.cyberCyan}${s}${C.reset}`) : [`  ${C.dim}None recorded.${C.reset}`])
           ]
         : [`${C.dim}No completed research yet. Run /research <question> to start.${C.reset}`];
 
@@ -404,9 +735,12 @@ export const handlers = {
     }
 
     if (action === 'sources') {
+      const cleanSources = (latest?.sources || [])
+        .map(s => cleanUrl(String(s)))
+        .filter(s => /^https?:\/\//i.test(s) && !s.includes('...') && !s.includes('…'));
       printSolidPanel({
-        title: 'Research Sources',
-        lines: latest?.sources?.length ? latest.sources.map((url, index) => `${C.gold}[${index + 1}]${C.reset} ${C.cyberCyan}${url}${C.reset}`) : [`${C.dim}No research sources recorded.${C.reset}`],
+        title: `Research Sources (${cleanSources.length})`,
+        lines: cleanSources.length ? cleanSources.map((url, index) => `${C.gold}[${index + 1}]${C.reset} ${C.cyberCyan}${url}${C.reset}`) : [`${C.dim}No research sources recorded.${C.reset}`],
       });
       return 'HANDLED';
     }
@@ -473,18 +807,21 @@ export const handlers = {
         durationMs: Date.now() - startTime,
       });
 
+      const cleanSources = (result.sources || [])
+        .map(s => cleanUrl(String(s)))
+        .filter(s => /^https?:\/\//i.test(s) && !s.includes('...') && !s.includes('…'));
       const lines = [
         `${C.bold}${C.emerald}[DONE] Research synthesis completed in ${elapsed}s across 3 workers.${C.reset}`,
         '',
         `${C.bold}${C.roseGlow}Comprehensive Findings:${C.reset}`,
         ...formatMarkdownLines(result.answer || 'No findings returned.').map(l => `  ${l}`),
         '',
-        `${C.bold}${C.lavender}Validated Sources (${result.sources.length}):${C.reset}`,
-        ...(result.sources.length > 0 ? result.sources.map((s, i) => `  [${i + 1}] ${C.cyberCyan}${s}${C.reset}`) : [`  ${C.dim}Catalog sources${C.reset}`]),
+        `${C.bold}${C.lavender}Validated Sources (${cleanSources.length}):${C.reset}`,
+        ...(cleanSources.length > 0 ? cleanSources.map((s, i) => `  [${i + 1}] ${C.cyberCyan}${s}${C.reset}`) : [`  ${C.dim}Catalog sources${C.reset}`]),
       ];
 
       printSolidPanel({
-        title: `Deep Research Report • ${result.sources.length} sources • ${elapsed}s`,
+        title: `Deep Research Report • ${cleanSources.length} sources • ${elapsed}s`,
         lines
       });
     } catch (error) {
@@ -737,6 +1074,42 @@ export const handlers = {
     const rawAction = (ctx.sub || 'list').toLowerCase();
     const extra = (ctx.extra || '').trim();
 
+    if (rawAction === 'news') {
+      const executor = ctx.executeTool || executeTool;
+      ctx.setIsProcessing?.(true, 'Scanning recent news for research ideas…');
+      try {
+        const result = await executor('search_news', { query: 'จวีจิ้งอี Ju Jingyi latest news when:7d', maxResults: 10 });
+        const items = (result?.results || []).slice(0, 10);
+        if (!items.length) {
+          printRichCard({
+            title: 'News-Driven Suggestions',
+            status: 'info',
+            lines: ['No recent news found in the last 7 days to seed suggestions.'],
+          });
+          return 'HANDLED';
+        }
+        const insight = await aiNarration(ctx, {
+          label: 'Generating news-driven suggestions…',
+          system: 'You are the Kiku research planner. From these news items propose exactly 3 specific research questions a Ju Jingyi fan would want answered. Output only the 3 numbered questions, nothing else.',
+          user: JSON.stringify({ items: items.map(i => ({ title: i.title, snippet: (i.snippet || '').slice(0, 200) })) }),
+          limit: 500,
+        });
+        printRichCard({
+          title: 'News-Driven Research Suggestions',
+          status: insight ? 'ok' : 'info',
+          lines: insight
+            ? insight.split('\n').filter(Boolean).map(l => `• ${l}`)
+            : items.slice(0, 3).map(i => `• ${i.title}`),
+        });
+        console.log(`  ${C.dim}Run /research "<question>" or /suggestion run all to investigate.${C.reset}\n`);
+      } catch (err) {
+        printRichCard({ title: 'News Suggestions Error', status: 'error', lines: [err.message || String(err)] });
+      } finally {
+        ctx.setIsProcessing?.(false);
+      }
+      return 'HANDLED';
+    }
+
     if (rawAction === 'run' || rawAction === 'exec' || rawAction === 'start') {
       const targets = extra || 'all';
 
@@ -994,31 +1367,7 @@ export const handlers = {
     }
 
     if (sub === 'summary' || sub === 'summarize') {
-      const messages = (agent?.session?.messages || []).map(m => {
-        const textPart = m.parts?.find(p => p.type === 'text');
-        return { role: m.role, text: textPart ? textPart.content : '' };
-      }).filter(m => m.text);
-      if (messages.length === 0) {
-        printSolidPanel({
-          title: 'History Summary',
-          lines: [`${C.dim}No conversation history to summarize.${C.reset}`],
-          headerBg: '\x1b[48;2;48;54;70m',
-          bg: '\x1b[48;2;36;40;52m',
-        });
-        return 'HANDLED';
-      }
-      const summary = await aiNarration(ctx, {
-        system: `You are the Kiku session archivist. In 2-3 concise sentences, summarize the key topics, queries, and findings discussed across this conversation history. ${languageHint(ctx)} Do not invent facts. No markdown.`,
-        user: JSON.stringify({ messageCount: messages.length, messages: messages.slice(-15) }),
-        limit: 450,
-      });
-      printSolidPanel({
-        title: `History Summary • ${messages.length} message${messages.length === 1 ? '' : 's'}`,
-        lines: summary ? [`  ${C.white}${summary}${C.reset}`] : [`${C.dim}Could not generate history summary (requires active chat model).${C.reset}`],
-        headerBg: '\x1b[48;2;48;54;70m',
-        bg: '\x1b[48;2;36;40;52m',
-      });
-      return 'HANDLED';
+      return handlers['/session']({ ...ctx, sub: 'summary' });
     }
 
     if (sub === 'search' && extra) {
@@ -1139,7 +1488,9 @@ export const handlers = {
         });
         return 'HANDLED';
       }
+      console.log(`\n  ${C.rose}🌸 Kiku Analyst${C.reset} ${C.dim}is generating session summary with AI model...${C.reset}\n`);
       const summary = await aiNarration(ctx, {
+        label: 'Summarizing session…',
         system: `You are the Kiku session analyst. In 2-3 concise sentences, summarize what this session achieved, what tools were used, and key takeaways for the user. ${languageHint(ctx)} Do not invent facts. No markdown.`,
         user: JSON.stringify({
           sessionId: sess.id,
@@ -1286,6 +1637,31 @@ export const handlers = {
     return 'HANDLED';
   },
 
+  '/autoresearch': async (ctx) => {
+    const { sub } = ctx;
+    const { config } = await import('./config.js');
+    const action = (sub || '').toLowerCase();
+    if (action === 'on' || action === 'off' || action === 'auto') {
+      config.agent.autoResearch = action;
+    }
+    const mode = String(config.agent.autoResearch || 'auto').toLowerCase();
+    const descriptions = {
+      on: 'Aggressive — every query with a research signal is routed into deep research',
+      off: 'Disabled — the model decides on its own (system prompt rule 8)',
+      auto: 'Smart — deep research is triggered automatically only when the question is long or multi-part (default)',
+    };
+    printSolidPanel({
+      title: 'Auto Deep Research',
+      lines: [
+        `${C.gold}Mode:${C.reset} ${C.bold}${C.white}${mode.toUpperCase()}${C.reset}`,
+        `${C.dim}${descriptions[mode] || descriptions.auto}${C.reset}`,
+        `${C.dim}Change: /autoresearch [on|off|auto]${C.reset} ${C.dim}(env: KIKU_AUTO_RESEARCH)${C.reset}`,
+      ],
+      headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m'
+    });
+    return 'HANDLED';
+  },
+
   '/lang': async (ctx) => {
     const { agent, sub } = ctx;
     const langArg = (sub || '').toLowerCase();
@@ -1402,6 +1778,7 @@ export const handlers = {
       parsedArgs = { [firstProp]: rawArgs };
     }
 
+    ctx.setIsProcessing?.(true, `Tool: ${actualToolName}`);
     const runner = createProgressRunner({
       badge: 'RUN',
       title: `Executing ${actualToolName}`,
@@ -1517,6 +1894,7 @@ export const handlers = {
         return 'HANDLED';
       }
       const summary = await aiNarration(ctx, {
+        label: 'Summarizing memory…',
         system: `You are the Kiku persona & memory archivist. Synthesize a concise profile (2-3 sentences) of what this user knows, likes, or tracks about Ju Jingyi based on their saved facts and topics. ${languageHint(ctx)} Do not invent facts. No markdown.`,
         user: JSON.stringify({
           storedFactsCount: facts.length,
@@ -1572,6 +1950,7 @@ export const handlers = {
     if (!songName) {
       console.log(`\n  ${C.amber}Usage: /play <song name>${C.reset}\n`);
     } else {
+      ctx.setIsProcessing?.(true, `Searching YouTube: ${songName.slice(0, 24)}…`);
       await audioPlayer.play(songName);
       console.log(`\n  ${C.emerald}[OK] Playing: ${C.white}${songName}${C.reset}\n`);
     }
@@ -1615,6 +1994,7 @@ export const handlers = {
     const q = ctx.extra || '';
     if (!q) { console.log(`\n  ${C.amber}Usage: /search <query>${C.reset}\n`); return 'HANDLED'; }
     try {
+      ctx.setIsProcessing?.(true, `Searching YouTube: ${q.slice(0, 24)}…`);
       const results = await audioPlayer.searchYouTube(q);
       if (results.length === 0) { console.log(`\n  ${C.amber}No results for "${q}"${C.reset}\n`); }
       else {
@@ -1663,7 +2043,9 @@ export const handlers = {
       ctx.tuiPrompt.render();
     } else {
       console.clear();
-      ctx.printWelcome();
+      if (typeof ctx.printWelcome === 'function') {
+        ctx.printWelcome();
+      }
       console.log(`  ${C.emerald}[OK] Fresh start.${C.reset}\n`);
     }
     return 'HANDLED';
@@ -1674,11 +2056,198 @@ export const handlers = {
     return handlers['/session']({ ...ctx, sub: 'export', extra: fmt });
   },
 
+  '/lan': async (ctx) => {
+    const { scanLan, mapServerTypeToProvider } = await import('./lanDiscovery.js');
+    const { savePersistedProviderBaseUrl } = await import('./config.js');
+    const action = (ctx.sub || 'scan').toLowerCase();
+    const parts = ctx.parts || [];
+
+    if (action === 'use') {
+      const arg = (parts[2] || ctx.extra || '').trim();
+      const endpoints = lastLanScan?.endpoints || [];
+      if (!arg) {
+        console.log(`\n  ${C.amber}Usage: /lan use <n>   (run /lan first to discover endpoints)${C.reset}\n`);
+        return 'HANDLED';
+      }
+      const endpoint = /^\d+$/.test(arg)
+        ? endpoints[Number(arg) - 1]
+        : endpoints.find(e => e.url === arg.replace(/\/+$/, '') || `${e.host}:${e.port}` === arg);
+      if (!endpoint) {
+        console.log(`\n  ${C.red}[ERROR] Endpoint "${arg}" not found in the last scan (${endpoints.length} found).${C.reset}`);
+        console.log(`  ${C.dim}Run /lan to refresh the list.${C.reset}\n`);
+        return 'HANDLED';
+      }
+
+      const provider = mapServerTypeToProvider(endpoint.serverType);
+      const model = endpoint.models[0] || null;
+      const cleanUrl = savePersistedProviderBaseUrl(provider, endpoint.url);
+      const options = { baseUrl: cleanUrl, ...(model ? { model } : {}) };
+      try {
+        const info = ctx.client.switchProvider(provider, options);
+        if (ctx.agent?.client) ctx.agent.client.switchProvider(provider, options);
+        if (ctx.modelManager) {
+          ctx.modelManager.client = ctx.client;
+          ctx.modelManager.requestedModel = info.model;
+          const resolution = await ctx.modelManager.resolve({ requestedModel: info.model });
+          if (resolution.connected && resolution.selectedModel) {
+            ctx.setCatalogOnlyMode?.(false);
+            if (ctx.tuiPrompt) {
+              ctx.tuiPrompt.isConnected = true;
+              ctx.tuiPrompt.modelName = resolution.selectedModel;
+              ctx.tuiPrompt.provider = info.providerName;
+              ctx.tuiPrompt.render();
+            }
+          } else if (!resolution.connected) {
+            ctx.setCatalogOnlyMode?.(true);
+            console.log(`  ${C.amber}• Endpoint did not answer model resolution: ${resolution.error}${C.reset}`);
+          }
+        }
+        ctx.baseUrl = info.baseUrl;
+        console.log(`\n  ${C.emerald}[OK] Connected to LAN endpoint ${C.bold}${endpoint.host}:${endpoint.port}${C.reset}`);
+        console.log(`  ${C.slate}• Server:${C.reset}    ${C.white}${endpoint.serverName}${C.reset}`);
+        console.log(`  ${C.slate}• Provider:${C.reset}  ${C.cyberCyan}${info.provider}${C.reset} → ${C.cyberCyan}${info.baseUrl}${C.reset}`);
+        console.log(`  ${C.slate}• Model:${C.reset}     ${C.white}${info.model}${C.reset}`);
+        if (endpoint.models.length > 1) {
+          console.log(`  ${C.dim}• ${endpoint.models.length} models available — switch with /model use <id>${C.reset}`);
+        }
+        console.log('');
+      } catch (err) {
+        console.log(`\n  ${C.red}[LAN ERROR] ${err.message}${C.reset}\n`);
+      }
+      return 'HANDLED';
+    }
+
+    console.log(`\n  ${C.cyberCyan}Scanning local network for LM servers (LM Studio :1234, vLLM :8000, Ollama :11434, :8080)...${C.reset}`);
+    const restTokens = parts.slice(2).map(t => String(t || '').trim()).filter(Boolean);
+    if (action !== 'scan' && action !== 'json' && action !== 'use') {
+      restTokens.unshift(action);
+    }
+    let scanTargets = null;
+    let scanPorts = null;
+    const portsFlagIdx = restTokens.indexOf('--ports');
+    if (portsFlagIdx >= 0) {
+      const rawPorts = String(restTokens[portsFlagIdx + 1] || '').split(',').map(Number).filter(p => Number.isInteger(p) && p >= 1 && p <= 65535);
+      if (rawPorts.length === 0) {
+        console.log(`\n  ${C.amber}Usage: /lan scan <targets> --ports <p1,p2,...>${C.reset}`);
+        console.log(`  ${C.dim}Example: /lan scan 192.168.1.0/24 --ports 1234,8000${C.reset}\n`);
+        return 'HANDLED';
+      }
+      scanPorts = rawPorts;
+      restTokens.splice(portsFlagIdx, 2);
+    }
+    if (restTokens.length > 0) {
+      scanTargets = restTokens.join(',').split(',').map(s => s.trim()).filter(Boolean);
+    }
+
+    let result;
+    try {
+      result = await scanLan({
+        ...(scanTargets ? { subnets: scanTargets } : {}),
+        ...(scanPorts ? { ports: scanPorts } : {}),
+        signal: ctx.signal,
+      });
+    } catch (err) {
+      if (err?.name === 'AbortError' || ctx.signal?.aborted) {
+        printRichCard({
+          title: 'LAN Scan Cancelled',
+          status: 'info',
+          lines: ['• Scan aborted by user before completion.'],
+        });
+      } else {
+        console.log(`  ${C.red}[LAN ERROR] ${err.message}${C.reset}\n`);
+      }
+      return 'HANDLED';
+    }
+    lastLanScan = result;
+
+    if (action === 'json') {
+      console.log(JSON.stringify(result, null, 2));
+      return 'HANDLED';
+    }
+
+    const endpoints = result.endpoints || [];
+    const lines = [
+      `${C.dim}Subnets: ${result.subnets.join(', ')}  •  ${result.targetsScanned} probes in ${(result.durationMs / 1000).toFixed(1)}s${C.reset}`,
+      '',
+    ];
+    if (endpoints.length === 0) {
+      lines.push(`  ${C.amber}No LM servers found on the local network.${C.reset}`);
+      lines.push('');
+      lines.push(`${C.dim}Checklist: is the LM Studio server started ("lms server start" / Developer > Server)?${C.reset}`);
+      lines.push(`${C.dim}vLLM running in WSL must bind 0.0.0.0 to be reachable ("vllm serve <model> --host 0.0.0.0").${C.reset}`);
+      lines.push(`${C.dim}Non-standard ports can be reached via /provider url <provider> <url>.${C.reset}`);
+    } else {
+      endpoints.forEach((e, i) => {
+        const authBadge = e.authRequired ? ` ${C.amber}[API key required]${C.reset}` : '';
+        lines.push(`  ${C.bold}${C.emerald}[${i + 1}]${C.reset} ${C.bold}${C.white}${e.serverName}${C.reset} ${C.dim}—${C.reset} ${C.cyberCyan}http://${e.host}:${e.port}${C.reset} ${C.dim}(${e.latencyMs}ms)${C.reset}${authBadge}`);
+        if (e.models.length > 0) {
+          for (const m of e.models.slice(0, 5)) {
+            lines.push(`        ${C.slate}• ${m}${C.reset}`);
+          }
+          if (e.models.length > 5) {
+            lines.push(`        ${C.dim}... and ${e.models.length - 5} more${C.reset}`);
+          }
+        } else {
+          lines.push(`        ${C.dim}no models reported${C.reset}`);
+        }
+      });
+      lines.push('');
+      lines.push(`${C.dim}Connect: /lan use <n>  (persists the Base URL for this provider)${C.reset}`);
+    }
+    printSolidPanel({ title: `LAN LM Server Discovery (${endpoints.length} found)`, lines });
+    return 'HANDLED';
+  },
+
   '/provider': async (ctx) => {
-    const { CLOUD_PROVIDERS, getProvider, getRecommendedModels, isProviderKeyPersistenceEnabled } = await import('./config.js');
+    const { CLOUD_PROVIDERS, getProvider, getRecommendedModels, isProviderKeyPersistenceEnabled, getUnifiedProviderCatalog, savePersistedProviderBaseUrl } = await import('./config.js');
     const action = (ctx.sub || 'status').toLowerCase();
     const parts = ctx.parts || [];
 
+    if (action === 'url' || action === 'endpoint' || action === 'baseurl') {
+      const arg1 = parts[2] || '';
+      const arg2 = parts[3] || '';
+      let targetProvider = ctx.client.provider;
+      let newUrl = arg1;
+
+      if (arg2 && getProvider(arg1)) {
+        targetProvider = arg1.toLowerCase();
+        newUrl = arg2;
+      }
+
+      if (!newUrl) {
+        const catalog = getUnifiedProviderCatalog();
+        const lines = [];
+        lines.push(`${C.gold}Active Engine:${C.reset}  ${C.bold}${C.white}${catalog.activeProvider}${C.reset} (${catalog.activeBaseUrl})`);
+        lines.push('');
+        lines.push(`${C.cyberCyan}Local Endpoints:${C.reset}`);
+        lines.push(`  • ${C.white}LM Studio (port 1234):${C.reset} ${C.slate}${catalog.localEndpoints.lmstudio.baseUrl}${C.reset} ${catalog.localEndpoints.lmstudio.isActive ? `${C.emerald}[ACTIVE]` : ''}`);
+        lines.push(`  • ${C.white}vLLM (port 8000 / WSL):${C.reset} ${C.slate}${catalog.localEndpoints.vllm.baseUrl}${C.reset} ${catalog.localEndpoints.vllm.isActive ? `${C.emerald}[ACTIVE]` : ''}`);
+        lines.push('');
+        lines.push(`${C.dim}Set custom URL: /provider url <provider> <url> (e.g. /provider url vllm http://127.0.0.1:8000/v1)${C.reset}`);
+        printSolidPanel({ title: 'API Base URL Manager', lines });
+        return 'HANDLED';
+      }
+
+      const pDef = getProvider(targetProvider);
+      if (!pDef) {
+        console.log(`\n  ${C.red}[ERROR] Unknown provider "${targetProvider}".${C.reset}\n`);
+        return 'HANDLED';
+      }
+
+      const cleanUrl = savePersistedProviderBaseUrl(targetProvider, newUrl);
+      if (ctx.client?.setBaseUrl) {
+        ctx.client.setBaseUrl(cleanUrl, targetProvider);
+      }
+      if (ctx.agent?.client?.setBaseUrl) {
+        ctx.agent.client.setBaseUrl(cleanUrl, targetProvider);
+      }
+      ctx.baseUrl = cleanUrl;
+
+      console.log(`\n  ${C.emerald}[OK] Base URL updated and saved for ${targetProvider}${C.reset}`);
+      console.log(`  ${C.slate}• New Base URL:${C.reset} ${C.cyberCyan}${cleanUrl}${C.reset}\n`);
+      return 'HANDLED';
+    }
+
     if (action === 'list') {
       const active = ctx.client.provider || 'lmstudio';
       const lines = Object.values(CLOUD_PROVIDERS).map(p => {
@@ -1694,7 +2263,7 @@ export const handlers = {
         lines: [
           ...lines,
           '',
-          `${C.dim}Switch: /provider use <name> [model] | Models: /provider models <name> | Docs: /provider info <name>${C.reset}`
+          `${C.dim}Switch: /provider use <name> [model] | Base URL: /provider url | Models: /provider models <name>${C.reset}`
         ],
       });
       return 'HANDLED';
@@ -1748,6 +2317,9 @@ export const handlers = {
         if (!info.hasApiKey && !info.isLocal) {
           console.log(`  ${C.dim}Tip: Set ${info.envKey} in .env or run /provider setkey <key>${C.reset}`);
         }
+        if (info.platformNotice && process.platform === 'win32') {
+          console.log(`  ${C.amber}[NOTICE] ${info.platformNotice}${C.reset}`);
+        }
         console.log('');
       } catch (err) {
         console.log(`\n  ${C.red}[PROVIDER ERROR] ${err.message}${C.reset}\n`);
@@ -1756,6 +2328,7 @@ export const handlers = {
     }
 
     if (action === 'models' || action === 'model' || action === 'catalog') {
+      ctx.setIsProcessing?.(true, 'Fetching model catalog…');
       const targetProvider = (ctx.extra || ctx.client.provider || 'lmstudio').toLowerCase().trim();
       const providerDef = getProvider(targetProvider);
       if (!providerDef) {
@@ -1815,6 +2388,7 @@ export const handlers = {
           `${C.gold}Features:${C.reset}    ${C.slate}${(p.features || []).join(', ')}${C.reset}`,
           `${C.gold}Docs:${C.reset}        ${C.cyberCyan}${p.docUrl || 'N/A'}${C.reset}`,
           `${C.gold}API Ref:${C.reset}     ${C.cyberCyan}${p.apiRefUrl || 'N/A'}${C.reset}`,
+          ...(p.platformNotice ? [`${C.gold}Platform:${C.reset}    ${C.amber}${p.platformNotice}${C.reset}`] : []),
           '',
           `${C.dim}Switch: /provider use ${p.id} | Models: /provider models ${p.id}${C.reset}`
         ],
@@ -1825,6 +2399,7 @@ export const handlers = {
     if (action === 'test' || action === 'ping' || action === 'check') {
       const targetProvider = (ctx.extra || ctx.client.provider || 'lmstudio').toLowerCase().trim();
       console.log(`\n  ${C.cyberCyan}[TESTING] Testing connection to ${targetProvider}...${C.reset}`);
+      ctx.setIsProcessing?.(true, `Testing ${targetProvider}…`);
       let testClient = ctx.client;
       if (targetProvider !== ctx.client.provider) {
         const { LLMClient } = await import('./llmClient.js');
@@ -1832,6 +2407,16 @@ export const handlers = {
       }
       const check = await testClient.checkConnection();
       if (check.connected) {
+        if (targetProvider === ctx.client.provider) {
+          ctx.setCatalogOnlyMode?.(false);
+          if (ctx.tuiPrompt) {
+            ctx.tuiPrompt.isConnected = true;
+            if (check.activeLoadedModel || check.model) {
+              ctx.tuiPrompt.modelName = check.activeLoadedModel || check.model;
+            }
+            ctx.tuiPrompt.render();
+          }
+        }
         console.log(`  ${C.emerald}[OK] Connected to ${check.providerName}!${C.reset}`);
         console.log(`  ${C.slate}• Latency:${C.reset}     ${C.emerald}${check.latencyMs || 0}ms${C.reset}`);
         console.log(`  ${C.slate}• Active Model:${C.reset} ${C.white}${check.activeModel || check.model || 'N/A'}${C.reset}`);
@@ -1871,10 +2456,10 @@ export const handlers = {
       const masked = newKey.length > 8
         ? `${newKey.slice(0, 4)}...${newKey.slice(-4)}`
         : '****';
-      const persistenceLabel = isProviderKeyPersistenceEnabled()
-        ? 'saved with encrypted persistence'
-        : 'saved in memory only (set KIKU_PROVIDER_KEY_ENCRYPTION_KEY to persist)';
-      console.log(`\n  ${C.emerald}[OK] API key ${persistenceLabel} for ${targetProvider}${C.reset} (${masked})\n`);
+      const persistenceLabel = isProviderKeyPersistenceEnabled()
+        ? 'saved with encrypted persistence'
+        : 'saved in memory only (set KIKU_PROVIDER_KEY_ENCRYPTION_KEY to persist)';
+      console.log(`\n  ${C.emerald}[OK] API key ${persistenceLabel} for ${targetProvider}${C.reset} (${masked})\n`);
       return 'HANDLED';
     }
 
@@ -1896,24 +2481,43 @@ export const handlers = {
         `${C.gold}Pricing:${C.reset}   ${C.slate}${pInfo.pricingSummary || 'N/A'}${C.reset}`,
         `${C.gold}Docs:${C.reset}      ${C.cyberCyan}${pInfo.docUrl || 'N/A'}${C.reset}`,
         '',
-        `${C.dim}Commands: /provider list | /provider use <name> [model] | /provider models | /provider test${C.reset}`,
+        `${C.dim}Commands: /provider list | /provider use <name> [model] | /provider url | /provider test${C.reset}`,
       ],
       headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m'
     });
     return 'HANDLED';
   },
 
+  '/url': async (ctx) => handlers['/provider']({ ...ctx, sub: 'url', parts: ['/provider', 'url', ...(ctx.parts?.slice(1) || [])] }),
+  '/endpoint': async (ctx) => handlers['/provider']({ ...ctx, sub: 'url', parts: ['/provider', 'url', ...(ctx.parts?.slice(1) || [])] }),
+
   '/model': async (ctx) => {
     const rawSub = (ctx.sub || '').trim();
     const action = (rawSub || 'status').toLowerCase();
     const providerName = ctx.client.providerName || 'Model';
     const { getRecommendedModels, CLOUD_PROVIDERS } = await import('./config.js');
 
+    if (action === 'ping') {
+      try {
+        const start = Date.now();
+        ctx.setIsProcessing?.(true, 'Pinging model server…');
+        const check = await ctx.client.checkConnection();
+        const ms = Date.now() - start;
+        console.log(check.connected
+          ? `\n  ${C.emerald}● Connected${C.reset} ${C.dim}(${ms}ms)${C.reset} — ${C.white}${check.activeModel || check.model || 'Ready'}${C.reset}\n`
+          : `\n  ${C.red}● Disconnected${C.reset} ${C.dim}(${ms}ms)${C.reset} — ${C.amber}${check.error || 'Server unreachable'}${C.reset}\n`);
+      } catch (err) {
+        console.log(`\n  ${C.red}[PING ERROR] ${err.message || String(err)}${C.reset}\n`);
+      }
+      return 'HANDLED';
+    }
+
     if (action === 'reconnect') {
       if (!ctx.modelManager) {
         console.log(`\n  ${C.red}[MODEL ERROR] Runtime model manager is unavailable.${C.reset}\n`);
         return 'HANDLED';
       }
+      ctx.setIsProcessing?.(true, 'Reconnecting model server…');
       const resolution = await ctx.modelManager.resolve();
       if (resolution.connected && resolution.selectedModel) {
         ctx.setCatalogOnlyMode?.(false);
@@ -1948,10 +2552,27 @@ export const handlers = {
       return 'HANDLED';
     }
 
+    ctx.setIsProcessing?.(true, 'Probing model server…');
     const liveCheck = ctx.modelManager
       ? await ctx.modelManager.inspect()
       : await ctx.client.checkConnection();
 
+    if (liveCheck.connected && (liveCheck.activeLoadedModel || (liveCheck.models && liveCheck.models.length > 0))) {
+      let resolvedModel = liveCheck.activeLoadedModel;
+      if (ctx.modelManager) {
+        const resolution = await ctx.modelManager.resolve();
+        if (resolution.connected && resolution.selectedModel) {
+          resolvedModel = resolution.selectedModel;
+        }
+      }
+      ctx.setCatalogOnlyMode?.(false);
+      if (ctx.tuiPrompt) {
+        ctx.tuiPrompt.isConnected = true;
+        if (resolvedModel) ctx.tuiPrompt.modelName = resolvedModel;
+        ctx.tuiPrompt.render();
+      }
+    }
+
     if (action === 'list') {
       const activeLoaded = liveCheck.activeLoadedModel;
       const serverModels = (liveCheck.models || []).slice(0, 40).map(id => {
@@ -2100,6 +2721,7 @@ export const handlers = {
     }
 
     if (action === 'connect' || action === 'add') {
+      ctx.setIsProcessing?.(true, 'Connecting MCP server…');
       const parts = (ctx.parts || []).slice(2);
       const name = parts[0];
       const targetUrlOrType = parts[1];
@@ -2183,6 +2805,7 @@ export const handlers = {
     }
 
     if (action === 'reload' || action === 'reconnect') {
+      ctx.setIsProcessing?.(true, 'Reloading MCP servers…');
       const target = (ctx.extra || '').trim();
       printRichCard({
         title: 'Reloading MCP Configuration',
@@ -2310,21 +2933,7 @@ export const handlers = {
     return 'HANDLED';
   },
 
-  '/ping': async (ctx) => {
-    try {
-      const start = Date.now();
-      const check = await ctx.client.checkConnection();
-      const ms = Date.now() - start;
-      if (check.connected) {
-        console.log(`\n  ${C.emerald}● Connected${C.reset} ${C.dim}(${ms}ms)${C.reset} — ${C.white}${check.activeModel || check.model || 'Ready'}${C.reset}\n`);
-      } else {
-        console.log(`\n  ${C.red}● Disconnected${C.reset} ${C.dim}(${ms}ms)${C.reset} — ${C.amber}${check.error || 'Server unreachable'}${C.reset}\n`);
-      }
-    } catch (err) {
-      console.log(`\n  ${C.red}[PING ERROR] ${err.message || String(err)}${C.reset}\n`);
-    }
-    return 'HANDLED';
-  },
+  '/ping': async (ctx) => handlers['/model']({ ...ctx, sub: 'ping', parts: ['/model', 'ping'] }),
 
   '/profile': async (ctx) => {
     const { listProfiles, getProfile, setActiveProfile, createOrUpdateProfile, deleteProfile, getActiveProfile } = await import('./profiles.js');
@@ -2451,6 +3060,7 @@ export const handlers = {
   '/doctor': async (ctx) => {
     try {
       const { runDoctor } = await import('./doctor.js');
+      ctx.setIsProcessing?.(true, 'Running diagnostics…');
       const report = await runDoctor({ client: ctx.client });
       printSolidPanel({
         title: `Kiku Doctor • ${report.ok ? 'READY' : 'ACTION REQUIRED'}`,
@@ -2465,22 +3075,12 @@ export const handlers = {
     return 'HANDLED';
   },
 
-  '/version': async () => {
-    printSolidPanel({
-      title: 'Version',
-      lines: [
-        `${C.gold}Package:${C.reset} ${C.white}${PACKAGE_NAME}${C.reset}`,
-        `${C.gold}Version:${C.reset} ${C.white}${PACKAGE_VERSION}${C.reset}`,
-        `${C.gold}Node:${C.reset}    ${C.white}${process.version}${C.reset}`,
-        `${C.gold}Platform:${C.reset} ${C.white}${process.platform} ${process.arch}${C.reset}`,
-      ],
-    });
-    return 'HANDLED';
-  },
+  '/version': async () => handlers['/about'](),
 
-  '/system': async () => {
+  '/system': async (ctx) => {
     const os = await import('node:os');
     const mem = process.memoryUsage();
+    ctx.setIsProcessing?.(true, 'Probing hardware…');
     const gpuData = await getGpuMetrics().catch(() => ({ available: false }));
 
     const lines = [
@@ -2507,7 +3107,8 @@ export const handlers = {
     return 'HANDLED';
   },
 
-  '/gpu': async () => {
+  '/gpu': async (ctx) => {
+    ctx.setIsProcessing?.(true, 'Probing hardware…');
     const gpuData = await getGpuMetrics().catch(() => ({ available: false }));
 
     if (!gpuData.available || !gpuData.primary) {
@@ -2558,17 +3159,189 @@ export const handlers = {
     return 'HANDLED';
   },
 
-  '/about': async () => {
-    printSolidPanel({
-      title: 'About Kiku AI Agent',
-      lines: [
-        `${C.white}Intelligent assistant for Ju Jingyi (鞠婧祎)${C.reset}`,
-        `${C.gold}Engine:${C.reset} ${C.white}LM Studio + Gemma 4${C.reset}`,
-        `${C.gold}Tools:${C.reset} ${C.white}${toolsSchema.length} registered${C.reset}`,
-        `${C.gold}Languages:${C.reset} ${C.white}TH, ZH, EN (auto)${C.reset}`,
-      ],
-    });
-    return 'HANDLED';
+  '/vram': async (ctx) => {
+    const { sub, extra } = ctx;
+    try {
+      if (sub === 'list') {
+        const capabilityTags = (entry) => (entry.capabilities || [])
+          .map(cap => `[${cap.toUpperCase()}]`).join(' ') || '[BASE]';
+        const lines = MODEL_REGISTRY.map(entry => {
+          const flags = [
+            `P=${entry.paramsB}B`,
+            `L=${entry.layers}`,
+            `GQA ${entry.queryHeads}Q/${entry.kvHeads}KV`,
+            `d=${entry.headDim}`,
+            entry.contextLength ? `ctx≤${entry.contextLength.toLocaleString('en-US')}` : null,
+            entry.isMoE ? 'MoE (total params)' : null,
+          ].filter(Boolean).join(' • ');
+          return `${C.gold}${capabilityTags(entry)} ${entry.label}${C.reset}\n    ${C.dim}${flags}${C.reset}`;
+        });
+        printSolidPanel({
+          title: 'Built-in Model Registry (approximate architectures)',
+          lines: [...lines, '', `${C.dim}Exact GGUF/HuggingFace metadata always takes precedence over these entries.${C.reset}`],
+        });
+        return 'HANDLED';
+      }
+
+      if (sub === 'live') {
+        return await printVramLivePanel(ctx, parseVramArgs(String(extra || '').trim().split(/\s+/).filter(Boolean)));
+      }
+      if (sub === 'compare') {
+        return await printVramQuantCompare(ctx, parseVramArgs(String(extra || '').trim().split(/\s+/).filter(Boolean)));
+      }
+      if (sub === 'ctx' || sub === 'contexts') {
+        return await printVramContextLadder(ctx, parseVramArgs(String(extra || '').trim().split(/\s+/).filter(Boolean)));
+      }
+      if (sub === 'tier' || sub === 'hardware' || sub === 'bus') {
+        const resolved = await resolveSystemHardwareTier();
+        const hw = resolved.hardware;
+        const profile = resolved.profile;
+        const spec = profile?.spec || profile;
+        const tier = resolved.tier;
+        const budget = resolved.budget;
+        const lines = [
+          `${C.gold}GPU Device:${C.reset}        ${C.bold}${C.white}${spec?.name || hw.name || 'Unknown GPU'}${C.reset}`,
+          `${C.gold}Architecture:${C.reset}      ${C.white}${spec?.arch || tier.architecture.family || 'Unknown'}${C.reset} ${C.dim}(${spec?.pcie || 'PCIe'})${C.reset}`,
+          `${C.gold}Memory Bus:${C.reset}        ${C.white}${spec?.busBits ? `${spec.busBits}-bit ${spec.memoryType || 'GDDR'}` : 'Unknown'}${C.reset} • ${C.cyberCyan}${spec?.bandwidthGbs ? `${spec.bandwidthGbs.toFixed(1)} GB/s` : 'N/A'}${C.reset}`,
+          `${C.gold}VRAM Capacity:${C.reset}     ${C.white}${hw.totalBytes ? formatGb(hw.totalBytes) : `${spec?.vramGb || 0} GB`}${C.reset}` + (hw.freeBytes ? ` ${C.dim}(${formatGb(hw.freeBytes)} free right now)${C.reset}` : ''),
+          '',
+          `${C.bold}${C.lavender}Hardware Classification & AI Budget:${C.reset}`,
+          `  • AI Tier:         ${C.bold}${C.emerald}${tier.name}${C.reset}`,
+          `  • Max Context:     ${C.white}${tier.contextLimit.toLocaleString('en-US')} tokens${C.reset}`,
+          `  • Rec. KV Quant:   ${C.bold}${C.gold}${tier.effectiveKvQuant}${C.reset}`,
+          `  • Dyn. KV Budget:  ${C.white}${budget?.kvBudgetMb ? `${budget.kvBudgetMb} MB` : 'N/A'}${C.reset}`,
+          `  • Constrained Card:${tier.isConstrained ? ` ${C.amber}Yes (KV quantization & compact context applied)${C.reset}` : ` ${C.emerald}No (high headroom)${C.reset}`}`,
+          '',
+          `${C.dim}Telemetry: Disambiguated against TechPowerUp offline catalog & local NVML hardware probe.${C.reset}`,
+        ];
+        printSolidPanel({
+          title: `GPU Hardware Classification • ${tier.name}`,
+          lines,
+          headerBg: '\x1b[48;2;48;54;70m',
+          bg: '\x1b[48;2;36;40;52m'
+        });
+        return 'HANDLED';
+      }
+
+      const argTokens = String(sub === 'check' ? (extra || '') : [sub, extra].filter(Boolean).join(' '))
+        .trim().split(/\s+/).filter(Boolean);
+      const { overrides, positional, force } = parseVramArgs(argTokens);
+      const target = positional.join(' ');
+      let modelName = null;
+      let modelPath = null;
+      if (target) {
+        if (/\.gguf$/i.test(target)) modelPath = target;
+        else modelName = target;
+      } else {
+        modelName = ctx.agent?.client?.model || null;
+      }
+
+      const result = await computeVramEstimate({ model: modelName, modelPath, ...overrides });
+      const est = result.estimate;
+      const cls = result.classification || { zone: 'UNKNOWN', usagePct: null, headroomBytes: null, message: '' };
+      const hw = result.hardware;
+      const zoneColor = cls.zone === 'GREEN' ? C.emerald : cls.zone === 'YELLOW' ? C.gold : cls.zone === 'RED' ? C.roseGlow : C.slate;
+      const barWidth = 18;
+      const usagePct = cls.usagePct !== null && cls.usagePct !== undefined ? cls.usagePct : 0;
+      const bigFilled = Math.round((Math.min(100, usagePct) / 100) * 46);
+      const bigBar = `${zoneColor}${'█'.repeat(bigFilled)}${C.dim}${'░'.repeat(46 - bigFilled)}${C.reset}`;
+
+      const row = (label, bytes) => {
+        const share = est.totalBytes > 0 && bytes !== null && bytes !== undefined ? bytes / est.totalBytes : 0;
+        const filled = Math.round(share * barWidth);
+        const miniBar = `${zoneColor}${'█'.repeat(filled)}${C.dim}${'░'.repeat(barWidth - filled)}${C.reset}`;
+        return `${C.white}${String(label).padEnd(34)}${C.reset}${C.cyberCyan}${formatGb(bytes).padStart(10)}${C.reset}   ${miniBar}`;
+      };
+
+      const quantLabel = String(est.quant || 'q4_k_m').toUpperCase();
+      const ctxLabel = est.contextLength ? `${est.contextLength.toLocaleString('en-US')} tokens` : 'unknown';
+      const kvLabelParts = [
+        est.layers ? `${est.layers}L` : null,
+        est.kvHeads && est.queryHeads ? `GQA ${est.queryHeads}/${est.kvHeads}` : null,
+        est.headDim ? `d=${est.headDim}` : null,
+      ].filter(Boolean).join(', ');
+
+      const isMeasured = cls.basis === 'measured';
+      const predCls = result.predictiveClassification || cls;
+      const predPct = predCls.usagePct !== null && predCls.usagePct !== undefined ? predCls.usagePct : 0;
+
+      const vramStatusRows = isMeasured
+        ? [
+            `${C.gold}Estimated Peak VRAM:${C.reset} ${C.bold}${C.white}${formatGb(est.totalBytes)}${C.reset}` +
+              (hw ? `${C.dim} vs ${(hw.totalBytes / 1024 ** 3).toFixed(2)} GB card (predicted: ${predPct}%)${C.reset}` : ''),
+            `${C.gold}Live GPU Usage:${C.reset}      ${C.bold}${C.white}${formatGb(cls.usedBytes)}${C.reset}` +
+              (hw ? `${C.dim} / ${(hw.totalBytes / 1024 ** 3).toFixed(2)} GB${C.reset} ${C.bold}${zoneColor}(${usagePct}% · measured)${C.reset}` : ''),
+            '',
+            `${C.bold}[STATUS: ${cls.zone === 'GREEN' ? 'FEASIBLE' : cls.zone === 'YELLOW' ? 'MARGINAL / WARNING' : cls.zone === 'RED' ? 'CRITICAL / OOM' : 'UNVERIFIED'} · LIVE MEASURED]${C.reset}`,
+            `[${bigBar}] ${zoneColor}${usagePct}% (${cls.zone} ZONE · measured)${C.reset}`,
+          ]
+        : [
+            `${C.gold}Total Estimated VRAM:${C.reset} ${C.bold}${C.white}${formatGb(est.totalBytes)}${C.reset}` +
+              (hw ? `${C.dim} / ${(hw.totalBytes / 1024 ** 3).toFixed(2)} GB${C.reset} ${C.dim}(${usagePct}%)${C.reset}` : ''),
+            '',
+            `${C.bold}[STATUS: ${cls.zone === 'GREEN' ? 'FEASIBLE' : cls.zone === 'YELLOW' ? 'MARGINAL / WARNING' : cls.zone === 'RED' ? 'CRITICAL / OOM' : 'UNVERIFIED'}]${C.reset}`,
+            `[${bigBar}] ${zoneColor}${usagePct}% (${cls.zone} ZONE)${C.reset}`,
+          ];
+
+      const lines = [
+        `${C.gold}Target Model:${C.reset}     ${C.bold}${C.white}${result.architecture.name || modelName || modelPath || 'unknown'}${C.reset}${result.approximate ? C.dim + ' (approximate)' : ''}${C.reset}`,
+        `${C.gold}Config Source:${C.reset}    ${C.white}${result.configSource}${C.reset}${result.configError ? C.dim + ` (${result.configError})` : ''}${C.reset}`,
+        `${C.gold}Context Length:${C.reset}  ${C.white}${ctxLabel}${C.reset}${C.dim} | Batch Size: ${est.batchSize} | Cache: ${est.cacheBits}-bit${C.reset}`,
+        `${C.gold}Detected Device:${C.reset} ${hw ? C.white + `${hw.name} (${(hw.totalBytes / 1024 ** 3).toFixed(2)} GB VRAM)` + C.reset : C.dim + 'No queryable VRAM device'}${C.reset}`,
+        '',
+        `${C.bold}${C.lavender}Component${C.reset}${' '.repeat(25)}${C.bold}${C.lavender}Calculated Memory${C.reset}`,
+        ...[
+          row(`Weights (P=${est.paramCount ? (est.paramCount / 1e9).toFixed(1) : '?' }B, ${quantLabel})`, est.weightsBytes),
+          row(`KV Cache (${kvLabelParts || 'geometry unknown'}, ${est.effectiveContextLength ? est.effectiveContextLength.toLocaleString('en-US') : '0'} tok)`, est.kvCacheBytes),
+          row('Activation Workspace', est.activationBytes),
+          row('CUDA / Runtime Overhead', est.overheadBytes),
+        ],
+        '',
+        ...vramStatusRows,
+      ];
+
+      if (cls.headroomBytes !== null && cls.headroomBytes !== undefined) {
+        lines.push('', `${C.gold}Headroom:${C.reset} ${cls.headroomBytes >= 0 ? C.emerald + formatGb(cls.headroomBytes) : C.roseGlow + `over budget by ${formatGb(-cls.headroomBytes)}`}${C.reset}`);
+      }
+      for (const note of result.notes || []) {
+        lines.push(`${C.dim}[INFO] ${note}${C.reset}`);
+      }
+      for (const warning of result.estimate.warnings) {
+        lines.push(`${C.dim}[WARN] ${warning}${C.reset}`);
+      }
+      for (const suggestion of result.remediation || []) {
+        lines.push(`${C.amber}Recommendation: ${suggestion.description}${C.reset}`);
+      }
+      if (cls.zone === 'RED') {
+        lines.push(force
+          ? `${C.roseGlow}[FORCED] Override active — execution may fail with CUDA OOM or heavy CPU offloading.${C.reset}`
+          : `${C.roseGlow}ABORT: Allocation exceeds safe limits. Re-run with --force to override.${C.reset}`);
+      }
+
+      printSolidPanel({
+        title: sub === 'check' ? 'KIKU Resource Verification • Pre-Flight' : 'KIKU Resource Verification',
+        lines,
+        headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m'
+      });
+    } catch (err) {
+      console.log(`\n  ${C.red}[VRAM ERROR] ${err.message || String(err)}${C.reset}\n`);
+    }
+    return 'HANDLED';
+  },
+
+  '/about': async () => {
+    printSolidPanel({
+      title: 'About Kiku AI Agent',
+      lines: [
+        `${C.white}Intelligent assistant for Ju Jingyi (鞠婧祎)${C.reset}`,
+        `${C.gold}Engine:${C.reset} ${C.white}LM Studio + Gemma 4${C.reset}`,
+        `${C.gold}Tools:${C.reset} ${C.white}${toolsSchema.length} registered${C.reset}`,
+        `${C.gold}Languages:${C.reset} ${C.white}TH, ZH, EN (auto)${C.reset}`,
+        `${C.gold}Package:${C.reset} ${C.white}${PACKAGE_NAME} v${PACKAGE_VERSION}${C.reset}`,
+        `${C.gold}Runtime:${C.reset} ${C.white}Node ${process.version} • ${process.platform}/${process.arch}${C.reset}`,
+      ],
+    });
+    return 'HANDLED';
   },
 
   '/login': async (ctx) => {
@@ -2609,7 +3382,7 @@ export const handlers = {
       if (audioPlayer.isPlaying || audioPlayer.queue.length > 0) {
         console.log(`\n  ${C.emerald}${await audioPlayer.clearQueue()}${C.reset}\n`);
       } else {
-        ctx.clearQueryQueue();
+        ctx.clearQueryQueue?.();
         console.log(`\n  ${C.emerald}[OK] Execution queue cleared.${C.reset}\n`);
       }
     } else if (audioPlayer.isPlaying || audioPlayer.queue.length > 0) {
@@ -2620,17 +3393,75 @@ export const handlers = {
         headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m'
       });
     } else {
-      const qLen = ctx.getQueryQueueLength();
+      const qLen = typeof ctx.getQueryQueueLength === 'function' ? ctx.getQueryQueueLength() : 0;
       console.log(`\n  ${C.slate}Execution queue: ${qLen} items${C.reset}\n`);
     }
     return 'HANDLED';
   },
 
   '/stats': async (ctx) => {
+    const view = String(ctx.sub || '').toLowerCase();
+    if (view === 'tokens' || view === 'session') {
+      const agent = ctx.agent;
+      const history = Array.isArray(agent?.queryMetricsHistory) ? agent.queryMetricsHistory : [];
+      if (history.length === 0) {
+        printSolidPanel({
+          title: 'Session Token Telemetry',
+          lines: [
+            `${C.dim}No token telemetry recorded yet — run a query first.${C.reset}`,
+            `${C.dim}Set KIKU_CONTEXT_LIMIT to enable context-budget tracking.${C.reset}`,
+          ],
+        });
+        return 'HANDLED';
+      }
+
+      const sums = history.reduce((acc, m) => {
+        acc.prompt += Number(m?.counts?.prompt_tokens) || 0;
+        acc.completion += Number(m?.counts?.completion_tokens) || 0;
+        acc.total += Number(m?.counts?.total_tokens) || 0;
+        acc.decodeTps.push(Number(m?.rates?.decode_tps) || 0);
+        acc.ttft.push(Number(m?.timing_ms?.ttft) || 0);
+        acc.itlMean.push(Number(m?.rates?.itl_mean_ms) || 0);
+        acc.itlP95.push(Number(m?.rates?.itl_p95_ms) || 0);
+        acc.e2e.push(Number(m?.rates?.e2e_tps) || 0);
+        return acc;
+      }, { prompt: 0, completion: 0, total: 0, decodeTps: [], ttft: [], itlMean: [], itlP95: [], e2e: [] });
+      const avg = arr => arr.length ? arr.reduce((a, b) => a + b, 0) / arr.length : 0;
+      const last = history[history.length - 1];
+
+      const lines = [
+        `${C.gold}Queries:${C.reset}       ${C.cyberCyan}${history.length}${C.reset}${C.dim} • latest model: ${last?.model_id || 'unknown'}${C.reset}`,
+        `${C.gold}Tokens:${C.reset}       ${C.white}${sums.prompt.toLocaleString('en-US')} in / ${sums.completion.toLocaleString('en-US')} out${C.reset} ${C.dim}(${sums.total.toLocaleString('en-US')} total)${C.reset}`,
+        `${C.gold}Decode:${C.reset}       ${C.emerald}${avg(sums.decodeTps).toFixed(1)} tok/s avg${C.reset} ${C.dim}• best ${Math.max(...sums.decodeTps).toFixed(1)} • last ${(Number(last?.rates?.decode_tps) || 0).toFixed(1)}${C.reset}`,
+        `${C.gold}TTFT:${C.reset}         ${C.white}avg ${avg(sums.ttft).toFixed(0)} ms • p95 ${computePercentile(sums.ttft, 0.95)?.toFixed(0) || 0} ms${C.reset}`,
+        `${C.gold}ITL:${C.reset}          ${C.white}avg ${avg(sums.itlMean).toFixed(1)} ms • p95 ${avg(sums.itlP95).toFixed(1)} ms${C.reset}`,
+        `${C.gold}E2E:${C.reset}          ${C.white}${avg(sums.e2e).toFixed(1)} tok/s avg (prompt + completion / wall time)${C.reset}`,
+      ];
+
+      if (last?.counts?.context_limit) {
+        lines.push(
+          `${C.gold}Context:${C.reset}      ${C.white}${(last.counts.total_tokens / 1000).toFixed(1)}k / ${(last.counts.context_limit / 1000).toFixed(1)}k${C.reset} ${C.dim}(${last.context_usage_pct}% • ${last.counts.remaining_tokens.toLocaleString('en-US')} remaining)${C.reset}`
+        );
+      } else {
+        lines.push(`${C.gold}Context:${C.reset}      ${C.dim}limit unknown — set KIKU_CONTEXT_LIMIT${C.reset}`);
+      }
+      if (ctx.agent?.lastTelemetry?.costUsd) {
+        lines.push(`${C.gold}Session cost:${C.reset} ${C.white}$${Number(ctx.agent.lastTelemetry.costUsd).toFixed(4)}${C.reset} ${C.dim}(last query)${C.reset}`);
+      }
+
+      printSolidPanel({
+        title: 'Session Token Telemetry',
+        lines,
+        headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m'
+      });
+      return 'HANDLED';
+    }
+
     try {
       const result = await executeTool('get_system_stats', {});
       const s = result.stats || {};
       const insight = await aiNarration(ctx, {
+        label: 'Narrating catalog stats…',
         system: `You are the Kiku data narrator. In ONE short sentence, point out the most interesting thing about this catalog snapshot. ${languageHint(ctx)} Mention only the numbers provided. Never invent numbers. No markdown.`,
         user: JSON.stringify({ totalWorks: s.totalWorks || 0, totalSongs: s.totalUniqueSongs || 0, brands: s.brandEndorsements || 0, awards: s.totalAwards || 0, timeline: s.timelineMilestones || 0 }),
         limit: 240,
@@ -2690,7 +3521,7 @@ export const handlers = {
       ctx.copyQueryDetails(reference);
       return 'HANDLED';
     }
-    const { getCopyableContent, copyToClipboard, parseDetailsRequest } = await import('./queryDetails.js');
+    const { getCopyableContent, copyToClipboardAsync, parseDetailsRequest } = await import('./queryDetails.js');
     const reference = [ctx.sub, ctx.extra].filter(Boolean).join(' ');
     const request = parseDetailsRequest(reference);
     const details = ctx.agent?.lastQueryDetails || ctx.agent?._lastQueryDetails || null;
@@ -2703,7 +3534,7 @@ export const handlers = {
       });
       return 'HANDLED';
     }
-    const copied = copyToClipboard(copyable.text);
+    const copied = await copyToClipboardAsync(copyable.text);
     printRichCard({
       title: copied ? 'Copied to Clipboard' : 'Copy Content Ready',
       status: copied ? 'ok' : 'info',
@@ -2717,7 +3548,11 @@ export const handlers = {
   },
 
   '/ads': async (ctx) => {
-    ctx.printAd();
+    if (typeof ctx.printAd === 'function') {
+      ctx.printAd();
+    } else {
+      console.log(`\n  ${C.amber}No sponsor card available in this view.${C.reset}\n`);
+    }
     return 'HANDLED';
   },
 
@@ -2751,6 +3586,7 @@ export const handlers = {
       return 'HANDLED';
     }
 
+    ctx.setIsProcessing?.(true, 'Rendering gallery image…');
     const displayed = typeof ctx.showTerminalImage === 'function' && ctx.showTerminalImage(renderOptions);
     if (!displayed) {
       printRichCard({
@@ -2818,6 +3654,8 @@ export const handlers = {
       if (stdin.isTTY) {
         try { stdin.setRawMode(false); } catch {}
       }
+   
+      ctx.setIsProcessing?.(false);
       rl = createInterface({ input: stdin, output: process.stdout });
     }
 
@@ -3005,6 +3843,478 @@ export const handlers = {
     return 'HANDLED';
   },
 
+  '/env': async (ctx) => {
+    const sub = String(ctx.sub || '').toLowerCase().trim();
+
+    const targets = resolveEnvTargets(ctx.envTargets || {});
+    const overridePath = typeof ctx.envOverridePath === 'string' && ctx.envOverridePath
+      ? ctx.envOverridePath
+      : null;
+    const targetPath = overridePath || targets.primaryPath;
+    const interactive = process.stdin.isTTY === true;
+    const merged = readMergedEnvMap({ packageEnvPath: targets.packageEnvPath, userEnvPath: targets.userEnvPath });
+    const effectiveMap = overridePath ? (readEnvFile(targetPath) || {}) : merged.map;
+    const effectiveBaseUrl = process.env.LMSTUDIO_BASE_URL
+      || merged.map.LMSTUDIO_BASE_URL
+      || (overridePath ? (readEnvFile(targetPath) || {}).LMSTUDIO_BASE_URL : null)
+      || 'http://127.0.0.1:1234/v1';
+    const probeAllowed = ctx.envProbe !== false && !ctx.signal?.aborted;
+
+    if (sub === 'path') {
+      printSolidPanel({
+        title: 'Environment File Location',
+        lines: [
+          `${C.gold}Mode:${C.reset} ${targets.mode === 'repo' ? 'repository .env (development checkout)' : 'user .env (global install)'}`,
+          `${C.gold}Active:${C.reset} ${C.white}${targetPath}${C.reset}`,
+          `${C.gold}Also scanned:${C.reset} ${C.dim}${targets.userEnvPath}${C.reset}`,
+          `${C.dim}Package .env wins when both exist; unset keys fall through to the user file.${C.reset}`,
+        ],
+      });
+      return 'HANDLED';
+    }
+
+    if (sub === 'set') {
+   
+      const key = String(ctx.parts?.[2] || '').trim().toUpperCase();
+      const value = String(ctx.parts?.slice(3).join(' ') || '').trim();
+      if (!key || !value) {
+        console.log(`\n  ${C.amber}Usage: /env set <KEY> <VALUE>${C.reset}\n`);
+        return 'HANDLED';
+      }
+      try {
+        upsertEnvKey(targetPath, key, value);
+        process.env[key] = value;
+        printRichCard({
+          title: 'Environment Updated',
+          status: 'ok',
+          lines: [
+            `${key}=${isSecretKey(key) ? maskValue(key, value) : value}`,
+            `${C.dim}file: ${targetPath}${C.reset}`,
+            `${C.dim}Applied to this session's process.env. Provider endpoint snapshots refresh on next launch —${C.reset}`,
+            `${C.dim}use /provider url <provider> <url> to switch the live endpoint right away.${C.reset}`,
+          ],
+        });
+      } catch (err) {
+        console.log(`\n  ${C.red}[ENV ERROR] ${err.message}${C.reset}\n`);
+      }
+      return 'HANDLED';
+    }
+
+    if (sub === 'get') {
+      const key = String(ctx.parts?.[2] || '').trim().toUpperCase();
+      if (!key) {
+        console.log(`\n  ${C.amber}Usage: /env get <KEY>${C.reset}\n`);
+        return 'HANDLED';
+      }
+      const sourcePath = overridePath
+        ? targetPath
+        : (merged.sources[key] || null);
+      if (!(key in effectiveMap)) {
+        const runtimeNote = process.env[key] !== undefined && process.env[key] !== ''
+          ? ` ${C.dim}(present in the running process environment only)${C.reset}`
+          : '';
+        console.log(`\n  ${C.amber}${key} is not set in ${targetPath}${C.reset}${runtimeNote}\n`);
+        return 'HANDLED';
+      }
+      const sourceLabel = overridePath ? '' : ` ${C.dim}(from ${sourcePath})${C.reset}`;
+      console.log(`\n  ${C.gold}${key}${C.reset}=${C.white}${maskValue(key, effectiveMap[key])}${C.reset}${sourceLabel}\n`);
+      return 'HANDLED';
+    }
+
+    if (sub === 'unset') {
+      const key = String(ctx.parts?.[2] || '').trim().toUpperCase();
+      if (!key) {
+        console.log(`\n  ${C.amber}Usage: /env unset <KEY>${C.reset}\n`);
+        return 'HANDLED';
+      }
+      try {
+        const results = overridePath
+          ? [removeEnvKey(targetPath, key)]
+          : [removeEnvKey(targets.packageEnvPath, key), removeEnvKey(targets.userEnvPath, key)];
+        delete process.env[key];
+        const touched = results.filter(r => r.removed).map(r => r.path);
+        console.log(touched.length > 0
+          ? `\n  ${C.emerald}[OK] Removed ${key} from:\n${touched.map(p => `    • ${p}`).join('\n')}${C.reset}\n`
+          : `\n  ${C.amber}${key} was not present in ${targetPath}${C.reset}\n`);
+      } catch (err) {
+        console.log(`\n  ${C.red}[ENV ERROR] ${err.message}${C.reset}\n`);
+      }
+      return 'HANDLED';
+    }
+
+    if (sub === 'init') {
+      const exists = fs.existsSync(targetPath);
+      if (exists && !overridePath) {
+        if (!interactive) {
+          printRichCard({
+            title: '.env Already Exists',
+            status: 'info',
+            lines: [
+              `${C.dim}${targetPath}${C.reset}`,
+              'Use /env set <KEY> <VALUE> to change individual keys,',
+              'or run /env init again from an interactive terminal to regenerate it.',
+            ],
+          });
+          return 'HANDLED';
+        }
+        const answer = await askEnvQuestion(`.env already exists at ${targetPath}. Overwrite? (y/N)`, 'N');
+        if (!/^y(es)?$/i.test(answer)) {
+          console.log(`\n  ${C.dim}Aborted — file left untouched.${C.reset}\n`);
+          return 'HANDLED';
+        }
+      }
+
+      const detected = await detectAutoDefaults({ baseUrl: effectiveBaseUrl, probe: probeAllowed, signal: ctx.signal });
+      let values;
+      if (interactive) {
+
+        ctx.setIsProcessing?.(false);
+        console.log(`\n  ${C.bold}${C.cyberCyan}Kiku environment setup${C.reset} ${C.dim}— Enter accepts the default; everything not asked stays optional.${C.reset}\n`);
+        values = {};
+        const baseUrl = await askEnvQuestion('LM Studio endpoint URL', 'http://127.0.0.1:1234/v1');
+        values.LMSTUDIO_BASE_URL = baseUrl || 'http://127.0.0.1:1234/v1';
+        if (detected.loadedModel) {
+          console.log(`  ${C.dim}Detected loaded model: ${detected.loadedModel}${C.reset}`);
+        }
+        const contextAnswer = await askEnvQuestion('Context window for token telemetry (tokens)', detected.contextLength ? String(detected.contextLength) : '');
+        if (contextAnswer && Number(contextAnswer) > 0) values.KIKU_CONTEXT_LIMIT = String(Math.trunc(Number(contextAnswer)));
+        const dirAnswer = await askEnvQuestion('LM Studio models directory', detected.modelsDir || '');
+        if (dirAnswer) values.LMSTUDIO_MODELS_DIR = dirAnswer;
+        const wantCloud = await askEnvQuestion('Configure a cloud provider API key now? (y/N)', 'N');
+        if (/^y(es)?$/i.test(wantCloud)) {
+          const provider = (await askEnvQuestion('Provider (openai/gemini/groq/deepseek/openrouter)', 'openai')).toUpperCase();
+          const keyMap = {
+            OPENAI: 'OPENAI_API_KEY',
+            GEMINI: 'GEMINI_API_KEY',
+            GROQ: 'GROQ_API_KEY',
+            DEEPSEEK: 'DEEPSEEK_API_KEY',
+            OPENROUTER: 'OPENROUTER_API_KEY',
+          };
+          const keyName = keyMap[provider];
+          if (keyName) {
+            const apiKey = await askEnvQuestion(`${provider} API key`, '');
+            if (apiKey) values[keyName] = apiKey;
+          }
+        }
+      } else {
+        values = { LMSTUDIO_BASE_URL: 'http://127.0.0.1:1234/v1' };
+        if (detected.contextLength) values.KIKU_CONTEXT_LIMIT = String(detected.contextLength);
+        if (detected.modelsDir) values.LMSTUDIO_MODELS_DIR = detected.modelsDir;
+      }
+
+      try {
+        const result = generateEnvFile({ targetPath, values, detected, allowOverwrite: true });
+        for (const [k, v] of Object.entries(values)) {
+          if (process.env[k] === undefined) process.env[k] = String(v);
+        }
+        printRichCard({
+          title: '.env Created',
+          status: 'ok',
+          lines: [
+            `${C.dim}${result.path}${C.reset}`,
+            `Set: ${result.keys.join(', ')}`,
+            detected.loadedModel
+              ? `${C.dim}LM Studio: ${detected.loadedModel}${detected.contextLength ? ` • ${detected.contextLength} ctx` : ''}${C.reset}`
+              : `${C.dim}LM Studio was offline — defaults written; run /env init again later to auto-detect.${C.reset}`,
+            'Everything else is intentionally left commented (not necessary for CLI usage).',
+            `${C.dim}Verify with /ping or /model status.${C.reset}`,
+          ],
+        });
+      } catch (err) {
+        console.log(`\n  ${C.red}[ENV ERROR] ${err.message}${C.reset}\n`);
+      }
+      return 'HANDLED';
+    }
+
+    if (sub && !['path', 'set', 'get', 'unset', 'init'].includes(sub)) {
+      console.log(`\n  ${C.amber}Unknown /env subcommand: ${sub}${C.reset} ${C.dim}(use init|set|get|unset|path)${C.reset}\n`);
+    }
+
+
+    const map = overridePath ? (readEnvFile(targetPath) || {}) : merged.map;
+    const detected = await detectAutoDefaults({ baseUrl: effectiveBaseUrl, probe: probeAllowed, timeoutMs: 800, signal: ctx.signal });
+    const catalogKeys = new Set(ENV_VAR_CATALOG.map(e => e.key));
+    const otherKeys = Object.keys(map).filter(k => !catalogKeys.has(k) && String(map[k] || ''));
+    const lines = [
+      `${C.gold}Mode:${C.reset} ${targets.mode === 'repo' ? 'repository .env (development)' : 'user .env (global install)'}`,
+      `${C.gold}File:${C.reset}  ${C.white}${targetPath}${C.reset}`,
+      `${C.gold}Effective endpoint:${C.reset} ${C.cyberCyan}${effectiveBaseUrl}${C.reset}`,
+      `${C.gold}LM Studio:${C.reset} ${probeAllowed
+        ? (detected.lmStudioReachable
+          ? `${C.emerald}reachable${C.reset}${detected.loadedModel ? ` ${C.dim}• ${detected.loadedModel}${detected.contextLength ? ` @ ${detected.contextLength} ctx` : ''}${C.reset}` : ''}`
+          : `${C.dim}not reachable (start LM Studio server, or set LMSTUDIO_BASE_URL)${C.reset}`)
+        : `${C.dim}probe skipped this run${C.reset}`}`,
+      '',
+    ];
+
+    for (const group of ['necessary', 'recommended']) {
+      lines.push(`${C.bold}${C.lavender}${describeGroup(group)}:${C.reset}`);
+      for (const entry of ENV_VAR_CATALOG.filter(e => e.group === group)) {
+        const isSet = entry.key in map;
+        const shown = isSet ? maskValue(entry.key, map[entry.key]) : (entry.defaultValue ? `default: ${entry.defaultValue}` : '—');
+        lines.push(`  ${isSet
+          ? `${C.emerald}set    ${C.reset}${C.white}${entry.key.padEnd(22)}${C.reset}${C.dim}${shown}${C.reset}`
+          : `${C.dim}unset  ${entry.key.padEnd(22)}${shown}${C.reset}`}`);
+      }
+      lines.push('');
+    }
+
+    for (const group of ['optional', 'cloud', 'server']) {
+      const entries = ENV_VAR_CATALOG.filter(e => e.group === group);
+      if (group === 'server' && targets.mode !== 'repo') {
+       
+        lines.push(`${C.bold}${C.lavender}Server deployment credentials:${C.reset} ${C.dim}owned by the platform developer (hosted API) — never needed or prompted for the CLI${C.reset}`);
+        continue;
+      }
+      const setKeys = entries.filter(e => e.key in map);
+      const summary = setKeys.length > 0
+        ? `${setKeys.length}/${entries.length} set ${C.dim}(${setKeys.map(e => e.key).join(', ')})${C.reset}`
+        : `${C.dim}none set — defaults apply; not required for CLI usage${C.reset}`;
+      lines.push(`${C.bold}${C.lavender}${describeGroup(group)}:${C.reset} ${summary}`);
+    }
+
+    if (otherKeys.length > 0) {
+      lines.push('');
+      lines.push(`${C.bold}${C.lavender}Other keys detected in your env files (not part of the standard catalog):${C.reset}`);
+      for (const k of otherKeys) {
+        lines.push(`  ${C.cyberCyan}• ${k.padEnd(26)}${C.reset}${C.dim}${maskValue(k, map[k])}${C.reset}`);
+      }
+    }
+
+    lines.push('');
+    lines.push(`${C.dim}/env init • /env set <KEY> <VALUE> • /env get <KEY> • /env unset <KEY> • /env path${C.reset}`);
+
+    printSolidPanel({
+      title: 'Local Environment (.env)',
+      lines,
+      headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m'
+    });
+    return 'HANDLED';
+  },
+
+  '/eval': async (ctx) => {
+    const sub = (ctx.sub || 'ui').toLowerCase();
+    const extra = (ctx.extra || '').trim();
+
+    if (sub === 'ui' || sub === 'studio') {
+      const port = Number(extra) || 3000;
+      const url = `http://localhost:${port}/eval`;
+      openBrowser(url);
+      printRichCard({
+        title: 'Interactive Eval Studio Opened',
+        status: 'ok',
+        lines: [
+          `• Eval Studio Dashboard: ${C.bold}${C.cyberCyan}${url}${C.reset}`,
+          `• Live benchmark test runner & performance visualization.`,
+          `• Web UI launched in default browser.`,
+        ],
+      });
+      return 'HANDLED';
+    }
+
+    if (sub === 'status') {
+      try {
+        const { DEFAULTS, REPO_ROOT } = await import('./eval/modules/core/config.js');
+        const raw = await fs.promises.readFile(path.join(REPO_ROOT, DEFAULTS.out), 'utf8');
+        const report = JSON.parse(raw);
+        const rows = Array.isArray(report.rows) ? report.rows : [];
+        const completed = rows.filter(r => r.status === 'completed').length;
+        const errors = rows.length - completed.length;
+        const passRate = report.summary?.passAt1 ?? report.summary?.lexicalCoverageRate;
+        const model = report.metadata?.model || 'unknown';
+        const finishedAt = report.metadata?.finishedAt || report.metadata?.startedAt || 'unknown';
+        const partialBadge = report.metadata?.archivedPartial === true ? ` ${C.amber}[partial]${C.reset}` : '';
+        printSolidPanel({
+          title: 'Eval Status • Live Report',
+          lines: [
+            `• Model: ${C.bold}${C.white}${model}${C.reset}${partialBadge}`,
+            `• Rows: ${C.bold}${C.white}${rows.length}${C.reset} (${completed} completed, ${errors > 0 ? `${C.amber}${errors} errors${C.reset}` : '0 errors'})`,
+            `• Pass@1: ${passRate != null ? `${C.emerald}${(Number(passRate) * 100).toFixed(1)}%${C.reset}` : `${C.dim}n/a${C.reset}`}`,
+            `• Last activity: ${C.dim}${finishedAt}${C.reset}`,
+            `${C.dim}Next: /eval ui (interactive studio) • /eval quick (3-case smoke) • /eval run --limit 3${C.reset}`,
+          ],
+        });
+      } catch {
+        printRichCard({
+          title: 'Eval Status',
+          status: 'info',
+          lines: [
+            'No evaluation report found yet.',
+            `• ${C.bold}/eval quick${C.reset} — 3-case smoke run against the active model`,
+            `• ${C.bold}/eval ui${C.reset} — interactive Eval Studio dashboard`,
+            `• ${C.bold}/eval validate${C.reset} — verify the 500-case frozen corpus (no LLM)`,
+          ],
+        });
+      }
+      return 'HANDLED';
+    }
+
+    if (sub === 'validate') {
+      try {
+        const { cases, securityCases, allCases, validateCases } = await import('./eval/modules/evaluation/cases.js');
+        validateCases();
+        const categories = [...new Set(allCases.map(c => c.category))];
+        printSolidPanel({
+          title: 'Evaluation Corpus Validation • Frozen Ground Truth',
+          lines: [
+            `${C.bold}${C.emerald}✓ Corpus Valid: ${allCases.length} cases verified${C.reset}`,
+            `• Total Cases: ${C.bold}${C.white}${allCases.length}${C.reset} (${cases.length} catalog + ${securityCases.length} security)`,
+            `• Categories: ${C.dim}${categories.join(', ')}${C.reset}`,
+            `• Integrity: Reference answers frozen — gold standards intact`,
+          ],
+          headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m'
+        });
+      } catch (err) {
+        console.log(`  ${C.amber}Validate error: ${err.message}${C.reset}`);
+      }
+      return 'HANDLED';
+    }
+
+    if (sub === 'dashboard' || sub === 'quick' || ['run', 'judge', 'compare', 'gate', 'analyze', 'dashboard-png'].includes(sub)) {
+      const { spawn } = await import('node:child_process');
+      let args;
+      if (sub === 'quick') {
+        args = ['server/agent/eval/modules/core/cli.js', 'run', '--limit', '3'];
+      } else {
+        args = ['server/agent/eval/modules/core/cli.js', sub];
+        if (extra) args.push(...extra.split(/\s+/).filter(Boolean));
+      }
+
+      const child = spawn(process.execPath, args, {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        cwd: process.cwd(),
+        windowsHide: true,
+      });
+
+      const forward = chunk => {
+        for (const line of chunk.split(/\r?\n/)) {
+          if (line.trim()) console.log(line);
+        }
+      };
+      child.stdout?.on('data', b => forward(b.toString()));
+      child.stderr?.on('data', b => forward(b.toString()));
+      child.on('error', err => {
+        console.log(`  ${C.amber}Eval error: ${err.message}${C.reset}`);
+      });
+      child.on('close', code => {
+        if (ctx.signal?.aborted) {
+          console.log(`  ${C.amber}/eval ${sub} cancelled.${C.reset}`);
+        } else if (code !== 0 && code !== null) {
+          console.log(`  ${C.amber}/eval ${sub} exited with code ${code}${C.reset}`);
+        }
+      });
+      ctx.signal?.addEventListener('abort', () => {
+        try { child.kill(); } catch {}
+      }, { once: true });
+      return 'HANDLED';
+    }
+
+    printRichCard({
+      title: 'Kiku Eval Suite & Benchmark Harness',
+      status: 'info',
+      lines: [
+        `• Subcommands: ${C.bold}${C.cyberCyan}ui, status, validate, quick, dashboard, run, judge, compare, gate, analyze${C.reset}`,
+        `• /eval status     - Show live report summary (rows, pass rate, errors)`,
+        `• /eval ui         - Open interactive Eval Studio web UI (/eval)`,
+        `• /eval dashboard  - Generate & open mobile-responsive HTML evaluation report`,
+        `• /eval validate   - Check 500 frozen ground truth cases without LLM`,
+        `• /eval quick      - Run 3-case live smoke evaluation against active model`,
+        `• /eval run|judge|compare|gate|analyze [flags] - forwarded to the eval CLI`,
+      ],
+    });
+    return 'HANDLED';
+  },
+
+  '/hub': async (ctx) => {
+    const filter = (ctx.sub || ctx.extra || '').trim();
+    try {
+      const { renderKikuHub } = await import('../../scripts/kikuHub.js');
+      await renderKikuHub(filter);
+    } catch (err) {
+      console.log(`\n  ${C.amber}[HUB ERROR] ${err.message}${C.reset}\n`);
+    }
+    return 'HANDLED';
+  },
+
+  '/portal': async (ctx) => {
+    const rawSub = (ctx.sub || 'open').toLowerCase();
+    const extraPort = Number(ctx.extra || (/^\d+$/.test(ctx.sub) ? ctx.sub : null)) || 3000;
+    const baseUrl = `http://localhost:${extraPort}`;
+
+    if (rawSub === 'api' || rawSub === 'docs') {
+      const url = `${baseUrl}/api-docs`;
+      openBrowser(url);
+      printRichCard({
+        title: 'REST API v1 Documentation Opened',
+        status: 'ok',
+        lines: [
+          `• Interactive API Docs: ${C.bold}${C.cyberCyan}${url}${C.reset}`,
+          `• OpenAPI 3.1 Spec: ${C.dim}${baseUrl}/openapi.json${C.reset}`,
+          `• Endpoints live at ${C.white}${baseUrl}/api/v1/*${C.reset}`,
+        ],
+      });
+      return 'HANDLED';
+    }
+
+    if (rawSub === 'chat') {
+      const url = `${baseUrl}/chat`;
+      openBrowser(url);
+      printRichCard({
+        title: 'Luxury Web Chat Opened',
+        status: 'ok',
+        lines: [
+          `• Web Chat interface: ${C.bold}${C.cyberCyan}${url}${C.reset}`,
+          `• Direct AI model streaming on Port ${extraPort}.`,
+        ],
+      });
+      return 'HANDLED';
+    }
+
+    if (rawSub === 'eval' || rawSub === 'studio') {
+      return handlers['/eval']({ ...ctx, sub: 'ui', extra: String(extraPort), parts: ['/eval', 'ui'] });
+    }
+
+    if (rawSub === 'status' || rawSub === 'info') {
+      const isLive = await new Promise((resolve) => {
+        const req = http.get(`${baseUrl}/api/v1/profile`, { timeout: 1500 }, (res) => {
+          resolve(res.statusCode >= 200 && res.statusCode < 400);
+          res.resume();
+        });
+        req.on('timeout', () => { req.destroy(); resolve(false); });
+        req.on('error', () => resolve(false));
+      });
+
+      const lines = [
+        `• Dev Server: ${isLive ? `${C.emerald}Active (Port ${extraPort})${C.reset}` : `${C.amber}Offline or starting (Port ${extraPort})${C.reset}`}`,
+        `• Fan Portal SPA: ${C.cyberCyan}${baseUrl}/${C.reset}`,
+        `• REST API v1: ${C.cyberCyan}${baseUrl}/api-docs${C.reset}`,
+        `• Luxury Web Chat: ${C.cyberCyan}${baseUrl}/chat${C.reset}`,
+        `• Eval Studio: ${C.cyberCyan}${baseUrl}/eval${C.reset}`,
+        '',
+        `${C.dim}Tip: Run "npm run dev" to launch all services in a single in-process dev server.${C.reset}`,
+      ];
+
+      printRichCard({
+        title: 'Kiku Web Portal & API Status',
+        status: isLive ? 'ok' : 'info',
+        lines,
+      });
+      return 'HANDLED';
+    }
+
+    openBrowser(baseUrl);
+    printRichCard({
+      title: 'Kiku Fan Portal Opened',
+      status: 'ok',
+      lines: [
+        `• Fan Portal SPA: ${C.bold}${C.cyberCyan}${baseUrl}/${C.reset}`,
+        `• In-process unified Vite dev server (Port ${extraPort}).`,
+        `• Browser opened automatically.`,
+      ],
+    });
+    return 'HANDLED';
+  },
+
   '/exit': async (ctx) => {
     try { await ctx.agent?.endSession(); } catch {}
     return 'EXIT';
@@ -3013,6 +4323,7 @@ export const handlers = {
 
 const ALIASES = {
   '/quit': '/exit', '/q': '/exit',
+  '/web-chat': '/web',
   '/abort': '/cancel',
   '/cp': '/copy', '/clip': '/copy', '/clipboard': '/copy',
   '/?': '/help', '/commands': '/help', '/menu': '/help',
@@ -3037,9 +4348,13 @@ const ALIASES = {
   '/health': '/ping',
   '/settings': '/config', '/conf': '/config',
   '/persona': '/prompt', '/sysprompt': '/prompt',
-  '/ver': '/version', '/v': '/version',
+  '/ver': '/about', '/v': '/about', '/version': '/about',
   '/sys': '/system', '/os': '/system',
-  '/vram': '/gpu', '/gpus': '/gpu',
+  '/gpus': '/gpu',
+  '/resource': '/vram',
+  '/benchmark': '/eval', '/evaluation': '/eval',
+  '/center': '/hub',
+  '/app': '/portal', '/webportal': '/portal',
   '/info': '/about',
   '/sponsor': '/ads', '/ad': '/ads',
   '/image': '/gallery', '/photo': '/gallery',
@@ -3050,10 +4365,10 @@ const ALIASES = {
   '/kvip': '/key',
   '/switch': '/provider',
   '/providers': '/provider',
-  '/fallback': '/provider',
   '/profiles': '/profile',
   '/preset': '/profile',
   '/presets': '/profile',
+  '/ingestion': '/ingest',
 };
 
 export async function routeCommand(rawInput, ctx) {