@squadbase/vantage 0.2.0 → 0.2.1

package/skills/vantage-app/SKILL.md

@@ -1,51 +1,32 @@
 ---
 name: vantage-app
-description: Vantage(@squadbase/vantage)ダッシュボードアプリの新規作成と、index.tsx 1ファイルの SPA から server/api・ネストレイアウト・動的ルート・404/error を備えた fullstack への拡張手順。Vantage アプリを一から作る/構成を広げるとき、ルーティング規約や definePage の書き方に迷ったときに使う。
+description: Vantage(@squadbase/vantage)ダッシュボードアプリを一から作る / 既存アプリの構成を広げるときの進め方。骨組みの用意、ルートの決め方、データ取得の選択(外部 API か自前の server/api か)、どこで手を止めて検証するかの順序を扱う。規約そのものはアプリルートの AGENTS.md が正本。
 ---
 
-# Vantage アプリの作成と fullstack 拡張
+# Vantage アプリの作り方 — 進め方と検証の順序
 
-Vantage は設定ファイル不要(config-free)な React ダッシュボードフレームワーク。アプリ作者が
-書くのは `index.tsx`(と任意の追加ファイル)だけで、Vite・ルーティング・TanStack Query・
-Tailwind・UI キット・開発サーバー・API サーバー・ビルドはすべて Vantage が所有する。
+規約・不変条件・import サブパスの一覧・各 API の書式は、アプリルートの **`AGENTS.md`** が正本。
+**先にそれを読む**(無ければ `vantage add agents` で置ける)。このスキルは「どの順で作り、どこで
+手を止めて検証するか」だけを扱い、AGENTS.md の内容は繰り返さない。
 
-このスキルは「アプリを一から作る」「最小の SPA を fullstack に広げる」ワークフローを扱う。
-個別のページ/API/UI の追加は `vantage-add-feature` スキル、実装中に踏みやすい落とし穴は
-`vantage-pitfalls` スキルを参照。
+- ページ / API / UI を 1 つ足すだけなら → `vantage-add-feature`
+- 実装したのに静かに壊れたら → `vantage-pitfalls`
 
-## 大原則(先に頭に入れる)
+## 全体の流れ
 
-- **設定ファイルを作らない。** `vite.config.*`・`tailwind.config.*`・`postcss.config.*`・
-  `components.json`・`vantage.config.*` はすべて禁止。存在すると `vantage check` がエラーにする。
-  設定は「ファイル名の規約」で表現する。
-- **import は必ず `@squadbase/vantage` のサブパス経由。** `@tanstack/*`・`@base-ui/react`・
-  `echarts`・`hono`・`vite`・`tailwindcss` を直接 import しない。`lucide-react` のアイコンだけは
-  直接 import してよい。
-- **`.vantage/` と `dist/` は生成物。** 編集しない・読みにいかない(gitignore 済み)。
+1. **骨組み** — `pnpm dev` が上がるところまで
+2. **ルートを決める** — ページファイルを置き、`vantage routes` で URL を確認
+3. **データを繋ぐ** — 外部 API か、自前の `server/api` か
+4. **仕上げ** — `check` → `build` → `preview`
 
-## サブパスの地図
+**各段階の終わりに `vantage check` を通す。** 静的診断(禁止ファイル・ルート衝突・境界違反・
+API export・env 誤用)はユーザーコードを実行しないので速く、エラーがあれば exit 1 になる。
+まとめて最後に回すと、原因の切り分けが難しくなる。
 
-| import 元 | 提供するもの |
-| --- | --- |
-| `@squadbase/vantage` | `definePage`(ページ設定) |
-| `@squadbase/vantage/router` | `Link`・`Outlet`・`useParams`・`useSearch`・`useNavigate`・`redirect`・`notFound`・`useRoutes`・`useCurrentRoute`・`useSearchParam`・`useSearchState` |
-| `@squadbase/vantage/query` | `useApiQuery`・`useApiMutation`・`apiJson`・`apiFetch`・`apiUrl`・`ApiError`、ほか `useQuery`/`useMutation` など TanStack Query の再エクスポート |
-| `@squadbase/vantage/ui` | shadcn/ui 系プリミティブ(`Button`・`Loading`・`ErrorState`・`Empty` ほか) |
-| `@squadbase/vantage/components` | 複合パーツ(`PageShell`・`DashboardCardPreset`・`DataTablePreset`・`EChart` ほか) |
-| `@squadbase/vantage/markdown` | `MarkdownRenderer`(Shiki を隔離するため専用サブパス) |
-| `@squadbase/vantage/server` | `ApiContext`・`HttpError`(server/ 側でのみ使う) |
+## Step 1 — 骨組み
 
-どのコンポーネントがあるか、props が何かは **`vantage docs` で引く**(パッケージ同梱。
-`vantage docs` で一覧、`vantage docs button` / `vantage docs parts/data-table` で個別ページ、
-`--json` で機械可読)。**props を推測で書かない。** 名前が分からないときは
-**`vantage search <やりたいこと>`**(例: `vantage search 期間を選ぶ UI が欲しい`)で探し、
-出てきた slug を `vantage docs` に渡す。
-
-## Step 1 — 最小アプリ(SPA モード)
-
-`package.json` と `index.tsx` の2ファイルだけで動く。
-
-`package.json`:
+新規なら `package.json` と `index.tsx` の 2 ファイルだけ。設定ファイルは**作らない**
+(`vite.config.*` 等は `vantage check` がエラーにする)。
 
 ```json
 {
@@ -67,223 +48,73 @@ Tailwind・UI キット・開発サーバー・API サーバー・ビルドは
 }
 ```
 
-`index.tsx`(ルートのデフォルトエクスポートが `/` ページになる):
-
-```tsx
-export default function Dashboard() {
-  return (
-    <main className="p-6">
-      <h1 className="text-2xl font-semibold">Dashboard</h1>
-    </main>
-  )
-}
-```
+`index.tsx` はデフォルトエクスポートの React コンポーネント 1 つ(これが `/` になる)。あとは
+`pnpm install && pnpm dev` で http://localhost:5173 が上がる。
 
-起動と検証:
+**既存アプリに合流したときは、作る前に現状を読む:**
 
 ```bash
-pnpm install
-pnpm dev      # → http://localhost:5173(HMR)
-pnpm check    # 静的診断。エラーがあれば exit 1
-pnpm routes   # ページ/API の URL マップ
-```
-
-`server/` ディレクトリが無いので、この時点では **SPA モード**(`vantage-manifest.json` の
-`mode: "spa"`)。
-
-## Step 2 — ページを足してファイルベースルーティングにする
-
-ルートディレクトリ直下の `.tsx`/`.jsx` がそのままページになる。規約:
-
-| ファイル | ルート |
-| --- | --- |
-| `index.tsx` | `/` |
-| `monthly-analysis.tsx` | `/monthly-analysis` |
-| `sales/index.tsx` | `/sales` |
-| `sales/[customerId].tsx` | `/sales/:customerId`(動的パラメータ) |
-| `_layout.tsx` | そのディレクトリ配下を包むネストレイアウト |
-| `_404.tsx` | Not Found ページ |
-| `_error.tsx` | ルートが throw したときのエラーページ |
-
-`components/`・`hooks/`・`lib/`・`server/`・`public/` はルート走査の対象外(ページにならない)。
-
-各ページは **デフォルトエクスポートの React コンポーネントが必須**。タイトル等は `definePage`:
-
-```tsx
-import { definePage } from "@squadbase/vantage"
-
-// navLabel は useRoutes() で組むナビの表示名(省略時は title)
-export const page = definePage({ title: "Monthly Analysis · Acme", navLabel: "Monthly" })
-
-export default function MonthlyAnalysis() {
-  return <main className="p-6">…</main>
-}
-```
-
-> `page` エクスポートはランタイムでは読まれない。title/description/navLabel はビルド時に
-> **静的抽出**されるので、値はリテラルで書く(変数や関数呼び出しにしない)。
-
-### ネストレイアウトと特殊ページ
-
-`_layout.tsx` は `Outlet` で子ルートを描く。ナビは `useRoutes()` から組むと、ページファイルを
-足すだけでリンクが増える(手で持つリンク配列を作らない):
-
-```tsx
-import { Link, Outlet, useCurrentRoute, useRoutes } from "@squadbase/vantage/router"
-
-export default function RootLayout() {
-  // 動的ルート(/sales/:id)は URL が定まらないので外す。label は navLabel → title → path
-  const routes = useRoutes().filter((r) => !r.dynamic)
-  const current = useCurrentRoute()
-
-  return (
-    <div className="min-h-screen">
-      <header>
-        {routes.map((r) => (
-          <Link key={r.path} to={r.to} activeClassName="font-semibold">
-            {r.label}
-          </Link>
-        ))}
-      </header>
-      <Outlet />
-    </div>
-  )
-}
-```
-
-`_404.tsx` / `_error.tsx` は `ui/` の状態コンポーネントを使うと早い:
-
-```tsx
-// _error.tsx
-import { ErrorState } from "@squadbase/vantage/ui"
-export default function RouteError({ error }: { error: unknown }) {
-  const message = error instanceof Error ? error.message : String(error)
-  return <ErrorState title="This page failed to render" message={message} />
-}
+vantage routes     # 既にあるページと API の URL マップ
+vantage check      # いま壊れていないか(これから出すエラーと切り分ける)
+ls server/         # あれば fullstack モード。無ければ SPA
+ls .claude/skills  # 配置済みの skill(このファイルの仲間)
 ```
 
-### 動的パラメータの「3つの綴り」を必ず同期させる
+## Step 2 — ルートを決める
 
-これは崩すと壊れる不変条件:
+ファイル名がそのままルートになる(対応表は AGENTS.md「ルーティング規約」)。**ルーターを設定
+する場所は無い**ので、決めるのは「どんなファイル名で置くか」だけ。
 
-- ファイル名 `sales/[customerId].tsx`
-- 表示ルート `/sales/:customerId`
-- リンク: `to="/sales/$customerId"` + `params={{ customerId }}`
+- ページを置いたら `vantage routes` で URL を確かめる。意図と違うなら**ファイル名が違う**。
+- ナビゲーションはリンク配列を手で持たず、`useRoutes()` から組む。この形にしておくと以後は
+  ページファイルを足すだけでナビが増える(AGENTS.md「ナビはルート一覧から組む」)。
+- 共通の枠(ヘッダ・サイドバー)は `_layout.tsx`、Not Found と例外は `_404.tsx` / `_error.tsx`。
+- 一覧 → 詳細を作るなら、**動的パラメータの「3 つの綴り」を先に決めてから**両方のファイルを
+  書く。後から変えると静かにマッチしなくなる。
 
-```tsx
-import { Link, useParams } from "@squadbase/vantage/router"
+## Step 3 — データを繋ぐ
 
-// 一覧側のリンク
-<Link to="/sales/$customerId" params={{ customerId: row.id }}>{row.name}</Link>
-
-// 詳細ページ側で取り出す
-const { customerId } = useParams()
-```
-
-## Step 3 — サーバー状態(API を持たない fetch)
-
-外部 API を叩くだけなら `server/` は不要。`@squadbase/vantage/query` の `useQuery` を使う:
-
-```tsx
-import { useQuery } from "@squadbase/vantage/query"
-
-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`(→ Step 4)。
-
-### フィルタ状態は URL に置く
-
-ダッシュボードの絞り込みは `useState` ではなく `useSearchParam` にする。リロードで消えず、
-URL をそのまま共有できる:
-
-```tsx
-import { useSearchParam, useSearchState } from "@squadbase/vantage/router"
-
-const [region, setRegion] = useSearchParam("region", "all")              // 値は常に string
-const [segments, setSegments] = useSearchState<string[]>("segments", []) // 配列・オブジェクト
-```
-
-デフォルト値(または `null`)を書き込むとキーは URL から消える。履歴は既定で `replace`
-(`{ replace: false }` で push)。動的ルートの上でもパスパラメータは保たれる。
-
-## Step 4 — fullstack へ拡張(server/api を足す)
-
-**`server/` ディレクトリを作った瞬間に fullstack モードになる。** `server/api/**` の各ファイルが
-API ルートになり、ビルドは client + server バンドル + `mode: "fullstack"` の manifest を出す。
-
-`server/api/monthly-analysis.ts` → `GET /api/monthly-analysis`:
-
-```ts
-import type { ApiContext } from "@squadbase/vantage/server"
-
-export async function GET(_ctx: ApiContext) {
-  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` が効くので `params.id!` 等で 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 の項目は落ちる → URL にもキーにも出ない)
-const rows = useApiQuery<Row[]>("/api/customers", { search: { segment } })
-
-// 書き込み。変数がそのまま JSON ボディになる
-const save = useApiMutation<Customer, Payload>("/api/customers", { method: "POST" })
-```
+**どちらの経路かを先に決める。** ここを間違えると後で全部書き直しになる:
 
-`ApiError` は `message`・`status`・`body`・`requestId`(dev ターミナルのログと突き合わせられる)を
-持つ。hook が使えない場所では `apiJson(path, init)`、生の `Response` が要るときは `apiFetch`。
+| データ元 | 使うもの | `server/` |
+| --- | --- | --- |
+| ブラウザから直接叩ける公開 API | `useQuery` + `fetch` | 不要 |
+| DB / シークレットが要る / CORS で叩けない | `server/api/*.ts` + `useApiQuery` | 必要 |
 
-### server/ とクライアントの境界(絶対に守る)
+**API キーが要る時点で後者しかない** — クライアントに届く env は `PUBLIC_*` だけで、
+シークレットは `ApiContext.env`(= `server/` の中)にしか届かない。
 
-- **クライアントコードは `server/` を import してはならない。** 共有したいコードは `lib/` に置く。
-  違反は `CLIENT_IMPORTS_SERVER` エラー(静的にもビルド時にも弾かれる)。
-- サーバー専用のデータ/ヘルパは `server/utils.ts` などに置き、`server/api/**` からのみ import する。
+後者の手順:
 
-## Step 5 — 環境変数
+1. `server/api/<name>.ts` に `GET` を書く。**このディレクトリを作った時点で fullstack モード**
+   になる(設定変更は不要)。
+2. `vantage routes` に `/api/<name>` が出ることを確認する。
+3. dev サーバーか `curl` で叩き、**返す JSON の形を確定させてから** UI を書く。エラー応答は
+   `HttpError(status, msg)` を throw して作る。
+4. クライアントから `useApiQuery<T>("/api/<name>")` で受ける。`isPending` / `isError` の分岐を
+   最初から書く(`Loading` / `ErrorState` が `ui/` にある)。
 
-- **クライアントに届くのは `PUBLIC_` 接頭辞の付いた env のみ**。`import.meta.env.PUBLIC_FOO`。
-  `VITE_` 系の API は無い。それ以外を `import.meta.env` で読むと `PUBLIC_ENV_MISUSE` 警告。
-- サーバー側のシークレットは `ApiContext.env.MY_SECRET` で読む(`server/` 内のみ)。
+ダッシュボードの**絞り込みは `useState` ではなく `useSearchParam` / `useSearchState`** に置く。
+リロードで消えず、URL をそのまま共有できる。これも後から差し替えると全ページに波及するので、
+最初のフィルタを作る時点で決める。
 
-## Step 6 — 検証・ビルド・プレビュー
+## Step 4 — 仕上げ
 
 ```bash
-pnpm check     # 静的診断(禁止ファイル・ルート衝突・境界・API export・env 誤用)
-pnpm routes    # ページ + API の URL マップを確認
+pnpm check     # エラーが残っていないか(exit 1 なら残っている)
+pnpm routes    # 公開される URL の最終確認
 pnpm build     # dist/ に client(+ server)+ vantage-manifest.json
-pnpm preview   # 本番ビルドをローカル実行(fullstack:4173 / spa は Vite preview)
+pnpm preview   # 本番ビルドをローカルで動かす
 ```
 
 `vantage-manifest.json` の `mode` は `server/` の有無から自動で決まる(手で書かない)。
-デプロイまでの詳細は別途デプロイ手順を参照。
+`preview` まで通れば、そのまま同じ成果物がデプロイされる。
 
 ## 詰まったら
 
-- `console.*` とランタイムエラーは開発ターミナルに `[browser:…]` として転送される。
-- `vantage check --json` / `vantage routes --json` はエージェント向けの機械可読出力。
-- 規約や props を確かめたいときは `vantage docs <name>`(ガイドは `vantage docs routing` など、
-  一覧は `vantage docs`)。名前が思い出せないときは `vantage search <やりたいこと>`、
-  綴りを横断で確かめたいときは `vantage search "<regex>" --regex`。
-- Base UI(≠ Radix)固有の罠、`SelectValue` の挙動、EChart のテーマ非追従などは
-  `vantage-pitfalls` スキルにまとまっている。
+- ブラウザの `console.*` とランタイムエラーは、**開発ターミナルに `[browser:…]` として転送
+  される**。ブラウザの devtools を開かなくても読める。
+- `vantage check --json` / `vantage routes --json` は機械可読出力。
+- props や規約を確かめたいときは `vantage docs <name>`、名前が思い出せないときは
+  `vantage search <やりたいこと>`。**推測で props を書かない。**
+- Base UI(≠ Radix)の癖など、静かに壊れる系は `vantage-pitfalls` にまとまっている。

package/skills/vantage-pitfalls/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vantage-pitfalls
-description: Vantage(@squadbase/vantage)アプリを書くときに静かに壊れる落とし穴のリファレンス。Base UI は Radix ではない(asChild 無し・render プロップ)、SelectValue は value を描く、クライアントから server/ を import しない、EChart はテーマ非追従、動的パラメータの3綴り同期、PUBLIC_ env、HttpError など。Vantage の UI コンポーネントやルーティングが思った通りに動かないとき、ビルドやスタイルが静かに欠落するときに参照する。
+description: Vantage(@squadbase/vantage)アプリを書くときに静かに壊れる落とし穴のリファレンス。Base UI は Radix ではない(asChild 無し・render プロップ)、Select の value/label、クライアントから server/ を import しない、EChart の配色と高さ、動的パラメータの3綴り同期、PUBLIC_ env、HttpError など。Vantage の UI コンポーネントやルーティングが思った通りに動かないとき、ビルドやスタイルが静かに欠落するときに参照する。
 ---
 
 # Vantage アプリの落とし穴リファレンス
@@ -19,26 +19,33 @@ Vantage の UI キットは shadcn/ui の **Base UI バリアント**。Radix
 - **`Checkbox` の `checked` は `boolean` のみ。** 中間状態は `indeterminate` プロップ。
 - **`ToggleGroup` の `value` は配列。**
 
-### `SelectValue` は「選択中の value」を描く。`SelectItem` の children は見ない
+### `SelectValue` の value/label は Vantage 側が吸収済み(残る 1 ケースだけ注意)
 
-値とラベルが違うと、トリガーに `kanto` や `/sales` といった**生の値**が出てしまう。ラベルを
-出したいときは `items`(value→label のマップ)を渡す:
+Base UI の `SelectValue` は選択中の **value をそのまま描き**、`SelectItem` の children を見ない
+部品。Vantage の `Select` は children から `value` → ラベルを集めて渡すので、普通に書けば
+トリガーに「関東」と出る。**手当てが要るのは 1 ケースだけ** — `SelectItem` を別のコンポーネント
+が返している場合は集められないので、`items` を明示する:
 
 ```tsx
-<Select items={{ kanto: "関東", kansai: "関西" }} … />
+// SelectItem がこの場に無い(<RegionItems /> の中で作られる)ときだけ必要
+<Select items={{ kanto: "関東", kansai: "関西" }} …>
+  <SelectContent><RegionItems /></SelectContent>
+</Select>
 ```
 
-`FilterBarSelect` / `AppShell` の header variant / `DataTablePagination` は内部でこの `items` を
-組み立てている。自前で `Select` を使うときは忘れやすい。
+トリガーに `kanto` や `/sales` と生の値が出たら、まずこれを疑う。
 
-## チャート:`EChart` はテーマに自動追従しない
+## チャート:`EChart` の配色はトークン追従。上書きは `option.color`
 
-`EChart` は薄いラッパー(init/resize/dispose・loading・`onEvents`・PNG コピー/ダウンロードだけ)。
-配色は**各アプリが `option.color`** で決める(または `theme` に echarts テーマを渡す)。
+系列色は `--chart-1..5`、軸・凡例・ツールチップは文字色/境界色のトークンから組まれ、
+ライト / ダークの切り替えにも追従する(init 時にトークンの実値を解決している)。
 
-- `--chart-1..5` を読んで明暗テーマを自動で組む機構は**意図的に無い**(ECharts はキャンバス
-  描画で CSS 変数を読めない)。ダークモード追従が要るなら自前で色を切り替える。
-- キャンバス系なので、コンテナに高さを与えないと何も見えない。
+- **`theme` プロップを渡すと追従は完全に止まる。** 系列の色だけ変えたいなら `option.color` を
+  使う ― option はテーマより優先されるので、軸まわりの追従は残る。
+- キャンバス系なので、**コンテナに高さを与えないと何も見えない**(既定は `h-[400px]`。
+  `h-full` を使うなら親に確定した高さが要る)。
+- `option` は `EChartsOption` を annotate するか `satisfies` を付ける。付けないと
+  `type: "category"` が `string` に広がってビルドが落ちる。
 
 ## 境界:クライアントから `server/` を import しない
 
@@ -108,7 +115,7 @@ throw new Error("boom")                 // → ログに出て汎用 500 に丸
 - `vite.config.*` — Vite 設定は Vantage が所有
 - `tailwind.config.*` — テーマは `styles.css` のトークンで調整
 - `postcss.config.*` — Vantage が管理
-- `components.json` — UI は `vantage add ui <name>` でコピー
+- `components.json` — shadcn CLI は使わない。UI は `@squadbase/vantage/ui` から import する
 - `vantage.config.*` — v1 に設定ファイルは無い(規約で表現)
 
 ## Markdown:`MarkdownRenderer` は `@squadbase/vantage/markdown` から

package/templates/AGENTS.md

@@ -9,10 +9,9 @@
 > `vantage upgrade` を実行するとフレームワーク同梱の正本から再同期されて上書きされます。
 > アプリ固有のメモは別ファイル(例: `README.md`)に書いてください。
 >
-> 手順を伴う踏み込んだワークフローは、同梱の Claude Code Skill に分かれています
-> (`vantage add skill --all --dir .claude/skills` で配置)。このファイルは「地図」、Skill は
-> 「手順書」という役割分担です。詰まったら `vantage-app` / `vantage-add-feature` /
-> `vantage-pitfalls` を参照してください。
+> 手順を伴う踏み込んだワークフローは、同梱の Claude Code Skill に分かれています。このファイルは
+> 「地図」、Skill は「手順書」という役割分担です。**配置済みの Skill を先に探す**手順は
+> 末尾の「さらに詳しく(同梱 Skill)」にあります。
 
 ## Vantage とは
 
@@ -50,9 +49,21 @@ UI キット・開発サーバー・API サーバー・ビルドはすべて Van
 | `@squadbase/vantage/ui` | shadcn/ui(Base UI バリアント)プリミティブ(`Button`・`Loading`・`ErrorState`・`Empty` ほか) |
 | `@squadbase/vantage/components` | 複合パーツ(`PageShell`・`DashboardCardPreset`・`DataTablePreset`・`EChart` ほか) |
 | `@squadbase/vantage/markdown` | `MarkdownRenderer`(Shiki を隔離するための専用サブパス) |
-| `@squadbase/vantage/server` | `ApiContext`・`HttpError`(server/ 側でのみ使う) |
+| `@squadbase/vantage/server` | `ApiContext`・`ApiHandler`・`HttpError`・`isHttpError`・`json`(server/ 側でのみ使う) |
 
-## 最小アプリ(SPA モード)
+## モードは 2 つ、切り替えるのは `server/` の有無だけ
+
+`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 ファイルだけで動く。
 
@@ -97,7 +108,7 @@ pnpm check    # 静的診断(エラーがあれば exit 1)
 pnpm routes   # ページ/API の URL マップ
 ```
 
-`server/` ディレクトリが無いので、この時点では **SPA モード**。
+`server/` ディレクトリが無いので、この構成は **SPA モード**。
 
 ## ルーティング規約(ファイル名 → ルート)
 
@@ -196,13 +207,13 @@ 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 に
-する」)。
+自分の `server/api` を叩くときは `useQuery` ではなく `useApiQuery`(→「API を持つ(fullstack
+モード)」)。
 
-## API を足して fullstack にする
+## API を持つ(fullstack モード)
 
-**`server/` ディレクトリを作った瞬間に fullstack モードになる。** `server/api/**` の各ファイルが
-API ルートになる。
+**`server/` ディレクトリがあれば fullstack モード**(無いアプリに足せば、その時点で切り替わる)。
+`server/api/**` の各ファイルが API ルートになる。
 
 `server/api/monthly-analysis.ts` → `GET /api/monthly-analysis`:
 
@@ -252,15 +263,16 @@ const save = useApiMutation<Customer, Payload>("/api/customers", { method: "POST
 ## 組み込み UI / コンポーネントの入口
 
 - **プリミティブ**は `@squadbase/vantage/ui` から import する(`Button`・`Loading`・
-  `ErrorState`・`Empty`・`Select`・`Checkbox` ほか)。編集したいコピーが要るなら
-  `vantage add ui <name>` で `components/ui/` に取り出す。
+  `ErrorState`・`Empty`・`Select`・`Checkbox` ほか)。
 - **複合パーツ**は `@squadbase/vantage/components` から(`PageShell`・`DashboardCardPreset`・
-  `DataTablePreset`・`EChart` ほか)。ブロックは `vantage add block <name>` で取り出す。
+  `DataTablePreset`・`EChart` ほか)。
 - **どの名前が import 可能か / props の詳細は `vantage docs` で引く。** ガイドとコンポーネント
   リファレンスはパッケージに同梱されていて、オフラインでも読める(→「ドキュメントを引く」)。
   **名前が分からないとき**はやりたいことで `vantage search` する(→ 同節)。
-- `vantage add ui`・`vantage add block` でコピーできる名前は、未知名で実行すると候補が一覧表示
-  される。
+- **UI は import して使うのが既定。取り出す(eject)必要はない。** `vantage add ui|block` は
+  ソースを手元にコピーして**改造したいとき専用**のコマンドで、取り出せるのは
+  `ui: data-table` と `block: sales-overview` の 2 つだけ。それ以外の名前は import 専用で
+  `add` の対象ではない(未知名で実行すると候補が一覧表示される)。
 
 ## ドキュメントを引く(`vantage docs` / `vantage search`)
 
@@ -302,9 +314,22 @@ pnpm preview   # 本番ビルドをローカル実行
 
 ## さらに詳しく(同梱 Skill)
 
-`vantage add skill --all --dir .claude/skills` で配置される(`--dir` を省くとルート直下):
+- **`vantage-app`** — アプリを一から作る / 構成を広げるときの進め方と検証の順序
+- **`vantage-add-feature`** — 既存アプリに page / api / ui を 1 つ足す定型
+- **`vantage-pitfalls`** — Base UI(≠ Radix)の癖など、静かに壊れる落とし穴のリファレンス
+
+**まず、このアプリに配置済みかを探す。** 手順書の本体は SKILL.md というファイルで、置き場所は
+アプリによって違う:
+
+```bash
+ls .claude/skills          # よくある置き場所
+ls -d vantage-*            # ルート直下に置くのが既定
+```
+
+見つかったらその `SKILL.md` を読む(`vantage add skill` を再実行する必要はない)。**無いときだけ**
+配置する ― 一覧は名前を省いて実行すると出る:
 
-- **`vantage-app`** — アプリを一から作る / SPA を fullstack に広げる手順
-- **`vantage-add-feature`** — 既存アプリに page / api / ui / block を 1 つ足す定型
-- **`vantage-pitfalls`** — Base UI(≠ Radix)の癖、`SelectValue` の挙動、EChart のテーマ
-  非追従など、静かに壊れる落とし穴のリファレンス
+```bash
+vantage add skill                              # 同梱されている skill 名の一覧
+vantage add skill --all --dir .claude/skills   # 配置(--dir を省くとルート直下)
+```