@squadbase/vantage 0.0.1 → 0.1.0

package/docs/ja/cli-reference.md

@@ -0,0 +1,305 @@
+# CLI リファレンス
+
+> vantage の全コマンド。dev・build・preview・check・routes・add・docs・search・doctor・upgrade。
+
+`vantage` はアプリ作者が使う唯一の CLI です。特記がなければプロジェクトルートで実行します。
+
+## コマンド一覧
+
+| コマンド | 役割 |
+|---|---|
+| `vantage dev` | 開発サーバー（HMR + オプションの API）。既定 `:5173` |
+| `vantage build` | クライアント + オプションのサーバーをビルド → `dist/` |
+| `vantage preview` | 本番ビルドをローカルで起動（fullstack は既定 `:4173`、spa は Vite プレビュー） |
+| `vantage check` | 静的検査（ルート・境界・禁止ファイル）。エラーがあれば exit 1 |
+| `vantage routes` | ページ + API の URL マップを表示 |
+| `vantage add <kind> <name>` | `page` / `api` / `ui` / `block` / `skill` / `agents` を雛形生成・配置（`--force` で上書き） |
+| `vantage docs [name]` | 同梱のガイド + コンポーネントリファレンスを表示 |
+| `vantage search <query>` | 同じリファレンスを全文検索（自然言語 or `--regex`） |
+| `vantage doctor` | 環境・インストールの健全性を診断 |
+| `vantage upgrade` | 生成成果物を再生成し、配置済みの `AGENTS.md` を正本から同期 |
+
+## クイックモード（パスを直接渡す）
+
+`cd` してからコマンドを打つ代わりに、**プロジェクトのパスを直接**渡して起動できます。第 1 引数が
+既知コマンドではなくファイルシステム上のパスを指す場合、そのパスを root として `dev` を起動します
+（ターミナルに `quick dev → <path>` と表示されます）。
+
+```bash
+vantage ./demo             # ディレクトリ → その中で dev を起動
+vantage ./demo/index.tsx   # ページファイル → 親ディレクトリを root にして dev
+```
+
+パスの解決ルール:
+
+| 渡したパス | root になるもの |
+|---|---|
+| ディレクトリ | そのディレクトリ自身 |
+| `.tsx` / `.jsx` のページファイル | その親ディレクトリ |
+| 存在しないパス・その他 | 該当なし（`Unknown command` エラー） |
+
+`add`・`docs`・`search` を除く root スコープの各コマンドも、末尾に path positional を取れます。`dev` を明示しても
+よいですし、`build` / `check` / `routes` などにも同じパスを渡せます。
+
+```bash
+vantage dev ./demo             # 明示的なクイック dev
+vantage build ./demo           # ./demo をビルド
+vantage check ./demo/index.tsx # ファイル指定でも親ディレクトリを検査
+```
+
+> [!NOTE]
+> `add`・`docs`・`search` はパス引数ではなく positional を自分の引数（`add page dashboard`・
+> `docs button`・`search 日付の選択`）に使うため、この短縮形の対象外です。
+
+## `vantage docs` — ドキュメントを CLI で読む
+
+このサイトの内容は**パッケージに同梱**されていて、`vantage docs` でそのまま読めます。ネット接続も
+ブラウザも不要なので、コーディングエージェントが props を確かめるのに向いています。
+
+```bash
+vantage docs                    # 全ページの一覧（ガイド + コンポーネント）
+vantage docs button             # 1 ページ表示（短縮名 → ui/button に解決）
+vantage docs parts/data-table   # 完全な slug でも引ける
+vantage docs --all              # 全ページを連結して出力
+```
+
+| フラグ | 意味 |
+|---|---|
+| `--list` | ページ名を表示するだけ（本文を出さない） |
+| `--all` | 全ページを連結して出力 |
+| `--json` | 機械可読出力（`{ slug, title, description, section, content }`） |
+| `--lang <ja\|en>` | 言語（既定 `ja`） |
+
+引数なしの `vantage docs` は、セクションごとに **slug と説明**を並べます（左の列がそのまま引数になります）。
+
+```text
+$ vantage docs
+
+ガイド
+  index                       設定ファイル不要（config-free）な React ダッシュボードフレームワーク。書くのは index.tsx だけ。
+  getting-started             インストールから最初の Vantage アプリを起動するまで。
+  routing                     ファイルを置くだけでルートが生まれる。ページ・レイアウト・動的パラメータ・404/error の規約。
+  …
+
+@squadbase/vantage/ui
+  ui/accordion                開閉する見出しの縦積み。既定では 1 つだけ開く。
+  ui/alert                    ページ内に置く通知。中身は表示したまま注意を促す。
+  ui/badge                    小さなラベル。件数・状態・タグに。
+  …
+
+vantage docs <name>   show one page      --json   machine-readable
+vantage docs --all    show every page    --lang   ja | en
+```
+
+名前を渡すと、そのページを **Markdown のまま**出力します（TTY では見出しと引用が色付けされ、パイプ
+すると素の Markdown になります）。props の表は Markdown の表として読めます。
+
+````text
+$ vantage docs button
+
+# Button
+
+> 6 つの variant と 8 つの size を持つボタン。
+
+いちばんよく使うコンポーネントです。`variant` で意味づけを、`size` で大きさを決めます。
+
+```tsx
+import { Button, buttonVariants } from "@squadbase/vantage/ui";
+```
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `variant` | `"default" \| "secondary" \| …` | `"default"` | 見た目と意味づけ。 |
+| `size` | `"default" \| "xs" \| "sm" \| …` | `"default"` | 高さと余白。`icon` 系は正方形になる。 |
+| `render` | `ReactElement` |  | 別の要素として描画する（Radix の `asChild` に相当）。 |
+…
+````
+
+名前は**短縮形で引けます**。`vantage docs button` は `ui/button` に、`vantage docs data-table` は
+`parts/data-table` に解決されます。曖昧なとき・見つからないときは候補が出て、終了コードは 1 になります。
+
+```text
+$ vantage docs sele
+✗ No page named "sele". Did you mean: ui/select, parts/multi-select, parts/searchable-select?
+```
+
+`--json` は 1 ページを機械可読にしたものです。`content` にページ全体の Markdown が入ります。
+
+```json
+{
+  "slug": "ui/badge",
+  "lang": "ja",
+  "title": "Badge",
+  "description": "小さなラベル。件数・状態・タグに。",
+  "section": "components/ui",
+  "sectionTitle": "@squadbase/vantage/ui",
+  "content": "# Badge\n\n> 小さなラベル。件数・状態・タグに。\n\nテキストの横に添える…"
+}
+```
+
+本文中のリンクは slug なので、`[DataTable](parts/data-table)` は `vantage docs parts/data-table`
+で開けます。
+
+> [!NOTE]
+> 同梱されるのは MDX をプレーンな Markdown に変換したものです。ライブプレビューはこのサイトだけの
+> 機能で、CLI では props の表・コード例・注意書きが読めます。
+
+## `vantage search` — 名前を知らなくても辿り着く
+
+`vantage docs <name>` は**名前を知っている**前提の参照です。「日付範囲を選ぶ UI が欲しい」のように
+**やりたいこと**から辿るときは `vantage search` を使います。対象は `vantage docs` と同じ同梱ドキュメント
+（ガイド + `ui` / `parts` / `markdown` のコンポーネント）で、結果はそのまま `vantage docs <name>` に渡せます。
+
+```bash
+vantage search 期間を選ぶ UI が欲しい   # 自然言語（クエリは引用符なしでもよい）
+vantage search "pagination"            # 英語のドキュメントを引くなら --lang en
+vantage search "enable[A-Z]\w+" --regex  # 正規表現で props を横断検索
+vantage search チャート --limit 3 --json # 機械可読
+```
+
+| フラグ | 意味 |
+|---|---|
+| `--regex` | クエリを正規表現として扱う（大文字小文字は区別しない） |
+| `--limit <n>` | 表示件数（既定 `10`） |
+| `--json` | 機械可読出力 |
+| `--lang <ja\|en>` | 言語（既定 `ja`） |
+
+既定は **BM25 による全文検索**です。ページ名・タイトル・説明文を本文より重く見て並べ、ヒットした
+ページごとに**一致した箇所のスニペット**を表示します。日本語は字種の切れ目（漢字・カタカナ・ひらがな）
+で区切って索引を作るので、「テーブルにページングを付けたい」のような文のままのクエリでも引けます。
+
+```text
+$ vantage search 期間を選ぶ UI が欲しい --limit 3
+
+  parts/date-range-picker  DateRangePicker · @squadbase/vantage/components
+                           > プリセット付きの期間選択。
+  ui/calendar              Calendar · @squadbase/vantage/ui
+                           単日・複数日・期間を選べるカレンダーです。ダッシュボードで期間を選ばせたい場合は、これを直接
+  ui/accordion             Accordion · @squadbase/vantage/ui
+                           常に開いている単独の折りたたみが欲しいだけなら
+```
+
+左の列がそのまま `vantage docs <name>` に渡せる slug、右がタイトルと import 元、その下が一致箇所の
+スニペットです。実際にはこの前後に `55 results for "…"  ja · bm25` の見出しと、`--limit` で隠れた
+件数・フラグのヒントが付きます（上の例では省略）。**件数は索引に 1 語でも一致したページの数**なので、
+下位はほとんど関係ありません。上から数件だけを見て、足りなければ `--limit` を上げてください。
+
+`--json` は同じ結果を機械可読にしたものです。`score` は BM25 のスコア、`command` はそのまま実行できる
+形です（以下は `vantage search 期間選択 --limit 1 --json` の出力）。
+
+```json
+{
+  "query": "期間選択",
+  "mode": "bm25",
+  "lang": "ja",
+  "count": 14,
+  "results": [
+    {
+      "slug": "parts/date-range-picker",
+      "title": "DateRangePicker",
+      "description": "プリセット付きの期間選択。",
+      "section": "components/parts",
+      "sectionTitle": "@squadbase/vantage/components",
+      "command": "vantage docs parts/date-range-picker",
+      "score": 18.033,
+      "snippet": "> プリセット付きの期間選択。"
+    }
+  ]
+}
+```
+
+`--regex` は名前・タイトル・説明・本文を正規表現で走査し、**行番号付き**で一致行を出します。props の
+綴りを横断で確かめたいときに向いています。
+
+```text
+$ vantage search "enable(Sorting|Filtering)" --regex
+
+  parts/data-table  DataTable  4 matches
+      30  | `enableSorting` | `boolean` | ヘッダークリックで並べ替える。 |
+      31  | `enableFiltering` | `boolean` | ツールバーに検索欄を出す。 |
+      49  <DataTable columns={columns} data={data} enableSorting enableFiltering>
+```
+
+1 ページにつき最初の 3 行までを表示しますが、`4 matches` の件数は正確です。名前・タイトル・説明だけが
+一致したページは `name match` と表示され、本文の行は出ません。ヒットが 0 件でもエラーにはならず
+（終了コード 0、`--json` なら `"count": 0`）、不正な正規表現のときだけ終了コード 1 になります。
+
+> [!NOTE]
+> 索引は実行時に組み立てられます（同梱ドキュメントの読み込み込みで数十ミリ秒）。事前生成された索引を
+> 同梱しないので、ドキュメントと検索結果がずれることはありません。
+>
+> **このページ自身も検索対象です。** 上の例のクエリをそのまま実行すると、例文を含むこの「CLI リファレンス」
+> もヒットに混ざります（上の出力例では省いています）。
+
+## `--json`
+
+`check` / `routes` / `doctor` / `build` / `upgrade` / `docs` / `search` は `--json` を受け付けます。CI や
+エージェントの自動処理に使えます。
+
+```bash
+vantage check --json
+```
+
+```json
+{
+  "code": "ROUTE_CONFLICT",
+  "severity": "error",
+  "message": "2 files resolve to /sales",
+  "files": ["sales.tsx", "sales/index.tsx"],
+  "fix": "Rename or remove one route file so each route is unique."
+}
+```
+
+> [!NOTE]
+> `build --json` は**コンパクトな 1 行**で出力されます。他のコマンドの `--json` は 2 スペース
+> インデントで整形されます。
+
+## `build --api-base-url`
+
+`vantage build` は、クライアントが `/api` を呼ぶベースURLを指定する `--api-base-url` を受け付けます。
+フロントとサーバーを別オリジンにデプロイするときに使います。
+
+```bash
+vantage build --api-base-url https://api.example.com
+```
+
+このフラグは `.env` の `PUBLIC_API_BASE_URL` より優先されます。未指定なら空(同一オリジンの
+相対パス)。詳細は[ビルドとデプロイ](build-and-deploy)を参照してください。
+
+## 静的診断（`check`）
+
+`vantage check` が検出する診断は次の 6 種類です（エラー 5・警告 1）。
+
+| コード | 深刻度 | 意味 |
+|---|---|---|
+| `FORBIDDEN_FILE` | エラー | 禁止された設定ファイルがルートに存在する |
+| `ROUTE_CONFLICT` | エラー | 2 つのファイルが同じルートに解決される |
+| `MISSING_DEFAULT_EXPORT` | エラー | ページに default export がない |
+| `INVALID_API_EXPORT` | エラー | API が有効な HTTP メソッドをエクスポートしていない |
+| `CLIENT_IMPORTS_SERVER` | エラー | クライアントが `server/` から import している |
+| `PUBLIC_ENV_MISUSE` | 警告 | クライアントが `PUBLIC_` 以外の env を読んでいる |
+
+いずれもユーザーコードを import・実行しません（純粋に静的な検査です）。
+
+## 生成物と成果物
+
+`dist/` の中身:
+
+```text
+dist/
+├── client/                クライアント（index.html + ハッシュ付きアセット）
+├── server/index.mjs       server/ がある場合のみ
+└── vantage-manifest.json  デプロイ契約（mode: "spa" | "fullstack"）
+```
+
+`vantage preview` はこの `vantage-manifest.json` の `mode` を読んで、Node サーバーを起動するか
+静的プレビューにするかを決めます。デプロイ手順は[ビルドとデプロイ](build-and-deploy)で詳しく
+解説します。
+
+## 完了
+
+以上でアプリ作者向けガイドは終わりです。最小の `index.tsx` から始めて、必要に応じて
+ページ・API・UI を足していってください。
+
+AI エージェントに手順ごと渡したいときは、同梱の [エージェントと Skills](agent-skills) を
+`vantage add skill` で、アプリの地図となる `AGENTS.md` を `vantage add agents` で配置してください。

package/docs/ja/components.md

@@ -0,0 +1,229 @@
+# コンポーネント
+
+> Vantage に同梱される shadcn/ui (Base UI) キットと、ダッシュボード用の複合コンポーネントのリファレンス。
+
+Vantage は **shadcn/ui** をそのまま同梱しています。インストールもコピーも不要で、import するだけで
+使えます。公開されている入り口は 3 つで、**サイドバーもこの 3 つで区切ってあります**。
+
+| サブパス | 中身 | 件数 |
+| --- | --- | --- |
+| [`@squadbase/vantage/ui`](ui/button) | shadcn/ui のプリミティブ（Base UI 版）と、`cn()` などのユーティリティ | 37 |
+| [`@squadbase/vantage/components`](parts/page-shell) | それらを組み上げたダッシュボード部品 | 15 |
+| [`@squadbase/vantage/markdown`](markdown/markdown-renderer) | Markdown の描画だけ（重いので分離） | 1 |
+
+```tsx
+import { Button, Card, Badge } from "@squadbase/vantage/ui";
+import { PageShell, DashboardCardPreset, EChart } from "@squadbase/vantage/components";
+import { MarkdownRenderer } from "@squadbase/vantage/markdown";
+```
+
+> [!NOTE]
+> UI キットは**パッケージから import して使う**のが基本です（コピーしません）。中身を書き換えたい
+> ときだけ [`vantage add`](cli-reference) で編集可能なソースを取り出します。
+
+## Base UI ベースであること
+
+同梱しているのは shadcn/ui の **Base UI 版**です。2026 年 7 月に shadcn/ui は既定のプリミティブを
+Radix UI から [Base UI](https://base-ui.com) へ切り替えており、Vantage はその新しい方を採用して
+います。Radix 版から来た場合、主な違いは次の 4 点です。
+
+- **`asChild` はありません。** 代わりに `render` プロップに要素を渡します。
+
+  ```tsx
+  // Radix 版
+  <PopoverTrigger asChild><Button>開く</Button></PopoverTrigger>
+
+  // Base UI 版（Vantage）
+  <PopoverTrigger render={<Button />}>開く</PopoverTrigger>
+  ```
+
+- **[`Checkbox`](ui/checkbox) の `checked` は `boolean` のみ。** 中間状態は
+  `indeterminate` プロップで表します。
+- **[`ToggleGroup`](ui/toggle-group) の `value` は配列。** 単一選択にしたいときは
+  [`SegmentedControl`](parts/segmented-control) を使ってください。
+- **[`Select`](ui/select) の `onValueChange` は `string | null`。** `null` のガードが
+  要ります。また `SelectValue` は既定で選択中の値をそのまま表示するので、ラベルを出すには
+  `items` に対応表を渡します。
+
+状態は `data-state="open"` ではなく `data-open` / `data-checked` のような属性で表現されます。
+Vantage の `theme.css` は両方の綴りを受ける custom variant を定義しているので、
+`data-open:animate-in` のようなクラスはどちらの流儀でも書けます。
+
+## `@squadbase/vantage/ui`
+
+shadcn/ui のプリミティブです。名前も props も shadcn/ui のものと同じなので、
+[shadcn/ui のドキュメント](https://ui.shadcn.com/docs/components) もそのまま参考になります。
+サイドバーはアルファベット順ですが、ここでは用途で並べています。
+
+### フォームと入力
+
+[`Button`](ui/button) ·
+[`Input`](ui/input) ·
+[`InputGroup`](ui/input-group) ·
+[`Textarea`](ui/textarea) ·
+[`Label`](ui/label) ·
+[`Select`](ui/select) ·
+[`Checkbox`](ui/checkbox) ·
+[`Switch`](ui/switch) ·
+[`Slider`](ui/slider) ·
+[`Toggle`](ui/toggle) ·
+[`ToggleGroup`](ui/toggle-group) ·
+[`Calendar`](ui/calendar) ·
+[`Command`](ui/command)
+
+### レイアウトとナビゲーション
+
+[`Card`](ui/card) ·
+[`Tabs`](ui/tabs) ·
+[`Separator`](ui/separator) ·
+[`ScrollArea`](ui/scroll-area) ·
+[`Sidebar`](ui/sidebar) ·
+[`Breadcrumb`](ui/breadcrumb) ·
+[`Accordion`](ui/accordion) ·
+[`Collapsible`](ui/collapsible)
+
+### データ表示
+
+[`Table`](ui/table) ·
+[`Badge`](ui/badge) ·
+[`Progress`](ui/progress)
+
+### オーバーレイ
+
+[`Dialog`](ui/dialog) ·
+[`Sheet`](ui/sheet) ·
+[`Popover`](ui/popover) ·
+[`Tooltip`](ui/tooltip) ·
+[`DropdownMenu`](ui/dropdown-menu)
+
+### 状態表示
+
+[`Alert`](ui/alert) ·
+[`Skeleton`](ui/skeleton) ·
+[`Spinner`](ui/spinner) ·
+[`Loading`](ui/loading) ·
+[`Empty`](ui/empty) ·
+[`ErrorState`](ui/error-state)
+
+`Loading` / `Empty` / `ErrorState` の 3 つだけは shadcn/ui にはなく、Vantage が足したものです。
+
+### ユーティリティ
+
+[`cn()`](ui/cn) · [`useIsMobile()`](ui/use-is-mobile)
+
+## `@squadbase/vantage/components`
+
+`ui/` を組み上げた、ダッシュボード向けの複合部品です。
+
+| コンポーネント | 概要 |
+| --- | --- |
+| [`PageShell`](parts/page-shell) | ヘッダー帯・サマリー・本文からなるページ枠 |
+| [`AppShell`](parts/app-shell) | ナビゲーション定義を渡すだけのアプリ枠 |
+| [`SectionHeader`](parts/section-header) | セクション見出しとアクション |
+| [`DashboardCard`](parts/dashboard-card) | ダッシュボードのタイル（プリセットとスケルトン付き） |
+| [`DataTable`](parts/data-table) | 並べ替え・検索・ページング・選択を備えた表 |
+| [`EChart`](parts/echart) | Apache ECharts のラッパー |
+| [`FunnelSteps`](parts/funnel-steps) | ファネルの棒表示 |
+| [`FilterBar`](parts/filter-bar) | フィルタ一式を 1 つの値で扱う行 |
+| [`DateRangePicker`](parts/date-range-picker) | プリセット付きの期間選択 |
+| [`SegmentedControl`](parts/segmented-control) | 単一選択のセグメント |
+| [`SearchableSelect`](parts/searchable-select) | 検索できる単一選択 |
+| [`MultiSelect`](parts/multi-select) | 検索できる複数選択 |
+| [`MetricValue`](parts/metric-value) | KPI の数値と単位 |
+| [`TrendIndicator`](parts/trend-indicator) | 増減の矢印と変化率 |
+| [`StatusBadge`](parts/status-badge) | ドット付きステータスバッジ |
+
+## `@squadbase/vantage/markdown`
+
+[`MarkdownRenderer`](markdown/markdown-renderer) だけが置かれた独立のサブパスです。
+Markdown 描画は Shiki の全言語文法を抱えており、`components` のバレルに混ぜるとビルド出力が
+10 MB 以上増えるため、意図的に分けてあります。
+
+## 組み合わせる
+
+```tsx
+import { Button } from "@squadbase/vantage/ui";
+import {
+  PageShell,
+  PageShellHeader,
+  PageShellHeading,
+  PageShellTitle,
+  PageShellDescription,
+  PageShellHeaderEnd,
+  PageShellActions,
+  PageShellContent,
+  DashboardCardPreset,
+  MetricValue,
+  TrendIndicator,
+  EChart,
+  type EChartsOption,
+} from "@squadbase/vantage/components";
+
+const option: EChartsOption = {
+  xAxis: { type: "category", data: monthly.map((m) => m.month) },
+  yAxis: { type: "value" },
+  series: [{ type: "bar", data: monthly.map((m) => m.revenue) }],
+};
+
+export default function Overview() {
+  return (
+    <PageShell>
+      <PageShellHeader>
+        <PageShellHeading>
+          <PageShellTitle>売上ダッシュボード</PageShellTitle>
+          <PageShellDescription>直近 6 か月の推移</PageShellDescription>
+        </PageShellHeading>
+        <PageShellHeaderEnd>
+          <PageShellActions>
+            <Button variant="outline">エクスポート</Button>
+          </PageShellActions>
+        </PageShellHeaderEnd>
+      </PageShellHeader>
+
+      <PageShellContent>
+        <div className="grid gap-4 md:grid-cols-3">
+          <DashboardCardPreset title="売上">
+            <MetricValue className="my-0">¥1,240,000</MetricValue>
+            <TrendIndicator value={12.4} direction="up" />
+          </DashboardCardPreset>
+          <DashboardCardPreset title="新規顧客">
+            <MetricValue className="my-0">128</MetricValue>
+            <TrendIndicator value={3.1} direction="down" />
+          </DashboardCardPreset>
+          <DashboardCardPreset title="解約率">
+            <MetricValue className="my-0">2.1%</MetricValue>
+          </DashboardCardPreset>
+        </div>
+
+        <DashboardCardPreset title="月次売上" className="mt-4">
+          <EChart option={option} height={320} />
+        </DashboardCardPreset>
+      </PageShellContent>
+    </PageShell>
+  );
+}
+```
+
+## テーマ
+
+見た目は CSS 変数（デザイントークン）で決まります。色や角丸を変えたいときは、プロジェクトルートの
+`styles.css` で変数だけを上書きします — 詳しくは [UI とテーマ](ui-and-theming) を参照してください。
+
+## ソースを編集したいとき
+
+コンポーネントの中身そのものを変えたい場合は、編集可能なコピーを取り出します。
+
+```bash
+vantage add ui data-table        # 編集可能な DataTable を components/ へ
+vantage add block sales-overview
+```
+
+> [!NOTE]
+> 現行プロトタイプで `vantage add` がコピーできるのは `data-table`（ui）と `sales-overview`（block）
+> のみです。その他のコンポーネントは import 専用です。
+
+## このページの読み方
+
+各コンポーネントのページには、**動くプレビュー**とその**ソース**がタブで並んでいます。
+プレビューのソース先頭にある `export const client = "only";` はドキュメントサイト側の指定で、
+アプリのコードには要りません。

package/docs/ja/data-fetching.md

@@ -0,0 +1,78 @@
+# データ取得
+
+> 管理された TanStack Query（useQuery）でサーバー状態を扱う。
+
+Vantage はサーバー状態のために **管理された TanStack Query** を同梱しています。`QueryClient` の
+セットアップは不要で、`@squadbase/vantage/query` から `useQuery` などを import するだけです。
+
+```tsx
+import { useQuery } from "@squadbase/vantage/query";
+
+export default function Customers() {
+  const { data, isLoading, error } = useQuery({
+    queryKey: ["customers"],
+    queryFn: async () => {
+      const res = await fetch("/api/customers");
+      if (!res.ok) throw new Error("failed to load");
+      return res.json();
+    },
+  });
+
+  if (isLoading) return <p>読み込み中…</p>;
+  if (error) return <p>エラーが発生しました</p>;
+  return (
+    <ul>
+      {data.map((c: { id: string; name: string }) => (
+        <li key={c.id}>{c.name}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## 単一の管理された QueryClient
+
+Vantage が用意する `QueryClient` は 1 つだけで、次のデフォルトを持ちます。
+
+| 設定 | 値 |
+|---|---|
+| `staleTime` | 30 秒 |
+| `retry` | 1 |
+| `refetchOnWindowFocus` | `false` |
+
+カスタマイズは**クエリごとのオプションで上書き**します。`QueryClient` 丸ごとの差し替えは、
+管理されたスタックを保つため意図的に公開していません。
+
+```tsx
+// このクエリだけ挙動を変える
+useQuery({
+  queryKey: ["metrics"],
+  queryFn: fetchMetrics,
+  staleTime: 5 * 60 * 1000, // 5 分
+  retry: 3,
+});
+```
+
+> [!NOTE]
+> `@tanstack/react-query` を直接 import しないでください。`@squadbase/vantage/query` の
+> キュレートされた再エクスポートを使うことで、Vantage が下層ライブラリを安全に進化させられます。
+
+## API との組み合わせ
+
+`queryFn` の中で `/api/*` を呼べば、[オプションのサーバー](api-and-server)と自然につながります。
+`server/` を持たないクライアントのみのアプリでも、外部 API を `fetch` して同じように扱えます。
+
+> [!TIP]
+> 組み込みの `/api` を呼ぶときは、`@squadbase/vantage/query` の `apiFetch` を使うと、ベースURLを
+> env で切り替えられます(フロントとサーバーを別オリジンにデプロイする場合)。詳しくは
+> [ビルドとデプロイ](build-and-deploy)を参照してください。
+>
+> ```tsx
+> import { apiFetch } from "@squadbase/vantage/query";
+>
+> queryFn: () => apiFetch("/api/customers").then((r) => r.json());
+> ```
+
+## 次に読む
+
+- [API とサーバー](api-and-server) — バックエンドを書く

package/docs/ja/environment-variables.md

@@ -0,0 +1,68 @@
+# 環境変数
+
+> PUBLIC_ 接頭辞の env だけがクライアントに届く。シークレットはサーバーの env から読む。
+
+Vantage は、環境変数を**クライアントに漏らさない**ことを既定にしています。境界は接頭辞で決まります。
+
+## クライアントに届くのは `PUBLIC_` だけ
+
+`PUBLIC_` で始まる変数だけがクライアントバンドルに入り、`import.meta.env` から読めます。
+
+```tsx
+// クライアントコード
+const analyticsId = import.meta.env.PUBLIC_ANALYTICS_ID;
+```
+
+クライアントで参照できるのは次だけです。
+
+- `PUBLIC_*`（あなたが定義した公開値）
+- `MODE` / `DEV` / `PROD` / `SSR` / `BASE_URL`（Vite の標準）
+
+> [!WARNING]
+> `PUBLIC_` 接頭辞の**付いていない** env をクライアントで読もうとすると、`vantage check` が
+> `PUBLIC_ENV_MISUSE` 警告を出します。ユーザー向けの `VITE_` API は存在しません。
+
+## シークレットはサーバーの `env` から
+
+API キーやトークンなどの秘密情報は、**クライアントに出さず**サーバーの `ApiContext.env` から
+読みます。これらは接頭辞を付けません。
+
+```ts
+// server/api/report.ts
+import type { ApiContext } from "@squadbase/vantage/server";
+
+export async function GET({ env }: ApiContext) {
+  const apiKey = env.SECRET_API_KEY; // クライアントには決して届かない
+  // …外部サービスを呼ぶ
+  return Response.json({ ok: true });
+}
+```
+
+## `.env` の例
+
+```bash
+# .env
+PUBLIC_ANALYTICS_ID=UA-XXXX     # クライアントに届く
+SECRET_API_KEY=sk_live_xxx      # サーバー専用（ApiContext.env）
+```
+
+> [!NOTE]
+> dev サーバーはリクエストごとに env を読み直します。本番の Node サーバーは起動時に一度だけ
+> `process.env` をスナップショットします。
+
+## デプロイで使う env
+
+フロントとサーバーを別オリジンにデプロイするときは、次の env が関わります。
+
+| 変数 | 側 | 役割 |
+|---|---|---|
+| `PUBLIC_API_BASE_URL` | クライアント(公開) | クライアントが `/api` を呼ぶベースURL。`--api-base-url` でも上書き可 |
+| `CORS_ORIGIN` | サーバー | `/api` に対して許可するオリジン。未設定なら CORS 無効 |
+| `CORS_CREDENTIALS` | サーバー | `true` で資格情報(Cookie 等)を許可 |
+
+使い方は[ビルドとデプロイ](build-and-deploy)で詳しく解説します。
+
+## 次に読む
+
+- [ビルドとデプロイ](build-and-deploy) — 本番の env と別オリジン構成
+- [UI とテーマ](ui-and-theming) — 見た目を整える