@squadbase/vantage-template 0.0.2 → 0.1.0-dev.55898c0

package/README.md

@@ -14,22 +14,22 @@ npx @squadbase/vantage-template <command> [options]
 
 #### `init`
 
-Initialize a new Vantage project in the current directory. Copies the base template — `src/index.tsx`, `src/_layout.tsx`, `src/_404.tsx`, `src/_error.tsx`, `src/styles.css`, `server/api/`, `tsconfig.json`, `squadbase.yml`, plus the agent guidance in `AGENTS.md` and `.squadbase/skills/` — and installs dependencies.
+Initialize a new Vantage project in the current directory. Copies the base template — `src/index.tsx`, `src/_layout.tsx`, `src/_404.tsx`, `src/_error.tsx`, `src/styles.css`, `server/api/`, `tsconfig.json`, `squadbase.yml`, plus the agent guidance in `AGENTS.md` (and `agents/`, when the framework ships per-type knowledge files) and `.squadbase/skills/` — and installs dependencies.
 
 ```bash
 npx @squadbase/vantage-template init
 npx @squadbase/vantage-template init --force                  # Overwrite existing files
-npx @squadbase/vantage-template init --skip-install           # Skip npm install
+npx @squadbase/vantage-template init --skip-install           # Skip dependency install (bun, or npm if bun is absent)
 npx @squadbase/vantage-template init --chart sunset           # Apply a chart preset during init
 ```
 
-After initialization:
+After initialization (the template ships `bun.lock` and declares `package_manager: bun` in `squadbase.yml`; `npm run` works too once dependencies are installed):
 
 ```bash
-npm run dev      # vantage dev --no-overlay — dev server + API on :5173
-npm run build    # vantage build → dist/
-npm run check    # vantage check — static diagnostics
-npm run routes   # vantage routes — page/API route map
+bun run dev      # vantage dev --no-overlay — dev server + API on :5173
+bun run build    # vantage build → dist/
+bun run check    # vantage check — static diagnostics
+bun run routes   # vantage routes — page/API route map
 ```
 
 There is no `vite.config.ts`, no `main.tsx`, and no route table: adding a file under `src/` adds a route (`src/index.tsx` → `/`, `src/sales/[id].tsx` → `/sales/:id`), and `src/_layout.tsx` builds the nav from `useRoutes()`.
@@ -56,6 +56,8 @@ npx @squadbase/vantage-template add funnel --force      # Overwrite existing fil
 
 Switch the chart color preset. Rewrites a marked block of `--chart-1`–`--chart-5` inside the project's `styles.css` (under `src/` when that layout is in use), leaving any other overrides in that file intact. Re-running replaces the block rather than stacking.
 
+A new project starts on the `blue` preset — the base template ships that block already written, so `init` and the gallery previews show the same colors. This command swaps it for another preset.
+
 ```bash
 npx @squadbase/vantage-template chart ocean
 npx @squadbase/vantage-template chart forest --dry-run

package/base-template/.squadbase/skills/project-storage/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: project-storage
+description: Squadbase の Project Storage(アップロード済みファイル)を @squadbase/react の useStorage() でブラウザから扱う手順。ファイル一覧、画像 / 動画 / PDF の埋め込み、中身の読み取り、アップロードと削除・移動。ページやコンポーネントがアップロード済みファイルを表示・埋め込み・アップロードするときに参照する。
+---
+
+# Project Storage(ブラウザ側)
+
+Squadbase の **Project Storage** を React コンポーネントから読み書きする手順。Squadbase 上で
+動くアプリでは資格情報も設定も要らず、そのまま動く。サーバー(`server/api/**`)からストレージを
+触る API は別物で、ここでは扱わない。
+
+## import は `@squadbase/react` から直接
+
+「import は `@squadbase/vantage` のサブパス経由」はフレームワークが所有するものの話。
+**`@squadbase/react` は Squadbase プラットフォームの SDK なので直接 import する**
+(`SquadbaseProvider` / `useUser` と同じ)。
+
+```tsx
+import { useStorage } from "@squadbase/react"
+
+const storage = useStorage()
+// 呼び出しはすべて storage.uploads.* の下
+```
+
+`useStorage()` が返すクライアントは安定なので、コンポーネント先頭で呼んで `useQuery` /
+`useMutation` の中で使ってよい。データ取得のフックは `@squadbase/vantage/query` から取る
+(`@tanstack/*` は直接 import しない)。
+
+## API
+
+すべて async。`key` はストレージ内の**相対**パス(例: `reports/2025-q1.pdf`)で、先頭に
+スラッシュを付けない。
+
+読み取り:
+
+- `list(prefix?, options?)` → `{ objects, commonPrefixes, nextCursor? }`。`objects` は
+  `{ key, size, lastModified }[]`。`options.delimiter = "/"` でフォルダ表示(サブフォルダが
+  `commonPrefixes` に入る)、省略すると再帰的なフラット一覧。`options.limit` / `options.cursor`
+  でページング(`cursor` は前回の `nextCursor`)
+- `head(key)` → `{ key, size, contentType, createdAt }`。メタ情報だけで本体は取らない
+- `getUrl(key)` → `{ url, expiresAt }`。埋め込み用の一時 URL
+- `get(key)` → 生の `Response`。`.json()` / `.text()` / `.blob()` / `.arrayBuffer()` で読む
+
+書き込み:
+
+- `put(key, data, options?)` → `void`。`data` は `Blob`(`File` を含む) / `ArrayBuffer` /
+  `Uint8Array` / `string`
+- `delete(key)` → `void`
+- `copy(srcKey, destKey, options?)` / `move(srcKey, destKey, options?)` → `void`
+
+## 一覧を出す
+
+```tsx
+import { useStorage } from "@squadbase/react"
+import { useQuery } from "@squadbase/vantage/query"
+
+const storage = useStorage()
+const { data, isPending, isError } = useQuery({
+  queryKey: ["storage", "list", prefix],
+  queryFn: () => storage.uploads.list(prefix, { delimiter: "/" }),
+})
+```
+
+`data.commonPrefixes` をフォルダ、`data.objects` をファイルとして描く。プレフィックス配下を
+まとめて出すなら `delimiter` を省く。
+
+## 画像 / 動画 / PDF を埋め込む
+
+埋め込みには URL が要るので `getUrl` を使う。**URL には期限がある**ので、切れる前に取り直す:
+
+```tsx
+import { useStorage } from "@squadbase/react"
+import { useQuery } from "@squadbase/vantage/query"
+
+function useStorageUrl(key: string) {
+  const storage = useStorage()
+  return useQuery({
+    queryKey: ["storage", "url", key],
+    queryFn: () => storage.uploads.getUrl(key),
+    refetchInterval: (query) => {
+      const expiresAt = query.state.data?.expiresAt
+      if (!expiresAt) return false
+      // 期限の 60 秒前に取り直す
+      return Math.max(0, new Date(expiresAt).getTime() - Date.now() - 60_000)
+    },
+  })
+}
+```
+
+```tsx
+import { ErrorState, Loading } from "@squadbase/vantage/ui"
+
+const { data, isPending, isError } = useStorageUrl("reports/cover.png")
+if (isPending) return <Loading />
+if (isError) return <ErrorState message="ファイルを読み込めませんでした" />
+return <img src={data.url} alt="" className="w-full rounded-lg" />
+```
+
+動画は `<video src={data.url} controls className="w-full rounded-lg" />`、PDF は
+`<iframe src={data.url} className="h-[80vh] w-full rounded-lg border border-border" />`。
+
+## 中身を JS で読む
+
+```tsx
+const { data } = useQuery({
+  queryKey: ["storage", "content", key],
+  queryFn: async () => {
+    const res = await storage.uploads.get(key)
+    return (await res.json()) as Row[] // または res.text()
+  },
+})
+```
+
+## アップロードする
+
+```tsx
+import { useStorage } from "@squadbase/react"
+import { useMutation, useQueryClient } from "@squadbase/vantage/query"
+
+const storage = useStorage()
+const queryClient = useQueryClient()
+const upload = useMutation({
+  mutationFn: (file: File) =>
+    storage.uploads.put(`uploads/${file.name}`, file, { contentType: file.type }),
+  onSuccess: () => queryClient.invalidateQueries({ queryKey: ["storage", "list"] }),
+})
+
+<input
+  type="file"
+  onChange={(e) => {
+    const file = e.target.files?.[0]
+    if (file) upload.mutate(file)
+  }}
+/>
+```
+
+`File` はそのまま `put` に渡す。書き込み後は該当する `["storage", "list", …]` を invalidate して
+UI を追従させる。
+
+## 落とし穴
+
+- **`getUrl` の URL は短命。** 結果を永続化したり長寿命のキャッシュに入れたりしない。
+  `expiresAt` の前に取り直す(上のフック)。`<img src>` に一度入れて放置すると、開いたままの
+  画面で後から読み込まれた分が失敗する
+- **`put` の `contentType` の既定は `application/octet-stream`。** 後で埋め込むもの(画像・動画・
+  PDF)には `file.type` を必ず渡す。付けないとブラウザが表示せずダウンロードに落ちる
+- **`key` は相対パス。** 先頭にスラッシュを付けない。`getUrl` を通さず `<img src="/foo.png">` の
+  ような静的パスで参照しない ― ストレージはアプリの `public/` ではない
+- **`copy` / `move` は既定で既存の宛先を上書きする。** 残したいときは `{ overwrite: false }`
+- **サーバー(`server/api/**`)からは呼ばない。** `useStorage` はブラウザ側の API
+
+---
+
+## 関連スキル
+
+- `vantage-add-feature` — ページ / API / コンポーネントを 1 つ足す手順
+- `vantage-pitfalls` — UI・配色・ルーティングの落とし穴

package/base-template/.squadbase/skills/vantage-app/SKILL.md

@@ -14,7 +14,7 @@ description: Vantage(@squadbase/vantage)ダッシュボードアプリを一か
 
 ## 全体の流れ
 
-1. **骨組み** — `pnpm dev` が上がるところまで
+1. **骨組み** — `bun run dev` が上がるところまで
 2. **ルートを決める** — ページファイルを置き、`vantage routes` で URL を確認
 3. **データを繋ぐ** — 外部 API か、自前の `server/api` か
 4. **仕上げ** — `check` → `build` → `preview`
@@ -52,7 +52,7 @@ exit 1 になる。
 ```
 
 `index.tsx` はデフォルトエクスポートの React コンポーネント 1 つ(これが `/` になる)。あとは
-`pnpm install && pnpm dev` で http://localhost:5173 が上がる。
+`bun install && bun run dev` で http://localhost:5173 が上がる(このプロジェクトの package manager は bun。`bun.lock` を持つ)。
 
 **既存アプリに合流したときは、作る前に現状を読む:**
 
@@ -105,10 +105,10 @@ vantage add skill  # 配置済みの skill(このファイルの仲間)と、そ
 ## Step 4 — 仕上げ
 
 ```bash
-pnpm check     # エラーが残っていないか(exit 1 なら残っている)
-pnpm routes    # 公開される URL の最終確認
-pnpm build     # dist/ に client(+ server)+ vantage-manifest.json
-pnpm preview   # 本番ビルドをローカルで動かす
+bun run check     # エラーが残っていないか(exit 1 なら残っている)
+bun run routes    # 公開される URL の最終確認
+bun run build     # dist/ に client(+ server)+ vantage-manifest.json
+bun run preview   # 本番ビルドをローカルで動かす
 ```
 
 `vantage-manifest.json` の `mode` は `server/` の有無から自動で決まる(手で書かない)。

package/base-template/.squadbase/skills/vantage-pitfalls/SKILL.md

@@ -35,6 +35,28 @@ Base UI の `SelectValue` は選択中の **value をそのまま描き**、`Sel
 
 トリガーに `kanto` や `/sales` と生の値が出たら、まずこれを疑う。
 
+## 配色:素のパレット + `dark:` ではなく、セマンティックトークンで書く
+
+色は `text-foreground` / `text-muted-foreground` / `bg-card` / `border-border` などの
+トークンで書く。トークンはライト / ダークの両方を持っているので、`dark:` を並べる必要が無い。
+
+`text-slate-900 dark:text-slate-100` のような素の Tailwind パレット + `dark:` の組は、
+**トークンで塗られた周囲と食い違う**。ダークトークンが効くのは祖先に `.dark` /
+`[data-theme="dark"]` が付いているときだけで、`dark:` ユーティリティも同じスイッチに
+繋がっている(`theme.css` の `@custom-variant dark`)。つまり自分でクラスを付けない限り
+アプリは常にライトで動くのに、素のパレットを使うとその 1 か所だけ手動で両モードを
+管理することになる。
+
+```tsx
+// ✗ 手動で 2 モードを管理することになる
+<div className="font-medium text-slate-900 dark:text-slate-100">{name}</div>
+// ✓ トークンなら 1 つで済む
+<div className="font-medium text-foreground">{name}</div>
+```
+
+`--muted` / `--accent` / `--secondary` / `--border` は**背景・境界用**で、ライトではほぼ白。
+文字色に使うと読めなくなる ― 弱い文字色は `text-muted-foreground`。
+
 ## チャート:`EChart` の配色はトークン追従。上書きは `option.color`
 
 系列色は `--chart-1..5`、軸・凡例・ツールチップは文字色/境界色のトークンから組まれる

package/base-template/AGENTS.md

@@ -1,17 +1,16 @@
 # AGENTS.md — Vantage アプリの地図
 
 このファイルは、**Vantage(`@squadbase/vantage`)アプリを作るコーディングエージェント**が
-最初に読むための地図です。アプリ作者(= `index.tsx` を書く側)が守るべき規約・不変条件・
-最小レシピを 1 ページに集約しています。ここに書かれた規約だけで、最小のダッシュボードアプリを
-正しく組めます。
+最初に読むための地図です。アプリ作者(= `index.tsx` を書く側)が守るべき規約・不変条件を
+1 ページに集約し、種類ごとの詳しいレシピは `agents/` 配下の知識ファイルに分けています。
 
-> このファイルは **Vantage フレームワークが所有する正本**のコピーです。手で書き換えても、
-> `vantage upgrade` を実行するとフレームワーク同梱の正本から再同期されて上書きされます。
-> アプリ固有のメモは別ファイル(例: `README.md`)に書いてください。
+> このファイルと `agents/*.md` は、いずれも **Vantage フレームワークが所有する正本**の
+> コピーです。手で書き換えても、`vantage upgrade` を実行するとフレームワーク同梱の正本から
+> 再同期されて上書きされます。アプリ固有のメモは別ファイル(例: `README.md`)に書いてください。
 >
 > 手順を伴う踏み込んだワークフローは、同梱の Claude Code Skill に分かれています。このファイルは
-> 「地図」、Skill は「手順書」という役割分担です。**配置済みの Skill を先に探す**手順は
-> 末尾の「さらに詳しく(同梱 Skill)」にあります。
+> 「地図」、`agents/*.md` は「種類ごとの静的リファレンス」、Skill は「手順書」という役割分担です。
+> **配置済みの Skill を先に探す**手順は末尾の「さらに詳しく(同梱 Skill)」にあります。
 
 ## Vantage とは
 
@@ -36,6 +35,11 @@ UI キット・開発サーバー・API サーバー・ビルドはすべて Van
 - **クライアントに届く env は `PUBLIC_` 接頭辞のものだけ。** `import.meta.env.PUBLIC_FOO`。
   それ以外を `import.meta.env` で読むと `PUBLIC_ENV_MISUSE` 警告。シークレットは
   `ApiContext.env`(server/ 内)にだけ届く。
+- **色はセマンティックトークンで書く。** `text-foreground`・`text-muted-foreground`・`bg-card`・
+  `border-border`。トークンがライト / ダークの両方を持つので `dark:` を並べる必要が無い。
+  素のパレット + `dark:`(`text-slate-900 dark:text-slate-100`)を混ぜると、その 1 か所だけ
+  手動で 2 モードを管理することになる(→ `agents/page.md` の「ダークモードは opt-in」)。
+  `--muted`・`--accent`・`--secondary`・`--border` は背景・境界用で、文字色に使うと読めない。
 - **`.vantage/` と `dist/` は生成物。** 編集しない・読みにいかない(gitignore 済み)。任意の CLI
   コマンド、または `vantage upgrade` で再生成される。
 - **`definePage` の値はリテラルで書く。** title/description/navLabel はビルド時に静的抽出される
@@ -88,6 +92,8 @@ 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/markdown` | `MarkdownRenderer`(Shiki を隔離するための専用サブパス) |
 | `@squadbase/vantage/server` | `ApiContext`・`ApiHandler`・`HttpError`・`isHttpError`・`json`(server/ 側でのみ使う) |
 
@@ -96,207 +102,24 @@ 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"
-  }
-}
-```
-
-`index.tsx`(ルートのデフォルトエクスポートが `/` ページになる):
-
-```tsx
-export default function Dashboard() {
-  return (
-    <main className="p-6">
-      <h1 className="text-2xl font-semibold">Dashboard</h1>
-    </main>
-  )
-}
-```
-
-```bash
-pnpm install
-pnpm dev      # → http://localhost:5173(HMR)
-pnpm check    # 静的診断(エラーがあれば exit 1)
-pnpm routes   # ページ/API の URL マップ
-```
+下の 2 つは段階ではなく、いま自分がどちらにいるかを確かめるための地図として読む。
 
-`server/` ディレクトリが無いので、この構成は **SPA モード**。ページを直下に置く形だが、
-`src/` を作ってその中に集めてもよい(テンプレートから始めた場合は最初から `src/` がある)。
-どちらか一方に寄せること(→「ディレクトリ構造」)。
+- `server/` が**ある** → データは自前の `/api/*` から `useApiQuery` で取る(→ `agents/api.md`)。
+- `server/` が**無い** → 外部 API を直接叩くなら `useQuery`(→ `agents/page.md`)。自前の API が
+  要るようになったら `server/api/*.ts` を足すだけでよい(設定変更は不要)。
 
-## ルーティング規約(ファイル名 → ルート)
+## 何を書くか → どのファイルを読むか
 
-ページルート(`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` |
+| `.xlsx` ページ | `agents/xlsx.md` |
+| `.csv` ページ | `agents/csv.md` |
 
 ## 環境変数
 
@@ -304,20 +127,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` の対象ではない(未知名で実行すると候補が一覧表示される)。
-
 ## ドキュメントを引く(`vantage docs` / `vantage search`)
 
 ```bash
@@ -363,7 +172,9 @@ body・レスポンスの status と形)まで出る。`vantage check --json` /
 
 - **`vantage-app`** — アプリを一から作る / 構成を広げるときの進め方と検証の順序
 - **`vantage-add-feature`** — 既存アプリに page / api / ui を 1 つ足す定型
+- **`vantage-slide`** — `.slide.tsx` でスライドデッキを書く(キャンバスの予算・段階表示・pptx 書き出し)
 - **`vantage-pitfalls`** — Base UI(≠ Radix)の癖など、静かに壊れる落とし穴のリファレンス
+- **`project-storage`** — Squadbase の Project Storage(アップロード済みファイル)をブラウザから読み書きする
 
 手順書の本体は `SKILL.md` というファイルで、置き場所はアプリによって違う(ルート直下・
 `.claude/skills/`・`.squadbase/skills/` など)。**探す必要はない ― CLI が探す:**
@@ -383,6 +194,9 @@ vantage add skill --all --dir .claude/skills   # 置き場所を指定(既定は
 配置済みのコピーを新しいバージョンに更新したいときだけ `--force` を付ける(見つかった場所を
 そのまま書き換える)。
 
+**役割分担:** Skill = 手順書(踏み込んだワークフロー) / `agents/*.md` = 種類ごとの静的
+リファレンス / `AGENTS.md`(このファイル) = 地図。
+
 ---
 
 # テンプレート固有の規約(Squadbase テンプレート)
@@ -391,8 +205,9 @@ vantage add skill --all --dir .claude/skills   # 置き場所を指定(既定は
 > フレームワーク規約と矛盾する場合は**こちらが優先**します。
 >
 > `vantage upgrade` はこのファイルをフレームワーク同梱の正本で丸ごと上書きするため、
-> このセクションは消えます。消えたら squadbase-templates リポジトリの `agents/vantage/`
-> から貼り直してください(リポジトリ側では `npm run agents` が正本と結合して再生成します)。
+> このセクションは消えます。消えたら squadbase-monorepo の
+> `packages/vantage-template/agents/vantage/` から貼り直してください
+> (リポジトリ側では `npm run agents` が正本と結合して再生成します)。
 
 ## Squadbase の Connection / Query からデータを読む
 
@@ -469,3 +284,51 @@ const res = await fetch(`${baseUrl}/queries/${QUERY_ID}?since=2026-01-01`, {
   body: JSON.stringify({ customerId: "c_123" }),
 })
 ```
+
+## 構築中の一時的なエラーを「進行中」に見せる(`components/build-recovery.tsx`)
+
+ページを書いている途中は、ファイルが書き終わる順番の都合で一瞬だけページが throw する
+(まだ存在しないモジュールの import、書きかけのコンポーネント)。これを受け止めるのは
+**Vantage の既定エラー画面**(`Something went wrong`)で、**テンプレートからは差し替えられない** —
+`_error.tsx` はルートルート専用で、ページごとの `errorComponent` は現行プロトタイプでは
+まだ結線されていない。しかも掴んでいるのは TanStack の CatchBoundary なので、HMR で
+ソースが差し替わってもリセットされず、**リロードするまでエラー画面が貼り付く**。
+
+`components/build-recovery.tsx` の `BuildRecovery` が、その画面を DOM から検知して
+`Working on it…` 表示を被せ、dev では 1.2 秒待ってから自動でリロードして復帰させる
+(上限 3 回。使い切ったら「再読み込み」の案内に降格し、無事に描けたら残数が戻る)。
+降格した画面にはエラー本文をそのまま出し、`Copy log` でコピーできるようにしてある —
+自力で直らないときに本文をそのまま貼り戻してもらうため。
+`_error.tsx` も同じ `RecoveringState` を描くので、ルートレイアウトが throw したときの
+見た目と復帰の仕方は揃っている。
+
+### 追加の不変条件
+
+- **`_layout.tsx` の `<BuildRecovery>` を外さない。** `<Outlet />` を包む形で 1 回だけ使う。
+  外すと、書き込み途中の一瞬のエラーが `Something went wrong` のまま残る。
+- **`components/build-recovery.tsx` と `_error.tsx` を消さない・作り直さない。** ページ側に
+  独自のエラー UI を足す必要はない(足しても既定エラー画面より内側には入れない)。
+- **`role="alert"` の中に `h2` を置かない。** これが既定エラー画面の目印なので、ページが
+  同じ形を描くと `BuildRecovery` が誤検知して中身を覆ってしまう。UI キットの `Alert` /
+  `ErrorState` は見出しを `div` / `p` で描くのでそのまま使ってよい。
+- **データ取得の失敗は各ページが `ErrorState` で出す。** `BuildRecovery` が拾うのは
+  「レンダリングが throw した」場合だけで、`useApiQuery` の `isError` はページの責任
+  (→ `agents/page.md` の「データ取得」)。
+
+## 依存の追加とスクリプトの実行は bun で
+
+このプロジェクトの package manager は **bun** です(`squadbase.yml` の `package_manager: bun`、
+lockfile は `bun.lock`)。Squadbase のサンドボックスは bun と依存のキャッシュを持っており、
+`bun install` はキャッシュだけで終わります。上のフレームワーク規約に出てくる
+`pnpm install` / `pnpm dev` / `pnpm check` は、そのまま `bun install` / `bun run dev` /
+`bun run check` に読み替えてください。
+
+### 追加の不変条件
+
+- **依存を足すときは `bun add <pkg>`(開発用は `bun add -d <pkg>`)。** `npm install` や
+  `pnpm add` を使わない — `package-lock.json` / `pnpm-lock.yaml` が生えて `bun.lock` と別の断面に
+  なり、次回起動時の install が lockfile を作り直す。
+- **`bun.lock` を消さない・手で編集しない。** `package.json` の依存を直接書き換えたときは
+  `bun install` を一度走らせて `bun.lock` を追従させ、両方を同じコミットに入れる。
+- スクリプトは `bun run <script>`(`bun run dev` / `bun run build` / `bun run check` /
+  `bun run routes`)。`npm run <script>` でも動くが、install に npm を使わないこと。