kiku-agent 1.2.0 → 1.3.1

package/server/agent/commandFeatures.js

@@ -1,6 +1,10 @@
 import { executeTool } from './tools.js';
 import { allowlistedValue, boundedInteger, parseCommandInput } from './commandInput.js';
 import { C, printSolidPanel, sanitizeTerminalText } from './ui.js';
+import { mergeNewsResults, classifyTopics, classifySource } from './newsIntelligence.js';
+import { checkNewsWatch, loadWatchState, saveWatchState, startNewsWatchLoop } from './newsWatch.js';
+import { KIKU_DATA_DIR } from './appPaths.js';
+import path from 'node:path';
 
 const ENTITY_TYPES = ['all', 'work', 'song', 'role', 'brand', 'award', 'photo', 'stage'];
 const FAVORITE_TYPES = ENTITY_TYPES.filter(type => type !== 'all');
@@ -133,6 +137,7 @@ async function handleFind(ctx) {
   }
   const entities = await findCatalogEntities(query, { type, year, limit, executeTool: ctx.executeTool });
   const summary = entities.length ? await aiNarration(ctx, {
+    label: 'Narrating search results…',
     system: `You are the Kiku catalog guide. In ONE short sentence, tell the user why the top search result matches their query and what to notice about it. ${languageHint(ctx)} Mention only facts present in the data. Never invent facts, dates, or titles. No markdown.`,
     user: JSON.stringify({ query, type, year, results: entities.slice(0, 3).map(e => ({ title: e.title, type: e.type, year: e.year, detail: e.detail })) }),
     limit: 260,
@@ -151,9 +156,12 @@ export function languageHint(ctx) {
   return lang === 'th' ? 'Answer in Thai.' : lang === 'zh' ? 'Answer in Chinese.' : lang === 'en' ? 'Answer in English.' : 'Answer in the same language as the surrounding UI (English is fine).';
 }
 
-export async function aiNarration(ctx, { system, user, limit = 400, multiline = false }) {
+export async function aiNarration(ctx, { system, user, limit = 400, multiline = false, label = null }) {
   const client = ctx?.agent?.client;
   if (!client || typeof client.chat !== 'function') return null;
+  if (label && typeof ctx?.setIsProcessing === 'function') {
+    ctx.setIsProcessing(true, label);
+  }
   try {
     const res = await client.chat({
       messages: [
@@ -177,6 +185,7 @@ export async function aiNarration(ctx, { system, user, limit = 400, multiline =
 async function aiDiscoverRationale(ctx, entity, { type, year, mood }) {
   const item = { type, title: entity.title, year: entity.year || year || 'unknown', detail: entity.detail || 'no extra detail' };
   const text = await aiNarration(ctx, {
+    label: 'Curating a pick…',
     system: `You are the Kiku fan-curator. Write ONE short, warm, factual sentence explaining why this Ju Jingyi catalog item is a good pick for the requested vibe. ${languageHint(ctx)} Mention only details present in the item. Never invent facts, dates, or titles. Max ~160 characters. Output only the sentence, no quotes, no markdown.`,
     user: JSON.stringify({ mood, year, type, item }),
     limit: 220,
@@ -266,6 +275,7 @@ async function handleCompare(ctx) {
   const a = { title: left.title, type: left.type, year: left.year, fields: comparableFields(left) };
   const b = { title: right.title, type: right.type, year: right.year, fields: comparableFields(right) };
   const aiSummary = await aiNarration(ctx, {
+    label: 'Comparing items…',
     system: `You are the Kiku comparisons editor. In ONE short paragraph, summarize how these two Ju Jingyi catalog items differ and what is notable about each. ${languageHint(ctx)} Mention only facts present in the data. Never invent facts, dates, or titles. Do not use markdown.`,
     user: JSON.stringify({ a, b }),
     limit: 420,
@@ -349,6 +359,7 @@ async function handleFavorites(ctx) {
     const poolResults = await Promise.allSettled(types.map(type => findCatalogEntities('', { type, limit: 8, executeTool: ctx.executeTool })));
     const pool = poolResults.flatMap(entry => entry.status === 'fulfilled' ? entry.value.map(e => ({ type: e.type, title: e.title, year: e.year, detail: e.detail })) : []);
     const aiText = await aiNarration(ctx, {
+      label: 'Suggesting favorites…',
       system: `You are the Kiku personal curator. Based on the fan's saved favorites, recommend 3 catalog items from the available pool that best match their taste. ${languageHint(ctx)} Reply with a plain list, one per line, format exactly: "<title> — <short reason>". Mention only items present in the pool and only facts present in their detail. Never invent titles or facts. No markdown, no numbering prefix.`,
       user: JSON.stringify({ profile, pool }),
       limit: 220,
@@ -395,41 +406,129 @@ function detectedDate(item) {
 
 async function handleNews(ctx) {
   const parsed = parsedRequest(ctx);
-  const days = boundedInteger(parsed.flags.days, 7, 1, 90);
+  const positionals = parsed.positionals || [];
+  const first = String(positionals[0] || '').toLowerCase();
+  const daysFlag = boundedInteger(parsed.flags.days, 7, 1, 90);
+  const executor = ctx.executeTool || executeTool;
+  const watchStatePath = path.join(KIKU_DATA_DIR, 'news-watch-state.json');
+
+  if (first === 'watch' || first === 'watches' || first === 'check') {
+    const topic = positionals.slice(1).join(' ').trim() || 'latest';
+
+    if (first === 'watches') {
+      const watches = typeof ctx.agent?.getJobs === 'function'
+        ? ctx.agent.getJobs().filter(job => job.type === 'news-watch')
+        : [];
+      printSolidPanel({
+        title: `News Watches • ${watches.length} active`,
+        lines: watches.length ? watches.map(jobLine) : [`${C.dim}No active watches. Start one with /news watch <topic>.${C.reset}`],
+      });
+      return 'HANDLED';
+    }
+
+    const state = loadWatchState(watchStatePath);
+    const fetcher = async (t, d) => {
+      const res = await executor('search_news', { query: `Ju Jingyi 鞠婧祎 ${t === 'latest' ? 'latest news' : t} when:${d}d`, maxResults: 12 });
+      return res?.results || [];
+    };
+
+    if (first === 'check') {
+      const delta = await checkNewsWatch({ topic, days: daysFlag, fetcher, state, statePath: watchStatePath });
+      saveWatchState(state, watchStatePath);
+      printSolidPanel({
+        title: `News Check • ${delta.topic} • ${delta.fresh.length} new of ${delta.total}`,
+        lines: delta.items.slice(0, 8).map((item, index) => {
+          const isNew = delta.fresh.includes(item);
+          const mark = isNew ? `${C.emerald}[NEW]${C.reset} ` : `${C.dim}[   ]${C.reset} `;
+          const date = item.date ? item.date.toISOString().slice(0, 10) : 'date unverified';
+          return `${mark}${C.bold}${C.cyberCyan}${clean(item.title, 110)}${C.reset} ${C.dim}${date}${C.reset}`;
+        }),
+      });
+      return 'HANDLED';
+    }
+
+    const every = boundedInteger(parsed.flags.every, 30, 5, 720);
+    const job = typeof ctx.agent?.jobs?.create === 'function'
+      ? ctx.agent.jobs.create('news-watch', `News watch • ${topic} • every ${every}m`)
+      : null;
+    if (!job) {
+      printSolidPanel({ title: 'News Watch', lines: [`${C.amber}Agent job manager is unavailable in this context.${C.reset}`] });
+      return 'HANDLED';
+    }
+    startNewsWatchLoop({
+      topic,
+      days: daysFlag,
+      intervalMinutes: every,
+      fetcher,
+      controller: job.controller,
+      state,
+      statePath: watchStatePath,
+      onDelta: delta => {
+        console.log(`\n  ${C.emerald}[NEWS WATCH] ${delta.topic}: ${delta.fresh.length} new item(s)${C.reset}`);
+        for (const item of delta.fresh.slice(0, 5)) {
+          console.log(`    • ${clean(item.title, 120)} ${C.dim}(${item.date ? item.date.toISOString().slice(0, 10) : 'date unknown'})${C.reset}`);
+        }
+        console.log('');
+      },
+      onError: err => console.log(`  ${C.amber}[news watch] check failed: ${err.message}${C.reset}`),
+    });
+    printSolidPanel({
+      title: 'News Watch Started',
+      lines: [
+        `• Topic: ${C.bold}${topic}${C.reset} • every ${every} min • window ${daysFlag}d`,
+        `• Job: ${C.dim}${job.id}${C.reset} — cancel with ${C.bold}/jobs cancel ${job.id}${C.reset}`,
+        `${C.dim}New items will be printed here automatically as they are detected.${C.reset}`,
+      ],
+    });
+    return 'HANDLED';
+  }
+
   const officialOnly = parsed.flags['official-only'] === true || String(parsed.flags['official-only']).toLowerCase() === 'true';
-  const topic = parsed.positionals.join(' ').trim();
+  const topic = positionals.join(' ').trim();
   const now = new Date();
-  const cutoff = new Date(now.getTime() - days * 86_400_000);
+  const cutoff = new Date(now.getTime() - daysFlag * 86_400_000);
   cutoff.setUTCHours(0, 0, 0, 0);
   const after = cutoff.toISOString().slice(0, 10);
   const before = new Date(now.getTime() + 86_400_000).toISOString().slice(0, 10);
-  const query = `Ju Jingyi 鞠婧祎 ${topic || 'latest news'} after:${after} before:${before}${officialOnly ? ' official studio' : ''}`;
-  const executor = ctx.executeTool || executeTool;
-  const result = await executor('web_search', { query });
-  const seen = new Set();
-  const items = (result?.results || []).filter(item => {
-    const url = safeNewsUrl(item.url);
-    if (!url || seen.has(url.href)) return false;
-    if (officialOnly && (!OFFICIAL_NEWS_HOSTS.has(url.hostname.toLowerCase()) || !OFFICIAL_NEWS_SIGNAL.test(`${item.title || ''} ${item.snippet || ''} ${url.pathname}`))) return false;
-    const date = detectedDate(item);
-    if (date && date.getTime() < cutoff.getTime()) return false;
-    seen.add(url.href);
-    return true;
-  }).slice(0, 8);
-  const summary = items.length ? await aiNarration(ctx, {
+  const baseQuery = `Ju Jingyi 鞠婧祎 ${topic || 'latest news'}`;
+
+  const [newsSettled, webSettled] = await Promise.allSettled([
+    executor('search_news', { query: `${baseQuery} when:${daysFlag}d`, maxResults: 12 }),
+    executor('web_search', { query: `${baseQuery} after:${after} before:${before}${officialOnly ? ' official studio' : ''}` }),
+  ]);
+  const newsResults = newsSettled.status === 'fulfilled' ? (newsSettled.value?.results || []) : [];
+  const webResults = webSettled.status === 'fulfilled' ? (webSettled.value?.results || []) : [];
+  const { items } = mergeNewsResults({
+    groups: [
+      { name: 'news-rss', results: newsResults },
+      { name: 'web', results: webResults },
+    ],
+    now,
+    cutoff,
+    officialOnly,
+    budget: 10,
+  });
+  const visible = officialOnly
+    ? items.filter(item => OFFICIAL_NEWS_SIGNAL.test(`${item.title || ''} ${item.snippet || ''}`))
+    : items;
+
+  const summary = visible.length ? await aiNarration(ctx, {
+    label: 'Summarizing news…',
     system: `You are the Kiku news desk. In ONE short paragraph (2-3 sentences), summarize what these Ju Jingyi news results say this week. ${languageHint(ctx)} Synthesize only from the provided items. Never invent facts, dates, or sources. No markdown.`,
-    user: JSON.stringify({ topic, items: items.slice(0, 8).map((item, index) => ({ title: item.title, snippet: item.snippet, source: safeNewsUrl(item.url)?.hostname || item.source })) }),
+    user: JSON.stringify({ topic, items: visible.slice(0, 8).map((item, index) => ({ title: item.title, snippet: item.snippet, source: safeNewsUrl(item.url)?.hostname || item.source })) }),
     limit: 420,
   }) : null;
   printSolidPanel({
-    title: `${officialOnly ? 'Official-source ' : ''}News Search • ${items.length} result${items.length === 1 ? '' : 's'} • requested ${days}-day window`,
-    lines: items.length
-      ? [...items.flatMap((item, index) => {
+    title: `${officialOnly ? 'Official-source ' : ''}News Search • ${visible.length} result${visible.length === 1 ? '' : 's'} • requested ${daysFlag}-day window`,
+    lines: visible.length
+      ? [...visible.flatMap((item, index) => {
           const url = safeNewsUrl(item.url);
-          const date = detectedDate(item);
+          const date = item.date || detectedDate(item);
+          const tierTag = `[${(item.tierLabel || 'community').toUpperCase()}]`;
+          const topicTags = (item.topics || []).slice(0, 2).join('/');
           return [
             `${C.gold}[${index + 1}]${C.reset} ${C.bold}${C.cyberCyan}${clean(item.title)}${C.reset}`,
-            `    ${C.dim}${date ? date.toISOString().slice(0, 10) : 'date unavailable • recency unverified'} • ${clean(url?.hostname || item.source || 'source', 100)}${C.reset}`,
+            `    ${C.dim}${date ? date.toISOString().slice(0, 10) : 'date unavailable • recency unverified'} • ${clean(url?.hostname || item.source || 'source', 100)} • ${tierTag}${topicTags ? ` • ${topicTags}` : ''}${C.reset}`,
             `    ${C.white}${clean(item.snippet, 260)}${C.reset}`,
             `    ${C.slate}${clean(url?.href || '', 500)}${C.reset}`,
           ];

package/server/agent/commandRegistry.js

@@ -11,7 +11,6 @@ export const COMMAND_DEFINITIONS = Object.freeze([
   { name: '/subagent', usage: '/subagent <research task>', desc: 'Run a bounded Ju Jingyi research subagent', insert: '/subagent ' },
   { name: '/research', usage: '/research <question|status|last|sources|cancel>', desc: 'Run coordinated multi-source Ju Jingyi research', insert: '/research ' },
   { name: '/verify', usage: '/verify <claim>', desc: 'Verify a Ju Jingyi claim with independent workers', insert: '/verify ' },
-  { name: '/sources', usage: '/sources', desc: 'Show sources from the latest research job', insert: '/sources' },
   { name: '/debate', usage: '/debate <claim|status|last>', desc: 'Run multi-agent adversarial debate & fact synthesis', insert: '/debate ' },
   { name: '/timeline', usage: '/timeline [year|era]', desc: 'Render career milestone graphic timeline in terminal', insert: '/timeline ' },
   { name: '/suggestion', usage: '/suggestion [list|run <id|all>|auto|refresh|topic <name>]', desc: 'Generate AI research suggestions & execute with concurrent subagents', insert: '/suggestion ' },
@@ -22,18 +21,23 @@ export const COMMAND_DEFINITIONS = Object.freeze([
   { name: '/compare', usage: '/compare <item-a> -- <item-b>', desc: 'Compare catalog entries or career years', insert: '/compare ' },
   { name: '/favorites', usage: '/favorites [list|add|suggest|remove|export]', desc: 'Manage a persistent fan collection', insert: '/favorites ' },
   { name: '/news', usage: '/news [topic] [--days N] [--official-only]', desc: 'Find recent source-backed Ju Jingyi news', insert: '/news ' },
+  { name: '/ingest', usage: '/ingest [status|run|add <text>|clear]', desc: 'Manage autonomous knowledge ingestion and dynamic catalog overlay', insert: '/ingest ' },
   { name: '/jobs', usage: '/jobs [list|show|cancel|clear]', desc: 'Inspect and control tracked agent jobs', insert: '/jobs ' },
   { name: '/discover', usage: '/discover [drama|song|stage|photo]', desc: 'Discover something from the catalog', insert: '/discover ' },
-  { name: '/stats', usage: '/stats', desc: 'Show the content database overview', insert: '/stats' },
-  { name: '/provider', usage: '/provider [list|use <name> [model]|models [name]|setkey [provider] <key>|info <name>|test|status]', desc: 'Manage AI providers (OpenAI, Gemini, Groq, DeepSeek, OpenRouter, LM Studio)', insert: '/provider ' },
-  { name: '/model', usage: '/model [status|list|recommend|use <id>|reconnect]', desc: 'Inspect, recommend, or switch active AI model', insert: '/model ' },
+  { name: '/stats', usage: '/stats [overview|tokens]', desc: 'Show catalog overview or session token telemetry', insert: '/stats ' },
+  { name: '/provider', usage: '/provider [list|use <name> [model]|url [provider] [url]|models [name]|setkey [provider] <key>|info <name>|test|status]', desc: 'Manage AI providers and unified API Base URLs (LM Studio, vLLM, OpenAI, Gemini, Groq, DeepSeek, OpenRouter)', insert: '/provider ' },
+  { name: '/lan', usage: '/lan [scan [<cidr|range|ip>,...] [--ports p1,p2]|use <n>|json]', desc: 'Scan the local network (or custom CIDR/ranges) for LM Studio / vLLM / Ollama servers and list their models', insert: '/lan ' },
+  { name: '/model', usage: '/model [status|ping|list|recommend|use <id>|reconnect]', desc: 'Inspect, recommend, or switch active AI model', insert: '/model ' },
+  { name: '/vram', usage: '/vram [check <model>|live|compare|ctx|list|tier] [--ctx <len>] [--quant <type>] [--force]', desc: 'Predictive VRAM analyzer: footprint, live usage, quant/context ladders, hardware tier & pre-flight check', insert: '/vram ' },
+  { name: '/eval', usage: '/eval [ui|dashboard|validate|quick|run|judge|compare|gate|status]', desc: 'Manage evaluation studio, benchmarks, and performance dashboards', insert: '/eval ' },
+  { name: '/hub', usage: '/hub [filter]', desc: 'Show Kiku Master Command Center hub with hardware telemetry & command index', insert: '/hub' },
+  { name: '/portal', usage: '/portal [open|api|chat|eval|status] [port]', desc: 'Inspect or open local portal, REST API docs, Web Chat, or Eval Studio (port 3000)', insert: '/portal ' },
   { name: '/profile', usage: '/profile [list|use <name>|show <name>|save <name>|delete <name>]', desc: 'Manage configuration profiles (default, fast, deep-reasoning, cloud, gemini)', insert: '/profile ' },
   { name: '/mcp', usage: '/mcp [status|list|connect <name> <url|cmd>|disconnect <name>|remove <name>|reconnect [all]|save|reload|tools]', desc: 'Manage persistent Model Context Protocol connections', insert: '/mcp ' },
-  { name: '/ping', usage: '/ping', desc: 'Check active model server latency', insert: '/ping' },
   { name: '/config', usage: '/config', desc: 'Show runtime configuration', insert: '/config' },
+  { name: '/env', usage: '/env [init|set <KEY> <VALUE>|get <KEY>|unset <KEY>|path]', desc: 'Create and manage the local .env file (sets only the necessary values; the rest stays optional)', insert: '/env ' },
   { name: '/doctor', usage: '/doctor', desc: 'Check first-run environment and optional features', insert: '/doctor' },
   { name: '/prompt', usage: '/prompt', desc: 'Preview the active system persona', insert: '/prompt' },
-  { name: '/version', usage: '/version', desc: 'Show Kiku Agent version information', insert: '/version' },
   { name: '/system', usage: '/system', desc: 'Show operating-system and memory information', insert: '/system' },
   { name: '/gpu', usage: '/gpu [status]', desc: 'Show GPU & VRAM hardware resource metrics', insert: '/gpu' },
   { name: '/about', usage: '/about', desc: 'Show information about Kiku Agent', insert: '/about' },
@@ -59,8 +63,7 @@ export const COMMAND_DEFINITIONS = Object.freeze([
   { name: '/search', usage: '/search <query>', desc: 'Search YouTube', insert: '/search ' },
   { name: '/current', usage: '/current', desc: 'Show the current track', insert: '/current' },
   { name: '/queue', usage: '/queue [clear]', desc: 'Show or clear the active queue', insert: '/queue ' },
-  { name: '/web', usage: '/web [start|open|stop|status|restart] [port]', desc: 'Start or open the standalone chatbot web app (port 3300)', insert: '/web ' },
-  { name: '/web-chat', usage: '/web-chat [start|open|stop|status|restart] [port]', desc: 'Start or open the standalone chatbot web app (port 3300)', insert: '/web-chat ' },
+  { name: '/web', usage: '/web [start|open|stop|status|restart] [port]', desc: 'Start or open the standalone chatbot web app (port 3002)', insert: '/web ' },
   { name: '/login', usage: '/login', desc: 'Connect a YouTube browser session', insert: '/login' },
   { name: '/ytstatus', usage: '/ytstatus', desc: 'Show YouTube authentication status', insert: '/ytstatus' },
   { name: '/exit', usage: '/exit', desc: 'Archive the session and quit', insert: '/exit' },
@@ -73,25 +76,25 @@ export const COMMAND_CATEGORIES = Object.freeze([
     id: 'conversation',
     name: 'Conversation & Session',
     icon: '◆',
-    commands: ['/help', '/web', '/web-chat', '/session', '/history', '/details', '/copy', '/thinking', '/clear', '/save', '/retry', '/cancel', '/exit'],
+    commands: ['/help', '/web', '/session', '/history', '/details', '/copy', '/thinking', '/clear', '/save', '/retry', '/cancel', '/exit'],
   },
   {
     id: 'research',
     name: 'Research & Intelligence',
     icon: '✦',
-    commands: ['/research', '/subagent', '/verify', '/debate', '/suggestion', '/sources', '/jobs'],
+    commands: ['/research', '/subagent', '/verify', '/debate', '/suggestion', '/jobs'],
   },
   {
     id: 'catalog',
     name: 'Catalog, News & Memory',
     icon: '■',
-    commands: ['/find', '/compare', '/timeline', '/discover', '/favorites', '/news', '/stats', '/mem', '/skill'],
+    commands: ['/find', '/compare', '/timeline', '/discover', '/favorites', '/news', '/ingest', '/stats', '/mem', '/skill'],
   },
   {
     id: 'model',
     name: 'AI Model & MCP Connectivity',
     icon: '●',
-    commands: ['/provider', '/model', '/profile', '/mcp', '/ping', '/prompt', '/config'],
+    commands: ['/provider', '/lan', '/model', '/profile', '/mcp', '/prompt', '/config', '/env'],
   },
   {
     id: 'media',
@@ -103,32 +106,36 @@ export const COMMAND_CATEGORIES = Object.freeze([
     id: 'system',
     name: 'System, Theme & Developer Tools',
     icon: '◆',
-    commands: ['/doctor', '/system', '/gpu', '/version', '/theme', '/lang', '/quiz', '/key', '/about', '/tools', '/tool', '/ads'],
+    commands: ['/doctor', '/system', '/gpu', '/vram', '/eval', '/hub', '/portal', '/theme', '/lang', '/quiz', '/key', '/about', '/tools', '/tool', '/ads'],
   },
 ]);
 
 export const SUB_COMMANDS = Object.freeze({
-  '/help': ['find', 'web', 'provider', 'model', 'session', 'details', 'copy', 'mcp', 'mem', 'research', 'verify', 'suggestion', 'skill', 'theme', 'quiz', 'key', 'play', 'doctor'],
+  '/help': ['find', 'web', 'provider', 'model', 'session', 'details', 'copy', 'mcp', 'mem', 'research', 'verify', 'suggestion', 'skill', 'theme', 'quiz', 'key', 'play', 'doctor'],
   '/web': ['start', 'open', 'status', 'stop', 'restart', '3001'],
-  '/web-chat': ['start', 'open', 'status', 'stop', 'restart', '3001'],
   '/mem': ['add <fact>', 'search <query>', 'list', 'topics', 'summary', 'del <id>', 'import <path>', 'export', 'clear'],
   '/quiz': ['lang th', 'lang en', 'lang zh'],
   '/key': ['show', 'apply <key>', 'clear'],
   '/subagent': ['<research task>', 'status', 'last'],
-  '/research': ['<question>', 'status', 'last', 'sources', 'cancel'],
+  '/research': ['<question>', 'status', 'last', 'sources', 'auto on|off|status', 'cancel'],
   '/verify': ['<claim>'],
   '/debate': ['<claim>', 'status', 'last', 'cancel'],
   '/timeline': ['2026', '2024-2026', 'snh48', 'solo', 'studio', 'drama'],
-  '/sources': ['show'],
   '/suggestion': ['list', 'run 1', 'run all', 'auto', 'refresh', 'topic drama', 'topic music', 'topic fashion', 'topic 2026'],
   '/skill': ['learn <instruction>', 'list', 'del <id>', 'on', 'off', 'clear'],
   '/find': ['--type work', '--type song', '--type role', '--type brand', '--type award', '--type photo', '--type stage', '--year 2026', '--limit 8'],
   '/compare': ['<item-a> -- <item-b>', '<year-a> -- <year-b>', '--type work', '--type song'],
   '/favorites': ['list', 'list --type work', 'add <query>', 'add song <query>', 'suggest', 'remove <id>', 'export json', 'export markdown'],
   '/news': ['--days 7', '--days 30', '--official-only', '<topic> --days 14'],
+  '/ingest': ['status', 'run', 'add <text>', 'clear'],
   '/jobs': ['list', 'show <id>', 'cancel <id>', 'clear'],
   '/discover': ['drama', 'song', 'stage', 'photo', 'song --mood calm', 'stage --year 2025'],
-  '/stats': ['overview'],
+  '/stats': ['overview', 'tokens', 'session'],
+  '/vram': ['check <model_path_or_name> --ctx 8192 --quant q4_k_m', 'live', 'compare --ctx 16384', 'ctx --quant q4_k_m', 'list', 'tier'],
+  '/eval': ['ui', 'dashboard', 'validate', 'quick', 'run', 'judge', 'compare', 'gate', 'status'],
+  '/hub': ['', '<filter>'],
+  '/portal': ['open', 'api', 'chat', 'eval', 'status', '3000'],
+  '/env': ['init', 'set <KEY> <VALUE>', 'get <KEY>', 'unset <KEY>', 'path'],
   '/provider': [
     'list',
     'status',
@@ -167,14 +174,13 @@ export const SUB_COMMANDS = Object.freeze({
     'test deepseek',
     'test lmstudio'
   ],
-  '/model': ['status', 'list', 'recommend', 'use <model-id>', 'reconnect'],
+  '/model': ['status', 'ping', 'list', 'recommend', 'use <model-id>', 'reconnect'],
+  '/lan': ['scan', 'scan 192.168.0.0/24', 'scan 10.0.0.1-10.0.0.50 --ports 1234,8000', 'use <n>', 'json'],
   '/profile': ['list', 'use default', 'use fast', 'use deep-reasoning', 'use cloud', 'use gemini', 'show default', 'save <name>', 'delete <name>'],
   '/mcp': ['status', 'list', 'tools', 'connect <name> <url>', 'disconnect <name>', 'remove <name>', 'reconnect [all]', 'save', 'reload'],
-  '/ping': ['status'],
   '/config': ['status'],
   '/doctor': ['check'],
   '/prompt': ['show'],
-  '/version': ['show'],
   '/system': ['info'],
   '/gpu': ['status'],
   '/about': ['info'],
@@ -221,10 +227,10 @@ export const COMMAND_DETAILS = Object.freeze({
     examples: ['/help', '/help provider', '/help session', '/help research', '/help copy'],
   },
   '/web': {
-    summary: 'Launch or manage the dedicated standalone web chatbot on port 3300',
+    summary: 'Launch or manage the dedicated standalone web chatbot on port 3002',
     usage: '/web [start|open|stop|status|restart] [port]',
     subcommands: [
-      { cmd: 'start [port]', desc: 'Start standalone web chatbot server (default port 3300) and open browser', example: '/web start' },
+      { cmd: 'start [port]', desc: 'Start standalone web chatbot server (default port 3002) and open browser', example: '/web start' },
       { cmd: 'open', desc: 'Open current web chatbot URL in default browser', example: '/web open' },
       { cmd: 'status', desc: 'Check standalone web server running state and port', example: '/web status' },
       { cmd: 'stop', desc: 'Stop the standalone web chatbot server', example: '/web stop' },
@@ -232,18 +238,7 @@ export const COMMAND_DETAILS = Object.freeze({
     ],
     examples: ['/web', '/web open', '/web status', '/web stop'],
   },
-  '/web-chat': {
-    summary: 'Launch or manage the dedicated standalone web chatbot on port 3300 (alias for /web)',
-    usage: '/web-chat [start|open|stop|status|restart] [port]',
-    subcommands: [
-      { cmd: 'start [port]', desc: 'Start standalone web chatbot server (default port 3300) and open browser', example: '/web-chat start' },
-      { cmd: 'open', desc: 'Open current web chatbot URL in default browser', example: '/web-chat open' },
-      { cmd: 'status', desc: 'Check standalone web server running state and port', example: '/web-chat status' },
-      { cmd: 'stop', desc: 'Stop the standalone web chatbot server', example: '/web-chat stop' },
-      { cmd: 'restart', desc: 'Restart the standalone web chatbot server', example: '/web-chat restart' },
-    ],
-    examples: ['/web-chat', '/web-chat open', '/web-chat status', '/web-chat stop'],
-  },
+
   '/find': {
     summary: 'Search works, songs, roles, brands, awards, photos, and performances without an active chat model',
     usage: '/find <query> [--type <type>] [--year YYYY] [--limit 1-20]',
@@ -278,14 +273,28 @@ export const COMMAND_DETAILS = Object.freeze({
     examples: ['/favorites add In Blossom', '/favorites suggest', '/favorites list', '/favorites export json'],
   },
   '/news': {
-    summary: 'Search recent Ju Jingyi coverage and display source URLs with available dates',
-    usage: '/news [topic] [--days 1-90] [--official-only]',
+    summary: 'Find, rank, dedupe, and watch recent source-backed Ju Jingyi news (RSS + web fusion with recency ranking, source trust tiers, and topic tags)',
+    usage: '/news [topic] [--days 1-90] [--official-only] | watch <topic> [--every M] | check [topic] | watches',
     subcommands: [
-      { cmd: '[topic]', desc: 'Search recent news for an optional topic', example: '/news ซีรีส์ใหม่' },
+      { cmd: '[topic]', desc: 'Search recent news for an optional topic (recency-ranked, cross-language deduped, trust-tiered)', example: '/news ซีรีส์ใหม่' },
       { cmd: '--days N', desc: 'Set the recent-news window from 1 to 90 days', example: '/news Versace --days 30' },
       { cmd: '--official-only', desc: 'Keep results from supported official social and media hosts', example: '/news --days 14 --official-only' },
+      { cmd: 'watch <topic>', desc: 'Start a background watch job that polls the topic and prints new items as detected (SimHash delta)', example: '/news watch comeback --every 30' },
+      { cmd: 'check [topic]', desc: 'One-shot delta check against the last watch snapshot', example: '/news check' },
+      { cmd: 'watches', desc: 'List active news watch jobs', example: '/news watches' },
     ],
-    examples: ['/news', '/news drama --days 7', '/news --official-only'],
+    examples: ['/news', '/news drama --days 7', '/news --official-only', '/news watch comeback', '/news check'],
+  },
+  '/ingest': {
+    summary: 'Autonomous knowledge ingestion and dynamic catalog overlay manager',
+    usage: '/ingest [status | run [topic] | add <text> | clear]',
+    subcommands: [
+      { cmd: 'status', desc: 'Display statistics of dynamic catalog overlay (counts per category)', example: '/ingest status' },
+      { cmd: 'run [topic]', desc: 'Scan and autonomously ingest source-backed news and events for a topic', example: '/ingest run Lafang' },
+      { cmd: 'add <text>', desc: 'Extract and ingest an event or live stream from text directly into dynamic catalog', example: '/ingest add จวีจิ้งอี ไลฟ์สดงานแบรนด์ Lafang' },
+      { cmd: 'clear', desc: 'Clear all dynamic catalog overlay entries', example: '/ingest clear' },
+    ],
+    examples: ['/ingest status', '/ingest run', '/ingest run Lafang', '/ingest add จวีจิ้งอี ไลฟ์สด Douyin', '/ingest clear'],
   },
   '/jobs': {
     summary: 'Inspect, cancel, and clear tracked research, verification, subagent, and suggestion jobs',
@@ -374,6 +383,17 @@ export const COMMAND_DETAILS = Object.freeze({
       '/provider models',
     ],
   },
+  '/lan': {
+    summary: 'Discover LM Studio / vLLM / Ollama servers on the local network — auto or custom ranges — and switch to them',
+    usage: '/lan [scan [<cidr|range|ip>,...] [--ports p1,p2] | use <n> | json]',
+    subcommands: [
+      { cmd: 'scan', desc: 'Scan the private subnets of every local interface (plus 127.0.0.1) for OpenAI-compatible LM servers', example: '/lan scan' },
+      { cmd: 'scan <targets>', desc: 'Scan custom ranges: CIDR any prefix, IP range a.b.c.d-e.f.g.h, or single IPs, comma-separated (private ranges only, capped by KIKU_LAN_SCAN_MAX_HOSTS)', example: '/lan scan 192.168.0.0/24, 10.0.0.1-10.0.0.50 --ports 1234,8000' },
+      { cmd: 'use <n>', desc: 'Switch provider/baseUrl to a numbered endpoint from the last scan and connect to its first model', example: '/lan use 1' },
+      { cmd: 'json', desc: 'Print the last scan result as raw JSON', example: '/lan json' },
+    ],
+    examples: ['/lan', '/lan scan 192.168.0.0/24', '/lan scan 10.0.0.1-10.0.0.50 --ports 1234,8000', '/lan use 2', '/lan json'],
+  },
   '/key': {
     summary: 'Manage your Developer VIP API Key (earned via /quiz or custom seed)',
     usage: '/key [show | apply <key> | clear]',
@@ -393,6 +413,7 @@ export const COMMAND_DETAILS = Object.freeze({
     usage: '/model [status | list | recommend | use <model-id> | reconnect]',
     subcommands: [
       { cmd: 'status', desc: 'Display active model name, provider, latency, and context configuration', example: '/model status' },
+      { cmd: 'ping', desc: 'Ping the active model endpoint and report round-trip latency', example: '/model ping' },
       { cmd: 'list', desc: 'List models reported by the active provider or local LM Studio instance', example: '/model list' },
       { cmd: 'use <model-id>', desc: 'Switch active model immediately without restarting the agent', example: '/model use google/gemma-4-e4b' },
       { cmd: 'recommend', desc: 'Show curated model recommendations optimized for Ju Jingyi knowledge tasks', example: '/model recommend' },
@@ -414,6 +435,7 @@ export const COMMAND_DETAILS = Object.freeze({
       { cmd: 'status', desc: 'Check status of running background research workers', example: '/research status' },
       { cmd: 'last', desc: 'Display synthesized findings from the latest research job', example: '/research last' },
       { cmd: 'sources', desc: 'List all validated URLs and citations collected during research', example: '/research sources' },
+      { cmd: 'auto on|off|status', desc: 'Control automatic deep research on complex questions (on = aggressive, auto = smart heuristic, off = model decides)', example: '/research auto on' },
       { cmd: 'cancel', desc: 'Cancel the currently active research job', example: '/research cancel' },
     ],
     examples: [
@@ -433,14 +455,7 @@ export const COMMAND_DETAILS = Object.freeze({
       '/verify Ju Jingyi will star in a new 2026 historical drama',
     ],
   },
-  '/sources': {
-    summary: 'Display full citation list, verified URLs, and media links from the most recent research job',
-    usage: '/sources',
-    subcommands: [
-      { cmd: '', desc: 'Show all citations, reference domains, and validated external sources from the latest research', example: '/sources' },
-    ],
-    examples: ['/sources'],
-  },
+
   '/quiz': {
     summary: 'Interactive 15-question Ju Jingyi quiz to claim a Developer VIP Key (1,000 req/min)',
     usage: '/quiz [lang <th|en|zh>]',
@@ -698,20 +713,28 @@ export const COMMAND_DETAILS = Object.freeze({
   },
   '/stats': {
     summary: 'Show comprehensive content metrics, database records, and catalog statistics',
-    usage: '/stats',
+    usage: '/stats [overview|tokens]',
     subcommands: [
       { cmd: '', desc: 'Display total counts for dramas, discography, brands, awards, and gallery photos', example: '/stats' },
+      { cmd: 'tokens', desc: 'Session token telemetry: counters, throughput, TTFT and ITL percentiles', example: '/stats tokens' },
     ],
-    examples: ['/stats'],
+    examples: ['/stats', '/stats tokens'],
   },
-  '/ping': {
-    summary: 'Measure live network latency and responsiveness to active LLM inference server',
-    usage: '/ping',
+  '/vram': {
+    summary: 'Predictive VRAM analyzer: weights, KV cache, activation workspace and runtime overhead against detected GPU memory — plus live usage, quantization and context ladders',
+    usage: '/vram [check <model_path_or_name>|live|compare|ctx|list|tier] [--ctx <len>] [--quant <type>] [--force]',
     subcommands: [
-      { cmd: '', desc: 'Send ping request to active AI model endpoint and report round-trip latency in ms', example: '/ping' },
+      { cmd: '', desc: 'Analyze the currently selected model against detected hardware', example: '/vram' },
+      { cmd: 'check <model_path_or_name>', desc: 'Evaluate a target model/config before loading it', example: '/vram check Qwen2.5-Coder-32B-Instruct-Q4_K_M.gguf --ctx 16384' },
+      { cmd: 'live', desc: 'Show live VRAM usage right now vs. the current model footprint (LM Studio runtime ctx)', example: '/vram live' },
+      { cmd: 'compare', desc: 'Table of every quantization (FP16 to Q2_K) and its feasibility at one context', example: '/vram compare --ctx 16384' },
+      { cmd: 'ctx', desc: 'Context ladder (2k to 262k): how far you can push context at the chosen quant', example: '/vram ctx --quant q4_k_m' },
+      { cmd: 'list', desc: 'List built-in registry architectures with tool/vision/reasoning tags', example: '/vram list' },
+      { cmd: 'tier', desc: 'Inspect GPU hardware tier, memory bus width, and architecture classification', example: '/vram tier' },
     ],
-    examples: ['/ping'],
+    examples: ['/vram', '/vram live', '/vram tier', '/vram compare --ctx 16384', '/vram ctx', '/vram check qwen2.5-7b-instruct --ctx 8192 --quant q4_k_m'],
   },
+
   '/config': {
     summary: 'Display current runtime configuration, active profile, provider, paths, and environment settings',
     usage: '/config',
@@ -720,6 +743,19 @@ export const COMMAND_DETAILS = Object.freeze({
     ],
     examples: ['/config'],
   },
+  '/env': {
+    summary: 'Create and manage the local .env file for global npm installs — only necessary values are set, optional ones stay commented',
+    usage: '/env [init|set <KEY> <VALUE>|get <KEY>|unset <KEY>|path]',
+    subcommands: [
+      { cmd: '', desc: 'Show .env location, LM Studio reachability, and which variables are set (secrets masked)', example: '/env' },
+      { cmd: 'init', desc: 'Interactive wizard: writes .env with necessary values auto-detected from the running LM Studio', example: '/env init' },
+      { cmd: 'set <KEY> <VALUE>', desc: 'Insert or replace one variable, preserving comments', example: '/env set KIKU_CONTEXT_LIMIT 32768' },
+      { cmd: 'get <KEY>', desc: 'Show one variable (API keys/cookies are masked)', example: '/env get LMSTUDIO_BASE_URL' },
+      { cmd: 'unset <KEY>', desc: 'Remove a variable from the file', example: '/env unset KIKU_VRAM_TOTAL_GB' },
+      { cmd: 'path', desc: 'Print the active .env path and the user-level fallback', example: '/env path' },
+    ],
+    examples: ['/env', '/env init', '/env set KIKU_CONTEXT_LIMIT 131072', '/env path'],
+  },
   '/profile': {
     summary: 'Manage AI configuration profiles (default, fast, deep-reasoning, cloud, gemini)',
     usage: '/profile [list | use <name> | show <name> | save <name> | delete <name>]',
@@ -748,14 +784,7 @@ export const COMMAND_DETAILS = Object.freeze({
     ],
     examples: ['/prompt'],
   },
-  '/version': {
-    summary: 'Display installed Kiku Agent release version, build channel, and package metadata',
-    usage: '/version',
-    subcommands: [
-      { cmd: '', desc: 'Show semantic version, git commit, Node runtime version, and release channel', example: '/version' },
-    ],
-    examples: ['/version'],
-  },
+
   '/system': {
     summary: 'Display host operating system, CPU architecture, memory usage, and Node process stats',
     usage: '/system',
@@ -932,6 +961,43 @@ export const COMMAND_DETAILS = Object.freeze({
     ],
     examples: ['/exit'],
   },
+  '/eval': {
+    summary: 'Manage evaluation studio, benchmark suites, and performance validation dashboards',
+    usage: '/eval [ui|dashboard|validate|quick|run|judge|compare|gate|status]',
+    subcommands: [
+      { cmd: 'ui', desc: 'Launch or open interactive Eval Studio web UI on port 3000 (/eval)', example: '/eval ui' },
+      { cmd: 'dashboard', desc: 'Generate mobile-responsive HTML evaluation report and open in browser', example: '/eval dashboard' },
+      { cmd: 'validate', desc: 'Validate all 500 benchmark cases without running live models', example: '/eval validate' },
+      { cmd: 'quick', desc: 'Run 3-case quick live evaluation smoke test against active model', example: '/eval quick' },
+      { cmd: 'run', desc: 'Run full frozen 500-case evaluation suite', example: '/eval run' },
+      { cmd: 'judge', desc: 'Judge recorded run results against frozen reference ground truth', example: '/eval judge' },
+      { cmd: 'compare', desc: 'Compare candidate evaluation run against baseline run', example: '/eval compare' },
+      { cmd: 'gate', desc: 'Evaluate quality gating metrics against pass/fail threshold', example: '/eval gate' },
+      { cmd: 'status', desc: 'Show latest evaluation runs and recorded report status', example: '/eval status' },
+    ],
+    examples: ['/eval ui', '/eval dashboard', '/eval validate', '/eval quick'],
+  },
+  '/hub': {
+    summary: 'Display Kiku Master Command Center hub with hardware telemetry, system metrics, and command index',
+    usage: '/hub [filter]',
+    subcommands: [
+      { cmd: '', desc: 'Render full Master Command Center hub dashboard in terminal', example: '/hub' },
+      { cmd: '<filter>', desc: 'Render hub filtering commands by category or keyword', example: '/hub system' },
+    ],
+    examples: ['/hub', '/hub system', '/hub media', '/hub research'],
+  },
+  '/portal': {
+    summary: 'Inspect or open local portal, REST API v1 documentation, Web Chat, or Eval Studio (port 3000)',
+    usage: '/portal [open|api|chat|eval|status] [port]',
+    subcommands: [
+      { cmd: 'open', desc: 'Open Fan Portal SPA home page in default browser', example: '/portal open' },
+      { cmd: 'api', desc: 'Open REST API v1 interactive documentation (/api-docs)', example: '/portal api' },
+      { cmd: 'chat', desc: 'Open Luxury Web Chat interface (/chat)', example: '/portal chat' },
+      { cmd: 'eval', desc: 'Open Eval Studio dashboard (/eval)', example: '/portal eval' },
+      { cmd: 'status', desc: 'Check Port 3000 in-process dev server status and endpoints', example: '/portal status' },
+    ],
+    examples: ['/portal', '/portal open', '/portal api', '/portal chat', '/portal eval'],
+  },
 });
 
 export function findCommandDefinition(name) {