@squadbase/vantage-template 0.0.1

package/README.md

@@ -0,0 +1,112 @@
+# @squadbase/vantage-template
+
+CLI tool for initializing and customizing Squadbase Vantage projects.
+
+It scaffolds a dashboard app built on [`@squadbase/vantage`](https://vantage-framework-vantage.vercel.app/) — a config-free React framework with file-based routing — and applies ready-made UI-pattern templates on top of it.
+
+## Usage
+
+```bash
+npx @squadbase/vantage-template <command> [options]
+```
+
+### Commands
+
+#### `init`
+
+Initialize a new Vantage project in the current directory. Copies the base template — `index.tsx`, `_layout.tsx`, `_404.tsx`, `_error.tsx`, `server/api/`, `styles.css`, `tsconfig.json`, `squadbase.yml`, plus the agent guidance in `AGENTS.md` 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 --chart sunset           # Apply a chart preset during init
+```
+
+After initialization:
+
+```bash
+npm run dev      # vantage dev — 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
+```
+
+There is no `vite.config.ts`, no `main.tsx`, and no route table: adding a file adds a route (`index.tsx` → `/`, `sales/[id].tsx` → `/sales/:id`), and `_layout.tsx` builds the nav from `useRoutes()`.
+
+#### `add <template-name>`
+
+Apply a UI-pattern template to an existing Vantage project. The entry page lands on `index.tsx`, and template-owned files go under `components/<slug>/` (plus `server/api/` for API-backed templates).
+
+```bash
+npx @squadbase/vantage-template add kpi-chart-simple
+npx @squadbase/vantage-template add funnel --dry-run    # Preview without writing
+npx @squadbase/vantage-template add funnel --force      # Overwrite existing files
+```
+
+`add` replaces `index.tsx`, so it warns before overwriting it, and it lists leftover files from a previously applied template (it never deletes them — you may have edited them).
+
+#### `chart <preset-name>`
+
+Switch the chart color preset. Rewrites a marked block of `--chart-1`–`--chart-5` inside the project's `styles.css`, leaving any other overrides in that file intact. Re-running replaces the block rather than stacking.
+
+```bash
+npx @squadbase/vantage-template chart ocean
+npx @squadbase/vantage-template chart forest --dry-run
+```
+
+Requires `@squadbase/vantage` v0.2.1+ (v0.2.2+ recommended), where `EChart` resolves its colors from the theme tokens and follows stylesheet changes.
+
+#### `list`
+
+List available UI templates and chart presets.
+
+```bash
+npx @squadbase/vantage-template list
+npx @squadbase/vantage-template list --lang ja     # Japanese variants (names ending in -ja)
+npx @squadbase/vantage-template list --json        # Machine-readable, includes preview image URLs
+```
+
+## UI templates
+
+| Template | Description |
+|---|---|
+| `blank` | Empty `PageShell` with a title and description — the minimal scaffold |
+| `kpi-chart-simple` | 4 KPI cards, one trend line, and a ranked-items table — served by `server/api` and filtered through the URL |
+| `kpi-chart-advanced` | Hero KPI (1 large + 4 small), bar+line comparison, donut breakdown, daily trend, detail table |
+| `chart-grid` | Six-chart grid — area, line, bar, scatter, radar, heatmap — with category filter chips |
+| `funnel` | Funnel chart with per-stage drop-off sidebar, pipeline KPIs, and a stage-performance ranking |
+| `table-focus` | Workbench layout — search, status chips, sortable detail table, trend + segment sidebar |
+
+Every template has a Japanese variant under `<name>-ja`. The EN and JA variants write to the same destinations, so apply only one of the pair.
+
+## AI customization (`add --prompt`)
+
+Passing `--prompt` relabels the applied template's display copy toward your domain, right after the files are copied. Structure, data, and logic are left alone — only string literals in pages and components are rewritten, and the data layer (mock data, types, API handlers) is excluded from the pass by the manifest.
+
+```bash
+npx @squadbase/vantage-template add kpi-chart-simple \
+  --prompt "SaaS MRR / ARR / churn dashboard" \
+  --provider openai --apiKey $OPENAI_API_KEY
+```
+
+| Flag | Description |
+|---|---|
+| `--prompt <text>` | Customization intent. Without it, no AI call is made. |
+| `--provider <name>` | `openai`, `anthropic`, `google`, `mistral`, `xai`, `groq`, … |
+| `--model <id>` | Model id. Each provider has a default. |
+| `--apiKey <key>` | Falls back to the provider's env var (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, …). |
+| `--env-file <path>` | Load a `.env` before the call; existing `process.env` wins. Needs Node.js 20.12+. |
+| `--base-url <url>` | OpenAI-compatible endpoint. |
+| `--dry-run` | Print the edits as a unified diff without writing. |
+| `--json` | Emit the result (`edits`, `unchanged`, `skipped`, `failedVerification`, `aiError`, `notes`) as JSON. |
+
+Each edit is verified against the current file content before it is applied; a file whose edits don't match cleanly is left untouched and reported. `ai` and `@ai-sdk/*` are optional dependencies, imported only when `--prompt` is used — if they are missing, the CLI tells you what to install and exits.
+
+## Requirements
+
+Node.js 18 or later. `--env-file` additionally requires 20.12+.
+
+## License
+
+See the [squadbase-templates](https://github.com/squadbase/squadbase-templates) repository.

package/base-template/.squadbase/skills/vantage-add-feature/SKILL.md

@@ -0,0 +1,162 @@
+---
+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"
+  ```
+- **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:…] で転送)
+```
+
+`vantage routes` は `--pages` / `--apis` で片側だけに絞れる。`--detail` を足すと各ルートの静的な
+仕様(ページ: パスパラメータ + `definePage` のメタ / API: メソッド・`searchParams` のキー・
+リクエストボディ・レスポンスの status と形・`HttpError`)まで出るので、**既存 API の呼び方を
+確かめる**ときはこれが速い(ソースを読むだけの推定で、実行はしない)。
+
+```bash
+vantage routes --apis --detail   # 既存 API のメソッド/入出力を確認
+```
+
+エージェントで自動処理するなら機械可読出力を使う:
+
+```bash
+vantage routes --json            # { pages, layouts, notFound, error, apis, hasServer }
+vantage routes --apis --detail --json  # { apis: [{ route, file, params, spec }], 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/base-template/.squadbase/skills/vantage-app/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: vantage-app
+description: Vantage(@squadbase/vantage)ダッシュボードアプリを一から作る / 既存アプリの構成を広げるときの進め方。骨組みの用意、ルートの決め方、データ取得の選択(外部 API か自前の server/api か)、どこで手を止めて検証するかの順序を扱う。規約そのものはアプリルートの AGENTS.md が正本。
+---
+
+# Vantage アプリの作り方 — 進め方と検証の順序
+
+規約・不変条件・import サブパスの一覧・各 API の書式は、アプリルートの **`AGENTS.md`** が正本。
+**先にそれを読む**(無ければ `vantage add agents` で置ける)。このスキルは「どの順で作り、どこで
+手を止めて検証するか」だけを扱い、AGENTS.md の内容は繰り返さない。
+
+- ページ / API / UI を 1 つ足すだけなら → `vantage-add-feature`
+- 実装したのに静かに壊れたら → `vantage-pitfalls`
+
+## 全体の流れ
+
+1. **骨組み** — `pnpm dev` が上がるところまで
+2. **ルートを決める** — ページファイルを置き、`vantage routes` で URL を確認
+3. **データを繋ぐ** — 外部 API か、自前の `server/api` か
+4. **仕上げ** — `check` → `build` → `preview`
+
+**各段階の終わりに `vantage check` を通す。** 静的診断(禁止ファイル・ルート衝突・境界違反・
+API export・env 誤用)はユーザーコードを実行しないので速く、エラーがあれば exit 1 になる。
+まとめて最後に回すと、原因の切り分けが難しくなる。
+
+## Step 1 — 骨組み
+
+新規なら `package.json` と `index.tsx` の 2 ファイルだけ。設定ファイルは**作らない**
+(`vite.config.*` 等は `vantage check` がエラーにする)。
+
+```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.2.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  }
+}
+```
+
+`index.tsx` はデフォルトエクスポートの React コンポーネント 1 つ(これが `/` になる)。あとは
+`pnpm install && pnpm dev` で http://localhost:5173 が上がる。
+
+**既存アプリに合流したときは、作る前に現状を読む:**
+
+```bash
+vantage routes     # 既にあるページと API の URL マップ
+vantage check      # いま壊れていないか(これから出すエラーと切り分ける)
+ls server/         # あれば fullstack モード。無ければ SPA
+vantage add skill  # 配置済みの skill(このファイルの仲間)と、その場所
+```
+
+## Step 2 — ルートを決める
+
+ファイル名がそのままルートになる(対応表は AGENTS.md「ルーティング規約」)。**ルーターを設定
+する場所は無い**ので、決めるのは「どんなファイル名で置くか」だけ。
+
+- ページを置いたら `vantage routes` で URL を確かめる。意図と違うなら**ファイル名が違う**。
+- ナビゲーションはリンク配列を手で持たず、`useRoutes()` から組む。この形にしておくと以後は
+  ページファイルを足すだけでナビが増える(AGENTS.md「ナビはルート一覧から組む」)。
+- 共通の枠(ヘッダ・サイドバー)は `_layout.tsx`、Not Found と例外は `_404.tsx` / `_error.tsx`。
+- 一覧 → 詳細を作るなら、**動的パラメータの「3 つの綴り」を先に決めてから**両方のファイルを
+  書く。後から変えると静かにマッチしなくなる。
+
+## Step 3 — データを繋ぐ
+
+**どちらの経路かを先に決める。** ここを間違えると後で全部書き直しになる:
+
+| データ元 | 使うもの | `server/` |
+| --- | --- | --- |
+| ブラウザから直接叩ける公開 API | `useQuery` + `fetch` | 不要 |
+| DB / シークレットが要る / CORS で叩けない | `server/api/*.ts` + `useApiQuery` | 必要 |
+
+**API キーが要る時点で後者しかない** — クライアントに届く env は `PUBLIC_*` だけで、
+シークレットは `ApiContext.env`(= `server/` の中)にしか届かない。
+
+後者の手順:
+
+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/` にある)。
+
+ダッシュボードの**絞り込みは `useState` ではなく `useSearchParam` / `useSearchState`** に置く。
+リロードで消えず、URL をそのまま共有できる。これも後から差し替えると全ページに波及するので、
+最初のフィルタを作る時点で決める。
+
+## Step 4 — 仕上げ
+
+```bash
+pnpm check     # エラーが残っていないか(exit 1 なら残っている)
+pnpm routes    # 公開される URL の最終確認
+pnpm build     # dist/ に client(+ server)+ vantage-manifest.json
+pnpm preview   # 本番ビルドをローカルで動かす
+```
+
+`vantage-manifest.json` の `mode` は `server/` の有無から自動で決まる(手で書かない)。
+`preview` まで通れば、そのまま同じ成果物がデプロイされる。
+
+## 詰まったら
+
+- ブラウザの `console.*` とランタイムエラーは、**開発ターミナルに `[browser:…]` として転送
+  される**。ブラウザの devtools を開かなくても読める。
+- `vantage check --json` / `vantage routes --json` は機械可読出力。
+- props や規約を確かめたいときは `vantage docs <name>`、名前が思い出せないときは
+  `vantage search <やりたいこと>`。**推測で props を書かない。**
+- Base UI(≠ Radix)の癖など、静かに壊れる系は `vantage-pitfalls` にまとまっている。

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

@@ -0,0 +1,137 @@
+---
+name: vantage-pitfalls
+description: Vantage(@squadbase/vantage)アプリを書くときに静かに壊れる落とし穴のリファレンス。Base UI は Radix ではない(asChild 無し・render プロップ)、Select の value/label、クライアントから server/ を import しない、EChart の配色と高さ、動的パラメータの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/label は Vantage 側が吸収済み(残る 1 ケースだけ注意)
+
+Base UI の `SelectValue` は選択中の **value をそのまま描き**、`SelectItem` の children を見ない
+部品。Vantage の `Select` は children から `value` → ラベルを集めて渡すので、普通に書けば
+トリガーに「関東」と出る。**手当てが要るのは 1 ケースだけ** — `SelectItem` を別のコンポーネント
+が返している場合は集められないので、`items` を明示する:
+
+```tsx
+// SelectItem がこの場に無い(<RegionItems /> の中で作られる)ときだけ必要
+<Select items={{ kanto: "関東", kansai: "関西" }} …>
+  <SelectContent><RegionItems /></SelectContent>
+</Select>
+```
+
+トリガーに `kanto` や `/sales` と生の値が出たら、まずこれを疑う。
+
+## チャート:`EChart` の配色はトークン追従。上書きは `option.color`
+
+系列色は `--chart-1..5`、軸・凡例・ツールチップは文字色/境界色のトークンから組まれる
+(init 時にトークンの実値を解決している)。ライト / ダークの切り替えにも、`styles.css` の
+書き換えやテーマプリセットの適用にも追従する。
+
+- **`theme` プロップを渡すと追従は完全に止まる。** 系列の色だけ変えたいなら `option.color` を
+  使う ― option はテーマより優先されるので、軸まわりの追従は残る。
+- キャンバス系なので、**コンテナに高さを与えないと何も見えない**(既定は `h-[400px]`。
+  `h-full` を使うなら親に確定した高さが要る)。
+- `option` は `EChartsOption` を annotate するか `satisfies` を付ける。付けないと
+  `type: "category"` が `string` に広がってビルドが落ちる。
+
+## 境界:クライアントから `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` で読む。
+
+## ルーティング:動的パラメータは「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` — shadcn CLI は使わない。UI は `@squadbase/vantage/ui` から import する
+- `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` で再生成される。