@squadbase/vantage 0.0.1 → 0.1.1

package/skills/vantage-add-feature/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: vantage-add-feature
+description: 既存の Vantage(@squadbase/vantage)アプリにページ・API エンドポイント・UI コンポーネント・ブロックを追加する定型ワークフロー。vantage add コマンドで雛形を出し、規約(動的パラメータの綴り・server 境界・大文字メソッド)を守り、vantage check / routes で確認するまでの一連。Vantage アプリに機能を1つ足すときに使う。
+---
+
+# Vantage への機能追加(page / api / ui / block)
+
+既存の Vantage アプリに要素を1つ追加するときの定型手順。アプリの新規作成や fullstack 化の
+全体像は `vantage-app` スキル、実装で踏みやすい罠は `vantage-pitfalls` スキルを参照。
+
+CLI は雛形を出すだけで、規約の遵守はこちらの責任。**追加したら必ず `vantage check` と
+`vantage routes` で確認する**。
+
+## `vantage add` の4種別
+
+```bash
+vantage add page  <name>    # ルートページ(.tsx)
+vantage add api   <name>    # server/api/**.ts の API モジュール
+vantage add ui    <name>    # registry から UI ソースを components/ui/ にコピー
+vantage add block <name>    # registry からブロックを components/blocks/ にコピー
+```
+
+`--force` で既存ファイルを上書き。`add` の雛形は import に `@squadbase/vantage` を焼き込む。
+
+## ページを追加する
+
+```bash
+vantage add page monthly-analysis        # → ./monthly-analysis.tsx  → ルート /monthly-analysis
+vantage add page sales/index             # → ./sales/index.tsx       → ルート /sales
+vantage add page "sales/[customerId]"    # → 動的ルート /sales/:customerId
+```
+
+出力される雛形は `definePage` + デフォルトエクスポートのコンポーネント。ファイル名の規約:
+
+| ファイル | ルート | 用途 |
+| --- | --- | --- |
+| `foo.tsx` | `/foo` | 通常ページ |
+| `foo/index.tsx` | `/foo` | ディレクトリのインデックス |
+| `foo/[id].tsx` | `/foo/:id` | 動的パラメータ |
+| `_layout.tsx` | — | 配下を包むネストレイアウト(`Outlet` を描く) |
+| `_404.tsx` / `_error.tsx` | — | Not Found / エラーページ |
+
+チェックリスト:
+
+1. **デフォルトエクスポートは必須**(無いと `MISSING_DEFAULT_EXPORT` エラー)。
+2. `definePage({ title })` の値は**リテラル**で書く(ビルド時に静的抽出されるため)。ナビに出す
+   短い名前が要るなら `navLabel` も足す(`useRoutes()` が読む。既定は `title`)。
+   `_layout.tsx` のナビを `useRoutes()` で組んでいれば、ページを足すだけでリンクも増える。
+3. 動的ページなら **3つの綴りを同期**:
+   - ファイル `foo/[id].tsx`
+   - 表示ルート `/foo/:id`
+   - リンク `to="/foo/$id"` + `params={{ id }}`、取り出しは `const { id } = useParams()`
+4. `components/`・`hooks/`・`lib/`・`server/`・`public/` はページにならない(ルート走査対象外)。
+
+## API を追加する(fullstack)
+
+```bash
+vantage add api monthly-analysis     # → server/api/monthly-analysis.ts → GET /api/monthly-analysis
+vantage add api "customers/[id]"     # → server/api/customers/[id].ts   → GET /api/customers/:id
+```
+
+**`server/` を作った時点でアプリは fullstack モードに切り替わる**(SPA → fullstack)。
+雛形は `GET` ハンドラ:
+
+```ts
+import type { ApiContext } from "@squadbase/vantage/server"
+
+export async function GET({ request, params }: ApiContext) {
+  return Response.json({ ok: true, params })
+}
+```
+
+チェックリスト:
+
+1. **エクスポート名は大文字の HTTP メソッド**のみ(`GET`/`POST`/`PUT`/`PATCH`/`DELETE`/`OPTIONS`)。
+   他の名前は `INVALID_API_EXPORT` エラー。
+2. `ApiContext` は Web 標準ベース: `request`(`Request`)・`params`・`env`・`waitUntil`。
+3. 動的パラメータは `params.id`。`noUncheckedIndexedAccess` が効くので `params.id!` などで narrowing。
+4. **クライアントに見せるエラーは `HttpError(status, msg)` を throw**。それ以外の throw は
+   500 に丸められログに出る。
+   ```ts
+   import { HttpError, type ApiContext } from "@squadbase/vantage/server"
+   export async function GET({ params }: ApiContext) {
+     const row = findCustomer(params.id!)
+     if (!row) throw new HttpError(404, `Customer ${params.id} not found`)
+     return Response.json(row)
+   }
+   ```
+5. **シークレットは `ctx.env` からのみ**読む。クライアントには決して渡さない。
+6. サーバー専用の共有コードは `server/utils.ts` 等に置く。**クライアントから `server/` を
+   import しない**(`CLIENT_IMPORTS_SERVER` エラー。共有は `lib/` に置く)。
+
+クライアント側から叩くときは `useApiQuery`(ベース URL 解決・JSON パース・非 2xx の `ApiError`
+化・クエリキー `["api", url]` が入っている):
+
+```tsx
+import { useApiQuery } from "@squadbase/vantage/query"
+
+const q = useApiQuery<Customer>(`/api/customers/${id}`)
+if (q.isError) return <ErrorState message={q.error.message} />  // HttpError のメッセージ
+
+// クエリ文字列は search で(undefined の項目は落ちる)
+const rows = useApiQuery<Row[]>("/api/customers", { search: { segment } })
+```
+
+書き込みは `useApiMutation(path, { method: "POST" })` — 変数がそのまま JSON ボディになる。
+
+## UI コンポーネント / ブロックを追加する
+
+```bash
+vantage add ui data-table       # → components/ui/data-table.tsx(編集可能なソースをコピー)
+vantage add block sales-overview # → components/blocks/sales-overview.tsx
+```
+
+- **多くの UI コンポーネントは「import 専用」で、`add ui` でコピーできる名前は限られる。**
+  現在 registry からコピー可能なのは `data-table`(ui)と `sales-overview`(block)のみ。
+  未知の名前を渡すと利用可能な名前一覧を出して失敗する。
+- コピーが要らない大半のプリミティブは `@squadbase/vantage/ui` から、複合パーツは
+  `@squadbase/vantage/components` から**そのまま import**するのが基本(コピー不要)。
+  ```tsx
+  import { Button, Loading, ErrorState } from "@squadbase/vantage/ui"
+  import { DashboardCardPreset, DataTablePreset, EChart } from "@squadbase/vantage/components"
+  ```
+- コピーしたソースの相対 import は**ランタイムの `.js` 指定子**で書く(`./cn.js` など)。
+- **props は `vantage docs <name>` で確認してから書く**(`vantage docs button`・
+  `vantage docs parts/data-table`。名前が分からなければ `vantage search <やりたいこと>` で
+  探してから `vantage docs` に渡す)。
+
+## 追加後に必ず確認する
+
+```bash
+vantage routes    # 追加したページ/API が意図した URL に出ているか
+vantage check     # 規約違反が無いか(exit 1 ならエラーあり)
+vantage dev       # 実際に動くか(console は開発ターミナルに [browser:…] で転送)
+```
+
+エージェントで自動処理するなら機械可読出力を使う:
+
+```bash
+vantage routes --json   # { pages, layouts, notFound, error, apis, hasServer }
+vantage check --json    # { ok, errorCount, warningCount, diagnostics[] }
+```
+
+`vantage check` が出しうる診断コード(参考):
+
+| code | 意味 |
+| --- | --- |
+| `FORBIDDEN_FILE` | `vite.config.*` などの禁止設定ファイルがある |
+| `ROUTE_CONFLICT` | 同じルートを指すファイルが複数ある |
+| `MISSING_DEFAULT_EXPORT` | ページ/レイアウトにデフォルトエクスポートが無い |
+| `INVALID_API_EXPORT` | API モジュールが大文字メソッド以外をエクスポート |
+| `CLIENT_IMPORTS_SERVER` | クライアントが `server/` を import している |
+| `PUBLIC_ENV_MISUSE`(warn) | `PUBLIC_*` 以外の env をクライアントで読んでいる |

package/skills/vantage-app/SKILL.md

@@ -0,0 +1,291 @@
+---
+name: vantage-app
+description: Vantage(@squadbase/vantage)ダッシュボードアプリの新規作成と、index.tsx 1ファイルの SPA から server/api・ネストレイアウト・動的ルート・404/error を備えた fullstack への拡張手順。Vantage アプリを一から作る/構成を広げるとき、ルーティング規約や definePage の書き方に迷ったときに使う。
+---
+
+# Vantage アプリの作成と fullstack 拡張
+
+Vantage は設定ファイル不要(config-free)な React ダッシュボードフレームワーク。アプリ作者が
+書くのは `index.tsx`(と任意の追加ファイル)だけで、Vite・ルーティング・TanStack Query・
+Tailwind・UI キット・開発サーバー・API サーバー・ビルドはすべて Vantage が所有する。
+
+このスキルは「アプリを一から作る」「最小の SPA を fullstack に広げる」ワークフローを扱う。
+個別のページ/API/UI の追加は `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 済み)。
+- **モジュール間 import はランタイムの `.js` 指定子を使う**(例: `./components/revenue-chart.js`)。
+  ソースは `.tsx`/`.ts` でも、相対 import の拡張子は `.js` と書く。ESM の Node 解決に必要。
+
+## サブパスの地図
+
+| 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/ 側でのみ使う) |
+
+どのコンポーネントがあるか、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`:
+
+```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.1.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 マップ
+```
+
+`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} />
+}
+```
+
+### 動的パラメータの「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()
+```
+
+## 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/ とクライアントの境界(絶対に守る)
+
+- **クライアントコードは `server/` を import してはならない。** 共有したいコードは `lib/` に置く。
+  違反は `CLIENT_IMPORTS_SERVER` エラー(静的にもビルド時にも弾かれる)。
+- サーバー専用のデータ/ヘルパは `server/utils.ts` などに置き、`server/api/**` からのみ import する。
+
+## Step 5 — 環境変数
+
+- **クライアントに届くのは `PUBLIC_` 接頭辞の付いた env のみ**。`import.meta.env.PUBLIC_FOO`。
+  `VITE_` 系の API は無い。それ以外を `import.meta.env` で読むと `PUBLIC_ENV_MISUSE` 警告。
+- サーバー側のシークレットは `ApiContext.env.MY_SECRET` で読む(`server/` 内のみ)。
+
+## Step 6 — 検証・ビルド・プレビュー
+
+```bash
+pnpm check     # 静的診断(禁止ファイル・ルート衝突・境界・API export・env 誤用)
+pnpm routes    # ページ + API の URL マップを確認
+pnpm build     # dist/ に client(+ server)+ vantage-manifest.json
+pnpm preview   # 本番ビルドをローカル実行(fullstack:4173 / spa は Vite preview)
+```
+
+`vantage-manifest.json` の `mode` は `server/` の有無から自動で決まる(手で書かない)。
+デプロイまでの詳細は別途デプロイ手順を参照。
+
+## 詰まったら
+
+- `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` スキルにまとまっている。

package/skills/vantage-pitfalls/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: vantage-pitfalls
+description: Vantage(@squadbase/vantage)アプリを書くときに静かに壊れる落とし穴のリファレンス。Base UI は Radix ではない(asChild 無し・render プロップ)、SelectValue は value を描く、クライアントから server/ を import しない、EChart はテーマ非追従、相対 import は .js 指定子、動的パラメータの3綴り同期、PUBLIC_ env、HttpError など。Vantage の UI コンポーネントやルーティングが思った通りに動かないとき、ビルドやスタイルが静かに欠落するときに参照する。
+---
+
+# Vantage アプリの落とし穴リファレンス
+
+Vantage アプリで「型は通るのに実行時/ビルド時に静かに壊れる」パターン集。症状が出たとき、
+または該当機能を書く前に参照する。アプリ作成の流れは `vantage-app`、機能追加は
+`vantage-add-feature` スキル。個々のコンポーネントの props と使用例は
+`vantage docs <name>`(例: `vantage docs ui/select`)で引ける。
+
+## UI:Base UI は Radix ではない
+
+Vantage の UI キットは shadcn/ui の **Base UI バリアント**。Radix の癖で書くと動かない。
+
+- **`asChild` は無い。** 代わりに `render` プロップを使う。
+- **`Select` の `onValueChange` は `string | null`** を渡す(null が来うる)。
+- **`Checkbox` の `checked` は `boolean` のみ。** 中間状態は `indeterminate` プロップ。
+- **`ToggleGroup` の `value` は配列。**
+
+### `SelectValue` は「選択中の value」を描く。`SelectItem` の children は見ない
+
+値とラベルが違うと、トリガーに `kanto` や `/sales` といった**生の値**が出てしまう。ラベルを
+出したいときは `items`(value→label のマップ)を渡す:
+
+```tsx
+<Select items={{ kanto: "関東", kansai: "関西" }} … />
+```
+
+`FilterBarSelect` / `AppShell` の header variant / `DataTablePagination` は内部でこの `items` を
+組み立てている。自前で `Select` を使うときは忘れやすい。
+
+## チャート:`EChart` はテーマに自動追従しない
+
+`EChart` は薄いラッパー(init/resize/dispose・loading・`onEvents`・PNG コピー/ダウンロードだけ)。
+配色は**各アプリが `option.color`** で決める(または `theme` に echarts テーマを渡す)。
+
+- `--chart-1..5` を読んで明暗テーマを自動で組む機構は**意図的に無い**(ECharts はキャンバス
+  描画で CSS 変数を読めない)。ダークモード追従が要るなら自前で色を切り替える。
+- キャンバス系なので、コンテナに高さを与えないと何も見えない。
+
+## 境界:クライアントから `server/` を import しない
+
+- クライアント側のどのファイルも `server/` 配下を import してはいけない(`CLIENT_IMPORTS_SERVER`
+  エラー。静的にもビルド時にも弾かれる)。**共有したいコードは `lib/` に置く。**
+- シークレット等の env は `ApiContext.env`(server/ 内)にだけ届く。クライアントには渡らない。
+
+## env:クライアントに届くのは `PUBLIC_` 接頭辞だけ
+
+- クライアントで読めるのは `import.meta.env.PUBLIC_*` と `MODE`/`DEV`/`PROD`/`SSR`/`BASE_URL` のみ。
+  それ以外を `import.meta.env` で読むと `PUBLIC_ENV_MISUSE` 警告。
+- `VITE_` 系の公開 API は無い。サーバーのシークレットは `ctx.env` で読む。
+
+## import:相対 import はランタイムの `.js` 指定子で書く
+
+ソースが `.tsx`/`.ts` でも、**モジュール間の相対 import は `.js`** と書く(ESM の Node 解決に必要):
+
+```tsx
+import { RevenueChart } from "./components/revenue-chart.js"  // ← .tsx ではなく .js
+```
+
+`@squadbase/vantage` のサブパス import はこの限りではない(`@squadbase/vantage/ui` 等)。
+
+## ルーティング:動的パラメータは「3つの綴り」を同期させる
+
+ズレると静かにマッチしなくなる:
+
+- ファイル `sales/[customerId].tsx`
+- 表示ルート `/sales/:customerId`
+- リンク `to="/sales/$customerId"` + `params={{ customerId }}` / 取り出し `useParams().customerId`
+
+## ページ:`definePage` の値はリテラルで書く
+
+title/description/navLabel は**ビルド時に静的抽出**される。変数・関数呼び出し・テンプレート補間を
+使うと抽出できない。`export const page = definePage({ title: "…" })` の右辺はリテラルにする。
+なお `page` エクスポートはランタイムでは読まれない(抽出専用)。
+
+## ナビ:`useRoutes()` は動的ルートも返す
+
+`/sales/:customerId` のような動的ルートは URL が 1 つに定まらない。ナビに出すなら
+`useRoutes().filter((r) => !r.dynamic)` で外す。リンク先は `r.path`(`:id` 形式)ではなく
+**`r.to`**(`$id` 形式)を `Link` に渡す。表示名は `r.label`(`navLabel` → `title` → `path` の順)。
+
+`useCurrentRoute()` は 404 のとき `undefined` を返す。動的ルートを開いているときに親を
+アクティブにしたいなら `current?.path.startsWith("/sales")` のように前方一致で判定する。
+
+## URL 状態:`useSearchParam` の値は常に string、既定値はURLから消える
+
+- TanStack は `?year=2024` を数値としてパースするが、`useSearchParam` は必ず `string` に戻す
+  (数値が欲しければ自分で `Number(...)`)。配列やオブジェクトは `useSearchState` を使う。
+- **デフォルト値または `null` を書き込むとキーが URL から消える**。「明示的に既定値を選んだ」
+  状態を URL に残すことはできない。
+- 履歴は既定で `replace`。戻るボタンで1手ずつ戻したいときだけ `{ replace: false }`。
+
+## API 呼び出し:`useApiQuery` のエラーは `ApiError`
+
+`(q.error as Error)` のキャストは要らない。`q.error` は `ApiError | null` で、`message` には
+サーバーが `HttpError` で明示したメッセージが入る(それ以外は汎用のステータス文言)。
+`status`・`body`・`requestId` も持つ。クエリキーは `["api", url]` なので、
+`invalidateQueries({ queryKey: ["api"] })` で API 由来のキャッシュを一括で捨てられる。
+
+## API:見せたいエラーは `HttpError` を throw する
+
+```ts
+import { HttpError } from "@squadbase/vantage/server"
+throw new HttpError(404, "Not found")   // → クライアントに 404 + message
+throw new Error("boom")                 // → ログに出て汎用 500 に丸められる
+```
+
+`instanceof HttpError` は dev の module realm 跨ぎで壊れることがある。ライブラリ側の判定は
+`isHttpError` を使う設計。アプリ側は素直に `throw new HttpError(...)` すればよい。
+
+## 設定ファイル:作った時点で `vantage check` がエラーにする
+
+以下はすべて禁止(`FORBIDDEN_FILE`)。Vantage が所有しているので置かない:
+
+- `vite.config.*` — Vite 設定は Vantage が所有
+- `tailwind.config.*` — テーマは `styles.css` のトークンで調整
+- `postcss.config.*` — Vantage が管理
+- `components.json` — UI は `vantage add ui <name>` でコピー
+- `vantage.config.*` — v1 に設定ファイルは無い(規約で表現)
+
+## Markdown:`MarkdownRenderer` は `@squadbase/vantage/markdown` から
+
+Markdown 描画は専用サブパスに隔離されている(Shiki の全言語文法を引き込むため)。
+`components/` から import しない。使うアプリだけが `@squadbase/vantage/markdown` から取り込む。
+
+## テーブル:`ColumnDef<Row>[]` を明示的に注釈する
+
+```tsx
+import { type ColumnDef } from "@squadbase/vantage/components"
+const columns: ColumnDef<Row>[] = [ … ]   // 注釈しないと accessorKey が string に広がり弾かれる
+```
+
+## 生成物:`.vantage/` と `dist/` は触らない
+
+どちらも gitignore 済みの生成物。編集しても次のコマンドで上書きされる。`.vantage/` は任意の CLI
+コマンド、または `vantage upgrade` で再生成される。