@squadbase/vantage 0.1.1 → 0.2.1

package/docs/en/changelog.md

@@ -0,0 +1,133 @@
+# Changelog
+
+> What changed in each Vantage release, newest first. Still a prototype (0.x), so APIs may change between releases.
+
+What changed in each Vantage release. Newest is on top.
+
+> [!NOTE]
+> Still a prototype (**0.x**). While on 0.x, **minor is effectively the major** — a
+> minor release may include backwards-incompatible changes. A patch is limited to
+> backwards-compatible additions and bug fixes.
+
+## v0.2.1
+
+Charts now follow the theme tokens, and `Select` works out the value-to-label
+map for you. Both are backwards-compatible.
+
+> [!NOTE]
+> **Chart colours change.** Charts without an explicit `option.color` used to paint
+> in ECharts' own defaults; they now use the theme's `--chart-1` through
+> `--chart-5`. Charts that set `option.color` are unaffected.
+
+### Changed
+
+- **[`EChart`](parts/echart) follows the theme tokens** — series
+  come from `--chart-1` through `--chart-5`, while axes, legend and tooltip are
+  built from the text and border tokens, and a light/dark switch is picked up.
+  ECharts can't read CSS variables *while painting*, so the tokens are resolved
+  once at init. Set `option.color` to override just the series — axes keep
+  following the tokens. To paint the whole chart yourself, pass the `theme` prop
+  (that turns token-following off entirely).
+- **[`Select`](ui/select) no longer needs `items`** — Base UI's
+  `SelectValue` renders the raw selected *value*, so a trigger would read
+  `kanto` where the list said "Kanto". Vantage now derives the map from your
+  `SelectItem`s. **An explicit `items` still wins**, so existing code is
+  unchanged (keep passing it when a separate component returns the options).
+
+### Fixed
+
+- The `SegmentedControl` example in `useSearchParam`'s JSDoc passed a
+  non-existent `onValueChange` prop (it's `onChange`).
+- Refreshed the bundled `AGENTS.md` and Skills: `vantage add ui|block` can copy
+  only `data-table` and `sales-overview`; the mode follows from whether `server/`
+  exists rather than being a "promote the SPA to fullstack" procedure; and look
+  for already-placed Skills before adding them. A placed `AGENTS.md` is synced by
+  `vantage upgrade`.
+
+## v0.2.0
+
+Makes the destination of `vantage add skill` selectable, and drops the `.js`
+specifier convention for relative imports. This carries one backwards-incompatible
+change (the default destination), so per the 0.x policy it goes out as a minor.
+
+Apps pinned to `"@squadbase/vantage": "^0.1.0"` will not pick up 0.2.0 — bump the
+range to `^0.2.0`.
+
+> [!WARNING]
+> **The default destination of `vantage add skill` changed.** It used to always
+> write into `.claude/skills/`; skills now land **directly under the project
+> root**. Pass `--dir .claude/skills` to keep the old location. Copies you already
+> placed stay where they are — you only need the flag when refreshing them.
+
+### Changed
+
+- **`vantage add skill --dir <path>`** — the destination is now a flag. The path
+  resolves from the project root (`--root` is honored) and absolute paths work
+  too. Use `--dir .claude/skills` for Claude Code to discover them automatically,
+  or whatever directory another agent expects
+  (see [Agents and Skills](agent-skills)).
+- **Dropped the `.js` specifier convention for relative imports** — writing
+  `./components/revenue-chart.js` is no longer required
+  (`./components/revenue-chart` is fine). Vantage code always goes through Vite
+  or tsup, and TypeScript resolves it with `moduleResolution: "Bundler"`, so
+  nothing ever handed a raw specifier to Node. **Existing imports with `.js`
+  keep working** — there is nothing to rewrite.
+
+## v0.1.1
+
+Adds hooks for the route list, URL-synced state, and API calls, and fixes two
+dev-time issues. Everything here is backwards-compatible.
+
+### Added
+
+- **Routing hooks** — `useRoutes()` / `useCurrentRoute()` in
+  [`@squadbase/vantage/router`](routing). They hand you the file-based route
+  list directly, so you can build navigation without maintaining it by hand.
+- **URL-synced state** — `useSearchParam` (always a string; writing the default
+  or `null` removes the key) and `useSearchState<T>` for JSON values with
+  functional updates. Keep filter and tab state in the URL.
+- **API-calling hooks** — `useApiQuery` / `useApiMutation` in
+  [`@squadbase/vantage/query`](data-fetching). They call `server/api` with
+  JSON, normalizing errors as `HttpError` → `ApiError` (`status` / `body` /
+  `requestId`).
+- **`navLabel` on `definePage`** — a field to set the navigation display name
+  independently of the page title (see [Pages and metadata](pages-and-metadata)).
+
+### Fixed
+
+- **Dev SPA fallback** — visiting a URL like `/sales` directly made Vite show a
+  `No matching HTML proxy module found` error overlay (the page itself still
+  rendered). The injected-script ids are now derived from the shell document's
+  URL.
+- **Queries stuck in `paused`** — when the browser's offline heuristic wrongly
+  reported offline, a failed query would stall instead of erroring and the page
+  never left its loading state. The managed `QueryClient` now uses
+  `networkMode: "always"` (the heuristic is meaningless for a dashboard hitting
+  its own origin).
+
+## v0.1.0
+
+The first prototype release — the full foundation of a config-free React
+dashboard framework.
+
+### Added
+
+- **Config-free foundation** — built on Vite 8. You write `index.tsx`; Vantage
+  owns routing, React, TanStack Query, Tailwind v4, the UI kit, the dev server,
+  the optional API server, and the build.
+- **File-based routing** — a `*.tsx` with a default export is a route,
+  `_layout.tsx` is a layout, `_404.tsx` / `_error.tsx` handle not-found / error,
+  and `[param].tsx` is a dynamic route (see [Routing](routing)).
+- **Optional API server** — add `server/api/**` to enable a backend that runs
+  identically in `dev` and in the production build (see
+  [API and server](api-and-server)).
+- **UI kit and components** — Tailwind v4, shadcn/ui (Base UI variant), and
+  composite dashboard components built on top (see [UI and theming](ui-and-theming)).
+- **CLI** — `dev` / `build` / `preview` / `check` / `routes` / `add` / `upgrade`
+  (see [CLI reference](cli-reference)).
+- **Bundled docs and search** — `vantage docs` prints the package's guide and
+  component reference offline, and `vantage search` searches the same content
+  with BM25.
+- **Distribution for agents** — `vantage add agents` places an `AGENTS.md`, and
+  `vantage add skill` installs the Claude Code Agent Skills into your app (see
+  [Agents and Skills](agent-skills)).

package/docs/en/cli-reference.md

@@ -13,7 +13,7 @@
 | `vantage preview` | Run the production build locally (fullstack default `:4173`; spa via Vite preview) |
 | `vantage check` | Static checks (routes, boundaries, forbidden files). Exit 1 on error |
 | `vantage routes` | Print the page + API URL map |
-| `vantage add <kind> <name>` | Scaffold or place a `page` / `api` / `ui` / `block` / `skill` / `agents` (`--force` to overwrite) |
+| `vantage add <kind> <name>` | Scaffold or place a `page` / `api` / `ui` / `block` / `skill` / `agents` (`--force` to overwrite; `skill` takes `--dir` for the destination) |
 | `vantage docs [name]` | Show the bundled guide and component reference |
 | `vantage search <query>` | Search that same reference in full text (natural language or `--regex`) |
 | `vantage doctor` | Diagnose environment / installation health |

package/docs/en/components.md

@@ -42,8 +42,8 @@ from the Radix build, four differences matter.
 - **[`ToggleGroup`](ui/toggle-group)'s `value` is an array.** For single choice, use
   [`SegmentedControl`](parts/segmented-control).
 - **[`Select`](ui/select)'s `onValueChange` gives `string | null`.** You need a
-  `null` guard. And `SelectValue` shows the raw value by default — pass the value-to-label map as
-  `items` to get labels.
+  `null` guard. The value-to-label `items` map is derived from your `SelectItem`s automatically, so
+  you rarely write it (only when a separate component returns the options).
 
 State is expressed as `data-open` / `data-checked` rather than `data-state="open"`. Vantage's
 `theme.css` declares custom variants that accept both spellings, so classes like

package/docs/en/parts/echart.md

@@ -1,10 +1,11 @@
 # EChart
 
-> A thin Apache ECharts wrapper. Set colours in your option.
+> A thin Apache ECharts wrapper whose colours follow the theme tokens.
 
-A thin wrapper around Apache ECharts. It only handles the canvas lifecycle (init, resize, dispose),
-the loading overlay, event subscriptions and PNG export. **The palette and axes do not auto-follow
-the theme** — set colours inside `option`, or pass an ECharts theme to `theme`.
+A thin wrapper around Apache ECharts. It handles the canvas lifecycle (init, resize, dispose), the
+loading overlay, event subscriptions and PNG export. **Colours follow the theme tokens** — series
+come from `--chart-1` through `--chart-5`, while axes, legend and tooltip are built from the text
+and border tokens. A light/dark switch is picked up too.
 
 ```tsx
 import { EChart } from "@squadbase/vantage/components";
@@ -16,16 +17,21 @@ import type { EChartsOption } from "@squadbase/vantage/components";
 | `option` | `EChartsOption` | The ECharts option, passed straight through. |
 | `height` | `string \| number` | Height; a number means px. `className` works too. |
 | `loading` | `boolean` | Show ECharts' loading overlay. |
-| `theme` | `string \| object` | The theme passed to `echarts.init` (a name or a registered theme). |
+| `theme` | `string \| object` | The theme passed to `echarts.init` (a name or a registered theme). Passing one turns token-following off. |
 | `onEvents` | `Record<string, (params: unknown) => void>` | Subscribe to ECharts events such as `click`. |
 | `ariaLabel` | `string` | A description of the chart. |
 | `actions` | `boolean` | Show actions such as save-as-image. |
 | `fileName` | `string` | File name used when saving. |
 
-## Setting the palette
+## Overriding the palette
 
-Series colours come from `option.color`. To match the theme's `--chart-1` through `--chart-5`, pass
-the resolved values — ECharts paints to canvas and cannot read CSS variables.
+By default the theme's `--chart-1` through `--chart-5` become the series colours. ECharts can't read
+CSS variables *while painting*, but `EChart` resolves the tokens once at init with
+`getComputedStyle` and passes them in as an ECharts theme. It watches for the `.dark` class going on
+and off, and re-reads the tokens when it changes.
+
+To give series their own colours, set `option.color` (or `series[].itemStyle.color`). Your option
+wins over the theme, so **axes, legend and tooltip keep following the tokens**.
 
 ```ts
 const option: EChartsOption = {
@@ -34,9 +40,10 @@ const option: EChartsOption = {
 };
 ```
 
-To reuse a palette across charts, register a theme with
-[`echarts.registerTheme`](https://echarts.apache.org/en/api.html#echarts.registerTheme) and pass its
-name to the `theme` prop.
+To paint the whole chart with a theme of your own, register it with
+[`echarts.registerTheme`](https://echarts.apache.org/en/api.html#echarts.registerTheme) and pass the
+name (or the theme object) to `theme`. That turns token-following off entirely — including the
+light/dark switch.
 
 ## Keeping the legend off the plot
 

package/docs/en/routing.md

@@ -33,10 +33,6 @@ server/       API (its presence enables the server)
 public/       Static assets
 ```
 
-> [!NOTE]
-> Imports between files use **runtime `.js` specifiers** (e.g. `./components/revenue-chart.js`) —
-> required for ESM Node resolution.
-
 ## The three spellings of a dynamic param
 
 The same param appears in three spellings depending on where it is. **They must match.**

package/docs/en/ui/select.md

@@ -39,24 +39,30 @@ import {
 > <Select onValueChange={(value) => value !== null && setRegion(value)}>
 > ```
 
-> [!WARNING]
-> `SelectValue` shows the **raw selected `value`** by default — it never looks inside `SelectItem`.
-> With `value="kanto"` the trigger reads `kanto`, not "Kanto". Give `Select` the value-to-label map
-> via `items`.
+> [!NOTE]
+> Base UI's `SelectValue` renders the **raw selected `value`** — it never looks inside `SelectItem`.
+> With `value="kanto"` the trigger would read `kanto`.
 >
-> ```tsx
-> const regions = { hokkaido: "Hokkaido", kanto: "Kanto", kansai: "Kansai" };
+> Vantage's `Select` **absorbs that quirk**: it walks its children, collects each `SelectItem`'s
+> `value` → label pair and hands them to Base UI as `items`, so the code below puts "Kanto" in the
+> trigger. It's the same treatment `SegmentedControl` gives `ToggleGroup`'s array API.
 >
-> <Select items={regions} value={region} onValueChange={…}>
+> ```tsx
+> <Select value={region} onValueChange={…}>
 >   <SelectTrigger><SelectValue placeholder="Pick a region" /></SelectTrigger>
->   …
+>   <SelectContent>
+>     <SelectItem value="kanto">Kanto</SelectItem>
+>   </SelectContent>
 > </Select>;
 > ```
 >
-> If you'd rather not carry `items`, a function child on `SelectValue` does the same job.
+> Only `SelectItem`s **written in place** are picked up (a `map` over them counts). When the options
+> come back from a separate component, pass `items` yourself — an explicit `items` always wins.
 >
 > ```tsx
-> <SelectValue>{(value) => regions[value] ?? "Pick a region"}</SelectValue>
+> const regions = { hokkaido: "Hokkaido", kanto: "Kanto", kansai: "Kansai" };
+>
+> <Select items={regions} value={region} onValueChange={…}>
 > ```
 
 `SelectContent` opens over the trigger with the selected item aligned to it. For a plain dropdown

package/docs/index.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "generatedFrom": "docs/content",
   "docs": [
     {
@@ -108,10 +108,21 @@
       "section": "guide",
       "sectionTitle": "ガイド",
       "title": "エージェントと Skills",
-      "description": "Vantage に同梱された Claude Code の Agent Skills。vantage add skill でアプリの .claude/skills/ に配置し、エージェントに手順を伴うワークフローを教える。",
+      "description": "Vantage に同梱された Claude Code の Agent Skills。vantage add skill でアプリに配置し（既定はルート直下、--dir で .claude/skills などに変更）、エージェントに手順を伴うワークフローを教える。",
       "file": "ja/agent-skills.md",
       "order": 9
     },
+    {
+      "slug": "changelog",
+      "lang": "ja",
+      "section": "guide",
+      "sectionTitle": "ガイド",
+      "title": "変更履歴",
+      "description": "Vantage のリリースごとの変更点。新しいものが上。まだプロトタイプ(0.x)のため、リリース間で API が変わることがあります。",
+      "file": "ja/changelog.md",
+      "order": 10,
+      "searchable": false
+    },
     {
       "slug": "components",
       "lang": "ja",
@@ -538,7 +549,7 @@
       "section": "components/parts",
       "sectionTitle": "@squadbase/vantage/components",
       "title": "EChart",
-      "description": "Apache ECharts の薄いラッパー。配色は option で指定する。",
+      "description": "Apache ECharts の薄いラッパー。配色はテーマトークンに追従する。",
       "file": "ja/parts/echart.md",
       "order": 4
     },
@@ -778,10 +789,21 @@
       "section": "guide",
       "sectionTitle": "Guide",
       "title": "Agents and Skills",
-      "description": "The Claude Code agent skills bundled with Vantage. Place them into your app's .claude/skills/ with vantage add skill to teach agents step-by-step workflows.",
+      "description": "The Claude Code agent skills bundled with Vantage. Place them into your app with vantage add skill (the project root by default, or anywhere via --dir, e.g. .claude/skills) to teach agents step-by-step workflows.",
       "file": "en/agent-skills.md",
       "order": 9
     },
+    {
+      "slug": "changelog",
+      "lang": "en",
+      "section": "guide",
+      "sectionTitle": "Guide",
+      "title": "Changelog",
+      "description": "What changed in each Vantage release, newest first. Still a prototype (0.x), so APIs may change between releases.",
+      "file": "en/changelog.md",
+      "order": 10,
+      "searchable": false
+    },
     {
       "slug": "components",
       "lang": "en",
@@ -1208,7 +1230,7 @@
       "section": "components/parts",
       "sectionTitle": "@squadbase/vantage/components",
       "title": "EChart",
-      "description": "A thin Apache ECharts wrapper. Set colours in your option.",
+      "description": "A thin Apache ECharts wrapper whose colours follow the theme tokens.",
       "file": "en/parts/echart.md",
       "order": 4
     },

package/docs/ja/agent-skills.md

@@ -1,6 +1,6 @@
 # エージェントと Skills
 
-> Vantage に同梱された Claude Code の Agent Skills。vantage add skill でアプリの .claude/skills/ に配置し、エージェントに手順を伴うワークフローを教える。
+> Vantage に同梱された Claude Code の Agent Skills。vantage add skill でアプリに配置し（既定はルート直下、--dir で .claude/skills などに変更）、エージェントに手順を伴うワークフローを教える。
 
 Vantage は **Claude Code の Agent Skills** を同梱しています。Skill は「手順を伴うワークフロー」を、
 エージェントが必要なときだけ呼び出せる形にしたものです。UI キットや CLI の使い方といった
@@ -18,16 +18,18 @@ Vantage は **Claude Code の Agent Skills** を同梱しています。Skill
 
 ## 配置する
 
-Skill のソースは `@squadbase/vantage` パッケージに同梱されています。`vantage add skill` で、
-対象アプリの `.claude/skills/` にコピーします。
+Skill のソースは `@squadbase/vantage` パッケージに同梱されています。`vantage add skill` で
+対象アプリにコピーします。配置先は既定で**プロジェクトルート直下**で、`--dir` で変えられます。
 
 ```bash
-vantage add skill --all          # 同梱スキルをすべて配置
-vantage add skill vantage-app    # 名前を指定して1つだけ配置
-vantage add skill vantage-app --force   # 既存を上書き
+vantage add skill --all                       # 同梱スキルをすべて、ルート直下に配置
+vantage add skill vantage-app                 # 名前を指定して1つだけ配置
+vantage add skill --all --dir .claude/skills  # Claude Code が読む場所に配置
+vantage add skill vantage-app --force         # 既存を上書き
 ```
 
-配置後のレイアウト:
+`--dir` のパスはプロジェクトルートからの相対で解決されます（絶対パスも可）。Claude Code に
+自動認識させるなら `.claude/skills/` に置きます:
 
 ```text
 your-app/
@@ -41,7 +43,8 @@ your-app/
 ```
 
 `.claude/skills/` は Claude Code が自動で認識します。エージェントはタスクに応じて、対応する
-Skill の手順を読み込んで実行します。
+Skill の手順を読み込んで実行します。他のエージェントに読ませる場合は、そのツールが期待する
+ディレクトリを `--dir` に渡してください。
 
 > [!NOTE]
 > `.claude/` はツール用の設定であり、アプリのコードではありません。`vantage check` の静的診断は
@@ -51,7 +54,8 @@ Skill の手順を読み込んで実行します。
 
 - **source-of-truth はパッケージ内**にあります。Skill はフレームワークのバージョンと一緒に
   配布・更新されるため、`@squadbase/vantage` を上げれば最新の手順が手に入ります。配置済みの
-  コピーを更新したいときは `vantage add skill --all --force` を実行します。
+  コピーを更新したいときは、配置したときと同じ `--dir` を付けて
+  `vantage add skill --all --force` を実行します。
 - **Squadbase テンプレートには配置済み**です。テンプレートから作ったアプリには、最初から
   `.claude/skills/` が入っています。手で作ったアプリには `vantage add skill` で足してください。
 

package/docs/ja/changelog.md

@@ -0,0 +1,124 @@
+# 変更履歴
+
+> Vantage のリリースごとの変更点。新しいものが上。まだプロトタイプ(0.x)のため、リリース間で API が変わることがあります。
+
+Vantage のリリースごとの変更点です。新しいものが上に来ます。
+
+> [!NOTE]
+> まだプロトタイプ(**0.x**)です。0.x の間は **minor が実質のメジャー**扱いで、後方互換性の
+> ない変更は minor で入ることがあります。patch は後方互換の機能追加とバグ修正のみです。
+
+## v0.2.1
+
+チャートをテーマトークンに追従させ、`Select` の値とラベルの対応を Vantage 側で組むように
+しました。API はどちらも後方互換です。
+
+> [!NOTE]
+> **チャートの配色が変わります。** これまで `option.color` を書いていないチャートは ECharts の
+> 既定色で描かれていましたが、テーマの `--chart-1` 〜 `--chart-5` で描かれるようになります。
+> 自分で `option.color` を指定しているチャートは今までどおりです。
+
+### 変更
+
+- **[`EChart`](parts/echart) がテーマトークンに追従するようになりました** ―
+  系列色は `--chart-1` 〜 `--chart-5`、軸・凡例・ツールチップは文字色と境界色のトークンから
+  組まれ、ライト / ダークの切り替えにも追いかけます。ECharts が CSS 変数を読めないのは
+  **キャンバスの描画中**の話なので、init のタイミングでトークンの実値を解決しています。
+  系列の色だけ変えたいときは `option.color` で上書きでき、その場合も軸まわりの追従は
+  残ります。チャート全体を自前のテーマで描きたいときは `theme` プロップを渡してください
+  (このときトークン追従は完全に無効になります)。
+- **[`Select`](ui/select) の `items` を書かなくてよくなりました** ―
+  Base UI の `SelectValue` は選択中の *value* をそのまま描く部品で、値とラベルが違うと
+  トリガーに `kanto` のような生の値が出ていました。`SelectItem` から対応表を組む処理を
+  Vantage 側に入れたので、普通に書けばラベルが出ます。**明示した `items` は今までどおり
+  優先される**ので、既存のコードはそのまま動きます(項目を別のコンポーネントが返している
+  場合は、これまでどおり `items` を渡してください)。
+
+### 修正
+
+- `useSearchParam` の JSDoc に載せていた `SegmentedControl` の例が、存在しない
+  `onValueChange` を渡していました(正しくは `onChange`)。
+- 同梱の `AGENTS.md` と Skill を更新しました ― `vantage add ui|block` でコピーできるのが
+  `data-table` と `sales-overview` の 2 つだけであること、モードは `server/` の有無で決まり
+  「SPA から fullstack へ昇格する」手順ではないこと、配置済みの Skill を先に探すこと。
+  配置済みの `AGENTS.md` は `vantage upgrade` で同期されます。
+
+## v0.2.0
+
+`vantage add skill` の配置先を選べるようにし、相対 import の `.js` 指定子の規約を廃止しました。
+後方互換でない変更(既定の配置先)を含むため、0.x の方針に従って minor を上げています。
+
+依存を `"@squadbase/vantage": "^0.1.0"` と書いているアプリには 0.2.0 は入りません。
+`^0.2.0` に上げてください。
+
+> [!WARNING]
+> **`vantage add skill` の既定の配置先が変わりました。** これまで常に `.claude/skills/` へ
+> 出していましたが、既定は**プロジェクトルート直下**になります。これまでと同じ場所に置くには
+> `--dir .claude/skills` を明示してください。配置済みのコピーはそのまま残るので、更新する
+> ときだけ `--dir` を付け直す形になります。
+
+### 変更
+
+- **`vantage add skill --dir <path>`** ― 配置先をコマンドで指定できるようになりました。
+  パスはプロジェクトルート(`--root` を尊重)からの相対で解決され、絶対パスも渡せます。
+  Claude Code に自動認識させたい場合は `--dir .claude/skills`、他のエージェント向けには
+  そのツールが期待するディレクトリを指定します(→ [エージェントと Skills](agent-skills))。
+- **相対 import の `.js` 指定子の規約を廃止** ― `./components/revenue-chart.js` のように
+  拡張子を書く必要はなくなりました(`./components/revenue-chart` で構いません)。Vantage の
+  コードは常に Vite / tsup を通り、TypeScript も `moduleResolution: "Bundler"` で解決する
+  ため、Node が生の指定子を読む経路がそもそもありませんでした。**既存の `.js` 付きの
+  import はそのまま動きます** ― 書き換えは不要です。
+
+## v0.1.1
+
+一覧・URL 状態・API 呼び出しの hook を追加し、開発時の 2 つの不具合を修正しました。
+すべて後方互換です。
+
+### 追加
+
+- **ルーティングの hook** ― `useRoutes()` / `useCurrentRoute()` を
+  [`@squadbase/vantage/router`](routing) に追加。ファイルベースルーティングの一覧を
+  そのまま受け取り、ナビゲーションを手で二重管理せずに組めます。
+- **URL 同期の状態** ― `useSearchParam`(常に文字列。既定値/`null` を書くとキーを消す)と、
+  JSON 値と関数更新に対応した `useSearchState<T>` を追加。フィルタやタブの状態を URL に置けます。
+- **API 呼び出しの hook** ― `useApiQuery` / `useApiMutation` を
+  [`@squadbase/vantage/query`](data-fetching) に追加。`server/api` を JSON で呼び、
+  エラーは `HttpError` → `ApiError`(`status` / `body` / `requestId`)に正規化されます。
+- **`definePage` の `navLabel`** ― ナビゲーションに出す表示名を、ページのタイトルと
+  独立して指定できるフィールドを追加(→ [ページとメタデータ](pages-and-metadata))。
+
+### 修正
+
+- **dev の SPA フォールバック** ― `/sales` のような URL に直接アクセスすると、Vite が
+  `No matching HTML proxy module found` のエラーオーバーレイを出していた問題を修正
+  (ページ自体は描画されていました)。注入スクリプトの id をシェル文書の URL から
+  導くようにしました。
+- **クエリが `paused` のまま止まる** ― ブラウザのオフライン判定が誤って offline を返すと、
+  失敗したクエリがエラーにならず停止し、ページが読み込み表示から戻らないことがありました。
+  管理された `QueryClient` の `networkMode` を `"always"` にして解消(自オリジンの API を
+  叩くダッシュボードでは、この判定に意味がありません)。
+
+## v0.1.0
+
+最初のプロトタイプリリース。設定ファイル不要(config-free)な React ダッシュボード
+フレームワークの土台一式です。
+
+### 追加
+
+- **config-free な土台** ― Vite 8 の上に構築。アプリ作者が書くのは `index.tsx` だけで、
+  ルーティング・React・TanStack Query・Tailwind v4・UI キット・開発サーバー・
+  オプションの API サーバー・ビルドはすべて Vantage が所有します。
+- **ファイルベースルーティング** ― `*.tsx`(デフォルトエクスポート)がルートに、
+  `_layout.tsx` がレイアウトに、`_404.tsx` / `_error.tsx` が not-found / error に、
+  `[param].tsx` が動的ルートになります(→ [ルーティング](routing))。
+- **オプションの API サーバー** ― `server/api/**` を足すとバックエンドが有効になり、
+  `dev` と本番ビルドで同一に動きます(→ [API とサーバー](api-and-server))。
+- **UI キットとコンポーネント** ― Tailwind v4、shadcn/ui(Base UI 版)、その上に組んだ
+  ダッシュボード向けの複合コンポーネント(→ [UI とテーマ](ui-and-theming))。
+- **CLI** ― `dev` / `build` / `preview` / `check` / `routes` / `add` / `upgrade`
+  (→ [CLI リファレンス](cli-reference))。
+- **同梱ドキュメントと検索** ― `vantage docs` がパッケージ同梱のガイドとコンポーネント
+  リファレンスをオフラインで表示し、`vantage search` が同じ内容を BM25 で検索します。
+- **エージェント向けの配布物** ― `vantage add agents` が `AGENTS.md` を、
+  `vantage add skill` が Claude Code の Agent Skills をアプリへ配置します
+  (→ [エージェントと Skills](agent-skills))。

package/docs/ja/cli-reference.md

@@ -13,7 +13,7 @@
 | `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 add <kind> <name>` | `page` / `api` / `ui` / `block` / `skill` / `agents` を雛形生成・配置（`--force` で上書き、`skill` は `--dir` で配置先を指定） |
 | `vantage docs [name]` | 同梱のガイド + コンポーネントリファレンスを表示 |
 | `vantage search <query>` | 同じリファレンスを全文検索（自然言語 or `--regex`） |
 | `vantage doctor` | 環境・インストールの健全性を診断 |

package/docs/ja/components.md

@@ -42,8 +42,8 @@ Radix UI から [Base UI](https://base-ui.com) へ切り替えており、Vantag
 - **[`ToggleGroup`](ui/toggle-group) の `value` は配列。** 単一選択にしたいときは
   [`SegmentedControl`](parts/segmented-control) を使ってください。
 - **[`Select`](ui/select) の `onValueChange` は `string | null`。** `null` のガードが
-  要ります。また `SelectValue` は既定で選択中の値をそのまま表示するので、ラベルを出すには
-  `items` に対応表を渡します。
+  要ります。値とラベルが違うときの `items` は Vantage 側が `SelectItem` から自動で組むので、
+  通常は書かなくて済みます(別コンポーネントが項目を返す形のときだけ明示)。
 
 状態は `data-state="open"` ではなく `data-open` / `data-checked` のような属性で表現されます。
 Vantage の `theme.css` は両方の綴りを受ける custom variant を定義しているので、

package/docs/ja/parts/echart.md

@@ -1,10 +1,11 @@
 # EChart
 
-> Apache ECharts の薄いラッパー。配色は option で指定する。
+> Apache ECharts の薄いラッパー。配色はテーマトークンに追従する。
 
 Apache ECharts をそのまま使えるようにした薄いラッパーです。キャンバスの初期化・リサイズ・破棄と、
-ローディング表示・イベント購読・PNG 保存だけを面倒みます。**配色や軸の見た目はテーマに自動追従
-しません** — `option` の中で色を決めるか、`theme` に ECharts のテーマを渡してください。
+ローディング表示・イベント購読・PNG 保存を面倒みます。**配色はテーマトークンに追従します** —
+系列色は `--chart-1` 〜 `--chart-5`、軸・凡例・ツールチップは文字色と境界色のトークンから組まれ、
+ライト / ダークの切り替えにも追いかけます。
 
 ```tsx
 import { EChart } from "@squadbase/vantage/components";
@@ -16,16 +17,21 @@ import type { EChartsOption } from "@squadbase/vantage/components";
 | `option` | `EChartsOption` | ECharts の option。そのまま渡す。 |
 | `height` | `string \| number` | 高さ。数値は px。`className` で決めても良い。 |
 | `loading` | `boolean` | ECharts のローディング表示を出す。 |
-| `theme` | `string \| object` | `echarts.init` に渡すテーマ（名前または登録済みテーマ）。 |
+| `theme` | `string \| object` | `echarts.init` に渡すテーマ（名前または登録済みテーマ）。渡すとトークン追従は無効になる。 |
 | `onEvents` | `Record<string, (params: unknown) => void>` | ECharts のイベント購読（`click` など）。 |
 | `ariaLabel` | `string` | チャートの説明。 |
 | `actions` | `boolean` | 画像保存などの操作を出す。 |
 | `fileName` | `string` | 保存時のファイル名。 |
 
-## 配色を決める
+## 配色を上書きする
 
-系列の色は `option.color` で指定します。テーマの `--chart-1` 〜 `--chart-5` に揃えたいときは、
-ECharts はキャンバス描画で CSS 変数を読めないため、色の実値を渡してください。
+既定ではテーマの `--chart-1` 〜 `--chart-5` がそのまま系列色になります。ECharts は**描画中**には
+CSS 変数を読めませんが、`EChart` は init のタイミングで `getComputedStyle` からトークンの実値を
+解決し、ECharts のテーマとして渡しています。`.dark` の付け外しを見張っていて、切り替われば
+読み直します。
+
+系列に固有の色を当てたいときは `option.color`(または `series[].itemStyle.color`)で上書きします。
+option はテーマより優先されるので、**軸・凡例・ツールチップのトークン追従は残ります**。
 
 ```ts
 const option: EChartsOption = {
@@ -34,8 +40,9 @@ const option: EChartsOption = {
 };
 ```
 
-複数チャートで配色を使い回すなら、[`echarts.registerTheme`](https://echarts.apache.org/en/api.html#echarts.registerTheme)
-でテーマを登録し、その名前を `theme` プロップに渡すのが簡潔です。
+チャート全体を自前のテーマで描きたいときは、[`echarts.registerTheme`](https://echarts.apache.org/en/api.html#echarts.registerTheme)
+で登録したテーマ名(またはテーマオブジェクト)を `theme` プロップに渡します。この場合は
+トークン追従が**完全に無効**になり、明暗の切り替えにも追従しなくなります。
 
 ## 凡例と重ならないようにする
 

package/docs/ja/routing.md

@@ -33,10 +33,6 @@ server/       API（存在するとサーバーが有効になる）
 public/       静的アセット
 ```
 
-> [!NOTE]
-> ファイル間の import は **ランタイムの `.js` 指定子**を使います（例: `./components/revenue-chart.js`）。
-> ESM の Node 解決に必要です。
-
 ## 動的パラメータの 3 つの綴り
 
 同じパラメータが、場所によって 3 つの綴りで現れます。**必ず一致させます。**