kiku-agent 1.0.4 → 1.0.6

package/server/agent/commandRegistry.js

@@ -1,74 +1,436 @@
-export const COMMAND_DEFINITIONS = Object.freeze([
-  { name: '/help', usage: '/help [command]', desc: 'Show all commands or details for one command', insert: '/help ' },
-  { name: '/history', usage: '/history [n|search|clear]', desc: 'View or search chat history', insert: '/history ' },
-  { name: '/session', usage: '/session [info|list|export|clear]', desc: 'Manage the current session', insert: '/session ' },
-  { name: '/thinking', usage: '/thinking [show|hide|toggle]', desc: 'Control reasoning visibility', insert: '/thinking ' },
-  { name: '/details', usage: '/details [Qn]', desc: 'Expand thinking and tool details (F2 opens latest)', insert: '/details ' },
-  { name: '/lang', usage: '/lang [th|zh|en|auto]', desc: 'Set the response language', insert: '/lang ' },
-  { name: '/theme', usage: '/theme [name|list|current|reset]', desc: 'View or change the terminal color theme', insert: '/theme ' },
-  { name: '/mem', usage: '/mem [add|del|search|list|topics|import|export|clear]', desc: 'Manage long-term memory', insert: '/mem ' },
-  { 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: '/skill', usage: '/skill [learn|list|del|on|off|clear]', desc: 'Teach Kiku how to answer for you', insert: '/skill ' },
-  { name: '/tool', usage: '/tool <name> [args]', desc: 'Execute a registered tool directly', insert: '/tool ' },
-  { name: '/tools', usage: '/tools [filter]', desc: 'List registered tools', insert: '/tools ' },
-  { name: '/stats', usage: '/stats', desc: 'Show the content database overview', insert: '/stats' },
-  { name: '/provider', usage: '/provider [list|use <name> [model]|models [name]|info <name>|test|setkey <key>|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: '/mcp', usage: '/mcp [status|list|connect <name> <url|cmd>|disconnect <name>|tools]', desc: 'Manage external 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: '/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' },
-  { name: '/ads', usage: '/ads', desc: 'Show the next sponsor card', insert: '/ads' },
-  { name: '/retry', usage: '/retry', desc: 'Retry the previous query', insert: '/retry' },
-  { name: '/clear', usage: '/clear', desc: 'Archive the session and clear the screen', insert: '/clear' },
-  { name: '/save', usage: '/save', desc: 'Export the transcript to Markdown', insert: '/save' },
-  { name: '/play', usage: '/play <song>', desc: 'Play music', insert: '/play ' },
-  { name: '/stop', usage: '/stop', desc: 'Stop music playback', insert: '/stop' },
-  { name: '/pause', usage: '/pause', desc: 'Pause music playback', insert: '/pause' },
-  { name: '/resume', usage: '/resume', desc: 'Resume music playback', insert: '/resume' },
-  { name: '/next', usage: '/next', desc: 'Play the next queued track', insert: '/next' },
-  { name: '/prev', usage: '/prev', desc: 'Return to the previous track', insert: '/prev' },
-  { name: '/mute', usage: '/mute', desc: 'Mute music playback', insert: '/mute' },
-  { name: '/unmute', usage: '/unmute', desc: 'Unmute music playback', insert: '/unmute' },
-  { name: '/add', usage: '/add <song>', desc: 'Add a song to the music queue', insert: '/add ' },
-  { name: '/remove', usage: '/remove <index>', desc: 'Remove a song from the music queue', insert: '/remove ' },
-  { name: '/clearqueue', usage: '/clearqueue', desc: 'Clear the music queue', insert: '/clearqueue' },
-  { 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: '/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' },
-]);
-
-export const COMMAND_NAMES = Object.freeze(COMMAND_DEFINITIONS.map(command => command.name));
-
-export const SUB_COMMANDS = Object.freeze({
-  '/mem': ['add <fact>', 'search <query>', 'list', 'topics', 'del <id>', 'import <path>', 'export', 'clear'],
-  '/subagent': ['<research task>'],
-  '/research': ['<question>', 'status', 'last', 'sources', 'cancel'],
-  '/verify': ['<claim>'],
-  '/skill': ['learn <instruction>', 'list', 'del <id>', 'on', 'off', 'clear'],
-  '/provider': ['list', 'status', 'models', 'models openai', 'models gemini', 'models groq', 'models deepseek', 'models openrouter', 'models lmstudio', 'use openai', 'use openrouter', 'use groq', 'use deepseek', 'use gemini', 'use lmstudio', 'use custom', 'info', 'test', 'setkey <key>'],
-  '/model': ['status', 'list', 'recommend', 'use <model-id>', 'reconnect'],
-  '/mcp': ['status', 'list', 'tools', 'connect <name> <url>', 'disconnect <name>'],
-  '/lang': ['th', 'zh', 'en', 'auto'],
-  '/theme': ['list', 'current', 'sakura', 'midnight', 'ocean', 'forest', 'sunset', 'monochrome', 'reset'],
-  '/thinking': ['show', 'hide', 'toggle'],
-  '/session': ['info', 'list', 'export', 'clear'],
-  '/history': ['10', '20', '50', 'search <query>', 'clear'],
-  '/queue': ['clear'],
-});
-
-export function findCommandDefinition(name) {
-  const normalized = name?.startsWith('/') ? name.toLowerCase() : `/${String(name || '').toLowerCase()}`;
-  return COMMAND_DEFINITIONS.find(command => command.name === normalized) || null;
-}
+export const COMMAND_DEFINITIONS = Object.freeze([
+  { name: '/help', usage: '/help [command]', desc: 'Show all commands or details for one command', insert: '/help ' },
+  { name: '/history', usage: '/history [n|search|clear]', desc: 'View or search chat history', insert: '/history ' },
+  { name: '/session', usage: '/session [info|list|export|clear]', desc: 'Manage the current session', insert: '/session ' },
+  { name: '/thinking', usage: '/thinking [show|hide|toggle]', desc: 'Control reasoning visibility', insert: '/thinking ' },
+  { name: '/details', usage: '/details [Qn] [overview|answer|thinking|tools|tool n]', desc: 'Inspect query diagnostics (F2 opens latest overview)', insert: '/details ' },
+  { name: '/copy', usage: '/copy [Qn] [answer|thinking|tools|tool n|all|markdown]', desc: 'Copy full untruncated model answer, thinking, or diagnostics to clipboard', insert: '/copy ' },
+  { name: '/lang', usage: '/lang [th|zh|en|auto]', desc: 'Set the response language', insert: '/lang ' },
+  { name: '/theme', usage: '/theme [name|list|current|reset]', desc: 'View or change the terminal color theme', insert: '/theme ' },
+  { name: '/mem', usage: '/mem [add|del|search|list|topics|import|export|clear]', desc: 'Manage long-term memory', insert: '/mem ' },
+  { 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: '/suggestion', usage: '/suggestion [list|run <id|all>|auto|refresh|topic <name>]', desc: 'Generate AI research suggestions & execute with concurrent subagents', insert: '/suggestion ' },
+  { name: '/skill', usage: '/skill [learn|list|del|on|off|clear]', desc: 'Teach Kiku how to answer for you', insert: '/skill ' },
+  { name: '/tool', usage: '/tool <name> [args]', desc: 'Execute a registered tool directly', insert: '/tool ' },
+  { name: '/tools', usage: '/tools [filter]', desc: 'List registered tools', insert: '/tools ' },
+  { name: '/stats', usage: '/stats', desc: 'Show the content database overview', insert: '/stats' },
+  { name: '/provider', usage: '/provider [list|use <name> [model]|models [name]|info <name>|test|setkey <key>|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: '/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: '/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: '/update', usage: '/update [check|install [target]|channel [name]|rollback]', desc: 'Check, install, configure, or roll back npm releases', insert: '/update ' },
+  { 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' },
+  { name: '/ads', usage: '/ads', desc: 'Show the next sponsor card', insert: '/ads' },
+  { name: '/retry', usage: '/retry', desc: 'Retry the previous query', insert: '/retry' },
+  { name: '/cancel', usage: '/cancel', desc: 'Abort the currently running query, tool, or subagent task', insert: '/cancel' },
+  { name: '/clear', usage: '/clear', desc: 'Archive the session and clear the screen', insert: '/clear' },
+  { name: '/save', usage: '/save', desc: 'Export the transcript to Markdown', insert: '/save' },
+  { name: '/play', usage: '/play <song>', desc: 'Play music', insert: '/play ' },
+  { name: '/stop', usage: '/stop', desc: 'Stop music playback', insert: '/stop' },
+  { name: '/pause', usage: '/pause', desc: 'Pause music playback', insert: '/pause' },
+  { name: '/resume', usage: '/resume', desc: 'Resume music playback', insert: '/resume' },
+  { name: '/next', usage: '/next', desc: 'Play the next queued track', insert: '/next' },
+  { name: '/prev', usage: '/prev', desc: 'Return to the previous track', insert: '/prev' },
+  { name: '/mute', usage: '/mute', desc: 'Mute music playback', insert: '/mute' },
+  { name: '/unmute', usage: '/unmute', desc: 'Unmute music playback', insert: '/unmute' },
+  { name: '/add', usage: '/add <song>', desc: 'Add a song to the music queue', insert: '/add ' },
+  { name: '/remove', usage: '/remove <index>', desc: 'Remove a song from the music queue', insert: '/remove ' },
+  { name: '/clearqueue', usage: '/clearqueue', desc: 'Clear the music queue', insert: '/clearqueue' },
+  { 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: '/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' },
+]);
+
+export const COMMAND_NAMES = Object.freeze(COMMAND_DEFINITIONS.map(command => command.name));
+
+export const SUB_COMMANDS = Object.freeze({
+  '/mem': ['add <fact>', 'search <query>', 'list', 'topics', 'del <id>', 'import <path>', 'export', 'clear'],
+  '/subagent': ['<research task>'],
+  '/research': ['<question>', 'status', 'last', 'sources', 'cancel'],
+  '/verify': ['<claim>'],
+  '/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'],
+  '/provider': ['list', 'status', 'models', 'models openai', 'models gemini', 'models groq', 'models deepseek', 'models openrouter', 'models lmstudio', 'use openai', 'use openrouter', 'use groq', 'use deepseek', 'use gemini', 'use lmstudio', 'use custom', 'info', 'test', 'setkey <key>'],
+  '/model': ['status', 'list', 'recommend', 'use <model-id>', 'reconnect'],
+  '/mcp': ['status', 'list', 'tools', 'connect <name> <url>', 'disconnect <name>', 'remove <name>', 'reconnect [all]', 'save', 'reload'],
+  '/lang': ['th', 'zh', 'en', 'auto'],
+  '/theme': ['list', 'current', 'sakura', 'midnight', 'ocean', 'forest', 'sunset', 'monochrome', 'reset'],
+  '/thinking': ['show', 'hide', 'toggle'],
+  '/details': ['latest', 'overview', 'answer', 'thinking', 'tools', 'tool <n>', 'all', 'markdown', 'Q1 overview', 'Q1 tool 1'],
+  '/copy': ['answer', 'thinking', 'tools', 'tool 1', 'overview', 'all', 'markdown', 'Q1 answer', 'Q1 thinking', 'Q1 all'],
+  '/session': ['info', 'list', 'export', 'clear'],
+  '/history': ['10', '20', '50', 'search <query>', 'clear'],
+  '/queue': ['clear'],
+  '/update': ['check', 'install', 'install next', 'install canary', 'channel', 'channel latest', 'channel next', 'channel canary', 'rollback', 'help'],
+});
+
+export const COMMAND_DETAILS = Object.freeze({
+  '/suggestion': {
+    summary: 'Generate AI research suggestions & execute with concurrent subagents',
+    usage: '/suggestion [list | run <id|ids|all> | auto | topic <name> | refresh]',
+    subcommands: [
+      { cmd: 'list', desc: 'Display generated research suggestions and categories (default)', example: '/suggestion list' },
+      { cmd: 'run <id|ids|all>', desc: 'Dispatch concurrent subagent workers to research the selected questions in parallel', example: '/suggestion run 1,2,3' },
+      { cmd: 'auto', desc: 'Auto-generate fresh research topics and immediately dispatch parallel subagents', example: '/suggestion auto' },
+      { cmd: 'topic <name>', desc: 'Generate research questions tailored to a specific topic (drama, music, brand, awards, 2026)', example: '/suggestion topic drama' },
+      { cmd: 'refresh', desc: 'Re-roll and generate a fresh batch of 5 suggestion topics', example: '/suggestion refresh' },
+    ],
+    examples: [
+      '/suggestion',
+      '/suggestion run 1',
+      '/suggestion run 1,2,3',
+      '/suggestion run all',
+      '/suggestion auto',
+      '/suggestion topic 2026',
+    ],
+  },
+  '/mcp': {
+    summary: 'Manage persistent Model Context Protocol (MCP) server connections and external tools',
+    usage: '/mcp [status | list | connect <name> <url|stdio> | disconnect <name> | remove <name> | reconnect [all] | save [workspace|global] | reload | tools]',
+    subcommands: [
+      { cmd: 'status / list', desc: 'Display active live MCP servers, saved offline configurations, and registered tool counts', example: '/mcp status' },
+      { cmd: 'connect <name> <url|cmd>', desc: 'Connect and permanently save an MCP server config (auto-reconnects on startup)', example: '/mcp connect kiku https://jujingyi-kikuuu.vercel.app/mcp' },
+      { cmd: 'save [workspace|global]', desc: 'Explicitly save all MCP configurations to workspace (.mcp.json) or global storage', example: '/mcp save workspace' },
+      { cmd: 'reload / reconnect [name|all]', desc: 'Reload and reconnect all configured MCP servers from disk', example: '/mcp reconnect all' },
+      { cmd: 'disconnect <name>', desc: 'Disconnect the active live session while keeping the configuration saved for later', example: '/mcp disconnect kiku' },
+      { cmd: 'remove <name>', desc: 'Permanently remove the server from saved configuration and disconnect', example: '/mcp remove kiku' },
+      { cmd: 'tools', desc: 'Inspect all registered MCP tools, parameters, and input schemas', example: '/mcp tools' },
+    ],
+    examples: [
+      '/mcp status',
+      '/mcp connect kiku https://jujingyi-kikuuu.vercel.app/mcp',
+      '/mcp connect local stdio node ./server/mcp/stdio.js',
+      '/mcp tools',
+      '/mcp save workspace',
+      '/mcp reconnect all',
+    ],
+  },
+  '/provider': {
+    summary: 'Manage AI model providers (OpenAI, Gemini, Groq, DeepSeek, OpenRouter, LM Studio)',
+    usage: '/provider [list | status | use <name> [model] | models [name] | info <name> | test | setkey <key>]',
+    subcommands: [
+      { cmd: 'list', desc: 'List all supported providers, availability, and active status', example: '/provider list' },
+      { cmd: 'status', desc: 'Show detailed connection metrics, latency, and credentials for active provider', example: '/provider status' },
+      { cmd: 'use <name> [model]', desc: 'Switch active AI provider and optionally specify initial model', example: '/provider use gemini gemini-2.5-flash' },
+      { cmd: 'models [name]', desc: 'Fetch live model catalog from the specified or active provider API', example: '/provider models groq' },
+      { cmd: 'setkey <key>', desc: 'Configure and persist API key for the active provider', example: '/provider setkey sk-...' },
+      { cmd: 'test', desc: 'Perform a lightweight ping/test call to verify provider responsiveness', example: '/provider test' },
+      { cmd: 'info <name>', desc: 'Show pricing, context window, token limits, and documentation for a provider', example: '/provider info deepseek' },
+    ],
+    examples: [
+      '/provider list',
+      '/provider use gemini',
+      '/provider use openai gpt-4o-mini',
+      '/provider setkey YOUR_API_KEY',
+      '/provider models',
+    ],
+  },
+  '/model': {
+    summary: 'Inspect, recommend, or switch active AI model',
+    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: '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' },
+      { cmd: 'reconnect', desc: 'Reconnect to the local or cloud model server and verify availability', example: '/model reconnect' },
+    ],
+    examples: [
+      '/model status',
+      '/model list',
+      '/model recommend',
+      '/model use gemma-4-e4b',
+      '/model reconnect',
+    ],
+  },
+  '/research': {
+    summary: 'Run coordinated multi-source Ju Jingyi research (3 parallel subagents: catalog, web, verifier)',
+    usage: '/research <question | status | last | sources | cancel>',
+    subcommands: [
+      { cmd: '<question>', desc: 'Launch multi-worker deep research across local database and web sources', example: '/research ผลงานซีรีส์ปี 2026 ของจวีจิ้งอี' },
+      { 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: 'cancel', desc: 'Cancel the currently active research job', example: '/research cancel' },
+    ],
+    examples: [
+      '/research What are Ju Jingyi\'s 2026 drama projects?',
+      '/research status',
+      '/research sources',
+    ],
+  },
+  '/verify': {
+    summary: 'Verify a Ju Jingyi claim or rumor with independent workers across official catalog & web sources',
+    usage: '/verify <claim about Ju Jingyi>',
+    subcommands: [
+      { cmd: '<claim>', desc: 'Run multi-worker verification to produce a strict verdict (VERIFIED, UNVERIFIED, CONFLICTING, FALSE)', example: '/verify จวีจิ้งอีเป็น Brand Ambassador ของ Versace ในปี 2026' },
+    ],
+    examples: [
+      '/verify จวีจิ้งอีชนะเลือกตั้ง SNH48 สองสมัยซ้อน',
+      '/verify Ju Jingyi will star in a new 2026 historical drama',
+    ],
+  },
+  '/subagent': {
+    summary: 'Spawn an isolated iterative research subagent to investigate a specific task or subtopic',
+    usage: '/subagent <task | status | last | tools>',
+    subcommands: [
+      { cmd: '<task>', desc: 'Dispatch dedicated bounded subagent with iterative tool execution', example: '/subagent Search all OST songs sung by Ju Jingyi in 2024-2026' },
+      { cmd: 'status / last', desc: 'Inspect tool calls and synthesized evidence from the previous subagent', example: '/subagent status' },
+    ],
+    examples: [
+      '/subagent Explore Versace brand ambassadorship milestones',
+      '/subagent status',
+    ],
+  },
+  '/mem': {
+    summary: 'Manage long-term semantic memory and persistent facts',
+    usage: '/mem [list | add <fact> | search <query> | topics | del <id> | import <path> | export | clear]',
+    subcommands: [
+      { cmd: 'list', desc: 'View all stored long-term memory facts', example: '/mem list' },
+      { cmd: 'add <fact>', desc: 'Store a verified fact directly into persistent memory', example: '/mem add จวีจิ้งอีเกิดวันที่ 18 มิถุนายน 1994' },
+      { cmd: 'search <query>', desc: 'Search stored memory facts using relevance ranking', example: '/mem search Versace' },
+      { cmd: 'topics', desc: 'View list of categorized memory topics', example: '/mem topics' },
+      { cmd: 'del <id>', desc: 'Delete a specific memory entry by ID', example: '/mem del m_123' },
+      { cmd: 'export', desc: 'Export memory facts to JSON file', example: '/mem export' },
+      { cmd: 'import <path>', desc: 'Import memory facts from a JSON file', example: '/mem import ./facts.json' },
+      { cmd: 'clear', desc: 'Wipe all long-term memory facts', example: '/mem clear' },
+    ],
+    examples: [
+      '/mem list',
+      '/mem add ผู้ใช้ชื่นชอบซีรีส์ In Blossom เป็นพิเศษ',
+      '/mem search In Blossom',
+    ],
+  },
+  '/skill': {
+    summary: 'Teach Kiku custom persona rules and response preferences',
+    usage: '/skill [learn <instruction> | list | on | off | del <id> | clear]',
+    subcommands: [
+      { cmd: 'learn <instruction>', desc: 'Teach Kiku how to format responses or adapt tone', example: '/skill learn ตอบภาษาไทยแบบสุภาพและกระชับเสมอ' },
+      { cmd: 'list', desc: 'List all active learned skills and their IDs', example: '/skill list' },
+      { cmd: 'on / off', desc: 'Enable or disable learned skills globally', example: '/skill off' },
+      { cmd: 'del <id>', desc: 'Remove a specific learned skill by ID', example: '/skill del s_123' },
+      { cmd: 'clear', desc: 'Delete all custom learned skills', example: '/skill clear' },
+    ],
+    examples: [
+      '/skill learn ตอบภาษาไทยและลงท้ายด้วยค่ะเสมอ',
+      '/skill list',
+    ],
+  },
+  '/details': {
+    summary: 'Inspect deep diagnostics, tool timeline, and token metrics for queries',
+    usage: '/details [Qn] [overview | answer | thinking | tools | tool <n> | all | markdown]',
+    subcommands: [
+      { cmd: 'overview / [Qn]', desc: 'View summary of duration, iterations, token counts, and tool timeline (Press F2 for latest)', example: '/details Q1' },
+      { cmd: 'answer', desc: 'View the complete untruncated final answer', example: '/details answer' },
+      { cmd: 'thinking', desc: 'Inspect raw chain-of-thought and model reasoning', example: '/details thinking' },
+      { cmd: 'tools', desc: 'List all tool calls executed during query processing', example: '/details tools' },
+      { cmd: 'tool <n>', desc: 'Inspect exact arguments and raw return payload for tool call N', example: '/details tool 1' },
+      { cmd: 'all / markdown', desc: 'View full formatted Markdown transcript of the query', example: '/details all' },
+    ],
+    examples: [
+      '/details',
+      '/details Q1 overview',
+      '/details Q1 tool 1',
+      '/details all',
+    ],
+  },
+  '/copy': {
+    summary: 'Copy complete untruncated model answer, thinking trace, tools, or markdown to system clipboard',
+    usage: '/copy [Qn] [answer | thinking | tools | tool <n> | all | markdown | overview]',
+    subcommands: [
+      { cmd: '[Qn] [answer]', desc: 'Copy complete untruncated model answer to system clipboard (default)', example: '/copy' },
+      { cmd: 'thinking', desc: 'Copy raw chain-of-thought and model reasoning', example: '/copy thinking' },
+      { cmd: 'tools', desc: 'Copy JSON tool executions and arguments', example: '/copy tools' },
+      { cmd: 'tool <n>', desc: 'Copy raw JSON result of specific tool call N', example: '/copy tool 1' },
+      { cmd: 'all / markdown', desc: 'Copy entire Q&A transcript in clean Markdown format', example: '/copy all' },
+      { cmd: 'overview', desc: 'Copy diagnostic overview and metadata', example: '/copy overview' },
+    ],
+    examples: [
+      '/copy',
+      '/copy thinking',
+      '/copy Q2 answer',
+      '/copy tool 1',
+      '/copy all',
+    ],
+  },
+  '/theme': {
+    summary: 'View or switch the terminal color theme dynamically',
+    usage: '/theme [sakura | midnight | ocean | forest | sunset | monochrome | list | current | reset]',
+    subcommands: [
+      { cmd: 'list', desc: 'Preview all available color theme palettes and descriptions', example: '/theme list' },
+      { cmd: 'current', desc: 'Show currently active theme and color samples', example: '/theme current' },
+      { cmd: '<name>', desc: 'Switch theme instantly (sakura, midnight, ocean, forest, sunset, monochrome)', example: '/theme midnight' },
+      { cmd: 'reset', desc: 'Reset to default theme (sakura)', example: '/theme reset' },
+    ],
+    examples: [
+      '/theme list',
+      '/theme midnight',
+      '/theme ocean',
+      '/theme monochrome',
+    ],
+  },
+  '/update': {
+    summary: 'Check, install, configure, or roll back npm package releases for kiku-agent',
+    usage: '/update [check | install [target] | channel [name] | rollback | help]',
+    subcommands: [
+      { cmd: 'check', desc: 'Check npm registry for newer versions across release channels', example: '/update check' },
+      { cmd: 'install [target]', desc: 'Install latest version or specific tag (next, canary, exact version)', example: '/update install' },
+      { cmd: 'channel [name]', desc: 'Switch release channel (latest, next, canary)', example: '/update channel next' },
+      { cmd: 'rollback', desc: 'Revert to the previously installed package version', example: '/update rollback' },
+    ],
+    examples: [
+      '/update check',
+      '/update install',
+      '/update channel next',
+      '/update rollback',
+    ],
+  },
+  '/session': {
+    summary: 'Manage current conversation session, storage, and snapshots',
+    usage: '/session [info | list | export | clear]',
+    subcommands: [
+      { cmd: 'info', desc: 'Display session ID, active duration, message count, and turn stats', example: '/session info' },
+      { cmd: 'list', desc: 'List all saved conversation sessions on disk', example: '/session list' },
+      { cmd: 'export', desc: 'Export full conversation session history to JSON', example: '/session export' },
+      { cmd: 'clear', desc: 'Archive current conversation session and reset history', example: '/session clear' },
+    ],
+    examples: [
+      '/session info',
+      '/session list',
+      '/session clear',
+    ],
+  },
+  '/history': {
+    summary: 'View or search recent chat message history',
+    usage: '/history [count | search <query> | clear]',
+    subcommands: [
+      { cmd: '[n]', desc: 'Display the last N messages (default: 20)', example: '/history 10' },
+      { cmd: 'search <query>', desc: 'Search messages in current session history', example: '/history search In Blossom' },
+      { cmd: 'clear', desc: 'Clear in-memory conversation history', example: '/history clear' },
+    ],
+    examples: [
+      '/history',
+      '/history 50',
+      '/history search drama',
+    ],
+  },
+  '/thinking': {
+    summary: 'Control reasoning and chain-of-thought visibility during generation',
+    usage: '/thinking [show | hide | toggle]',
+    subcommands: [
+      { cmd: 'show', desc: 'Display live model reasoning process in real time', example: '/thinking show' },
+      { cmd: 'hide', desc: 'Hide thinking process and display only final answers', example: '/thinking hide' },
+      { cmd: 'toggle', desc: 'Toggle thinking display mode on/off', example: '/thinking toggle' },
+    ],
+    examples: [
+      '/thinking show',
+      '/thinking hide',
+      '/thinking toggle',
+    ],
+  },
+  '/lang': {
+    summary: 'Set response language for AI synthesis',
+    usage: '/lang [th | zh | en | auto]',
+    subcommands: [
+      { cmd: 'th', desc: 'Set response language to Thai (ค่ะ/นะคะ)', example: '/lang th' },
+      { cmd: 'zh', desc: 'Set response language to Chinese (中文)', example: '/lang zh' },
+      { cmd: 'en', desc: 'Set response language to English', example: '/lang en' },
+      { cmd: 'auto', desc: 'Auto-detect response language from user input (default)', example: '/lang auto' },
+    ],
+    examples: [
+      '/lang th',
+      '/lang zh',
+      '/lang auto',
+    ],
+  },
+  '/queue': {
+    summary: 'Inspect or clear music playback audio queue',
+    usage: '/queue [clear]',
+    subcommands: [
+      { cmd: '', desc: 'Show currently queued music tracks and playback state', example: '/queue' },
+      { cmd: 'clear', desc: 'Wipe all pending tracks from the music queue', example: '/queue clear' },
+    ],
+    examples: [
+      '/queue',
+      '/queue clear',
+    ],
+  },
+  '/gpu': {
+    summary: 'Show GPU & VRAM hardware resource metrics',
+    usage: '/gpu [status]',
+    subcommands: [
+      { cmd: 'status', desc: 'Show real-time NVIDIA/Metal GPU compute utilization and VRAM memory usage', example: '/gpu' },
+    ],
+    examples: [
+      '/gpu',
+    ],
+  },
+  '/tools': {
+    summary: 'List registered SSOT knowledge and external tools',
+    usage: '/tools [filter]',
+    subcommands: [
+      { cmd: '[filter]', desc: 'List all registered tools or filter by keyword', example: '/tools drama' },
+    ],
+    examples: [
+      '/tools',
+      '/tools search',
+      '/tools mcp',
+    ],
+  },
+  '/cancel': {
+    summary: 'Abort the currently running query, tool, or subagent task',
+    usage: '/cancel',
+    subcommands: [
+      { cmd: '', desc: 'Instantly cancel running model generation, tool execution, or research subagents', example: '/cancel' },
+    ],
+    examples: [
+      '/cancel',
+    ],
+  },
+  '/tool': {
+    summary: 'Execute a registered SSOT tool directly with arguments',
+    usage: '/tool <name> [json_args | raw_query]',
+    subcommands: [
+      { cmd: '<name> [args]', desc: 'Call tool directly without model synthesis', example: '/tool search_works {"year":2026}' },
+    ],
+    examples: [
+      '/tool get_profile_and_fandom',
+      '/tool search_works In Blossom',
+      '/tool search_discography {"category":"ost"}',
+    ],
+  },
+  '/play': {
+    summary: 'Stream YouTube audio for Ju Jingyi songs and OSTs',
+    usage: '/play <song_name_or_url>',
+    subcommands: [
+      { cmd: '<song>', desc: 'Search and play song on YouTube in the background', example: '/play 恋爱告急' },
+    ],
+    examples: [
+      '/play In Blossom OST',
+      '/play 恋爱告急',
+    ],
+  },
+});
+
+export function findCommandDefinition(name) {
+  const normalized = name?.startsWith('/') ? name.toLowerCase() : `/${String(name || '').toLowerCase()}`;
+  return COMMAND_DEFINITIONS.find(command => command.name === normalized) || null;
+}
+
+export function getCommandDetails(name) {
+  if (!name) return null;
+  const normalized = name.startsWith('/') ? name.toLowerCase() : `/${String(name).toLowerCase()}`;
+  return COMMAND_DETAILS[normalized] || null;
+}