kiku-agent 1.0.7 → 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.7.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.
 
 ---
 
@@ -151,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
@@ -170,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)
 
@@ -266,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:
@@ -277,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`.
 
 ---
 
@@ -298,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).

package/package.json

@@ -1,93 +1,96 @@
-{
-  "name": "kiku-agent",
-  "version": "1.0.7",
-  "description": "Kiku AI terminal agent and MCP server for Ju Jingyi knowledge, media, and career data.",
-  "type": "module",
-  "bin": {
-    "kiku-agent": "server/agent/cli.js",
-    "kiku-mcp": "server/mcp/stdio.js"
-  },
-  "exports": {
-    ".": "./server/agent/agentCore.js",
-    "./mcp": "./server/mcp/server.js",
-    "./tools": "./server/agent/tools.js"
-  },
-  "files": [
-    "server/agent/*.js",
-    "server/mcp/*.js",
-    "server/mcp/data/*.js",
-    "server/mcp/**/*.json",
-    "src/data/**/*.js",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=20.0.0"
-  },
-  "kikuUpdate": {
-    "channel": "stable",
-    "releaseSummary": [
+{
+  "name": "kiku-agent",
+  "version": "1.0.8",
+  "description": "Kiku AI terminal agent and MCP server for Ju Jingyi knowledge, media, and career data.",
+  "license": "GPL-3.0",
+  "type": "module",
+  "bin": {
+    "kiku-agent": "server/agent/cli.js",
+    "kiku-mcp": "server/mcp/stdio.js"
+  },
+  "exports": {
+    ".": "./server/agent/agentCore.js",
+    "./mcp": "./server/mcp/server.js",
+    "./tools": "./server/agent/tools.js"
+  },
+  "files": [
+    "server/agent/*.js",
+    "server/mcp/*.js",
+    "server/mcp/data/*.js",
+    "server/mcp/**/*.json",
+    "src/data/**/*.js",
+    "src/assets/images/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "kikuUpdate": {
+    "channel": "stable",
+    "releaseSummary": [
       "Updated production model defaults and live fallback resolution across cloud providers",
       "Hardened REST API key validation and isolated rate-limit probes",
       "Fixed discography filtering, MCP configuration isolation, and environment loading order",
       "Secured YouTube iframe messaging and expanded provider and API regression coverage"
-    ],
-    "releaseUrl": "https://www.npmjs.com/package/kiku-agent"
-  },
-  "keywords": [
-    "kiku",
-    "ju-jingyi",
-    "cli",
-    "ai-agent",
-    "mcp",
-    "model-context-protocol",
-    "lm-studio"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ThemeHackers/jujingyi_kikuuu.git"
-  },
-  "homepage": "https://jujingyi-kikuuu.vercel.app/",
-  "bugs": {
-    "url": "https://github.com/ThemeHackers/jujingyi_kikuuu/issues"
-  },
-  "license": "UNLICENSED",
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "dev": "vite",
-    "build": "vite build",
-    "preview": "vite preview",
-    "kiku-agent": "node server/agent/cli.js",
-    "kiku-mcp": "node server/mcp/stdio.js",
-    "kiku-ink": "npx tsx server/agent/ink/main.jsx",
-    "test": "node --test server/agent/tests/*.test.js server/mcp/tests/*.test.js"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
-    "clsx": "^2.1.1",
-    "framer-motion": "^12.4.7",
-    "lucide-react": "^1.16.0",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "tailwind-merge": "^3.0.2",
-    "zod": "^4.4.3"
-  },
-  "devDependencies": {
-    "@tailwindcss/vite": "^4.0.9",
-    "@types/react": "^19.0.10",
-    "@types/react-dom": "^19.0.4",
-    "@vitejs/plugin-react": "^4.3.4",
-    "ink": "^7.1.1",
-    "ink-select-input": "^6.2.0",
-    "ink-spinner": "^5.0.0",
-    "ink-text-input": "^6.0.0",
-    "tailwindcss": "^4.0.9",
-    "tsx": "^4.23.12",
-    "vite": "^6.2.0"
-  },
-  "allowScripts": {
-    "esbuild@0.25.12": true,
-    "esbuild@0.28.2": true
-  }
-}
+    ],
+    "releaseUrl": "https://www.npmjs.com/package/kiku-agent"
+  },
+  "keywords": [
+    "kiku",
+    "ju-jingyi",
+    "cli",
+    "ai-agent",
+    "mcp",
+    "model-context-protocol",
+    "lm-studio"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ThemeHackers/jujingyi_kikuuu.git"
+  },
+  "homepage": "https://jujingyi-kikuuu.vercel.app/",
+  "bugs": {
+    "url": "https://github.com/ThemeHackers/jujingyi_kikuuu/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "kiku-agent": "node server/agent/cli.js",
+    "kiku-mcp": "node server/mcp/stdio.js",
+    "kiku-ink": "npx tsx server/agent/ink/main.jsx",
+    "test": "node --test server/agent/tests/*.test.js server/mcp/tests/*.test.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "clsx": "^2.1.1",
+    "framer-motion": "^12.4.7",
+    "jpeg-js": "^0.4.4",
+    "lucide-react": "^1.16.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tailwind-merge": "^3.0.2",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.0.9",
+    "@types/react": "^19.0.10",
+    "@types/react-dom": "^19.0.4",
+    "@vitejs/plugin-react": "^4.3.4",
+    "ink": "^7.1.1",
+    "ink-select-input": "^6.2.0",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^6.0.0",
+    "tailwindcss": "^4.0.9",
+    "tsx": "^4.23.12",
+    "vite": "^6.2.0"
+  },
+  "allowScripts": {
+    "esbuild@0.25.12": true,
+    "esbuild@0.28.2": true
+  }
+}