ui-chan-mcp 0.5.0

package/docs/CLIENTS.md

@@ -0,0 +1,110 @@
+# クライアントへの入れかた
+
+> **どのアプリに、何が書き込まれるのかを知りたいとき**に読みます。
+> 入れるだけなら [../README.md](../README.md) で足ります。
+
+---
+
+## `01` 対応クライアント
+
+| id | クライアント | 書き込み先 |
+|---|---|---|
+| `claude-code` | Claude Code（MCPサーバ） | `claude mcp add -s user` |
+| `claude-code-plugin` | Claude Code プラグイン（`/talk` `/mode` 等のスキル・サブエージェント・EventCueフック） | `~/.claude/plugins`（インストール後にクローンへ symlink 化） |
+| `claude-desktop` | Claude Desktop | `claude_desktop_config.json` |
+| `opencode` | OpenCode | `~/.config/opencode/opencode.json`（MCP＋EventCueプラグイン） |
+| `cursor` | Cursor | `~/.cursor/mcp.json` |
+| `vscode` | VS Code (Copilot Chat) | `User/mcp.json` |
+| `hermes` | Hermes Agent | `~/.hermes/config.yaml` の `mcp_servers:`＋`~/.hermes/plugins/ui-chan/`（EventCue。`HERMES_HOME` / `UI_CHAN_HERMES_CONFIG` で変更可） |
+
+一覧に無いクライアントには `ui-chan print <id>`（引数なしなら汎用の stdio 設定）が
+貼り付け用のスニペットを出します。新しいホストへの対応は `tools/setup/clients.mjs` に
+1エントリ追加するだけで、インストーラを書き足す必要はありません。
+
+登録される起動コマンドは、どのクライアントでも同じです。
+
+```
+<パッケージ>/bin/ui-chan-node  <パッケージ>/dist/mcp-server.js
+```
+
+`bin/ui-chan-node` は node を自力で探して exec するランチャです。GUI から起動される
+クライアント（Claude Desktop など）は launchd の最小 PATH しか持たず、Homebrew や nvm の
+`node` が見えないため、`"command": "node"` と書くと**何も出さずに起動失敗**します。
+
+
+---
+
+## `02` ui-chan コマンド
+
+```bash
+ui-chan                      # 対話セットアップ
+ui-chan install claude-desktop opencode   # 指定クライアントへ登録（--all で全部）
+ui-chan uninstall --all      # 全クライアントから解除（ユーザーデータは残る）
+ui-chan uninstall --all --purge           # ~/.ui-chan ごと消す
+ui-chan doctor               # 状態チェック
+ui-chan print opencode       # 設定スニペットだけ表示
+ui-chan home                 # ユーザーデータの場所
+ui-chan start / stop         # マスコットの起動・停止
+ui-chan update               # 最新版にする（--check で確認だけ）
+```
+
+**登録した時点で完了です。** アプリと VoiSona Talk はセッション開始時に自動起動し、人格は
+MCP のハンドシェイク（`instructions`）に乗って渡ります。人格ファイルを貼り付ける作業はありません。
+
+マスコット右上のつまみを開くと、接続中のセッション（クライアント名とプロジェクト名）と操作が出ます。
+
+---
+
+## `03` 複数のコピーが入っている場合
+
+npm 版を入れたあとに開発用のクローンを作る、という流れはよくあります。**両方あっても構いません。**
+どちらが動くかはクライアントの設定に書かれたパスだけが決めるので、
+
+- `ui-chan use` … 登録済みのクライアントを、**そのコマンドを打ったコピー**へ向け直す
+- `ui-chan doctor` … いま動いているコピーと、各クライアントがどこを指しているかを表示。
+  ズレていれば警告する
+
+なお、アプリ本体は同時に1つしか起動できません（ポートの取り合いになるため）。
+切り替えたら `ui-chan stop` してから起こし直してください。
+
+---
+
+## `04` プラグインとコネクタの違い
+
+| | MCPサーバ（コネクタ） | プラグイン |
+|---|---|---|
+| ツール（`set_cue` ほか） | ○ | ✕ |
+| 人格（ハンドシェイクで注入） | ○ | ○（SessionStart フック） |
+| アプリ・音声エンジンの自動起動 | ○ | ○ |
+| `/talk` `/mode` `/beam` `/eli14` | ✕ | ○ |
+| サブエージェント（talk / mode） | ✕ | ○ |
+| 作業への自動リアクション（EventCue） | ✕ | ○ |
+
+**EventCue** は、セッション中に起きたこと（コマンドの失敗、ターンの終了、サブエージェントの
+往復など）に反応して自動で再生される演目です。`ui-chan install <id>` が MCP 登録と同時に配置します。
+
+| ホスト | 状態 |
+|---|---|
+| Claude Code | ✅ 実機で確認済み |
+| OpenCode | 実装済み・**未検証**（`event` / `tool.execute.*` フック） |
+| Hermes Agent | 実装済み・**未検証**（Python プラグイン） |
+
+未検証のものは、設定への書き込みと構文までは確認済みですが、実際に発火するところまでは
+確認できていません。試して問題があれば [Issue](https://github.com/Uncle-Peke/ui-chan-mcp/issues) へ。
+
+フック側が決めるのは「**何が起きたか**」だけです。セリフ・重み・クールダウン・好感度ゲートは
+`ui-chan.config.json` の `eventCues` にあるので、ホストが違っても反応は同じですし、
+セリフを直すのに JavaScript を触る必要はありません。
+
+以前はプラグインが MCP サーバも兼ねていましたが、プラグイン文脈の外では設定中の
+`${CLAUDE_PLUGIN_ROOT}` が展開されず**必ず起動に失敗する**ため、役割を分けました。
+MCP の登録はどのクライアントでも `ui-chan install <id>` に統一されています。
+Claude Code で全部入りにするなら `ui-chan install claude-code claude-code-plugin`。
+
+Claude Desktop はプラグインの台帳を Claude Code と共有しますが、**プラグイン同梱の MCP サーバは
+起動しません**（実測）。Desktop では「スキルはプラグインから、ツールと人格はコネクタから」という
+組み合わせになります。
+
+---
+
+<sub>次に読むなら [TROUBLESHOOTING.md](TROUBLESHOOTING.md)（繋いだのに動かないとき） / [TOOLS.md](TOOLS.md)（エージェントから何ができるか）</sub>

package/docs/CUE_AUTHORING.md

@@ -0,0 +1,76 @@
+# Cue を書く / 設定を変える
+
+> **新しい表情（Cue）を足すとき**と、**設定を調整するとき**に読みます。
+> 使えるレイヤー名の早見表は [PSD_LAYERS.md](PSD_LAYERS.md)、カタログ全体の方針は [design/CUE_CATALOG.md](design/CUE_CATALOG.md)。
+
+---
+
+## `01` Cue（cues/）
+
+見た目＋声のセットは **`cues/<Cue名>.json` に 1 Cue = 1 ファイル**で管理します
+（`cue.schema.json` 準拠）。ファイル名がそのまま `set_cue` の `cue` 名になり、ファイルを追加すれば
+新しいCueが増えます。継承なし・完全に自己完結（同じレイヤー指定が複数ファイルに重複してもよい）。
+**保存すると即時リロード**され、表示中のCueにもすぐ反映されるので、アプリを再起動せずに調整できます。
+
+```json
+{
+  "select": ["!眉/*上がり", "!目/*にっこり2", "!口/*あは", "!頬・顔色/*頬2"],
+  "blink": false,
+  "voice": {
+    "style_weights": { "Happy": 0.7, "Bashful": 0.3 }
+  }
+}
+```
+
+- `select / show / hide` — 生の PSD レイヤーパス指定（全Cue共通の `cues/default.json` に上書きされる
+  差分だけ書けばよい）。顔・腕・エフェクトを区別せず、そのCueに必要なレイヤーパスを並べるだけでよい
+- `blink` — まばたきの有効化（目が開いているCueのみ true 推奨）
+- `voice.style_weights` — スタイル名 → 重みのオブジェクト。省略すればデフォルトの声
+- `voice.alp` / `voice.huskiness` — このCue固有の声色パラメータ（VoiSona の `global_parameters` にそのまま渡る）
+- 強さ違い（例: 「激おこ」）は intensity ではなく別ファイル（例 `gekioko.json`）として作る
+- JSON が壊れている、または `cue.schema.json` に適合しないファイルはスキップされ、`get_state` の
+  `warnings` に出ます
+- `cues/default.json` は全Cue共通の下地（旧`config.base`＋腕の基本ポーズに相当）で、他のCueと
+  同じ形式の1ファイル。`set_cue`はこの`default`のdirectivesの上に指定されたCueのdirectivesを重ねて合成する
+- `description`（任意） — このCueがどんな場面・気持ちを表すかの短い説明。`set_cue`の実行には一切
+  使われず、`persona` MCPプロンプトが起動のたびに`cues/`の中身から動的にAI向けカタログを生成する
+  ためだけに読まれる（手書きの早見表を持たないので、Cue追加時にドキュメント更新を忘れてズレる、
+  ということが起きない）
+- `internal`（任意・真偽値） — `true`にすると、そのCueはAI向けカタログから除外される（`set_cue`で
+  直接呼べば動作はする）。IdlingCueが内部的に組み立てるための部品Cue（`cues/idling_*.json`）に付与
+
+Cue選定・PSDレイヤー名カタログなど、**新規Cue制作のための人間向け参照ドキュメント**は
+`docs/PSD_LAYERS.md` を参照。実行時にもAIのコンテキストにもロードされない（`context/`ではなく
+あえて`docs/`に置いている）。
+
+---
+
+## `02` 設定（ui-chan.config.json）
+
+- `assetsDir` — PSD を探すディレクトリ（最初に見つかった `.psd` を使用）
+- `window` — ウィンドウサイズ・画面端からのマージン
+- `exitAfterLastAgentSec` — 最後のエージェントが切断してから終了するまでの秒数（既定 60、`0` で無効）。
+  アプリは detached で起動するため、これが無いとクライアントを閉じても残り続ける。
+  猶予を置くのは、Claude Code の再起動による一時的な切断で消えないようにするため
+- `cuesDir` — Cueのディレクトリ（デフォルト `cues`）
+- `idle.idlingCues` — アイドル中に自発的に再生される**IdlingCue**（Cue＋任意のセリフのステップ列）のプール。
+  `items[].steps[]`は`{ cue?, text?, reading?, holdMs? }`で、`cue`を省略すると直前のCueを維持する。
+  各 IdlingCue は `weight`（出やすさ、デフォルト 1）、`minAffinity`（必要な好感度）、`maxAffinity`（上限好感度）を持てる。
+  無言の仕草（あくび、きょろきょろなど）は `weight` を高く、レアな独り言や高好感度専用セリフは `weight` を低く／`minAffinity` を高く、低好感度専用の冷たい反応は `maxAffinity` を低く設定する。
+- `lipSync` — リップシンク設定。`mouths` は母音（a/e/i/o/u/n）→ 口レイヤー名、`charsPerSec` は口を
+  動かす速度、`audioPollMs`（デフォルト33）は音声駆動リップシンクが再生位置をチェックする間隔。
+  読みのかなを母音に変換して口形を切り替える。漢字など読めない文字はパクパク
+  （開閉交互）にフォールバック。発話終了時・無音区間は `n`（閉じ口）に自動復帰
+- `speech` — `set_cue`の`duration_ms`省略時の表示時間算出パラメータ。テキスト駆動は
+  `baseMs + 文字数*msPerChar` を `minMs`〜`maxMs` にクランプ、音声駆動は合成音声の長さ +
+  `audioPaddingMs`（`audioMinMs`床）
+- `ambient` — レンダラーのBlink（`blinkMinIntervalMs`/`blinkMaxIntervalMs`/`blinkDurationMs`）の
+  タイミング。VISION.mdの語彙でBlinkはCue/Idling外で唯一独立ループする演出なので、IdlingCueとは
+  別枠でレンダラー側に残る
+
+レイヤーパスは `/` 区切りで PSD のレイヤー名と完全一致。存在しないパスは無視され、
+`get_state` の `warnings` に報告されます（別 PSD への差し替えを安全にするため）。
+
+---
+
+<sub>次に読むなら [PSD_LAYERS.md](PSD_LAYERS.md)（レイヤー名を引く） / [TTS.md](TTS.md)（声色の指定）</sub>

package/docs/DEVELOPMENT.md

@@ -0,0 +1,129 @@
+# 開発ガイド
+
+> **ういちゃんMCP そのものを直すとき**に読みます。設計判断とその理由は [../CLAUDE.md](../CLAUDE.md)、用語は [../VISION.md](../VISION.md) に。
+
+---
+
+## `01` 開発の準備
+
+```bash
+git clone https://github.com/Uncle-Peke/ui-chan-mcp.git && cd ui-chan-mcp
+npm install          # 依存の取得 + ビルド（prepare で dist/ まで）
+npx ui-chan          # 対話セットアップ
+npx ui-chan use      # クライアントの参照先をこのクローンに向ける（npm 版も入れている場合）
+```
+
+`npx ui-chan doctor` が「このコピー」と、各クライアントがどのコピーを指しているかを表示します。
+**npm 版とクローンを同時に入れても構いません** — どちらが動くかはクライアントの設定に
+書かれたパスで決まり、`ui-chan use` を打ったコピーが担当になります。
+
+---
+
+## `02` コマンド
+
+| コマンド | 説明 |
+|---|---|
+| `npx ui-chan` | 対話セットアップ（TUI） |
+| `npx ui-chan update` | 本体を最新にして再ビルド（`--check` で確認のみ、`--branch <名前>` で追従先指定） |
+| `npx ui-chan use` | 登録済みクライアントの参照先を「このコピー」に切り替える |
+| `npm run doctor` | セットアップの事前チェック（＝`ui-chan doctor`） |
+| `npm run app` / `stop` / `restart` | Electron アプリの起動／終了／再起動 |
+| `npm run build` | `src/` を `dist/` にビルド（`npm install` 時に自動実行） |
+| `npm run editor` | Cue エディタ「雨衣ちゃんのデバッグルーム」 |
+| `npm run dump-psd -- assets/foo.psd` | PSD レイヤー構造のダンプ |
+| `npm run validate-cues` | `cues/*.json` のスキーマ検証 |
+| `npm run lint` / `lint:fix` / `format` | Biome |
+| `node tools/mcp-test.mjs` | MCP stdio 経由の E2E テスト |
+
+---
+
+## `03` パッケージとユーザーデータ
+
+**アップデートしても壊れない**のはこれのおかげ。
+
+| | 場所 | 中身 | 更新時 |
+|---|---|---|---|
+| パッケージ | クローン／`node_modules` | コード・同梱Cue・人格・設定の既定値 | **まるごと入れ替わる** |
+| ユーザーデータ | `~/.ui-chan/`（`UI_CHAN_HOME` で変更可） | PSD・`.env`・`config.json`・自作Cue・人格の上書き | **触られない** |
+
+上書きしたいものだけ置けば済みます。全部を複製する必要はありません。
+
+| 対象 | 解決のしかた |
+|---|---|
+| `config.json` | 同梱の設定に**深いマージで上書き**。3行だけ書いても、後から増えた項目は継承される |
+| `cues/` | 同梱と**両方読み込み**、同名はユーザー側が勝つ |
+| `context/` | 同じくファイル名単位。`persona/ui-chan.md` も置けばそちらが使われる |
+| `assets/` | 立ち絵。同梱できないため実質ここだけ |
+| `.env` | 環境変数があればそちらが優先 |
+
+---
+
+## `04` スクリーンショットを撮る
+
+マスコットのウィンドウは透過なので、そのまま撮ると白以外の場所に置けない画像になります。
+`ui-chan shot` は**撮る瞬間だけ背景を敷いて**から撮ります。
+
+```bash
+ui-chan shot                      # ~/.ui-chan/ui-chan-shot.png（背景 light）
+ui-chan shot hero.png dark        # ファイル名と背景を指定
+ui-chan shot x.png "#1a1926"      # CSS の値をそのまま渡してもいい
+```
+
+背景のプリセットは `light` / `dark` / `desk` / `white`。それ以外の文字列は CSS の
+`background` にそのまま渡されるので、グラデーションでも画像でも指定できます。
+README に載せている画像もこれで撮っています。
+
+---
+
+## `05` 変更が反映されるタイミング
+
+| 直したもの | 反映 |
+|---|---|
+| `cues/*.json` | **保存した瞬間**（ホットリロード） |
+| `ui-chan.config.json` | アプリの再起動 |
+| `persona/*.md`・`context/*.md` | 次のセッション（またはプロンプト `persona` の再実行） |
+| `src/**` | `npm run build` → アプリ再起動。**MCP サーバはセッション開始時のコードを抱えたまま動く**ので、繋ぎ直すかセッションを開き直す |
+
+レンダラ（`src/renderer/`）は tsc だけでは反映されません。esbuild が要るので `npm run build` を使ってください。
+
+---
+
+## `06` アーキテクチャ
+
+MCP サーバは薄いブリッジで、**状態はすべて Electron アプリ側に一元化**されています。
+複数のエージェントが同時に繋いでも状態が食い違いません。
+
+```mermaid
+flowchart LR
+  agent["エージェント<br/>(Claude Code 等)"]
+  mcp["dist/mcp-server.js<br/>ステートレスなブリッジ"]
+
+  subgraph app["Electron アプリ (dist/app/main.js)"]
+    direction TB
+    state["UiChanState<br/>発話キュー・好感度・アイドル"]
+    tts["VoiSonaTalkClient<br/>音声合成"]
+    renderer["レンダラ<br/>PSD合成・吹き出し・口パク"]
+  end
+
+  voisona["VoiSona Talk<br/>REST API :32766"]
+
+  agent -- "stdio (MCP)" --> mcp
+  mcp -- "WebSocket :8123" --> state
+  mcp -. "未起動なら自動起動" .-> app
+  mcp -. "未起動なら自動起動" .-> voisona
+  state --> tts
+  tts -- "WAV + 音素タイミング" --> renderer
+  tts <--> voisona
+  state -- "IPC (RenderCommand)" --> renderer
+```
+
+- **ポート** — `ui-chan.config.json` の `port`、または環境変数 `UI_CHAN_PORT`
+- **自動起動** — アプリはセッション開始時（SessionStart フック）と各ツール呼び出し時に、
+  VoiSona Talk は MCP 起動時と `set_cue` のたびに、落ちていれば起こし直されます
+- **エージェント名** — MCP クライアント情報から自動取得（`UI_CHAN_AGENT_NAME` で上書き可）
+
+より詳しい実装のガイドは [CLAUDE.md](../CLAUDE.md) を参照。
+
+---
+
+<sub>次に読むなら [../CLAUDE.md](../CLAUDE.md)（実装ガイド） / [STYLE.md](STYLE.md)（ドキュメントを書くとき）</sub>

package/docs/PERSONA.md

@@ -0,0 +1,61 @@
+# 人格の注入
+
+> **性格や口調を変えたいとき**、および「なぜ繋いだだけでキャラクターが乗るのか」を
+> 知りたいときに読みます。
+
+---
+
+## `01` 人格はどこにあるか
+
+MCP が渡せるのはツール（＝身体）だけです。**キャラクターの人格は、エージェント側の
+コンテキストに文章として入れる**必要があります。置き場所は2つ。
+
+| 場所 | 中身 |
+|---|---|
+| `persona/ui-chan.md` | 基本人格とツール使用方針（`reading` を必ず付ける、セリフは1〜2文で区切る、など）。`personaFile` で変更可 |
+| `context/*.md` | 追加コンテキスト。`SOUL.md`（価値観・内面）、`VOCABULARY.md`（語彙・口癖・NGワード）、`AFFINITY.md`（好感度の機微）。**ファイル名順に全部**読み込まれます |
+
+`~/.ui-chan/` 側に同じ名前で置けば、同梱のものを上書きできます。パッケージを更新しても
+消えません。
+
+> [!IMPORTANT]
+> **`context/` に人間向けの資料を置かないでください。** ここは中身を問わず丸ごと AI に
+> 注入される場所です。PSD レイヤーパスの一覧のような、AI が読んでも意味のないものを置くと、
+> 毎セッション無駄なトークンを食います。制作用の資料は `docs/` へ
+> （[PSD_LAYERS.md](PSD_LAYERS.md) がその例）。
+
+利用できる Cue の一覧は `context/` には**書きません**。`cues/*.json` の `description` から
+起動のたびに生成して渡すので、手で書いた一覧が古くなることがありません。
+
+---
+
+## `02` どうやって届くか
+
+3つの経路があり、上ほど手間がかかりません。**どれも同じ本文**（`buildPersonaText()`）を配ります。
+
+| | 経路 | 対象 | いつ |
+|:---:|---|---|---|
+| 1 | MCP ハンドシェイクの `instructions` | **すべての MCP クライアント** | 接続時に自動。何もしなくてよい |
+| 2 | SessionStart フック | Claude Code（プラグイン導入時） | セッション開始時に自動 |
+| 3 | MCP プロンプト `persona` | すべての MCP クライアント | 手動。Claude Code なら `/mcp__ui-chan__persona` |
+
+3 はファイルを編集したあとの読み込み直しに使います。呼ぶたびにファイルを読むので、
+編集が即座に反映されます。
+
+> [!TIP]
+> 1 と 2 の両方が効いていると、同じ人格が二重に入ります。無駄だと感じたら
+> `UI_CHAN_NO_PERSONA_INSTRUCTIONS=1`（サーバ側）か `UI_CHAN_NO_PERSONA_HOOK=1`（フック側）で
+> 片方を止められます。
+
+---
+
+## `03` 別のキャラクターにする
+
+`persona/` と `context/` を書き換え、PSD に合わせて `cues/` とレイヤー設定を作り直します。
+どれも `~/.ui-chan/` 側に置けば上書きになるので、同梱物を削る必要はありません。
+
+手順は [CUE_AUTHORING.md](CUE_AUTHORING.md) を参照してください。
+
+---
+
+<sub>次に読むなら [TOOLS.md](TOOLS.md)（人格が使うツール） / [../CLAUDE.md](../CLAUDE.md)（実装の詳細）</sub>

package/docs/PSD_LAYERS.md

@@ -0,0 +1,123 @@
+# PSD レイヤー早見表
+
+> **Cue を書くときに「どのレイヤー名を指定すればいいか」を引く表**です。書式は [CUE_AUTHORING.md](CUE_AUTHORING.md)。
+
+---
+
+## `01` 使い方の基本（Cue制作者向け）
+
+- 場面に合う Cue 名を選んで `set_cue({ cue: "emo_joy", text: "やったー！", reading: "やったー！" })`
+- 無言で見た目だけ変えたいときは `text` を省略できる
+- 声の抑揚を1行だけ変えたいときは `pitch`/`speed`/`volume`/`intonation` を渡す（Cueに焼き込まれた
+  `voice.style_weights`/`alp`/`huskiness` の上にアドリブとして重なる）
+- 存在しない Cue 名を指定すると `default` にフォールバックし、結果に `note` が付く
+- 強さ違いは別の Cue 名（`emo_anger`→`emo_anger_hi`、`emo_joy`→`emo_joy_hi` のように）。intensityパラメータは無い
+- 新しいCueを作ったら、必ず`description`フィールドに「どんな場面・気持ちのCueか」を短く書く
+  （これが唯一、AIに伝わる経路）
+- AIに直接選ばせたくない、IdlingCue専用の内部部品Cueには`"internal": true`を付ける（後述）。
+  ファイル名のprefix等の暗黙の命名規則には頼らない — 明示的なフラグでのみ判定する
+
+---
+
+---
+
+## `02` 新規Cue制作のためのパーツ・カタログ
+
+`cues/*.json` の `select`/`show`/`hide` には生のPSDレイヤーパスをそのまま書く。以下は
+そのパスを組み立てるための参照表（旧 `set_face`/`set_pose` が使っていたスロット分類を、
+制作用メモとして残したもの。実行時のツールやconfigとしては存在しない）。
+
+### 目は3階層になっている
+- `!目/*<形>` … 目まるごとの形（ジト目・閉じ・上向き…）。`基本目セット` を選ぶと下2つで詰められる
+- `!目/*基本目セット/!白目/*<白目>` … 白目のかたち（`基本目セット` のときだけ効く）
+- `!目/*基本目セット/*<視線>` … 黒目の向き・種類（`基本目セット` のときだけ効く）
+
+**注意**: `!目/*基本目セット/*<視線>`（ネストした選択）と `!目/*<形>`（`!目`直下の兄弟）は、
+どちらも最終的に同じ `!目` レベルのラジオ排他に巻き込まれる。同じCueのselect配列内で両方を
+指定すると、後に書いた方が親ごと勝ち、先に書いた方（とその配下）は丸ごと非表示になり無意味に
+なる（`emo_anger_hi.json`等で実際に起きていた事故。同じ軸を2回指定しないこと）。
+
+### `eyes` — 目まるごと（`!目/*...`、13）
+| 名前 | どんな目 |
+|---|---|
+| `基本目セット` | 標準の目。これを選ぶと白目/視線で詰められる |
+| `ジト目` | 半目のジト目。塩鮭・呆れ・「ふ〜ん」 |
+| `○○` | まん丸見開き。びっくり |
+| `ぐるぐる` | ぐるぐる目。混乱・目が回る |
+| `＞＜` | ぎゅっと閉じた `><`。爆笑・痛い・きゃっきゃ |
+| `ーー` | 一本線の閉じ目。眠い・真顔・悟り |
+| `閉じ` | 穏やかに閉じた目。安らぎ・まばたき |
+| `にっこり1` | 笑い目（控えめ） |
+| `にっこり2` | 笑い目（大きめ・満面） |
+| `細目` | 細めたドヤ目。にやり・自信家 |
+| `細目ハート` | 細めた目＋ハート。ういおじ・でれ |
+| `コンセント` | 光の消えた目（コンセント顔）。無・虚無・真顔ネタ |
+| `上向き1` | 上目遣い（考え中） |
+| `上向き2` | 上目遣い（強め・遠い目） |
+
+### 白目（`!目/*基本目セット/!白目/*...`、3）
+`白目基本` / `白目ジト`（半目・呆れの詰め） / `白目見開き`（かっと見開いた白目、衝撃）
+
+### 視線（`!目/*基本目セット/*...`、10）
+`正面1`(デフォルト) / `正面2` / `カメラ目線1` / `カメラ目線2` / `目そらし1` / `目そらし2`（強め、照れ・
+気まずい） / `きらきら目`（ワクワク・尊い） / `ハート目`（mix_joy_trust） / `ぐるぐる目` / `縮小`（恐怖・戦慄）
+
+### 口（`!口/*...`、22）
+`ん`=閉じ(標準) / `あ``え``お`=小さく開く / `お`=すぼめ丸口 / `あは`=笑い / `あはー`=大笑い /
+`えへ`=てへ照れ笑い / `ほほえみ`=にっこり閉じ / `にし`=にやり(ドヤ) / `むふ`=含み笑い / `ほわ`=とろけ /
+`ほあー`=ほへ〜(脱力) / `ゆ`=きゅっ(照れ) / `んー`=思案のハミング / `む`=むっ(ふくれ) / `え`(えー)=不満の口 /
+`えあー`=あわあわ(困り) / `いー`=歯を食いしばる(力み・怒り) / `おおー`=感嘆の大口 / `おー`=おお /
+`△`=三角口(緊張) / `うわー`=大口(絶叫・泣き) / `お`(小)=ぽかん
+
+### 眉（`!眉/*...`、5）
+`普通`(標準) / `上がり`=上げ眉(驚き・喜び) / `困り`=困り眉(下がり) / `怒り1`=怒り / `怒り2`=激おこ
+
+### 頬・顔色（`!頬・顔色/*...`、7）
+`頬1`(標準) / `頬2`(血色よい) / `頬赤め1`=照れ赤 / `頬赤め2`=真っ赤 / `青ざめ1`=青ざめ /
+`青ざめ2`=真っ青 / `(非表示)`=頬色なし
+
+### 重ねエフェクト（`show`/`hide` で指定）
+`!汗・涙/汗1`=汗1滴(焦り) / `!汗・涙/汗2`=汗だく(パニック) / `!汗・涙/涙`=涙 / `!頬・顔色/かげり`=顔の影(暗い・絶望・げんなり)
+
+### 腕（`!奥の腕/*...` / `!手前の腕/*...`）— 現在使用中のCueが焼き込んでいる組み合わせ
+| 腕の見た目 | 使っているCue |
+|---|---|
+| 通常（`default`に焼き込み） | 全Cue共通の下地 |
+| 傘さし | `pose_umbrella` |
+| 両手ばんざい | `pose_banzai` |
+| あご手（考え中） | `pose_think` |
+| 腕組み | `pose_smug_arms`, `pose_arms_crossed` |
+| 腰に手 | `pose_smug_hips` |
+
+以下は旧 `set_pose` カタログに存在したが、現在どのCueにも焼き込まれていない腕の組み合わせ。
+新しいCueが必要になったときの生レイヤーパスの参照用（実在確認はPSD側で行うこと）：
+
+| 名前（旧pose名） | 生レイヤーパス | 使いどころの目安 |
+|---|---|---|
+| `call` | `!奥の腕/*呼びかけ` + `!手前の腕/*呼びかけ` | 登場・「はいどうも〜」・挨拶 |
+| `fist` | `!奥の腕/*基本` + `!手前の腕/*ぐっ` | やる気・気合い |
+| `point` | `!奥の腕/*基本` + `!手前の腕/*指さし手前` | 強調・ういビーム代用 |
+| `point_side` | `!奥の腕/*指さし横` + `!手前の腕/*基本` | 説明・案内・「あれ見て」 |
+| `mic` | `!奥の腕/*マイク` + `!手前の腕/*基本` | 配信・実況・発表 |
+| `palm_up` | `!奥の腕/*手のひら上` + `!手前の腕/*手のひら上` | どうぞ・提示・愛でる |
+| `mouth_cover` | `!奥の腕/*口元` + `!手前の腕/*基本` | くすっ・「すいませんねぇ」・しまった |
+
+> 注意: 傘（`pose_umbrella`）は吹き出しと干渉することがある。傘のときは長ゼリフを避けるか位置に注意。
+
+---
+
+---
+
+## `03` IdlingCue専用Cue（`idling_*`）
+
+`cues/idling_yawn_1〜3` / `idling_lookaround_1〜3` / `idling_ponder` / `idling_doze_1〜3` /
+`idling_giggle_1〜2` / `idling_sigh_1〜2` は、`ui-chan.config.json` の `idle.idlingCues`
+（あくび・きょろきょろ・ぼんやり・うたた寝・くすくす・ため息）が内部的に参照する、無言の一瞬の
+表情変化用Cue。他のCueと形式は同じだが、単体で場面に当てる想定ではなく複数ステップの一部として
+使うために作られている。全ファイルに`"internal": true`を明示しており、`buildCueCatalog()`が
+AI向けの一覧生成時にこのフラグを見て除外している（ファイル名が`idling_`で始まることは判定条件では
+ない。たまたま命名が揃っているだけ）。`set_cue`から直接呼んでも動作はするが、通常は呼ばない。
+
+---
+
+<sub>次に読むなら [CUE_AUTHORING.md](CUE_AUTHORING.md)（書式と保存先） / [design/CUE_CATALOG.md](design/CUE_CATALOG.md)（何を作るべきか）</sub>

package/docs/README.md

@@ -0,0 +1,43 @@
+# ドキュメント索引
+
+> **どのページを読めばいいか分からないとき**に見ます。
+> 入れて使うだけなら [../README.md](../README.md) で足ります。
+
+---
+
+## `01` 使う人向け
+
+| やりたいこと | 読むもの |
+|---|---|
+| 図解でセットアップを見る | [SETUP.html](SETUP.html) |
+| どのアプリに何が書き込まれるか知る | [CLIENTS.md](CLIENTS.md) |
+| 動かないので調べる | [TROUBLESHOOTING.md](TROUBLESHOOTING.md) |
+| 声を出す・調整する | [TTS.md](TTS.md) |
+| エージェントから何ができるか知る | [TOOLS.md](TOOLS.md) |
+
+---
+
+## `02` 作る人向け
+
+| やりたいこと | 読むもの |
+|---|---|
+| 開発を始める（準備・コマンド・全体像） | [DEVELOPMENT.md](DEVELOPMENT.md) |
+| コードを直す（設計判断と、その理由） | [../CLAUDE.md](../CLAUDE.md) |
+| 用語を確認する（Idling / Cue / EventCue …） | [../VISION.md](../VISION.md) |
+| 新しい表情（Cue）を足す | [CUE_AUTHORING.md](CUE_AUTHORING.md) → レイヤー名は [PSD_LAYERS.md](PSD_LAYERS.md) |
+| 性格・口調を変える | [PERSONA.md](PERSONA.md) |
+| Cueカタログの設計方針を知る | [design/CUE_CATALOG.md](design/CUE_CATALOG.md) |
+| **ドキュメントを書く・直す** | [STYLE.md](STYLE.md) |
+
+---
+
+## `03` ドキュメントではないもの
+
+> [!IMPORTANT]
+> `persona/` と `context/` の Markdown は**資料ではなく、AI に注入される設定**です。
+> 編集するとういちゃんの振る舞いが変わります。人間向けの制作資料をそこに置かないでください
+> （理由は [PERSONA.md](PERSONA.md)）。
+
+---
+
+<sub>ページの型・色の使い分け・口調のルールは [STYLE.md](STYLE.md) にあります。</sub>