kiku-agent 1.0.11 → 1.2.0

package/README.md

@@ -1,463 +1,279 @@
-# 🌸 Ju Jingyi (鞠婧祎) Portal & Kiku AI Agent
-
-![npm](https://img.shields.io/badge/Node-%3E%3D20-brightgreen) ![ESM](https://img.shields.io/badge/ESM-only-4a90d9)
-
-> Full-stack fan archive, REST API Suite v1.0, autonomous AI Agent CLI, and MCP server powered by **LM Studio** (`google/gemma-4-e4b` / Gemma models) or any major cloud provider.
-
----
-
-## 📦 What's in the box
-
-This monorepo ships three deliverables in a single `kiku-agent` npm package:
-
-| Deliverable | Location | What it does |
-|---|---|---|
-| **Fan portal (SPA)** | `src/` (+ `api/` for Vercel) | Vite + React 19 + Tailwind 4 fan site served & deployed to Vercel |
-| **REST API v1** | `server/apiRouter.js` | Framework-free Node `http` router with all `/api/v1/*` routes, `/api-docs`, and `/openapi.json` |
-| **AI agent CLI + MCP server** | `server/agent/cli.js`, `server/mcp/stdio.js` | ReAct agent over local LM Studio or cloud providers, plus a stdio/HTTP MCP server — published as `kiku-agent` |
-
-**Core CLI highlights** (kept up to date — see each section below for details):
-
-- **Autonomous ReAct agent** with **38+ validated tools** across catalog, web, media, filesystem, and music.
-- **Multi-provider support**: LM Studio (local, free) plus OpenAI, Google Gemini, Groq, DeepSeek, OpenRouter, and custom OpenAI-compatible gateways.
-- **Bounded research workers**: `/subagent`, `/research`, and `/verify` run coordinated, capacity-limited workers with source-backed answers.
-- **Persistent fan collection**: `/favorites` builds a reusable personal archive, `/news` surfaces dated coverage, `/jobs` tracks background work.
-- **Multilingual**: automatically detects and responds in Thai, Chinese, or English.
-- **Career knowledge dashboard**: 15-question `/quiz`, giftable Developer VIP keys, terminal image `/gallery`, GPU/VRAM `/gpu`, and system `/system` monitors.
-- **Interactive TUI** with rich panels, themes, thinking/reasoning panels, and markdown rendering.
-
----
-
-## 🚀 Kiku AI Agent CLI
-
-The **Kiku AI Agent** is an autonomous ReAct agent and specialized encyclopedia for Ju Jingyi. It connects to your local **LM Studio** instance and has access to catalog, web, media, filesystem, and music tools.
-
-### Global installation
-
-```bash
-npm install -g kiku-agent
-kiku-agent
-```
-
-The global package intentionally excludes native audio build dependencies, so Windows users do not need Python, Visual Studio Build Tools, `node-gyp`, or FFmpeg to install the core CLI. On a new machine, run `kiku-agent` and then `/doctor`; if LM Studio or a chat model is unavailable, Kiku starts in catalog-only mode instead of crashing.
-
-If Windows is upgrading from an older failed install and reports `EBUSY` for `ffmpeg-static`, close every running Kiku/Node terminal and use a fresh PowerShell window:
-
-```powershell
-npm uninstall -g kiku-agent
-$stale = Join-Path (npm root -g) 'kiku-agent'
-if (Test-Path $stale) { Remove-Item -Recurse -Force $stale }
-npm cache verify
-npm install -g kiku-agent
-```
-
-Node 20 remains supported by the published core CLI. Ink 7 is development-only and is not installed globally; the Node 22 engine warnings from `ink`, `cli-truncate`, and `slice-ansi` should therefore no longer appear.
-
-Kiku never needs Administrator privileges. Sessions are stored in `%APPDATA%\\kiku-agent` on Windows, not in the current directory or under `Program Files`. If an older release still tries to create `.kiku_sessions` in a protected folder, install version 1.0.2 or newer and remove any old `KIKU_DATA_DIR` override:
-
-```powershell
-[Environment]::SetEnvironmentVariable('KIKU_DATA_DIR', $null, 'User')
-$env:KIKU_DATA_DIR = $null
-npm uninstall -g kiku-agent
-npm cache verify
-npm install -g kiku-agent@latest
-kiku-agent
-```
-
-The same package also installs the stdio MCP server command:
-
-```bash
-kiku-mcp
-```
-
-### Updating the CLI and MCP server
-
-Kiku uses the published `kiku-agent` package on npm as its update source. Inside an interactive session:
-
-```text
-/update                         # Check the configured release channel
-/update install                 # Install the stable `latest` release
-/update install next            # Install a preview release
-/update install 1.2.3           # Install an exact published version
-/update channel next            # Persist the preferred channel
-/update rollback                # Restore the previously recorded version
-```
-
-Automatic installation is available for global npm installs. Source checkouts, local dependencies, and `npx` executions receive a safe manual command instead of having their files replaced. Major updates require `--allow-major`; deprecated releases require `--allow-deprecated`. npm commands are executed without a shell and only allow known channel names or strict semantic versions.
-
-After an update or rollback, restart `kiku-agent` and any application hosting `kiku-mcp`. Update settings and rollback history are stored in the normal Kiku user data directory as `update-state.json`; sessions, memory, `.env`, and YouTube cookies are not modified.
-
-For a local checkout before the package is published, use `npm pack` followed by `npm install -g ./kiku-agent-1.0.11.tgz`.
-
-### ✨ Features
-- **LM Studio Integration**: Connects seamlessly to LM Studio's OpenAI-compatible server at `http://127.0.0.1:1234/v1` (default model `google/gemma-4-e4b`, with auto-detection of loaded models).
-- **Validated Tool Calling**: Schema validation, argument coercion, timeouts, duplicate-call caching, normalized results, and 38 catalog/media/web/filesystem/music tools.
-- **Music Player**: Search YouTube, stream audio locally through ffmpeg, and control a queue with play/pause/skip commands.
-- **Multilingual Support**: Automatically detects and responds in Thai, Chinese, or English based on user input language.
-- **Multi-turn Memory**: Retains conversation context with memory inspection and clear controls.
-- **Resilient ReAct Loop**: Supports OpenAI function calling as well as structured JSON tool parsing optimized for Gemma models.
-- **Graceful Diagnostics**: Displays real-time connection status, loaded model names, and fallback search modes if LM Studio is offline.
-- **Interactive TUI**: Optional Ink-based terminal UI (`npm run kiku-ink`) with themes, thinking panels, and tool result rendering.
-- **Sourced Research**: `/research`, `/verify`, and `/subagent` run bounded workers that cite source URLs; `/sources` lists them and `/suggestion` auto-generates research prompts.
-- **Fan Collection & Discovery**: `/favorites` persists a reusable collection (JSON/Markdown export); `/discover` recommends items by type, year, and mood; `/quiz` awards Developer VIP keys.
-- **Background Jobs**: `/jobs` tracks research, verification, subagent, and suggestion runs with show/cancel/clear controls.
-- **Learned Response Skills**: `/skill learn <instruction>` persists reusable response preferences across sessions.
-
----
-
-## 🛠️ LM Studio Quick Setup
-
-1. Open **LM Studio** on your computer.
-2. In the Search tab, download or load **`google/gemma-4-e4b`** (quantization: `Q4_K_M`, `Q6_K`, or `Q8_0`).
-3. Click the **Developer / Local Server** tab (icon with `<->`) on the left bar.
-4. Select your loaded Gemma model and click **Start Server** on port `1234` (`http://localhost:1234`).
-5. In this terminal, run:
-   ```bash
-   npm run kiku-agent
-   ```
-
----
-
-## 💻 CLI Usage
-
-### Interactive Chat Mode
-```bash
-npm run kiku-agent
-```
-
-### Launch with Specific Cloud Provider & Model
-```bash
+<div align="center">
+
+<img src="./public/images/jujingyi_portrait.jpg" width="96" height="96" style="border-radius: 50%; object-fit: cover;" alt="Ju Jingyi Icon" />
+
+# Ju Jingyi (鞠婧祎) Portal & Kiku AI Agent
+
+*Full-stack fan archive, REST API Suite v1.0, and autonomous AI Agent CLI + MCP Server*
+
+[![npm version](https://img.shields.io/npm/v/kiku-agent?style=flat-square&color=cb3837)](https://www.npmjs.com/package/kiku-agent)
+[![Node.js version](https://img.shields.io/badge/Node.js-%3E%3D20-3c873a?style=flat-square)](https://nodejs.org)
+[![ESM only](https://img.shields.io/badge/ESM-only-4a90d9?style=flat-square)](https://nodejs.org/api/esm.html)
+[![MCP Protocol](https://img.shields.io/badge/MCP-Protocol-8a2be2?style=flat-square)](https://modelcontextprotocol.io)
+[![License](https://img.shields.io/badge/License-GPL--3.0-blue?style=flat-square)](LICENSE)
+
+⭐ If you find this project helpful, star it on GitHub!
+
+[Overview](#overview) • [Quick Start](#quick-start) • [Features](#features) • [CLI Commands](#interactive-chat-slash-commands) • [Agent Tools](#available-agent-tools-45) • [Cloud & Local Models](#multi-provider-cloud--local-models) • [MCP Integration](#model-context-protocol-mcp) • [Web App & REST API](#web-app--rest-api) • [Troubleshooting](#troubleshooting)
+
+</div>
+
+---
+
+## Overview
+
+This repository ships a complete full-stack ecosystem for Chinese singer and actress **Ju Jingyi (鞠婧祎)**, packaged and distributed under the single [`kiku-agent`](https://www.npmjs.com/package/kiku-agent) npm package:
+
+| Deliverable | Location | Description |
+|---|---|---|
+| **Fan Portal (SPA)** | `src/` | Vite + React 19 + Tailwind 4 interactive showcase featuring discography, filmography, 4K visual gallery, trivia quiz, and timeline. |
+| **REST API v1** | `server/apiRouter.js` | Framework-free Node `http` REST API suite serving 16 endpoints, OpenAPI 3.0 specs, and live interactive `/api-docs`. |
+| **AI Agent CLI & MCP Server** | `server/agent/`, `server/mcp/` | Autonomous ReAct agent CLI (`kiku-agent`) and Model Context Protocol server (`kiku-mcp`) connecting to local LM Studio or cloud LLMs. |
+
+> [!TIP]
+> **100% Free Local Inference**: Kiku Agent runs completely offline with zero API token cost when connected to [LM Studio](https://lmstudio.ai/) running `google/gemma-4-e4b`. If no LLM is running, Kiku automatically starts in **catalog-only mode** instead of crashing.
+
+---
+
+## Quick Start
+
+### Global Installation
+
+Install the Kiku Agent CLI and MCP server globally via npm:
+
+```bash
+npm install -g kiku-agent
+kiku-agent
+```
+
+> [!NOTE]
+> The global package deliberately excludes native binary build dependencies (Python, `node-gyp`, Visual Studio C++ build tools are not required). For a local checkout before publishing, pack and install via `npm install -g ./kiku-agent-1.2.0.tgz`.
+
+### Zero-Install One-Shot Query
+
+Ask questions directly from your terminal using `npx`:
+
+```bash
+npx kiku-agent --query "ผลงานซีรีส์ปี 2026 มีเรื่องอะไรบ้างและรับบทเป็นใคร"
+```
+
+### Local LM Studio Setup
+
+1. Open **LM Studio** on your machine.
+2. Download or load **`google/gemma-4-e4b`** (quantization: `Q4_K_M`, `Q6_K`, or `Q8_0`).
+3. Click the **Developer / Local Server** tab (`<->`) on the left sidebar.
+4. Select your loaded Gemma model and click **Start Server** on port `1234` (`http://localhost:1234`).
+5. Launch Kiku Agent:
+   ```bash
+   kiku-agent
+   ```
+
+### Launch with Cloud Providers
+
+```bash
+# OpenAI (GPT-5.6 / GPT-4o)
 npm run kiku-agent -- --provider openai --model gpt-5.6-luna
+
+# Google Gemini (Gemini 3.7 Flash)
 npm run kiku-agent -- --provider gemini --model gemini-3.7-flash
+
+# Groq (Ultra-fast LPU inference)
 npm run kiku-agent -- --provider groq --model openai/gpt-oss-120b
+
+# DeepSeek (DeepSeek V4)
 npm run kiku-agent -- --provider deepseek --model deepseek-v4-flash
+
+# OpenRouter (Dynamic routing)
 npm run kiku-agent -- --provider openrouter --model openrouter/auto
-```
-
-### One-shot Question Query
-```bash
-npm run kiku-agent -- --query "ผลงานซีรีส์ปี 2026 มีเรื่องอะไรบ้างและรับบทเป็นใคร"
-```
-
-### Specify Custom Model or Base URL
-```bash
-npm run kiku-agent -- --model google/gemma-4-e4b-Q4_K_M --url http://127.0.0.1:1234/v1
-```
-
-### CLI Flags
-| Flag | Description |
-|---|---|
-| `-h`, `--help` | Show usage help |
-| `-V`, `--version` | Print the installed package version and exit |
-| `-P`, `--provider <name>` | Select active provider (`lmstudio`, `openai`, `gemini`, `groq`, `deepseek`, `openrouter`, `custom`) |
-| `-k`, `--api-key <key>` | Specify API key for cloud provider |
-| `-m`, `--model <id>` | Override model ID (e.g. `gpt-5.6-luna`, `google/gemma-4-e4b-Q4_K_M`) |
-| `-u`, `--url <url>` | Override provider base URL |
-| `-t`, `--tools` | List all registered tools |
-| `-s`, `--stats` | Print catalog overview statistics |
-| `-v`, `--verbose` | Verbose mode with reasoning shown |
-| `--thinking [show\|hide]` | Toggle reasoning visibility |
-| `-q`, `--query "<text>"` | One-shot query mode |
-
-### Interactive Chat Slash Commands
-
-Run `/help` inside a session for the full list. Commonly used:
-
-- `/provider` — View active AI provider status, model, URL, and API key status
-- `/provider list` — View all 7 supported AI providers and readiness status
-- `/provider use <name> [model]` — Switch provider and model in a single command
-- `/provider models [name]` — List curated active cost-effective models with pricing & context window
-- `/provider info <name>` — Display developer documentation links, API references, and required ENV keys
-- `/provider test [name]` — Test live endpoint connection and measure latency in milliseconds
-- `/provider setkey <key>` — Dynamically set or update API key at runtime
-- `/model` — Inspect active models currently loaded in LM Studio or cloud provider
-- `/model list` — List loaded models from server alongside recommended models
-- `/model recommend` — Show recommended active models for current provider
-- `/model use <model-id>` — Switch runtime model without restarting the CLI
-- `/model reconnect` — Recheck server and leave catalog-only mode after a chat model is loaded
-- `/doctor` — Check Node, writable app data, LM Studio, model availability, FFmpeg, speaker, and yt-dlp
-- `/update [check|install|channel|rollback]` — Manage npm-backed CLI and MCP package updates
-- `/tools` — View all tool names and parameter descriptions
-- `/find <query> [--type <type>] [--year YYYY]` — Search works, songs, roles, brands, awards, photos, and stages without a chat model; when an LLM is available it adds a short explanation of why the top results match your query
-- `/compare <item-a> -- <item-b>` — Compare two catalog entries or two career years side by side; when an LLM is available it adds a natural-language summary of the differences
-- `/favorites [list|add|remove|export|suggest]` — Build a persistent personal collection and export it as JSON or Markdown; `suggest` uses an LLM (when available) to recommend items that fit your saved taste
-- `/news [topic] [--days N] [--official-only]` — Find recent source-backed coverage with available dates and URLs; when an LLM is available it adds a short desk-style summary of the results
-- `/jobs [list|show|cancel|clear]` — Inspect and control research, verification, subagent, and suggestion jobs
-- `/discover [drama|song|stage|photo]` — Pick a catalog recommendation with optional year and mood filters; when an LLM is available it also adds a short AI rationale for the pick (falls back to catalog-only offline)
-- `/details [Qn]` — Open a compact diagnostic overview for the latest or selected question (F2 opens latest)
-- `/details [Qn] answer|thinking|tools` — Inspect one diagnostic section without dumping every raw result
-- `/details [Qn] tool <n>` — Inspect bounded raw arguments and result for one tool call
-- `/stats` — Print summary counts of dramas, songs, brands, and awards; when an LLM is available it adds a one-line insight about the snapshot
-- `/thinking [show|hide]` — Toggle reasoning process visibility
-- `/save` — Export session transcript to Markdown file
-- `/history` — Review conversation history
-- `/theme` — Switch terminal color theme
-- `/subagent <task>` — Send a focused Ju Jingyi research subtask to a bounded worker with catalog and web-research tools
-- `/research <question>` — Coordinate catalog, current-web, and verification workers in parallel, then synthesize one sourced answer
-- `/verify <claim>` — Classify a claim as verified, unverified, conflicting, or false
-- `/sources` — Show the source URLs captured by the latest research run
-- `/skill learn <instruction>` — Teach Kiku a persistent response preference, such as “ตอบภาษาไทยแบบสั้น กระชับ”
-- `/skill list`, `/skill del <id>`, `/skill on|off`, `/skill clear` — Review and control learned response skills
-- Music controls: `/play <song>`, `/stop`, `/pause`, `/resume`, `/next`, `/prev`, `/queue`, `/add <song>`, `/remove <n>`, `/clearqueue`, `/mute`, `/unmute`, `/current`
-- `/clear` — Reset conversation history
-- `/exit` — Exit the agent
-
-##### AI-compatible commands
-`/find`, `/compare`, `/favorites suggest`, `/news`, `/discover`, and `/stats` are **catalog-native + AI-enhanced**: they run fully in catalog-only mode with no model, and layer a short, bounded AI narration on top whenever a chat model is available. All AI output is sanitized (ANSI-injection-safe), length-capped, respects `/lang`, and **always** falls back silently to the plain result if the model is missing or errors — so the commands never crash or block in offline mode. Deliberately **not** AI-driven are commands that execute side effects or mutate config/credentials (`/tool`, `/mcp`, `/provider`, `/model`, `/key`, `/login`, `/play` & music controls, `/update`, `/copy`, `/exit`).
-
-#### Memory & Session commands
-- `/mem add <fact>` / `/mem search <query>` — Add to or search long-term memory
-- `/mem list`, `/mem topics`, `/mem del <id>` — Review, summarize, or delete stored facts
-- `/mem import <path>` / `/mem export` / `/mem clear` — Back up, restore, or reset memory
-- `/session info|list|export|clear` — Manage the current session and its transcript
-- `/history [n|search|clear]` — View or search prior conversation turns
-- `/save` — Export the session transcript to a Markdown file
-- `/copy [Qn] [answer|thinking|tools|all|markdown]` — Copy untruncated model output or diagnostics to the clipboard
-
-#### Language & Appearance
-- `/lang [th|zh|en|auto]` — Set the response language
-- `/theme [name|list|current|reset]` — Switch or inspect the terminal color theme
-- `/thinking [show|hide|toggle]` — Control reasoning-visibility
-
-#### Diagnostics & System
-- `/details [Qn] [overview|answer|thinking|tools|tool n]` — Inspect query diagnostics (F2 opens the latest)
-- `/stats` — Print summary counts of the catalog database
-- `/system` — Show OS, CPU, RAM, and heap information
-- `/gpu [status]` — Show GPU & VRAM resource metrics (NVIDIA)
-- `/ping` — Check active model server latency
-- `/config` — Show runtime configuration
-- `/prompt` — Preview the active system persona
-- `/doctor` — Check first-run environment and optional features
-- `/about` / `/version` — Show info and installed package version
-
-#### Extras & Engagement
-- `/gallery` — Render the next Ju Jingyi image directly in the terminal
-- `/quiz [lang]` — Take the 15-question quiz; correctly completing it claims a Developer VIP Key
-- `/key [show|apply <key>|clear]` — Manage your Developer VIP API Key
-- `/ads` — Show the next sponsor card
-- `/retry` — Retry the previous query
-- `/cancel` — Abort the running query, tool, or subagent task
-
-#### Research & Collection (advanced)
-- `/suggestion [list|run <id|all>|auto|refresh|topic <name>]` — Auto-generate research prompts and execute them with concurrent subagents
-- `/subagent <task>` — Run a single bounded Ju Jingyi research worker
-- `/research <question|status|last|sources|cancel>` — Coordinate parallel catalog/web/verification workers and synthesize a sourced answer
-- `/verify <claim>` — Classify a claim as verified, unverified, conflicting, or false
-- `/sources` — Show source URLs captured by the latest research run
-- `/jobs [list|show|cancel|clear]` — Inspect and control research, verification, subagent, and suggestion jobs
-
-Examples:
-
-```text
-/find "In Blossom" --type work
-/compare "In Blossom" -- "Beauty of Resilience"
-/compare 2024 -- 2025
-/favorites add song "Rain Love"
-/favorites list --type song
-/favorites export markdown
-/news ซีรีส์ใหม่ --days 14 --official-only
-/jobs list
-/discover song --mood calm
-/research "Ju Jingyi 2026 upcoming dramas"
-/verify "Ju Jingyi is a Versace brand ambassador"
-/suggestion auto
-/subagent "List Ju Jingyi's fashion brand partnerships"
-/skill learn "ตอบภาษาไทยแบบสั้น กระชับ"
-/quiz lang th
-/mem add "Ju Jingyi debuted with SNH48 in 2013"
 ```
 
 ---
-
-## 📚 Available API Tools in Kiku Agent (38)
-
-**Catalog**
-| Tool Name | Description |
-|---|---|
-| `get_profile_and_fandom` | Bio, Thai/Chinese/Pinyin names, Miju (蜜橘) fan community, slogans, socials |
-| `get_quotes` | Inspiring quotes with Thai translation and original Chinese text |
-| `search_works` | Filter filmography by year (2013–2026), category, keywords |
-| `get_work_detail` | Detailed synopsis, roles, ratings, streaming platform, and OST |
-| `get_character_roles` | Portrayed roles (Yang Caiwei, Lu Wuyi, Bai Suzhen, Han Yunxi, etc.) |
-| `search_discography` | Deduplicated music catalog, singles, OSTs, and albums |
-| `get_music_videos` | MVs, stage performances, dance practices, and special stages |
-| `get_media_links` | Locate official media links by song/drama/stage/MV name |
-| `get_brand_endorsements` | Commercial endorsements, luxury brands (PRSR, FRED), Milan fashion week |
-| `get_career_timeline` | Milestone eras from SNH48 debut (2013) to solo studio to present |
-| `get_awards` | Honors in music, television acting, and fashion influence |
-| `get_social_feed` | Recent Weibo & Douyin social media updates and metrics |
-| `get_gallery_photos` | High-res fashion sets, red carpet, photoshoot, and drama stills |
-| `global_search` | Universal fuzzy search across all entities in the database |
-
-**Web & Network**
-| Tool Name | Description |
-|---|---|
-| `web_search` | Live internet search for up-to-date news and info |
-| `web_extract` | Extract readable article content from live pages |
-| `fetch_webpage` | Fetch raw page content from live URLs |
-| `fetch_json` | Fetch and parse JSON from any endpoint |
-| `screenshot_webpage` | Capture a webpage screenshot |
-| `fetch_api` | Query the official Ju Jingyi REST API for structured JSON data |
-
-**Music Player (local audio via ffmpeg)**
-| Tool Name | Description |
-|---|---|
-| `search_youtube` | Search YouTube for songs and videos |
-| `play_music` | Play a song by name via yt-dlp/ytdl-core + ffmpeg |
-| `pause_music` / `resume_music` / `stop_music` | Playback control |
-| `next_track` / `prev_track` | Skip within the queue |
-| `add_to_queue` / `remove_from_queue` / `get_queue` / `clear_queue` | Queue management |
-| `get_current_track` / `get_music_status` | Current playback state |
-
-**Filesystem & System**
-| Tool Name | Description |
-|---|---|
-| `list_directory` | List files in an allowed local directory |
-| `read_local_file` | Read a local text file safely |
-| `get_system_stats` | High-level summary metrics of the entire Ju Jingyi archive |
-
----
-
-## 🤖 Multi-Provider Cloud & Local Models
-
-`kiku-agent` natively supports local LM Studio inference alongside top Cloud AI Providers with official endpoints, active cost-effective models, and tool-calling capabilities:
-
-| Provider | Recommended Active Models | Pricing / Cost Tier | Doc & API Reference | Required ENV Variable |
-|---|---|---|---|---|
-| **LM Studio** (Local) | `google/gemma-4-e4b` *(Q4_K_M, Q6_K, Q8_0)* | **100% Free / Local** (Zero token cost) | [Docs](https://lmstudio.ai/docs) • [API Ref](https://lmstudio.ai/docs/api/local-server) | `LMSTUDIO_BASE_URL` (default: `http://127.0.0.1:1234/v1`) |
+
+## Features
+
+- **Autonomous ReAct Agent**: Equipped with **45 validated tools** covering catalog knowledge, live web search, YouTube audio playback, filesystem inspection, and research workers.
+- **Dynamic Multiline TUI & Instant Paste**: Terminal input area auto-expands up to 6 rows with continuation prefixes, `Shift+Enter` multiline editing, `Ctrl+V` clipboard paste, and bracketed paste batch rendering (pasting 5,000+ characters completes in <30ms without UI freezing).
+- **Multi-Agent Adversarial Debate**: The `/debate` command orchestrates dialectic affirmative vs. negative agent workers to challenge factual claims against catalog records and synthesize evidence-backed truth matrices.
+- **Smart Memory 2.0**: Long-term conversational memory (`/mem`) featuring TF-IDF keyword indexing, recency decay scoring, topic categorization, and JSON export/import.
+- **Multi-Provider Engine**: Seamless switching between local LM Studio and 6 top cloud providers (OpenAI, Gemini, Groq, DeepSeek, OpenRouter, and custom OpenAI-compatible endpoints) with runtime health and latency diagnostics.
+- **Local Audio Player**: YouTube streaming via `yt-dlp` and `ffmpeg` with play, pause, skip, track queueing, and mute/unmute controls.
+- **Model Context Protocol (MCP)**: Official stdio (`kiku-mcp`) and Streamable HTTP endpoints exposing **43 tools**, **7 resources**, and **7 prompt templates** for Claude Desktop, Cursor, and VS Code.
+- **Standalone Web Chat Portal**: Interactive browser chatbot (`/chat` or `/web` on port 3300) with character network visualization, mini Jukebox player, and direct catalog fallback.
+- **Developer VIP Keys**: Integrated 15-question trivia quiz (`/quiz`) allowing users to test fan knowledge and earn Developer VIP API keys with elevated rate limits.
+- **Rich Transcript Export**: `/save` and `/session export` output single-file self-contained HTML (with embedded CSS & dark mode), Markdown, JSON, or plain text.
+
+---
+
+## CLI Usage
+
+### Command-Line Flags
+
+| Flag | Description |
+|---|---|
+| `-h`, `--help` | Display usage instructions and options |
+| `-V`, `--version` | Print installed package version |
+| `-P`, `--provider <name>` | Select provider (`lmstudio`, `openai`, `gemini`, `groq`, `deepseek`, `openrouter`, `custom`) |
+| `-k`, `--api-key <key>` | Cloud provider API key override |
+| `-m`, `--model <id>` | Model ID override (e.g. `gpt-5.6-luna`, `gemini-3.7-flash`, `google/gemma-4-e4b`) |
+| `-u`, `--url <url>` | Provider base URL override |
+| `-t`, `--tools` | List all 45 registered tools |
+| `-s`, `--stats` | Print catalog overview statistics |
+| `-v`, `--verbose` | Verbose mode with reasoning output |
+| `--thinking [show\|hide]` | Toggle visibility of reasoning process |
+| `-q`, `--query "<text>"` | One-shot query mode |
+
+---
+
+## Interactive Chat Slash Commands
+
+Type `/help` inside any active session for the interactive command palette. Commands are organized by functional domain:
+
+### 🤖 Provider & Model
+- `/provider [list|use|models|info|test|setkey]` — Inspect, switch, and test AI providers, or set API keys at runtime
+- `/model [list|recommend|use|reconnect]` — Switch models on the fly without restarting, or reconnect after starting LM Studio
+
+### 🧠 Memory & Conversation Sessions
+- `/mem [add|search|list|topics|summary|del|import|export|clear]` — Long-term conversational memory with TF-IDF keyword scoring & recency decay
+- `/session [info|summary|list|load|export|clear]` — Manage, restore, or summarize conversation sessions
+- `/history [n|search|summary|clear]` — Review and search past conversation turns
+- `/save [markdown|html|json|text]` — Export session transcript (single-file HTML with dark mode, Markdown, JSON, plain text)
+- `/copy [session|[Qn] [answer|thinking|tools|tool n|all|json]]` — Copy transcript, answers, or diagnostic info to clipboard
+- `/clear` — Reset active conversation history
+
+### 🔍 Catalog & Discovery
+- `/find <query> [--type <type>] [--year YYYY]` — Search works, songs, roles, brands, awards, and stages (AI-enhanced)
+- `/compare <item-a> -- <item-b>` — Side-by-side comparison of catalog items or career years (AI-enhanced)
+- `/favorites [list|add|remove|export|suggest]` — Personal collection builder with AI recommendations
+- `/discover [drama|song|stage|photo]` — Recommendations by type, year, and mood (AI-enhanced)
+- `/news [topic] [--days N] [--official-only]` — Dated coverage and recent source-backed updates (AI-enhanced)
+- `/stats` — Print summary counts of dramas, songs, brands, and awards (AI-enhanced)
+- `/gallery` — Render Ju Jingyi images directly in the terminal
+
+### 🔬 Research, Debate & Subagents (Advanced)
+- `/debate <claim|status|last>` — Multi-agent adversarial debate with affirmative/negative roles and truth matrix synthesis
+- `/timeline [year|era]` — Render career milestone ASCII timeline graphic in terminal
+- `/subagent <task>` — Dispatch a bounded research subagent with catalog & web access
+- `/research <question>` — Coordinate parallel catalog, web, and verification workers
+- `/verify <claim>` — Classify a claim as verified, unverified, conflicting, or false
+- `/suggestion [list|run|auto|refresh|topic]` — Auto-generate exploration prompts and execute them with subagents
+- `/sources` — Show source URLs captured by the latest research run
+- `/jobs [list|show|cancel|clear]` — Inspect and control background research jobs
+- `/skill [learn|list|del|on|off|clear]` — Teach persistent response persona preferences across sessions
+
+### 🎵 Music Player (Local Audio)
+- `/play <song>` / `/stop` / `/pause` / `/resume` — YouTube audio streaming via yt-dlp & FFmpeg
+- `/next` / `/prev` / `/queue` / `/add` / `/remove` / `/clearqueue` — Queue and track management
+- `/mute` / `/unmute` / `/current` — Volume and playback status
+
+### 🛠️ System, UI & Diagnostics
+- `/doctor` — Diagnostic check for Node, app data, LM Studio, models, FFmpeg, speaker, and yt-dlp
+- `/details [Qn]` — Diagnostic overview of answers, reasoning process, and bounded tool calls (F2)
+- `/tools` — View all 45 registered tools with parameter descriptions
+- `/lang [th|zh|en|auto]` — Set response language (Thai, Chinese, English)
+- `/theme [name|list|current|next|prev|reset]` — Switch terminal color theme
+- `/thinking [show|hide|toggle]` — Toggle reasoning process visibility
+- `/system` / `/gpu` / `/ping` / `/config` — System info, NVIDIA GPU/VRAM monitor, server latency, and runtime config
+- `/quiz [lang]` — 15-question fan trivia quiz to claim a Developer VIP API key
+- `/key [show|apply <key>|clear]` — Manage Developer VIP API Key
+- `/web [start|open|stop|status|restart] [port]` — Launch or open standalone Web Chat interface (port 3300)
+- `/cancel` / `/retry` / `/exit` — Abort query, retry, or exit the agent
+
+> [!NOTE]
+> `/find`, `/compare`, `/favorites suggest`, `/news`, `/discover`, and `/stats` are **catalog-native + AI-enhanced**: they run in catalog-only mode without an LLM, and layer an AI summary on top whenever a model is active.
+
+### Example CLI Workflows
+
+```text
+/find "In Blossom" --type work
+/compare "In Blossom" -- "Beauty of Resilience"
+/favorites add song "Rain Love"
+/debate "Ju Jingyi debuted with SNH48 in 2013"
+/timeline 2024
+/research "Ju Jingyi 2026 upcoming dramas"
+/skill learn "ตอบภาษาไทยแบบสั้น กระชับ"
+/quiz lang th
+```
+
+---
+
+## Available Agent Tools (45)
+
+Kiku Agent includes **45 validated tools** across 5 categories that the agent autonomously invokes during conversations:
+
+- **Catalog (14)**: Profile, fandom facts, quotes, filmography (2013–2026), character roles, discography, music videos, brands, career timeline, awards, Weibo/Douyin feeds, 4K gallery, and global fuzzy search.
+- **Web & Network (6)**: Live DuckDuckGo search, article extraction, raw webpage fetch, JSON parser, page screenshots, and REST API querying.
+- **Music Player (15)**: YouTube streaming via `yt-dlp` & `ffmpeg`, playlist queue management, track playback controls, and volume mute/unmute.
+- **Filesystem & System (3)**: Directory listing, safe local file reader, and archive statistics.
+- **Research, Skills & VIP (7)**: Autonomous research subagents, deep research coordinator, claim verification, topic suggestion, persistent skill learning, trivia quiz challenge, and Developer VIP key management.
+
+> [!TIP]
+> Run `/tools` inside the CLI or visit [`/api-docs`](https://jujingyi-kikuuu.vercel.app/api-docs) to inspect parameter schemas and test all tools interactively.
+
+---
+
+## Multi-Provider Cloud & Local Models
+
+`kiku-agent` natively supports local LM Studio inference alongside top Cloud AI Providers with official endpoints, active cost-effective models, and tool-calling capabilities:
+
+| Provider | Recommended Active Models | Pricing / Cost Tier | Doc & API Reference | Required ENV Variable |
+|---|---|---|---|---|
+| **LM Studio** (Local) | `google/gemma-4-e4b` *(Q4_K_M, Q6_K, Q8_0)* | **100% Free / Local** (Zero token cost) | [Docs](https://lmstudio.ai/docs) • [API Ref](https://lmstudio.ai/docs/api/local-server) | `LMSTUDIO_BASE_URL` (default: `http://127.0.0.1:1234/v1`) |
 | **OpenAI** | `gpt-5.6-luna` *(default)*, `gpt-5.6-terra`, `gpt-5.6-sol` | **Cost-sensitive → Flagship** ($0.20 - $4.00 / 1M input) | [Docs](https://developers.openai.com/api/docs/models) • [API Ref](https://developers.openai.com/api/reference) | `OPENAI_API_KEY` |
 | **Google Gemini** | `gemini-3.7-flash` *(default)*, `gemini-3.5-flash-lite`, `gemini-3.6-flash` | **Free tier / Stable Flash** ($0.30 - $0.75 / 1M input) | [Docs](https://ai.google.dev/gemini-api/docs/models) • [API Ref](https://ai.google.dev/api/generate-content) | `GEMINI_API_KEY` |
 | **Groq** | `openai/gpt-oss-120b` *(default)*, `openai/gpt-oss-20b` | **LPU Ultra-Fast** ($0.075 - $0.15 / 1M input) | [Docs](https://console.groq.com/docs/quickstart) • [API Ref](https://console.groq.com/docs/api-reference) | `GROQ_API_KEY` |
 | **DeepSeek** | `deepseek-v4-flash` *(default)*, `deepseek-v4-pro` | **V4 / 1M context** ($0.22 - $1.32 / 1M uncached input) | [Docs](https://api-docs.deepseek.com/quick_start/pricing/) • [API Ref](https://api-docs.deepseek.com/api/create-chat-completion) | `DEEPSEEK_API_KEY` |
 | **OpenRouter** | `openrouter/auto` *(default, dynamic catalog)* | **Automatic routing** (billed at routed model rate) | [Docs](https://openrouter.ai/docs/guides/routing/routers/auto-router) • [API Ref](https://openrouter.ai/docs/api/reference/overview) | `OPENROUTER_API_KEY` |
-| **Custom Gateway** | Any OpenAI-compatible server (vLLM, Ollama, TGI, Azure) | **Custom** | [OpenAI Spec](https://platform.openai.com/docs/api-reference) | `LLM_BASE_URL`, `LLM_API_KEY` |
-
-```bash
-# Launch with a specific cloud provider and model
-npm run kiku-agent -- --provider openai --model gpt-5.6-luna
-npm run kiku-agent -- --provider gemini --model gemini-3.7-flash
-npm run kiku-agent -- --provider groq --model openai/gpt-oss-120b
-npm run kiku-agent -- --provider deepseek --model deepseek-v4-flash
-npm run kiku-agent -- --provider openrouter --model openrouter/auto
-
-# Manage providers interactively within the agent CLI
-/provider list                                     # View all 7 providers and key status
+| **Custom Gateway** | Any OpenAI-compatible server (vLLM, Ollama, TGI, Azure) | **Custom** | [OpenAI Spec](https://platform.openai.com/docs/api-reference) | `LLM_BASE_URL`, `LLM_API_KEY` |
+
+```bash
+# Manage providers interactively within the agent CLI:
+/provider list                                     # View all 7 providers and key status
 /provider use groq openai/gpt-oss-120b             # Switch provider and model in one command
-/provider models gemini                            # List curated cost-effective models with pricing & context
-/provider info openai                              # Show developer documentation & API details
-/provider test groq                                # Test live endpoint connection and measure latency
-/provider setkey groq gsk-...                      # Set or update API key dynamically at runtime
-/model recommend                                   # View recommended models for active provider
+/provider models gemini                            # List curated cost-effective models with pricing & context
+/provider info openai                              # Show developer documentation & API details
+/provider test groq                                # Test live endpoint connection and measure latency
+/provider setkey groq gsk-...                      # Set or update API key dynamically at runtime
+/model recommend                                   # View recommended models for active provider
 /model use gpt-5.6-luna                            # Switch active model on current provider
 ```
 
-At interactive startup, provider switches, and before a one-shot query, the CLI checks the provider's live `/models` catalog. If a configured model has been retired, it selects the first available model from that provider's maintained recommendation list and reports the fallback. Legacy IDs for Groq, DeepSeek, and selected renamed models are normalized automatically.
-
----
-
-## 🔌 Model Context Protocol (MCP)
-
-### 1. MCP Server (`kiku-mcp`)
-The package ships a Model Context Protocol server exposing the catalog as tools, resources, and prompts:
-```bash
-# stdio transport (Claude Desktop, Cursor, ...)
-npm run kiku-mcp
-```
-The production deployment exposes a stateless Streamable HTTP endpoint at `https://jujingyi-kikuuu.vercel.app/mcp` (`POST /mcp`). The server offers catalog tools (`search_works`, `get_work_detail`, `search_discography`, `get_brand_endorsements`, `get_awards`, `get_career_timeline`, `global_search`, …), resources, and prompts — see `server/mcp/`.
-
-**HTTP security** — the remote MCP endpoint is guarded by a bearer token and CORS allow-list:
-- Set `MCP_API_KEY` to require `Authorization: Bearer <MCP_API_KEY>` on `POST /mcp`.
-- Set `MCP_CORS_ORIGINS` to a comma-separated list of allowed browser origins (empty = no CORS).
-
-```bash
-# Example: curl the Streamable HTTP endpoint
-curl -X POST https://jujingyi-kikuuu.vercel.app/mcp \
-  -H "Authorization: Bearer $MCP_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
-```
-
-### 2. MCP Client in `kiku-agent`
-`kiku-agent` can connect to external MCP servers (Streamable HTTP, Stdio) and dynamically load their tools:
-```bash
-# Connect to an MCP server from CLI:
-/mcp connect kiku-remote https://jujingyi-kikuuu.vercel.app/mcp
-/mcp connect filesystem stdio npx -y @modelcontextprotocol/server-filesystem ./
-/mcp tools
-```
-
-`/mcp` shows the connection summary plus every available MCP tool command in a compact list. `/mcp tools` expands the same list with parameters and descriptions. Long command panels open at their first page in the classic TUI; use Page Down or End to continue through the result. Manage persistent connections with `/mcp status|list|disconnect <name>|remove <name>|reconnect [all]|save|reload`.
-
-> **Note on web tools:** MCP web tools are gated behind `KIKU_MCP_ENABLE_WEB_TOOLS=true`.
-
----
-
-## ⚙️ Environment Variables
-
-Copy `.env.example` → `.env` (parsed automatically when the CLI runs; only unset variables are filled):
-
-| Variable | Purpose |
-|---|---|
-| `LLM_PROVIDER` | Active provider override (`openai`, `openrouter`, `groq`, `deepseek`, `gemini`, `lmstudio`, `custom`) |
-| `OPENAI_API_KEY` | OpenAI API Key |
-| `OPENROUTER_API_KEY` | OpenRouter API Key |
-| `GROQ_API_KEY` | Groq Cloud API Key |
-| `DEEPSEEK_API_KEY` | DeepSeek API Key |
-| `GEMINI_API_KEY` | Google Gemini API Key |
-| `LMSTUDIO_BASE_URL` | LM Studio endpoint (default `http://127.0.0.1:1234/v1`) |
-| `KIKU_YT_COOKIES` | Path to a `cookies.txt` file for YouTube playback |
-| `KIKU_YT_BROWSER` | Import cookies from a browser (`chrome`, `edge`, `firefox`) |
-| `KIKU_YTDLP` | Path/command for yt-dlp binary (default `yt-dlp`) |
-| `KIKU_YTDLP_CLIENT` | YouTube player client override (`tv`, `ios`, `web`) |
-| `MCP_API_KEY` | Bearer token required by the HTTP MCP endpoint (`POST /mcp`) |
-| `MCP_CORS_ORIGINS` | Comma-separated allowed origins for browser MCP calls |
-| `KIKU_MCP_ENABLE_WEB_TOOLS` | Set `true` to enable web tools in the MCP server |
-| `KIKU_API_KEYS` | Pre-seeded REST API keys (higher rate limits) |
-| `KIKU_VIP_KEYS` | Pre-seeded Developer VIP API keys (highest rate limits) |
-
-> `.env` is gitignored — never commit it. The checked-in `.env.example` contains placeholders only.
-> Likewise, `cookies.txt` at the repo root contains real YouTube session cookies and must never be staged.
-
----
-
-## 🧭 Web App & API Development
-
-### Frontend (Vite + React 19 + Tailwind 4)
-```bash
-# Start frontend dev server (API v1 works in-process)
-npm run dev
-
-# Production build
-npm run build
-```
-The SPA lives in `src/` (entry `src/App.jsx`) and is state-navigated via `NavigationContext` (no react-router). All non-API paths rewrite to `/` in `vercel.json`.
-
-### REST API v1
-The API is a single framework-free Node handler in `server/apiRouter.js` (~2000 lines) serving every `/api/v1/*` route plus interactive docs and an OpenAPI spec.
-
-- **Base URL (prod):** `https://jujingyi-kikuuu.vercel.app/api/v1`
-- **Base URL (dev):** `http://localhost:3000/api/v1`
-- **Interactive docs:** `https://jujingyi-kikuuu.vercel.app/api-docs`
-- **OpenAPI 3.0 JSON:** `https://jujingyi-kikuuu.vercel.app/api/v1/openapi.json`
-- **Health check:** `GET /api/v1/health`
-
-```bash
-
 ---
 
-## 🔌 Model Context Protocol (MCP)
+## Model Context Protocol (MCP)
 
 ### 1. MCP Server (`kiku-mcp`)
-The package ships a Model Context Protocol server exposing the catalog as tools, resources, and prompts:
+
+The package ships an official Model Context Protocol server exposing the Ju Jingyi encyclopedia as **43 tools**, **7 resources**, and **7 prompt templates**:
+
 ```bash
-# stdio transport (Claude Desktop, Cursor, ...)
-npm run kiku-mcp
+# Stdio transport (Claude Desktop, Cursor, VS Code)
+kiku-mcp
+
+# Zero-install via npx:
+npx -y kiku-agent kiku-mcp
+```
+
+#### Claude Desktop & Cursor Integration
+
+Add the following snippet to your `claude_desktop_config.json` or Cursor MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "kiku": {
+      "command": "npx",
+      "args": ["-y", "kiku-agent", "kiku-mcp"]
+    }
+  }
+}
 ```
-The production deployment exposes a stateless Streamable HTTP endpoint at `https://jujingyi-kikuuu.vercel.app/mcp` (`POST /mcp`). The server offers catalog tools (`search_works`, `get_work_detail`, `search_discography`, `get_brand_endorsements`, `get_awards`, `get_career_timeline`, `global_search`, …), resources, and prompts — see `server/mcp/`.
 
-**HTTP security** — the remote MCP endpoint is guarded by a bearer token and CORS allow-list:
-- Set `MCP_API_KEY` to require `Authorization: Bearer <MCP_API_KEY>` on `POST /mcp`.
-- Set `MCP_CORS_ORIGINS` to a comma-separated list of allowed browser origins (empty = no CORS).
+The production deployment exposes a stateless Streamable HTTP endpoint at `https://jujingyi-kikuuu.vercel.app/mcp` (`POST /mcp`).
+
+> [!IMPORTANT]
+> **HTTP Security**: The remote MCP endpoint is guarded by a bearer token and CORS allow-list:
+> - Set `MCP_API_KEY` to require `Authorization: Bearer <MCP_API_KEY>` on `POST /mcp`.
+> - Set `MCP_CORS_ORIGINS` to a comma-separated list of allowed browser origins (empty = no CORS).
 
 ```bash
 # Example: curl the Streamable HTTP endpoint
@@ -468,21 +284,19 @@ curl -X POST https://jujingyi-kikuuu.vercel.app/mcp \
 ```
 
 ### 2. MCP Client in `kiku-agent`
+
 `kiku-agent` can connect to external MCP servers (Streamable HTTP, Stdio) and dynamically load their tools:
+
 ```bash
-# Connect to an MCP server from CLI:
+# Connect to an MCP server from the CLI:
 /mcp connect kiku-remote https://jujingyi-kikuuu.vercel.app/mcp
 /mcp connect filesystem stdio npx -y @modelcontextprotocol/server-filesystem ./
 /mcp tools
 ```
 
-`/mcp` shows the connection summary plus every available MCP tool command in a compact list. `/mcp tools` expands the same list with parameters and descriptions. Long command panels open at their first page in the classic TUI; use Page Down or End to continue through the result. Manage persistent connections with `/mcp status|list|disconnect <name>|remove <name>|reconnect [all]|save|reload`.
-
-> **Note on web tools:** MCP web tools are gated behind `KIKU_MCP_ENABLE_WEB_TOOLS=true`.
-
 ---
 
-## ⚙️ Environment Variables
+## Environment Variables
 
 Copy `.env.example` → `.env` (parsed automatically when the CLI runs; only unset variables are filled):
 
@@ -505,14 +319,16 @@ Copy `.env.example` → `.env` (parsed automatically when the CLI runs; only uns
 | `KIKU_API_KEYS` | Pre-seeded REST API keys (higher rate limits) |
 | `KIKU_VIP_KEYS` | Pre-seeded Developer VIP API keys (highest rate limits) |
 
+> [!CAUTION]
 > `.env` is gitignored — never commit it. The checked-in `.env.example` contains placeholders only.
-> Likewise, `cookies.txt` at the repo root contains real YouTube session cookies and must never be staged.
+> Likewise, `cookies.txt` at the repo root contains real YouTube session cookies and must never be staged or committed.
 
 ---
 
-## 🧭 Web App & API Development
+## Web App & REST API
 
 ### Frontend (Vite + React 19 + Tailwind 4)
+
 ```bash
 # Start frontend dev server (API v1 works in-process)
 npm run dev
@@ -520,83 +336,72 @@ npm run dev
 # Production build
 npm run build
 ```
-The SPA lives in `src/` (entry `src/App.jsx`) and is state-navigated via `NavigationContext` (no react-router). All non-API paths rewrite to `/` in `vercel.json`.
+
+The SPA lives in `src/` (entry `src/App.jsx`) and uses state-based navigation via `NavigationContext` (no react-router). All non-API paths rewrite to `/` in `vercel.json`.
 
 ### REST API v1
-The API is a single framework-free Node handler in `server/apiRouter.js` (~2000 lines) serving every `/api/v1/*` route plus interactive docs and an OpenAPI spec.
+
+The API is a single framework-free Node handler in `server/apiRouter.js` (~2000 lines) serving every `/api/v1/*` route plus OpenAPI specifications and interactive documentation:
 
 - **Base URL (prod):** `https://jujingyi-kikuuu.vercel.app/api/v1`
-- **Base URL (dev):** `http://localhost:3000/api/v1`
+- **Base URL (dev):** `http://localhost:3000/api/v1` *(or dynamically assigned port e.g. 5173)*
 - **Interactive docs:** `https://jujingyi-kikuuu.vercel.app/api-docs`
 - **OpenAPI 3.0 JSON:** `https://jujingyi-kikuuu.vercel.app/api/v1/openapi.json`
 - **Health check:** `GET /api/v1/health`
+- **Web Chat:** `https://jujingyi-kikuuu.vercel.app/chat` *(or local `/web` on port 3300)*
 
 ```bash
 curl https://jujingyi-kikuuu.vercel.app/api/v1/health
 ```
 
-Endpoint groups include catalog (works, discography, brands, awards, timeline, profile, gallery), stats, quiz challenges and Developer VIP key claiming (`/api/v1/quiz/challenge`, `/api/v1/keys/claim`), plus agent/REST integration. `?key=` or bearer auth with a `KIKU_API_KEYS` / `KIKU_VIP_KEYS` value unlocks higher rate limits.
-
-In production `/api/*` is served by the Vercel serverless wrapper.
+#### 🌟 Kiku Agent Showcase on `/api-docs`
 
-## 🗃️ Data architecture & gotchas
+The interactive `/api-docs` portal features a dedicated **Kiku AI Agent & MCP Ecosystem Showcase** card:
+- One-click copyable global CLI installation (`npm install -g kiku-agent`, `kiku-agent`).
+- Zero-install one-shot command (`npx kiku-agent --query "..."`).
+- Instant MCP server commands (`kiku-mcp`) and ready-to-paste `claude_desktop_config.json` / Cursor JSON snippets.
+- Direct links to npm, GitHub, and the live Web Chat interface.
 
-- **The catalog exists twice** — `src/data/*.js` (used by the SPA, REST API, and agent tools) and `server/mcp/data/*.js` (used by the MCP server) are two independent copies with the same export names but different content (the site copy is richer and Thai-heavy; the MCP copy is compact English). **Any catalog change must be applied to both trees**, or MCP answers will drift from the site/API.
-- **Packaging**: `package.json` `"files"` ships `src/data/**/*.js` because the agent imports them — don't move that directory without updating both `"files"` and every importer. Bins are `kiku-agent` and `kiku-mcp`; package exports map `.` → `server/agent/agentCore.js`.
-- **Path aliases**: the `@/*` alias in `jsconfig.json` is unused — use relative imports everywhere (no matching alias in `vite.config.js`).
-- **No linter/formatter/typecheck**: verification is `npm test` plus a successful build. CI (GitHub Actions) only runs Snyk + secret scanning.
+Endpoint groups include catalog (works, discography, brands, awards, timeline, profile, gallery), stats, quiz challenges and Developer VIP key claiming (`/api/v1/quiz/challenge`, `/api/v1/keys/claim`), plus agent/REST integration. `?key=` or bearer auth with a `KIKU_API_KEYS` / `KIKU_VIP_KEYS` value unlocks higher rate limits.
 
 ---
 
-## 🧱 Project structure
+## Data Architecture & Gotchas
 
-```
-├── src/                     # Vite + React 19 + Tailwind 4 fan portal (SPA)
-│   ├── App.jsx              # Entry (state-based navigation)
-│   ├── components/          # Navbar, Hero, MusicPlayer, ApiDocsModal, …
-│   ├── pages/               # Biography, Dramas, Music, Gallery, …
-│   ├── data/                # Rich, Thai-heavy catalog (shared with API + agent)
-│   └── context/             # NavigationContext, i18n, …
-├── server/
-│   ├── apiRouter.js         # All /api/v1/* routes, /api-docs, /openapi.json
-│   ├── agent/               # Agent CLI core, tools, commands, TUI (ui.js), memory,
-│   │                        #  research/subagent/verify, suggestions, job manager,
-│   │                        #  audio player, MCP client, model/provider manager, …
-│   ├── mcp/                 # MCP server (stdio.js) + compact English catalog data
-│   └── supabase_schema.sql  # Optional SQL for a hosted database
-├── api/                     # Vercel serverless wrappers (delegate to apiRouter)
-├── test_api.ps1             # API verification suite
-└── .env.example             # Environment variable template
-```
+> [!IMPORTANT]
+> **Dual Catalog Notice**: The catalog data lives in two independent copies with the same export names but different contents:
+> - `src/data/*.js` (used by the SPA, REST API, and agent tools): Rich, Thai-heavy.
+> - `server/mcp/data/*.js` (used by the MCP server): Compact English.
+>
+> **Any catalog change must be applied to both trees**, or MCP answers will drift from the site/API.
+
+- **Packaging**: `package.json` `"files"` ships `src/data/**/*.js` because the agent imports them — don't move that directory without updating both `"files"` and every importer. Bins are `kiku-agent` and `kiku-mcp`; package exports map `.` → `server/agent/agentCore.js`.
+- **Path aliases**: The `@/*` alias in `jsconfig.json` is unused — use relative imports everywhere (no matching alias in `vite.config.js`).
+- **Testing & Verification**: There is no linter or typechecker setup. Verification is `npm test` (running 330 unit/integration tests) plus `npm run build`.
 
 ---
 
-## 🧰 Troubleshooting
+## Troubleshooting
 
 **Agent won't start or stays in catalog-only mode**
-- Ensure LM Studio is running with a Gemma model loaded and the local server on `127.0.0.1:1234`, or pass a cloud provider + key.
-- Run `/doctor` inside the session to diagnose Node, app data, LM Studio, model, FFmpeg, speaker, and yt-dlp availability. If no chat model is available, Kiku deliberately starts in catalog-only mode instead of crashing.
-
-**Windows install fails with `EBUSY` on `ffmpeg-static`**
-- Close every Kiku/Node terminal, then in a fresh PowerShell: `npm uninstall -g kiku-agent`, remove the stale `kiku-agent` folder under `npm root -g`, `npm cache verify`, then reinstall.
-
-**Kiku tries to write to a protected folder**
-- Remove any old `KIKU_DATA_DIR` user override and upgrade to ≥ 1.0.2. Sessions live in `%APPDATA%\kiku-agent` on Windows; no Administrator rights are needed.
+- Ensure LM Studio is running with a Gemma model loaded and the local server started on `127.0.0.1:1234`, or specify a cloud provider with `-P <provider> -k <key>`.
+- Run `/doctor` inside the session to diagnose Node, app data, LM Studio, model, FFmpeg, speaker, and yt-dlp availability.
+
+**Windows install reports `EBUSY` for `ffmpeg-static`**
+- Close all active terminal windows running Node or Kiku. In a fresh PowerShell window:
+  ```powershell
+  npm uninstall -g kiku-agent
+  $stale = Join-Path (npm root -g) 'kiku-agent'
+  if (Test-Path $stale) { Remove-Item -Recurse -Force $stale }
+  npm cache verify
+  npm install -g kiku-agent
+  ```
 
 **YouTube playback fails**
 - Re-authenticate with `/login`, or point `KIKU_YT_COOKIES` / `KIKU_YT_BROWSER` at a valid session and `KIKU_YTDLP` at a working yt-dlp binary. Some regions/clients need `KIKU_YTDLP_CLIENT` set to `tv` or `ios`.
 
-**Remote MCP returns 401**
-- Set `MCP_API_KEY` on the server and send `Authorization: Bearer <MCP_API_KEY>`; for browser clients, set `MCP_CORS_ORIGINS` to the allowed origins.
-
-**MCP answers disagree with the site/API**
-- The catalog lives in two copies (`src/data` vs `server/mcp/data`). Update both trees whenever a fact changes.
+**Remote MCP returns 401 Unauthorized**
+- Set `MCP_API_KEY` on the server and send `Authorization: Bearer <MCP_API_KEY>`. For browser clients, set `MCP_CORS_ORIGINS` to the allowed origins.
 
 **Reports of missing or stale model after switching providers**
-- The CLI re-checks the live `/models` catalog at startup, on provider switches, and before one-shot queries, auto-falling back to that provider's recommendation list if a configured model was retired.
-
----
-
-## 📄 License
-
-This project is licensed under the [GNU General Public License v3.0 (GPL-3.0)](LICENSE).
+- The CLI automatically queries the provider's live `/models` endpoint at startup, on provider switches, and before one-shot queries, falling back gracefully to recommended active models if a configured model was retired.