kiku-agent 1.2.0 → 1.3.0

package/README.md

@@ -1,407 +1,459 @@
-<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
-```
-
----
-
-## 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
-# 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
-/model use gpt-5.6-luna                            # Switch active model on current provider
-```
-
----
-
-## Model Context Protocol (MCP)
-
-### 1. MCP Server (`kiku-mcp`)
-
-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, 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`).
-
-> [!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
-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 the CLI:
-/mcp connect kiku-remote https://jujingyi-kikuuu.vercel.app/mcp
-/mcp connect filesystem stdio npx -y @modelcontextprotocol/server-filesystem ./
-/mcp tools
-```
-
----
-
-## 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) |
-
-> [!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 or committed.
-
----
-
-## Web App & REST API
-
-### 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 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 OpenAPI specifications and interactive documentation:
-
-- **Base URL (prod):** `https://jujingyi-kikuuu.vercel.app/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
-```
-
-#### 🌟 Kiku Agent Showcase on `/api-docs`
-
-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.
-
-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.
-
----
-
-## Data Architecture & Gotchas
-
-> [!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
-
-**Agent won't start or stays in catalog-only mode**
-- 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 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 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.
+<div align="center">
+
+<img src="https://jujingyi-kikuuu.vercel.app/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-59) • [Cloud & Local Models](#multi-provider-cloud--local-models) • [MCP Integration](#model-context-protocol-mcp) • [Evaluation](#live-answer-evaluation) • [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`, 59 tools) and Model Context Protocol server (`kiku-mcp`, 58 tools) connecting to local LM Studio or cloud LLMs. |
+| **Stateful Memory Engine** | `server/agent/memory/` | Hierarchical run-scoped memory (`kiku/runs/{run_id}/...`), pointer-over-data rule, step checkpoints, and 4-tier context allocator. |
+| **Hybrid Meta-Search Engine** | `server/agent/websearch/` | Zero-key multi-engine search (DuckDuckGo, SearXNG, Jina), token bucket rate limiting, circuit breaker, SSRF defense, and RRF rank fusion. |
+| **Command Center Hub & Dev Suite** | `scripts/kikuHub.js`, `scripts/devAll.js` | Terminal interactive command center (`npm start`) and 3-tier dev environment (`npm run dev:all`: ports 3000, 3001, 3002). |
+| **VRAM & Hardware Engine** | `server/agent/vramService.js`, `src/lib/vram/` | Predictive VRAM footprint estimation, multi-stage memory bus width disambiguation, and offline database of 100+ accelerators. |
+| **NVIDIA Nsight Systems Profiler** | `scripts/profileNsys.js` | Automated GPU CUDA kernel, cuBLAS GEMM, FlashAttention, and memory bus bandwidth profiler with bottleneck diagnostics and GUI support. |
+
+> [!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.3.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
+```
+
+---
+
+## Features
+
+- **Autonomous ReAct Agent**: Equipped with **59 validated tools** covering catalog knowledge, live web search, news/encyclopedia discovery, YouTube audio playback, filesystem inspection, stateful memory checkpoints, entertainment analytics, and research workers.
+- **Stateful & Self-Reflective Memory Engine**: Hierarchical workspace (`kiku/runs/{run_id}/...`), pointer-over-data rule (>1,000 chars referenced to prevent context bloat), real-time step checkpoints (`checkpoint_step`, `record_failure`, `load_active_run`), post-run compaction into global reflections (`kiku/knowledge/reflections.md`), and 4-tier token budget allocation.
+- **Fault-Tolerant Hybrid Meta-Search**: Zero-key search combining DuckDuckGo, SearXNG, and Jina with token bucket rate limiting, circuit breakers, SSRF DNS pinning, multilingual query fan-out, and Reciprocal Rank Fusion (RRF).
+- **Predictive VRAM & Telemetry Engine**: Real-time GPU memory footprint estimation, context scaling ladder, multi-stage memory bus width disambiguation, sliding-window attention (SWA) KV cache modeling, and offline database of 100+ accelerators (`/vram`, `npm run vram:live`).
+- **NVIDIA Nsight Systems Profiling Engine**: Automated GPU CUDA kernel tracing, memory bandwidth saturation analysis, and CPU/PCIe bottleneck diagnostics (`npm run profile:nsys`). Captures cuBLAS GEMM, FlashAttention-2, RMSNorm, and RoPE kernels, calculates memory bus efficiency ($(\text{tok/s} \times \text{Model Size}) / \text{Bandwidth Peak}$), warns against PCIe thrashing, and exports executive Markdown summaries with optional GUI visualization (`--gui`).
+- **Interactive Evaluation & Performance Studio**: Standalone offline benchmark reports with zero-click auto-open browser execution, mobile-responsive layouts, live latency, Thai Buddhist Era (พ.ศ.) & duration normalizers, category partitioning (`npm run eval:split`), clamped `[0, 100]%` progress tracking, dedicated workbench on port 3001 (`npm run eval:ui`), automated anomaly row detection (`isAnomalyRow`), targeted one-click retry (`#btnRetry`), and AI benchmark executive summaries with strict thinking-block suppression.
+- **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.
+- **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 **58 tools** (55 agent tools + 3 compatibility aliases: `get_profile`, `get_timeline`, `search_gallery`), **8 resources**, and **7 prompt templates** for Claude Desktop, Cursor, and VS Code.
+- **Standalone Web Chat Portal**: Interactive browser chatbot (`/chat` or `/web` on port 3002 or in-process on port 3000) 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 59 registered tools |
+| `-s`, `--stats` | Print catalog overview statistics |
+| `-v`, `--verbose` | Verbose mode with reasoning output |
+| `--hub [filter]` | Launch Kiku Master Command Center hub dashboard |
+| `--portal [open\|api\|chat\|eval\|status]` | Inspect or open Port 3000 Web Portal SPA, REST API docs, or Eval Studio |
+| `--eval [ui\|dashboard\|validate\|quick\|split]` | Manage Eval Studio web UI, performance reports, benchmark validation, and category splitting |
+| `--vram [live\|compare\|ctx\|list\|tier]`, `--gpu` | Real-time VRAM budget, bus width, hardware tier & KV allocation monitor |
+| `npm run profile:nsys` | NVIDIA Nsight Systems GPU CUDA kernels & memory bus bottleneck analyzer (`--mode inference\|agent`, `--gui`) |
+| `--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
+- `/hub [filter]` — Show Kiku Master Command Center hub with hardware telemetry, system metrics, and command index
+- `/portal [open|api|chat|eval|status]` — Inspect or open local Web Portal SPA, REST API v1 docs, Web Chat, or Eval Studio (port 3000)
+- `/eval [ui|dashboard|validate|quick|run|judge|compare|gate|status]` — Interactive Eval Studio dashboard, report generation, and frozen ground truth benchmark suites
+- `/vram [live|compare|ctx|list|check|tier]` — Real-time VRAM budget, hardware classification tier, bus width disambiguation, context ladders, and pre-flight check
+- `/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 56 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 (59)
+
+Kiku Agent includes **59 validated tools** across 6 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, hybrid meta-search orchestrator (SearXNG, Jina), article extraction, raw webpage fetch, JSON parser, page screenshots, and REST API querying.
+- **Discovery & Analytics (11)**: Live news/RSS feeds, encyclopedia lookup, Chinese web portals, Chinese web image search (`search_web_images` for on-set stills, red carpet & press photos), Bilibili video search, music-platform search, YouTube transcripts, datetime utility, and entertainment/industry metrics.
+- **Music Player (15)**: YouTube streaming via `yt-dlp` & `ffmpeg`, playlist queue management, track playback controls, and volume mute/unmute.
+- **Filesystem & Stateful Memory (6)**: Directory listing, safe local file reader, archive statistics, plus **Hierarchical Memory Checkpoints**: `checkpoint_step` (record execution step and state), `record_failure` (capture error code and recovery path), and `load_active_run` (hydrate run context and memory pointers).
+- **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
+# 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
+/model use gpt-5.6-luna                            # Switch active model on current provider
+```
+
+---
+
+## Model Context Protocol (MCP)
+
+### 1. MCP Server (`kiku-mcp`)
+
+The package ships an official Model Context Protocol server exposing the Ju Jingyi encyclopedia as **58 tools** (55 agent tools + 3 compatibility aliases: `get_profile`, `get_timeline`, `search_gallery`), **8 resources**, and **7 prompt templates**. Live-web and Chinese tools are opt-in via `KIKU_MCP_ENABLE_WEB_TOOLS=true` and `KIKU_ENABLE_CN_WEB_TOOLS=true`:
+
+```bash
+# 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`).
+
+> [!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
+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 the CLI:
+/mcp connect kiku-remote https://jujingyi-kikuuu.vercel.app/mcp
+/mcp connect filesystem stdio npx -y @modelcontextprotocol/server-filesystem ./
+/mcp tools
+```
+
+---
+
+## Live Answer Evaluation
+
+A frozen catalog QA harness in `server/agent/eval/` runs **500 fixed multilingual cases** (350 catalog & reasoning + 150 security & red-teaming across 17 categories) through a fresh real `KikuAgent` per case on local LM Studio, recording answers, tool traces, latency, and token telemetry:
+
+```bash
+npm run eval:validate                 # Validate frozen 500-case corpus integrity
+npm run eval:quick                    # 3-case smoke run (needs LM Studio)
+npm run eval:ui                       # Launch visual Kiku Eval Studio workbench on port 3001 (/eval)
+npm run eval:dashboard                # Open interactive mobile-responsive HTML eval report in browser
+npm run eval:split                    # Split benchmark report into per-category JSON subsets
+npm run eval:run -- --suite catalog --out artifacts/eval/live.json
+npm run eval:run -- --suite all --judge-model google/gemma-4-e4b --gate --dashboard --save-as run1
+npm run eval:compare -- --baseline a.json --candidate b.json
+npm run eval:gate                     # Gate check against strict quality/security thresholds
+npm run eval:analyze                  # Deep category & token latency breakdown
+npm run eval:smoke:web
+npm run eval:calibrate
+```
+
+> [!NOTE]
+> The eval harness is dev-only and never published to npm (`package.json`
+> `files` ships `server/agent/*.js` but not the `eval/` subdirectory).
+> Features automatic answer normalization for Thai Buddhist Era years (พ.ศ. 2567 → 2024)
+> and song durations (`03:45` → `3:45`), along with clamped `[0, 100]%` progress tracking.
+> Full operator guide: `server/agent/eval/AGENTS.md`.
+
+---
+
+## 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_ENABLE_CN_WEB_TOOLS` | Set `true` to enable Chinese web search portals, Bilibili, and image search |
+| `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 or committed.
+
+---
+
+## Web App & REST API
+
+### Frontend & Ecosystem Services
+
+```bash
+# 3-tier development suite (runs SPA on 3000, Eval Studio on 3001, and Web Chat on 3002)
+npm run dev:all
+
+# Standard Vite dev server (API v1, Web Chat & Eval Studio work in-process on port 3000)
+npm run dev
+
+# Production build
+npm run build
+```
+
+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` (~4000 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` *(all endpoints work in-process alongside Vite)*
+- **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:** `http://localhost:3002/chat` *(or local in-process `http://localhost:3000/chat`)*
+- **Eval Studio:** `http://localhost:3001/eval` *(or local in-process `http://localhost:3000/eval`)*
+
+```bash
+curl https://jujingyi-kikuuu.vercel.app/api/v1/health
+```
+
+#### 🌟 Kiku Agent Showcase on `/api-docs`
+
+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.
+
+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.
+
+---
+
+## Data Architecture & Gotchas
+
+> [!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` (**656 unit/integration tests across 18 suites**) plus `npm run build`.
+
+---
+
+## 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 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 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 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.