kiku-agent 1.0.6 → 1.0.8

package/README.md

@@ -1,8 +1,30 @@
 # 🌸 Ju Jingyi (鞠婧祎) Portal & Kiku AI Agent
 
-> **New CLI capabilities:** `/subagent <task>` runs a bounded Ju Jingyi research worker, while `/skill learn <instruction>` teaches Kiku persistent response preferences.
+![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).
+> 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.
 
 ---
 
@@ -65,7 +87,7 @@ Automatic installation is available for global npm installs. Source checkouts, l
 
 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.6.tgz`.
+For a local checkout before the package is published, use `npm pack` followed by `npm install -g ./kiku-agent-1.0.8.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).
@@ -76,6 +98,10 @@ For a local checkout before the package is published, use `npm pack` followed by
 - **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.
 
 ---
 
@@ -101,10 +127,11 @@ npm run kiku-agent
 
 ### Launch with Specific Cloud Provider & Model
 ```bash
-npm run kiku-agent -- --provider openai --model gpt-4o-mini
-npm run kiku-agent -- --provider gemini --model gemini-2.5-flash
-npm run kiku-agent -- --provider groq --model llama-3.1-8b-instant
-npm run kiku-agent -- --provider openrouter --model google/gemini-2.5-flash
+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
 ```
 
 ### One-shot Question Query
@@ -124,7 +151,7 @@ npm run kiku-agent -- --model google/gemma-4-e4b-Q4_K_M --url http://127.0.0.1:1
 | `-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-4o-mini`, `google/gemma-4-e4b-Q4_K_M`) |
+| `-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 |
@@ -150,11 +177,17 @@ Run `/help` inside a session for the full list. Commonly used:
 - `/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
+- `/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
+- `/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
@@ -169,7 +202,72 @@ Run `/help` inside a session for the full list. Commonly used:
 - `/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)
 
@@ -227,30 +325,33 @@ Run `/help` inside a session for the full list. Commonly used:
 | 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-4o-mini` *(default)*, `gpt-4o`, `o3-mini` | **Ultra-Cheap** (~$0.15 / 1M input) | [Docs](https://platform.openai.com/docs) • [API Ref](https://platform.openai.com/docs/api-reference) | `OPENAI_API_KEY` |
-| **Google Gemini** | `gemini-2.5-flash` *(default)*, `gemini-2.5-flash-lite`, `gemini-2.5-pro`, `gemini-3.1-pro` | **Ultra-Cheap** ($0.10 / 1M in, 1M-2M context) | [Docs](https://ai.google.dev/docs) • [API Ref](https://ai.google.dev/api) | `GEMINI_API_KEY` |
-| **Groq** | `llama-3.3-70b-versatile` *(default)*, `llama-3.1-8b-instant`, `gpt-oss-120b` | **LPU Ultra-Fast** ($0.05 - $0.59 / 1M in) | [Docs](https://console.groq.com/docs/quickstart) • [API Ref](https://console.groq.com/docs/api-reference) | `GROQ_API_KEY` |
-| **DeepSeek** | `deepseek-chat` *(default, V3)*, `deepseek-reasoner` *(R1 CoT)* | **Ultra-Low Cost** ($0.14 - $0.27 / 1M in) | [Docs](https://api-docs.deepseek.com) • [API Ref](https://api-docs.deepseek.com/api/create-chat-completion) | `DEEPSEEK_API_KEY` |
-| **OpenRouter** | `google/gemini-2.5-flash`, `deepseek/deepseek-chat`, `deepseek/deepseek-r1`, `meta-llama/llama-3.3-70b-instruct`, `qwen/qwen-2.5-72b-instruct`, `:free` | **Flexible Aggregator** (Free & Paid) | [Docs](https://openrouter.ai/docs/quick-start) • [API Ref](https://openrouter.ai/docs/api_reference/overview) | `OPENROUTER_API_KEY` |
+| **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-4o-mini
-npm run kiku-agent -- --provider gemini --model gemini-2.5-flash
-npm run kiku-agent -- --provider groq --model llama-3.1-8b-instant
-npm run kiku-agent -- --provider openrouter --model google/gemini-2.5-flash
+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
-/provider use groq llama-3.1-8b-instant            # Switch provider and model in one command
+/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
-/model use gpt-4o-mini                             # Switch active model on current 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.
 
 ---
 
@@ -262,7 +363,19 @@ The package ships a Model Context Protocol server exposing the catalog as tools,
 # 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 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:
@@ -273,7 +386,9 @@ The production deployment exposes a stateless Streamable HTTP endpoint at `https
 /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.
+`/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`.
 
 ---
 
@@ -294,23 +409,194 @@ Copy `.env.example` → `.env` (parsed automatically when the CLI runs; only uns
 | `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
+## 🧭 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`.
 
-# Run unit tests (agent + MCP, no LM Studio required)
-npm test
+### 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.
 
-# Run API verification tests against localhost:3000
-powershell -ExecutionPolicy Bypass -File test_api.ps1 -BaseHost localhost:3000
-```
+- **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)
+
+### 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
+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.
+
+## 🗃️ Data architecture & gotchas
+
+- **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.
+
+---
+
+## 🧱 Project structure
+
+```
+├── 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
+```
+
+---
+
+## 🧰 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.
+
+**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.
+
+**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).