@squadbase/vantage 0.5.3 → 0.6.1-dev.2d25e94

package/skills/vantage-slide/references/tokens.md

@@ -0,0 +1,87 @@
+# デザイントークンと書体
+
+## トークンの解決順
+
+スライドの色と書体は CSS カスタムプロパティ `--slide-*` から来ます。値は 3 段で解決されます:
+
+1. **`theme.css`（フレームワーク）** —— `--slide-bg: var(--background)` のように、アプリ自身の
+   トークンへの**別名**が張ってあります。CSS 変数は遅延解決なので、これだけでデッキは
+   アプリのライト / ダークの切り替えに自動で追従します
+2. **アプリの `styles.css`** —— アプリがトークンを上書きしていれば、デッキもそれに従います
+3. **`<SlideDeck theme={{ … }}>`** —— そのデッキのルートにインラインで書かれ、上の 2 つに勝ちます
+
+| プロパティ | CSS 変数 | 既定 |
+| --- | --- | --- |
+| `bg` | `--slide-bg` | `var(--background)` |
+| `fg` | `--slide-fg` | `var(--foreground)` |
+| `accent` | `--slide-accent` | `var(--primary)` |
+| `muted` | `--slide-muted` | `var(--muted-foreground)` |
+| `fontDisplay` | `--slide-font-display` | 日本語を含むシステムスタック |
+| `fontBody` | `--slide-font-body` | `var(--slide-font-display)` |
+| `sizeHero` | `--slide-size-hero` | `168px` |
+| `sizeBody` | `--slide-size-body` | `36px` |
+| `radius` | `--slide-radius` | `var(--radius)` |
+
+```tsx
+<SlideDeck theme={{ bg: "#0f172a", fg: "#f8fafc", accent: "#fbbf24" }}>
+```
+
+**使うときは変数で参照します** —— `color: "var(--slide-fg)"`、`fontSize: "var(--slide-size-hero)"`。
+`theme` に渡した値を直接書かないこと。変数経由にしておけば、`theme` を 1 行変えるだけでデッキ全体が
+追従します。
+
+**`theme` に無い色はプレーンな const に置く**（`const muted = "#94a3b8"`）。`theme` は
+「デッキの土台となる 3〜4 色」のためのもので、パレット全部を入れる場所ではありません。
+
+## ダークモード
+
+`theme` を渡さないデッキは、アプリのトークンをそのまま使います —— つまり `.dark` /
+`[data-theme="dark"]` が祖先に付いていればダークで描かれます。**明暗の両方を自分で管理する必要は
+ありません。**
+
+`theme` に具体的な色（`bg: "#0f172a"`）を書いた瞬間、そのデッキは明暗に追従しなくなります。
+これは意図的です —— 配色を決め打ちしたデッキは、どちらのモードでもその配色であるべきだからです。
+追従させたいなら `theme` を渡さないこと。
+
+## 書体
+
+**既定はシステムスタックで、まずこれを使ってください。** 日本語を含むスタックが最初から入っています。
+
+webfont が本当に必要なとき（ブランドフォント、あるいはシステムのカバーが薄い言語）:
+
+- **`<head>` に 1 回だけ、冪等に読み込む。** スライドコンポーネントの中でスタイルシートを描かないこと。
+  切り替え中は 2 枚のスライドが同時にマウントされ、pptx 書き出しでは全スライドが同時にマウントされます
+  —— コンポーネントの中で `<link>` を描くと `@font-face` の集合が**マウント数だけ**登録されます。
+  `.slide.tsx` のモジュールのトップレベルから 1 回だけ注入します:
+
+  ```tsx
+  const FONT_HREF = "https://fonts.googleapis.com/css2?family=...&display=swap"
+  const FONT_LINK_ID = "vantage-slide-font-june"  // デッキごとに違う id にする
+  if (typeof document !== "undefined" && !document.getElementById(FONT_LINK_ID)) {
+    const link = document.createElement("link")
+    link.id = FONT_LINK_ID
+    link.rel = "stylesheet"
+    link.href = FONT_HREF
+    document.head.appendChild(link)
+  }
+  ```
+
+- **実際に使うウェイトだけを列挙する。** 余分な 1 ウェイトが `@font-face` の数を倍にします。
+
+## webfont と pptx 書き出し —— ここが壊れやすい
+
+pptx 書き出しは、スライドを SVG の `foreignObject` の中でラスタライズします。この隔離された
+描画コンテキストでは:
+
+- **ローカルにインストールされたフォントはファミリ名で解決されます。** システムスタックなら
+  埋め込みは 1 バイトも要りません。既定のままなら何もしなくてよい、ということです
+- **webfont は data URL としてインライン化されていなければ使えません。** 書き出しは
+  `getFontEmbedCSS` で自動的にインライン化しますが、それには 2 つの条件があります:
+  - **同一オリジンか CORS が有効**であること（Google Fonts は CORS 有効）
+  - **サブセットしてあること。** 日本語の webfont は致命的です —— Noto Sans JP のフルセットは
+    100 を超える `unicode-range` の face を持ち、全部を base64 化しようとして書き出しが
+    タイムアウトするか、文字が豆腐になります。デッキの文字が固定なら Google Fonts の URL に
+    **`&text=<使う文字>`** を付けて、単一 face の小さなサブセットを要求してください
+
+**判断の目安**: 日本語のデッキで pptx を配る予定があるなら、**システムスタックのままにする**のが
+最も確実です。ブランドフォントが要件なら `&text=` のサブセットにすること。

package/skills/vantage-slide/references/transitions.md

@@ -0,0 +1,196 @@
+# ページ間トランジション（`SlideTransition`）
+
+スライドが切り替わるときの enter / exit アニメーションです。**既定はありません** ——
+宣言しない限りページはスナップで入れ替わり、そのスナップも十分に上品な既定です。
+動きが何かを足すときだけ opt-in してください。
+
+`prefers-reduced-motion: reduce` は自動で尊重されます。フォールバックを書く必要はありません。
+
+（2 枚にまたがる同一要素を動かす「Magic Move」は `morph.md`。この契約の上に載っています。）
+
+## 契約
+
+トランジションは `<Slide transition={...}>` に付けます。**入ってくる側が勝ちます**:
+A → B の移動では B の `transition` が使われ、その `exit` が A で、`enter` が B で再生されます。
+B → A と戻るときは A の `transition` が使われるので、**両方向で動かしたいなら両方のスライドに
+同じオブジェクトを渡します**。
+
+```tsx
+import { Slide, SlideDeck, type SlideTransition } from "@squadbase/vantage/slide"
+
+const RISE: SlideTransition = { /* … */ }
+
+<SlideDeck>
+  <Slide>…</Slide>
+  <Slide transition={RISE}>…</Slide>
+</SlideDeck>
+```
+
+```ts
+type TransitionPhase = {
+  keyframes: Keyframe[] | PropertyIndexedKeyframes  // WAAPI のキーフレーム
+  duration?: number   // ms（省略時は上位の duration）
+  easing?: string     // CSS easing
+  delay?: number      // ms —— exit と enter を重ねるのに使う
+}
+type SlideTransition = {
+  duration: number                     // 上位のフォールバック
+  easing?: string
+  enter?: TransitionPhase              // 入ってくる側で再生
+  exit?: TransitionPhase               // 出ていく側で再生
+  morph?: boolean | MorphTransition    // 共有要素のモーフ → morph.md
+}
+```
+
+ラッパーには `--slide-dir`（前進 `1` / 後退 `-1`）と `data-slide-dir`（`"forward"` / `"backward"`）が
+出るので、JS のコールバック無しに 1 つのキーフレームで方向を反転できます。
+
+## 設計原則（ここは崩さない）
+
+「PowerPoint で作りました」と最も大きく告げるのは、1 つのデッキに 6 種類のトランジションがあることです。
+節度がリズムを作ります。
+
+- **DNA を 1 つ選び、デッキ全体で保つ。** 同じ duration 帯、同じ easing の組、同じ out → in のずらし方。
+  変えてよいのは**どのプロパティに小さな一押しを乗せるか**だけ —— Y、X、opacity、scale、blur
+- **duration: 140–280ms。** exit 140–180ms、enter 200–280ms、enter を 80ms ほど遅らせて重ねる。
+  350ms を超えると動画編集の領域で、本当の状態変化のために取っておく
+- **振れ幅の上限: 12px か 3% スケール。** 6px の Y 上昇は「次の考え」に読める。1920px の translateX は
+  「別の書類」に読める。上質なツールは、気づく分だけしか動かさない
+- **opacity は常に混ぜる。** transform だけのトランジションは硬く、opacity だけのものは最も安全な既定
+- **easing: exit は ease-in、enter は ease-out。** 出るとき `cubic-bezier(0.4, 0, 1, 1)`、
+  入るとき `cubic-bezier(0, 0, 0.2, 1)`。`linear` は使わない（スライドショーに見える）。
+  対称な ease-in-out は状態が繋がるモーフのために取っておく
+
+## 上品な family —— 6 つ、1 つの DNA
+
+ここから選んでください。1 つをデッキの標準にし、必要ならヒーロー / 表紙用に 2 つ目、
+本当の章の切れ目に 3 つ目を取っておきます。
+
+```tsx
+const EASE_OUT = "cubic-bezier(0, 0, 0.2, 1)"
+const EASE_IN = "cubic-bezier(0.4, 0, 1, 1)"
+
+// RISE —— 標準の静けさ。Y に 6px。デッキの既定にする
+const RISE: SlideTransition = {
+  duration: 200,
+  exit: {
+    duration: 140, easing: EASE_IN,
+    keyframes: [
+      { opacity: 1, transform: "translateY(0)" },
+      { opacity: 0, transform: "translateY(-4px)" },
+    ],
+  },
+  enter: {
+    duration: 200, delay: 80, easing: EASE_OUT,
+    keyframes: [
+      { opacity: 0, transform: "translateY(6px)" },
+      { opacity: 1, transform: "translateY(0)" },
+    ],
+  },
+}
+
+// DISSOLVE —— opacity だけ。最も静か
+const DISSOLVE: SlideTransition = {
+  duration: 240,
+  exit: { duration: 200, easing: EASE_IN, keyframes: [{ opacity: 1 }, { opacity: 0 }] },
+  enter: { duration: 240, delay: 40, easing: EASE_OUT, keyframes: [{ opacity: 0 }, { opacity: 1 }] },
+}
+
+// SETTLE —— 表紙向き。上昇 + enter だけにわずかな blur
+const SETTLE: SlideTransition = {
+  duration: 280,
+  exit: {
+    duration: 160, easing: EASE_IN,
+    keyframes: [
+      { opacity: 1, transform: "translateY(0)" },
+      { opacity: 0, transform: "translateY(-6px)" },
+    ],
+  },
+  enter: {
+    duration: 280, delay: 100, easing: EASE_OUT,
+    keyframes: [
+      { opacity: 0, transform: "translateY(12px)", filter: "blur(4px)" },
+      { opacity: 1, transform: "translateY(0)", filter: "blur(0)" },
+    ],
+  },
+}
+
+// BLOOM —— scale 0.97 → 1、移動なし。その場で像を結ぶ
+const BLOOM: SlideTransition = {
+  duration: 240,
+  exit: {
+    duration: 160, easing: EASE_IN,
+    keyframes: [
+      { opacity: 1, transform: "scale(1)" },
+      { opacity: 0, transform: "scale(1.01)" },
+    ],
+  },
+  enter: {
+    duration: 240, delay: 80, easing: EASE_OUT,
+    keyframes: [
+      { opacity: 0, transform: "scale(0.97)" },
+      { opacity: 1, transform: "scale(1)" },
+    ],
+  },
+}
+
+// FALL —— RISE の鏡像。上から降りてくる
+const FALL: SlideTransition = {
+  duration: 200,
+  exit: {
+    duration: 140, easing: EASE_IN,
+    keyframes: [
+      { opacity: 1, transform: "translateY(0)" },
+      { opacity: 0, transform: "translateY(4px)" },
+    ],
+  },
+  enter: {
+    duration: 200, delay: 80, easing: EASE_OUT,
+    keyframes: [
+      { opacity: 0, transform: "translateY(-6px)" },
+      { opacity: 1, transform: "translateY(0)" },
+    ],
+  },
+}
+
+// BREATH —— 章の切れ目。完全に消してから 120ms 置いて入る
+// 本当の区切りにだけ、デッキ 1 本で 1〜2 回まで
+const BREATH: SlideTransition = {
+  duration: 460,
+  exit: { duration: 180, easing: EASE_IN, keyframes: [{ opacity: 1 }, { opacity: 0 }] },
+  enter: {
+    duration: 240, delay: 300, easing: EASE_OUT,
+    keyframes: [
+      { opacity: 0, transform: "translateY(8px)" },
+      { opacity: 1, transform: "translateY(0)" },
+    ],
+  },
+}
+```
+
+6 つは同じ DNA を共有していて、小さな一押しをどのプロパティに乗せるかだけが違います。
+読み手には変化に見え、それでいて 1 つの手つきに読めます。
+
+## 方向を意識したキーフレーム（控えめに）
+
+上品なツールの多くは後退時に鏡像化しません。本当に必要なとき（横に流れるスライドを逆再生したい等）
+だけ `--slide-dir` を `calc()` の中で使います:
+
+```tsx
+{ transform: "translateX(calc(var(--slide-dir, 1) * 8px))" },
+{ transform: "translateX(0)" },
+```
+
+毎回これに手が伸びるなら、たぶん設計しすぎです。前進 = 後退の方が洗練された既定。
+
+## アンチパターン
+
+- ❌ 6 ページに 6 種類のトランジション —— 最も大きな「PowerPoint 感」の合図
+- ❌ `translateX(100%)` の横スライド —— iOS のモーダルや PowerPoint の Push であって、スライドの切り替えではない
+- ❌ 強いスケールのポップ（`0.85 → 1`）+ blur —— ライトボックスの語彙で、何かに「ズームイン」する意味になる
+- ❌ `clip-path: inset(…)` のワイプ —— After Effects の語彙。芝居がかる
+- ❌ 両方のレイヤーに同時に blur —— 視覚的な濁り。目が焦点を結べない
+- ❌ 通常の切り替えで 350ms を超える duration —— 間延びする
+- ❌ 12px / 3% を超える移動 —— 連続ではなく断絶に読める
+- ❌ `linear` easing —— プロダクトではなくスライドショーに見える
+- ❌ とりあえずトランジションを宣言する。**理由が無いなら書かない。** スナップで十分

package/templates/AGENTS.md

@@ -1,17 +1,18 @@
 # AGENTS.md — Vantage アプリの地図
 
 このファイルは、**Vantage(`@squadbase/vantage`)アプリを作るコーディングエージェント**が
-最初に読むための地図です。アプリ作者(= `index.tsx` を書く側)が守るべき規約・不変条件・
-最小レシピを 1 ページに集約しています。ここに書かれた規約だけで、最小のダッシュボードアプリを
-正しく組めます。
-
-> このファイルは **Vantage フレームワークが所有する正本**のコピーです。手で書き換えても、
-> `vantage upgrade` を実行するとフレームワーク同梱の正本から再同期されて上書きされます。
-> アプリ固有のメモは別ファイル(例: `README.md`)に書いてください。
+最初に読むための地図です。アプリ作者(= `index.tsx` を書く側)が守るべき規約・不変条件を
+1 ページに集約し、種類ごとの詳しいレシピは `agents/` 配下の知識ファイルに分けています。
+
+> このファイルと `agents/*.md` は、いずれも **Vantage フレームワークが所有する正本**の
+> コピーです。手で書き換えても、`vantage upgrade` を実行するとフレームワーク同梱の正本から
+> 再同期されて上書きされます。アプリ固有のメモは別ファイル(例: `README.md`)に書いてください。
+> 例外はプロジェクトルートの `DESIGN.md` で、これは**ユーザーが所有**します(`vantage upgrade` も
+> `vantage add agents` も触らない。→「デザインの意図(DESIGN.md)」)。
 >
 > 手順を伴う踏み込んだワークフローは、同梱の Claude Code Skill に分かれています。このファイルは
-> 「地図」、Skill は「手順書」という役割分担です。**配置済みの Skill を先に探す**手順は
-> 末尾の「さらに詳しく(同梱 Skill)」にあります。
+> 「地図」、`agents/*.md` は「種類ごとの静的リファレンス」、Skill は「手順書」という役割分担です。
+> **配置済みの Skill を先に探す**手順は末尾の「さらに詳しく(同梱 Skill)」にあります。
 
 ## Vantage とは
 
@@ -39,8 +40,8 @@ UI キット・開発サーバー・API サーバー・ビルドはすべて Van
 - **色はセマンティックトークンで書く。** `text-foreground`・`text-muted-foreground`・`bg-card`・
   `border-border`。トークンがライト / ダークの両方を持つので `dark:` を並べる必要が無い。
   素のパレット + `dark:`(`text-slate-900 dark:text-slate-100`)を混ぜると、その 1 か所だけ
-  手動で 2 モードを管理することになる(→「ダークモードは opt-in」)。`--muted`・`--accent`・
-  `--secondary`・`--border` は背景・境界用で、文字色に使うと読めない。
+  手動で 2 モードを管理することになる(→ `agents/page.md` の「ダークモードは opt-in」)。
+  `--muted`・`--accent`・`--secondary`・`--border` は背景・境界用で、文字色に使うと読めない。
 - **`.vantage/` と `dist/` は生成物。** 編集しない・読みにいかない(gitignore 済み)。任意の CLI
   コマンド、または `vantage upgrade` で再生成される。
 - **`definePage` の値はリテラルで書く。** title/description/navLabel はビルド時に静的抽出される
@@ -93,6 +94,9 @@ root/
 | `@squadbase/vantage/query` | `useApiQuery`・`useApiMutation`・`apiJson`・`apiFetch`・`apiUrl`・`ApiError`、ほか `useQuery`/`useMutation` など TanStack Query の再エクスポート |
 | `@squadbase/vantage/ui` | shadcn/ui(Base UI バリアント)プリミティブ(`Button`・`Loading`・`ErrorState`・`Empty` ほか) |
 | `@squadbase/vantage/components` | 複合パーツ(`PageShell`・`DashboardCardPreset`・`DataTablePreset`・`EChart` ほか) |
+| `@squadbase/vantage/table` | `FilePageView`・`TableViewer`(データファイルページの表ビューア) |
+| `@squadbase/vantage/slide` | `SlideDeck`・`Slide`・`Steps`・`Step`・`MorphElement`・`useSlideNumber`・`useIsActiveSlide`(スライド専用。1920×1080 の固定キャンバス) |
+| `@squadbase/vantage/doc` | `Document`(ドキュメント専用。中の素の HTML 要素に見出し・表などのスタイルが当たる) |
 | `@squadbase/vantage/markdown` | `MarkdownRenderer`(Shiki を隔離するための専用サブパス) |
 | `@squadbase/vantage/server` | `ApiContext`・`ApiHandler`・`HttpError`・`isHttpError`・`json`(server/ 側でのみ使う) |
 
@@ -101,207 +105,37 @@ root/
 `server/` ディレクトリがあれば **fullstack**、無ければ **SPA**。`vantage-manifest.json` の
 `mode` はここから自動で決まり、手で書く設定は無い。**SPA から始めて fullstack へ「昇格」する
 必要はない** ― テンプレートから始めた場合は最初から `server/` があり、その時点で fullstack。
-下の 2 節は段階ではなく、いま自分がどちらにいるかを確かめるための地図として読む。
-
-- `server/` が**ある** → 「API を持つ(fullstack モード)」を見る。データは自前の `/api/*` から
-  `useApiQuery` で取る。
-- `server/` が**無い** → 「最小アプリ(2 ファイル)」の構成。外部 API を直接叩くなら `useQuery`。
-  自前の API が要るようになったら `server/api/*.ts` を足すだけでよい(設定変更は不要)。
-
-## 最小アプリ(2 ファイル)
-
-`package.json` と `index.tsx` の 2 ファイルだけで動く。
-
-`package.json`:
-
-```json
-{
-  "name": "my-dashboard",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "dev": "vantage dev",
-    "build": "vantage build",
-    "preview": "vantage preview",
-    "check": "vantage check",
-    "routes": "vantage routes"
-  },
-  "dependencies": {
-    "@squadbase/vantage": "^0.5.0",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7"
-  }
-}
-```
+下の 2 つは段階ではなく、いま自分がどちらにいるかを確かめるための地図として読む。
 
-`index.tsx`(ルートのデフォルトエクスポートが `/` ページになる):
+- `server/` が**ある** → データは自前の `/api/*` から `useApiQuery` で取る(→ `agents/api.md`)。
+- `server/` が**無い** → 外部 API を直接叩くなら `useQuery`(→ `agents/page.md`)。自前の API が
+  要るようになったら `server/api/*.ts` を足すだけでよい(設定変更は不要)。
 
-```tsx
-export default function Dashboard() {
-  return (
-    <main className="p-6">
-      <h1 className="text-2xl font-semibold">Dashboard</h1>
-    </main>
-  )
-}
-```
+## デザインの意図(DESIGN.md)
 
-```bash
-pnpm install
-pnpm dev      # → http://localhost:5173(HMR)
-pnpm check    # 静的診断(エラーがあれば exit 1)
-pnpm routes   # ページ/API の URL マップ
-```
+プロジェクトルートに `DESIGN.md` があれば、**UI(ページ・スライド・コンポーネント)を書く前に
+読む。** 色・チャート・書体・レイアウトの使い分けがトークン名で書いてあるので、それに従って
+トークンで書く(値は `styles.css` にあり、`DESIGN.md` には色コードを書かない)。
 
-`server/` ディレクトリが無いので、この構成は **SPA モード**。ページを直下に置く形だが、
-`src/` を作ってその中に集めてもよい(テンプレートから始めた場合は最初から `src/` がある)。
-どちらか一方に寄せること(→「ディレクトリ構造」)。
+- **会話中の指示は `DESIGN.md` より優先する。** 同じ指示が繰り返されたら、`DESIGN.md` への
+  反映をユーザーに提案する。
+- **「色を変えて」「ブランドに合わせて」などデザイン全体の変更は、ファイルごとに直さない。**
+  Skill `vantage-design` の手順で `DESIGN.md` と `styles.css` をまとめて更新する。
+- `DESIGN.md` はユーザーの持ち物。`vantage upgrade` は書き換えない。
 
-## ルーティング規約(ファイル名 → ルート)
+## 何を書くか → どのファイルを読むか
 
-ページルート(`src/` があればその中、無ければプロジェクトルート)からの相対パスが、そのまま
-URL になる。各ページは**デフォルトエクスポートの React コンポーネントが必須**(無いと
-`MISSING_DEFAULT_EXPORT`)。以下の「ファイル」列はページルートからの相対パス。
+**書こうとしている種類のファイルだけを開けばよい。** まず該当する 1 ファイルを readFiles で
+読んでから書き始める。
 
-| ファイル | ルート |
+| 書こうとしているもの | 読むファイル |
 | --- | --- |
-| `index.tsx` | `/` |
-| `monthly-analysis.tsx` | `/monthly-analysis` |
-| `sales/index.tsx` | `/sales` |
-| `sales/[customerId].tsx` | `/sales/:customerId`(動的パラメータ) |
-| `_layout.tsx` | そのディレクトリ配下を包むネストレイアウト(`Outlet` で子を描く) |
-| `_404.tsx` | Not Found ページ |
-| `_error.tsx` | ルートが throw したときのエラーページ |
-
-`components/`・`hooks/`・`lib/`・`server/`・`public/` はどの階層でもルート走査の対象外
-(ページにならない)。それ以外のディレクトリ名は URL のセグメントになる(→「ディレクトリ構造」)。
-
-```tsx
-import { definePage } from "@squadbase/vantage"
-
-// title は document.title、navLabel は useRoutes() で組むナビの表示名(既定は title)
-export const page = definePage({ title: "Monthly Analysis · Acme", navLabel: "Monthly" })
-
-export default function MonthlyAnalysis() {
-  return <main className="p-6">…</main>
-}
-```
-
-### ナビはルート一覧から組む
-
-`useRoutes()` がページルート一覧(スキャン順)を返すので、リンク配列を手で持たない。
-`useCurrentRoute()` は現在のルート(404 なら `undefined`)。
-
-```tsx
-import { Link, useCurrentRoute, useRoutes } from "@squadbase/vantage/router"
-
-// 動的ルートは URL が定まらないので外す。label は navLabel → title → path の順
-const routes = useRoutes().filter((r) => !r.dynamic)
-const current = useCurrentRoute()
-
-routes.map((r) => (
-  <Link key={r.path} to={r.to} activeClassName="font-semibold">
-    {r.label}
-  </Link>
-))
-```
-
-`RouteInfo`: `path`(`/sales/:id`)・`to`(`/sales/$id`)・`params`・`dynamic`・`index`・`label`・
-`title`・`description`・`navLabel`。
-
-### フィルタ状態は URL に置く
-
-リロードで消えず、URL をそのまま共有できる。`useState` と同じ形。
-
-```tsx
-import { useSearchParam, useSearchState } from "@squadbase/vantage/router"
-
-const [region, setRegion] = useSearchParam("region", "all")   // 常に string
-const [segments, setSegments] = useSearchState<string[]>("segments", []) // JSON になる値
-```
-
-デフォルト値(または `null`)を書くとキーは URL から消える。履歴は既定で `replace`
-(`{ replace: false }` で push)。
-
-### 動的パラメータの「3 つの綴り」を同期させる
-
-崩すと静かにマッチしなくなる不変条件:
-
-- ファイル名 `sales/[customerId].tsx`
-- 表示ルート `/sales/:customerId`
-- リンクトークン `to="/sales/$customerId"` + `params={{ customerId }}`
-
-```tsx
-import { Link, useParams } from "@squadbase/vantage/router"
-
-<Link to="/sales/$customerId" params={{ customerId: row.id }}>{row.name}</Link>
-
-// 詳細ページ側で取り出す
-const { customerId } = useParams()
-```
-
-## データ取得(server を持たない fetch)
-
-外部 API を叩くだけなら `server/` は不要。`@squadbase/vantage/query` の `useQuery` を使う:
-
-```tsx
-import { useQuery } from "@squadbase/vantage/query"
-import { Loading, ErrorState } from "@squadbase/vantage/ui"
-
-const q = useQuery({ queryKey: ["stats"], queryFn: () => fetch("/…").then((r) => r.json()) })
-if (q.isPending) return <Loading />
-if (q.isError) return <ErrorState message={(q.error as Error).message} />
-```
-
-`QueryClient` は Vantage が 1 つだけ管理する(staleTime 30s・retry 1・
-refetchOnWindowFocus false・networkMode "always")。挙動を変えたいときはクエリ側のオプションで
-上書きする。
-自分の `server/api` を叩くときは `useQuery` ではなく `useApiQuery`(→「API を持つ(fullstack
-モード)」)。
-
-## API を持つ(fullstack モード)
-
-**`server/` ディレクトリがあれば fullstack モード**(無いアプリに足せば、その時点で切り替わる)。
-`server/api/**` の各ファイルが API ルートになる。
-
-`server/api/monthly-analysis.ts` → `GET /api/monthly-analysis`:
-
-```ts
-import type { ApiContext } from "@squadbase/vantage/server"
-import { HttpError } from "@squadbase/vantage/server"
-
-export async function GET({ params, env }: ApiContext) {
-  if (!env.API_KEY) throw new HttpError(500, "API_KEY missing")
-  return Response.json({ ok: true })
-}
-```
-
-- API モジュールは**大文字の HTTP メソッド**(`GET`/`POST`/`PUT`/`PATCH`/`DELETE`/`OPTIONS`)を
-  エクスポートする。それ以外の名前は `INVALID_API_EXPORT` エラー。
-- 動的 API も `[id].ts` 記法: `server/api/customers/[id].ts` → `GET /api/customers/:id`。
-  `params.id` で取り出す(`noUncheckedIndexedAccess` が効くので narrowing が要る)。
-- **クライアントに見せたいエラーは `HttpError(status, msg)` を throw する。** それ以外の throw は
-  ログに記録され汎用の 500 に丸められる。
-- **シークレットは `ApiContext.env` にだけ届く**(クライアントには決して届かない)。
-
-クライアント側からは `useApiQuery` で `/api/*` を叩く。ベース URL の解決・JSON パース・
-非 2xx の `ApiError` 化・クエリキー(`["api", url]`)が入っている:
-
-```tsx
-import { useApiQuery, useApiMutation } from "@squadbase/vantage/query"
-
-const q = useApiQuery<Customer>(`/api/customers/${customerId}`)
-if (q.isError) return <ErrorState message={q.error.message} />  // HttpError のメッセージ
-
-// クエリ文字列は search で。undefined の項目は落ちる
-const rows = useApiQuery<Row[]>("/api/customers", { search: { segment } })
-
-// 書き込み。変数がそのまま JSON ボディになる
-const save = useApiMutation<Customer, Payload>("/api/customers", { method: "POST" })
-```
-
-`ApiError` は `message`・`status`・`body`・`requestId` を持つ。hook が使えない場所では
-`apiJson(path, init)`、生の `Response` が要るときは `apiFetch`。
+| ダッシュボード / 通常ページ(`.tsx`) | `agents/page.md` |
+| API(`server/`) | `agents/api.md` |
+| スライド(`.slide.tsx`) | `agents/slide.md` |
+| ドキュメント(`.doc.tsx`) | `agents/doc.md` |
+| `.xlsx` ページ | `agents/xlsx.md` |
+| `.csv` ページ | `agents/csv.md` |
 
 ## 環境変数
 
@@ -309,30 +143,6 @@ const save = useApiMutation<Customer, Payload>("/api/customers", { method: "POST
   のみ。** `VITE_` 系の公開 API は無い。
 - サーバー側のシークレットは `ApiContext.env.MY_SECRET` で読む(`server/` 内のみ)。
 
-## 組み込み UI / コンポーネントの入口
-
-- **プリミティブ**は `@squadbase/vantage/ui` から import する(`Button`・`Loading`・
-  `ErrorState`・`Empty`・`Select`・`Checkbox` ほか)。
-- **複合パーツ**は `@squadbase/vantage/components` から(`PageShell`・`DashboardCardPreset`・
-  `DataTablePreset`・`EChart` ほか)。
-- **どの名前が import 可能か / props の詳細は `vantage docs` で引く。** ガイドとコンポーネント
-  リファレンスはパッケージに同梱されていて、オフラインでも読める(→「ドキュメントを引く」)。
-  **名前が分からないとき**はやりたいことで `vantage search` する(→ 同節)。
-- **UI は import して使うのが既定。取り出す(eject)必要はない。** `vantage add ui|block` は
-  ソースを手元にコピーして**改造したいとき専用**のコマンドで、取り出せるのは
-  `ui: data-table` と `block: sales-overview` の 2 つだけ。それ以外の名前は import 専用で
-  `add` の対象ではない(未知名で実行すると候補が一覧表示される)。
-
-### ダークモードは opt-in
-
-ダークのトークンが効くのは、祖先に `.dark` か `[data-theme="dark"]` が付いているときだけ。
-**OS / ブラウザの設定(`prefers-color-scheme`)は見ない。** `dark:` ユーティリティも同じ
-スイッチに繋いであるので(`theme.css` の `@custom-variant dark`)、自分でクラスを付けない限り
-アプリは常にライトで描かれる ― `dark:` を書いてもそこだけダークになることはない。
-
-明暗を切り替えたいときは、レイアウトのルート要素などに `.dark` / `data-theme="dark"` を
-自分で付ける。
-
 ## ドキュメントを引く(`vantage docs` / `vantage search`)
 
 ```bash
@@ -378,6 +188,8 @@ body・レスポンスの status と形)まで出る。`vantage check --json` /
 
 - **`vantage-app`** — アプリを一から作る / 構成を広げるときの進め方と検証の順序
 - **`vantage-add-feature`** — 既存アプリに page / api / ui を 1 つ足す定型
+- **`vantage-slide`** — `.slide.tsx` でスライドデッキを書く(キャンバスの予算・段階表示・pptx 書き出し)
+- **`vantage-design`** — `DESIGN.md` と `styles.css` をまとめて作る / 直す(配色・書体・ブランド合わせ)
 - **`vantage-pitfalls`** — Base UI(≠ Radix)の癖など、静かに壊れる落とし穴のリファレンス
 - **`project-storage`** — Squadbase の Project Storage(アップロード済みファイル)をブラウザから読み書きする
 
@@ -398,3 +210,6 @@ vantage add skill --all --dir .claude/skills   # 置き場所を指定(既定は
 `add skill` はプロジェクト内を走査してから動くので、**再実行しても二重に配置されない**。
 配置済みのコピーを新しいバージョンに更新したいときだけ `--force` を付ける(見つかった場所を
 そのまま書き換える)。
+
+**役割分担:** Skill = 手順書(踏み込んだワークフロー) / `agents/*.md` = 種類ごとの静的
+リファレンス / `AGENTS.md`(このファイル) = 地図。

package/templates/agents/api.md

@@ -0,0 +1,49 @@
+# API(server/)
+
+フレームワーク所有の知識ファイルで、`vantage upgrade` で再同期されます。`server/api/**`
+に API ルートを書くときに読んでください。不変条件・ディレクトリ構造は `AGENTS.md` を
+先に読んでいる想定です。
+
+## API を持つ(fullstack モード)
+
+**`server/` ディレクトリがあれば fullstack モード**(無いアプリに足せば、その時点で切り替わる)。
+`server/api/**` の各ファイルが API ルートになる。
+
+`server/api/monthly-analysis.ts` → `GET /api/monthly-analysis`:
+
+```ts
+import type { ApiContext } from "@squadbase/vantage/server"
+import { HttpError } from "@squadbase/vantage/server"
+
+export async function GET({ params, env }: ApiContext) {
+  if (!env.API_KEY) throw new HttpError(500, "API_KEY missing")
+  return Response.json({ ok: true })
+}
+```
+
+- API モジュールは**大文字の HTTP メソッド**(`GET`/`POST`/`PUT`/`PATCH`/`DELETE`/`OPTIONS`)を
+  エクスポートする。それ以外の名前は `INVALID_API_EXPORT` エラー。
+- 動的 API も `[id].ts` 記法: `server/api/customers/[id].ts` → `GET /api/customers/:id`。
+  `params.id` で取り出す(`noUncheckedIndexedAccess` が効くので narrowing が要る)。
+- **クライアントに見せたいエラーは `HttpError(status, msg)` を throw する。** それ以外の throw は
+  ログに記録され汎用の 500 に丸められる。
+- **シークレットは `ApiContext.env` にだけ届く**(クライアントには決して届かない)。
+
+クライアント側からは `useApiQuery` で `/api/*` を叩く。ベース URL の解決・JSON パース・
+非 2xx の `ApiError` 化・クエリキー(`["api", url]`)が入っている:
+
+```tsx
+import { useApiQuery, useApiMutation } from "@squadbase/vantage/query"
+
+const q = useApiQuery<Customer>(`/api/customers/${customerId}`)
+if (q.isError) return <ErrorState message={q.error.message} />  // HttpError のメッセージ
+
+// クエリ文字列は search で。undefined の項目は落ちる
+const rows = useApiQuery<Row[]>("/api/customers", { search: { segment } })
+
+// 書き込み。変数がそのまま JSON ボディになる
+const save = useApiMutation<Customer, Payload>("/api/customers", { method: "POST" })
+```
+
+`ApiError` は `message`・`status`・`body`・`requestId` を持つ。hook が使えない場所では
+`apiJson(path, init)`、生の `Response` が要るときは `apiFetch`。