@squadbase/vantage 0.2.1 → 0.2.3

package/dist/index.d.ts

@@ -10,6 +10,6 @@ import 'react';
  */
 
 /** Framework version, kept in sync with package.json at build time. */
-declare const VERSION = "0.2.1";
+declare const VERSION = "0.2.3";
 
 export { VERSION };

package/dist/index.js

@@ -6,7 +6,7 @@ function definePage(config) {
 }
 
 // src/index.ts
-var VERSION = "0.2.1";
+var VERSION = "0.2.3";
 
 export { VERSION, definePage };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/runtime/define-page.ts","../src/index.ts"],"names":[],"mappings":";;;AAyCO,SAAS,WAAW,MAAA,EAAgC;AACzD,EAAA,OAAO,MAAA;AACT;;;AChCO,IAAM,OAAA,GAAU","file":"index.js","sourcesContent":["import type { ComponentType, ReactNode } from \"react\"\n\n/**\n * Optional per-page configuration. The only required part of a page module is\n * its default-exported component; `definePage` covers everything else.\n */\nexport interface PageConfig {\n  /** Document title applied when this route is active. */\n  title?: string\n  /** Description metadata for the page. */\n  description?: string\n  /**\n   * Short label for navigation built from `useRoutes()`. Defaults to `title`,\n   * which is often too long for a nav (\"Overview · Acme Analytics\").\n   */\n  navLabel?: string\n  /**\n   * Component rendered while the route is loading.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  pendingComponent?: ComponentType\n  /**\n   * Component rendered when the route throws.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  errorComponent?: ComponentType<{ error: unknown }>\n  /**\n   * Validate/transform the URL search params for this route.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  validateSearch?: (search: Record<string, unknown>) => Record<string, unknown>\n}\n\n/**\n * Declare optional page configuration.\n *\n * ```tsx\n * export const page = definePage({ title: \"Monthly Analysis\" })\n * export default function MonthlyAnalysis() { return <div/> }\n * ```\n */\nexport function definePage(config: PageConfig): PageConfig {\n  return config\n}\n\n/** Convenience type for a Vantage page component. */\nexport type PageComponent = ComponentType & { (): ReactNode }\n","/**\n * `@squadbase/vantage` — public runtime surface.\n *\n * The only import most pages need. Server state lives in\n * `@squadbase/vantage/query`, navigation in `@squadbase/vantage/router`,\n * UI in `@squadbase/vantage/ui`, and API types in `@squadbase/vantage/server`.\n */\nexport { definePage } from \"./runtime/define-page\"\nexport type { PageConfig, PageComponent } from \"./runtime/define-page\"\n\n/** Framework version, kept in sync with package.json at build time. */\nexport const VERSION = \"0.2.1\"\n"]}
+{"version":3,"sources":["../src/runtime/define-page.ts","../src/index.ts"],"names":[],"mappings":";;;AAyCO,SAAS,WAAW,MAAA,EAAgC;AACzD,EAAA,OAAO,MAAA;AACT;;;AChCO,IAAM,OAAA,GAAU","file":"index.js","sourcesContent":["import type { ComponentType, ReactNode } from \"react\"\n\n/**\n * Optional per-page configuration. The only required part of a page module is\n * its default-exported component; `definePage` covers everything else.\n */\nexport interface PageConfig {\n  /** Document title applied when this route is active. */\n  title?: string\n  /** Description metadata for the page. */\n  description?: string\n  /**\n   * Short label for navigation built from `useRoutes()`. Defaults to `title`,\n   * which is often too long for a nav (\"Overview · Acme Analytics\").\n   */\n  navLabel?: string\n  /**\n   * Component rendered while the route is loading.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  pendingComponent?: ComponentType\n  /**\n   * Component rendered when the route throws.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  errorComponent?: ComponentType<{ error: unknown }>\n  /**\n   * Validate/transform the URL search params for this route.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  validateSearch?: (search: Record<string, unknown>) => Record<string, unknown>\n}\n\n/**\n * Declare optional page configuration.\n *\n * ```tsx\n * export const page = definePage({ title: \"Monthly Analysis\" })\n * export default function MonthlyAnalysis() { return <div/> }\n * ```\n */\nexport function definePage(config: PageConfig): PageConfig {\n  return config\n}\n\n/** Convenience type for a Vantage page component. */\nexport type PageComponent = ComponentType & { (): ReactNode }\n","/**\n * `@squadbase/vantage` — public runtime surface.\n *\n * The only import most pages need. Server state lives in\n * `@squadbase/vantage/query`, navigation in `@squadbase/vantage/router`,\n * UI in `@squadbase/vantage/ui`, and API types in `@squadbase/vantage/server`.\n */\nexport { definePage } from \"./runtime/define-page\"\nexport type { PageConfig, PageComponent } from \"./runtime/define-page\"\n\n/** Framework version, kept in sync with package.json at build time. */\nexport const VERSION = \"0.2.3\"\n"]}

package/dist/vite/index.js

@@ -1,4 +1,4 @@
-export { vantagePlugin } from '../chunk-UHZ7XSAN.js';
+export { vantagePlugin } from '../chunk-3QKPNWKJ.js';
 import '../chunk-46QI6GFC.js';
 import '../chunk-B7LLBNLV.js';
 //# sourceMappingURL=index.js.map

package/docs/en/agent-skills.md

@@ -22,12 +22,29 @@ The skills ship inside the `@squadbase/vantage` package. `vantage add skill` cop
 your app. They land **directly under the project root** by default; `--dir` puts them elsewhere.
 
 ```bash
-vantage add skill --all                       # every bundled skill, under the root
+vantage add skill                             # list the skills and where they sit (writes nothing)
+vantage add skill --all                       # every skill that isn't placed yet, under the root
 vantage add skill vantage-app                 # a single skill by name
 vantage add skill --all --dir .claude/skills  # where Claude Code looks for them
-vantage add skill vantage-app --force         # overwrite an existing copy
+vantage add skill --all --force               # refresh the placed copies in place
 ```
 
+**The destination is scanned for, not assumed.** `add skill` walks the project first (skipping
+`node_modules` and friends) and **skips any skill that is already placed, reporting where it is** —
+under the root, under `.claude/skills/`, under `.squadbase/skills/`, it doesn't matter, so
+**re-running never creates a second copy**. Drop the name to get just the list:
+
+```text
+$ vantage add skill
+Bundled skills:
+  vantage-add-feature  .claude/skills/vantage-add-feature/
+  vantage-app          .claude/skills/vantage-app/
+  vantage-pitfalls     not placed
+```
+
+With `--force`, the copies that were found are rewritten **where they are** (an explicit `--dir`
+still wins as the destination).
+
 A `--dir` path resolves from the project root (absolute paths work too). To have Claude Code pick
 them up automatically, place them in `.claude/skills/`:
 
@@ -54,8 +71,8 @@ skill based on the task at hand. For other agents, pass whatever directory that
 
 - **The source of truth lives in the package.** Skills are distributed and updated together with
   the framework version, so bumping `@squadbase/vantage` gets you the latest procedures. To refresh
-  copies you've already placed, run `vantage add skill --all --force` with the same `--dir` you
-  used originally.
+  copies you've already placed, run `vantage add skill --all --force` — the destination is scanned
+  for, so you don't have to remember the `--dir` you used originally.
 - **The Squadbase template ships them pre-placed.** Apps created from the template already contain
   `.claude/skills/`. For a hand-made app, add them with `vantage add skill`.
 

package/docs/en/changelog.md

@@ -9,6 +9,61 @@ What changed in each Vantage release. Newest is on top.
 > minor release may include backwards-incompatible changes. A patch is limited to
 > backwards-compatible additions and bug fixes.
 
+## v0.2.3
+
+`vantage routes` can be narrowed to one side of the map, and can print the spec of
+every route. Additions only, so it is backwards-compatible.
+
+### Added
+
+- **`vantage routes` takes `--pages` / `--apis`** (see
+  [CLI reference](cli-reference)) — pages only (plus layout / 404 / error), or
+  API routes only. They are not exclusive: passing both, or neither, prints
+  everything exactly as before.
+- **`--detail` adds each route's static spec** — for a page, the `definePage`
+  title / navLabel / description and its path params; for an API, **per method**,
+  the query keys read through `searchParams`, the request body (`json` /
+  `formData` / `text`, with its keys when destructured), the response status,
+  content type and object keys, and the status and message of every `HttpError`.
+  It answers "how do I call this endpoint?" without opening the handler.
+  - With `--json`, every entry gains a `spec`. The existing keys (`route`,
+    `file`, `dynamic`, `params`) are untouched, so current readers keep working.
+  - Everything is **inferred by reading the source** — like `check`, your code is
+    never imported or executed. Keys assembled at runtime, or input and output
+    hidden inside helper functions, will not show up: treat the output as a
+    **draft** of the spec, not a contract.
+
+## v0.2.2
+
+`vantage add skill` now scans for where the skills already are, and charts follow
+stylesheet swaps too. Both are backwards-compatible.
+
+### Changed
+
+- **`vantage add skill` looks for placed skills before copying** — it walks the
+  project for `<skill>/SKILL.md` and **skips anything already placed, reporting
+  where it is**. Under the root, under `.claude/skills/`, under
+  `.squadbase/skills/` — it makes no difference, so **re-running never creates a
+  second copy**, and an agent no longer has to know the candidate locations.
+  - `--force` rewrites the copies **where they were found** (an explicit `--dir`
+    still wins as the destination), so refreshing placed copies doesn't require
+    remembering the `--dir` you used originally.
+  - `vantage add skill` with no name is now a listing command: it prints the
+    bundled skills and where each one sits, and writes nothing.
+  - The bundled `AGENTS.md` drops its `ls`-the-usual-places routine in favour of
+    letting the CLI find them (a placed `AGENTS.md` is synced by `vantage upgrade`).
+
+### Fixed
+
+- **[`EChart`](parts/echart) could miss a CSS update** — token
+  changes were only watched through attributes on `<html>` / `<body>`, so a
+  change that **only rewrites the injected `<style>`** (editing `styles.css` with
+  the dev server running, applying a theme preset, …) left the chart painted in
+  the previous colours while the DOM tokens were already new. A reload fixed it,
+  which made it read as "the preset didn't apply". Stylesheet swaps are now
+  watched as well, and the chart repaints **only when the token values actually
+  change**.
+
 ## v0.2.1
 
 Charts now follow the theme tokens, and `Select` works out the value-to-label

package/docs/en/cli-reference.md

@@ -12,8 +12,8 @@
 | `vantage build` | Build client + optional server → `dist/` |
 | `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; `skill` takes `--dir` for the destination) |
+| `vantage routes` | Print the page + API URL map (`--pages` / `--apis` for one side only, `--detail` for each route's spec) |
+| `vantage add <kind> <name>` | Scaffold or place a `page` / `api` / `ui` / `block` / `skill` / `agents` (`--force` to overwrite; `skill` scans for copies already placed and skips them, `--dir` picks 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 |
@@ -51,6 +51,57 @@ vantage check ./demo/index.tsx # a file argument still checks its parent directo
 > `add`, `docs` and `search` use their positionals for their own arguments (`add page dashboard`,
 > `docs button`, `search date picker`) rather than a path, so they are excluded from this shortcut.
 
+## `vantage routes` — the URL map, with specs
+
+With no flags it prints the URL map of pages, layouts and API routes. Flags narrow it to **one
+side** or add the **static spec** of every route.
+
+| Flag | Meaning |
+|---|---|
+| `--pages` | Pages only (plus layout / 404 / error) |
+| `--apis` | API routes only |
+| `--detail` | Add each route's spec (pages: path params + `definePage` metadata; APIs: methods, request, response) |
+| `--json` | Machine-readable output (with `--detail`, every entry gains a `spec`) |
+
+`--pages` and `--apis` are not exclusive — passing both, or neither, prints everything.
+
+```bash
+vantage routes --pages           # pages only
+vantage routes --apis --detail   # APIs with their specs
+vantage routes --detail --json   # machine-readable, specs included
+```
+
+```text
+Pages
+  /sales/:customerId           sales/[customerId].tsx
+      title    Customer detail
+      params   :customerId
+
+API
+  /api/customers/:id           server/api/customers/[id].ts
+      GET
+        path     :id
+        response 200 application/json
+        error    404 "Customer ${params.id} not found"
+```
+
+`--detail` reads these shapes:
+
+| Line | Where it comes from |
+|---|---|
+| `title` / `nav` / `desc` | String literals in `definePage({ ... })` |
+| `params` | `[id]` / `[...rest]` in the filename |
+| Method | HTTP method exports such as `export function GET` |
+| `query` | `searchParams.get/getAll/has("x")` |
+| `body` | `request.json()` / `formData()` / `text()` (plus the keys of `const { a, b } = await request.json()`) |
+| `response` | Status, content type and object-literal keys of `Response.json(…)` / `json(…)` / `new Response(…)` |
+| `error` | `new HttpError(status, "message")` |
+
+> [!NOTE]
+> Like `check`, `--detail` is **static text analysis** — your code is never imported or executed. Keys
+> assembled at runtime, or input/output hidden inside helper functions, will not show up. Treat the
+> output as a draft of the spec, not a contract.
+
 ## `vantage docs` — read the docs from the CLI
 
 The content of this site is **bundled into the package**, so `vantage docs` prints it as plain

package/docs/en/parts/echart.md

@@ -27,8 +27,10 @@ import type { EChartsOption } from "@squadbase/vantage/components";
 
 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.
+`getComputedStyle` and passes them in as an ECharts theme. It watches for anything that can change
+those tokens and re-reads them when the values actually move — the `.dark` class going on and off,
+and **stylesheet swaps** too (editing `styles.css` with the dev server running, applying a theme
+preset, …).
 
 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**.

package/docs/ja/agent-skills.md

@@ -22,12 +22,29 @@ Skill のソースは `@squadbase/vantage` パッケージに同梱されてい
 対象アプリにコピーします。配置先は既定で**プロジェクトルート直下**で、`--dir` で変えられます。
 
 ```bash
-vantage add skill --all                       # 同梱スキルをすべて、ルート直下に配置
+vantage add skill                             # 一覧と配置場所を表示するだけ(何も書かない)
+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         # 既存を上書き
+vantage add skill --all --force               # 配置済みのコピーをその場で最新に更新
 ```
 
+**配置先は決め打ちではなく、走査して見つけます。** `add skill` はまずプロジェクト内
+(`node_modules` などを除く)を走査し、**既に配置されている skill はスキップして場所を報告**
+します。ルート直下でも `.claude/skills/` でも `.squadbase/skills/` でも同じで、**再実行しても
+二重に配置されません**。名前を省いて実行すると、一覧と配置場所だけが出ます:
+
+```text
+$ vantage add skill
+Bundled skills:
+  vantage-add-feature  .claude/skills/vantage-add-feature/
+  vantage-app          .claude/skills/vantage-app/
+  vantage-pitfalls     not placed
+```
+
+`--force` を付けると、**見つかった場所をそのまま**新しい内容で書き換えます(`--dir` を明示した
+ときは、そちらが配置先として優先されます)。
+
 `--dir` のパスはプロジェクトルートからの相対で解決されます（絶対パスも可）。Claude Code に
 自動認識させるなら `.claude/skills/` に置きます:
 
@@ -54,8 +71,8 @@ Skill の手順を読み込んで実行します。他のエージェントに
 
 - **source-of-truth はパッケージ内**にあります。Skill はフレームワークのバージョンと一緒に
   配布・更新されるため、`@squadbase/vantage` を上げれば最新の手順が手に入ります。配置済みの
-  コピーを更新したいときは、配置したときと同じ `--dir` を付けて
-  `vantage add skill --all --force` を実行します。
+  コピーを更新したいときは `vantage add skill --all --force` を実行します(置き場所は走査して
+  見つけるので、`--dir` を覚えておく必要はありません)。
 - **Squadbase テンプレートには配置済み**です。テンプレートから作ったアプリには、最初から
   `.claude/skills/` が入っています。手で作ったアプリには `vantage add skill` で足してください。
 

package/docs/ja/changelog.md

@@ -8,6 +8,56 @@ Vantage のリリースごとの変更点です。新しいものが上に来ま
 > まだプロトタイプ(**0.x**)です。0.x の間は **minor が実質のメジャー**扱いで、後方互換性の
 > ない変更は minor で入ることがあります。patch は後方互換の機能追加とバグ修正のみです。
 
+## v0.2.3
+
+`vantage routes` を片側だけに絞れるようになり、各ルートの仕様も出せるようになりました。
+すべて追加のみで後方互換です。
+
+### 追加
+
+- **`vantage routes` に `--pages` / `--apis` が付きました**(→ [CLI リファレンス](cli-reference))
+  ― ページ(+ layout / 404 / error)だけ、API ルートだけに絞れます。排他ではないので、両方
+  付けても、どちらも付けなくても今までどおり全部出ます。
+- **`--detail` で各ルートの静的な仕様を併記します** ― ページは `definePage` の
+  title / navLabel / description とパスパラメータ、API は**メソッドごと**に
+  `searchParams` で読むクエリキー・リクエストボディ(`json` / `formData` / `text`。
+  分割代入していればキーも)・レスポンスの status と content-type とオブジェクトのキー・
+  `HttpError` の status とメッセージが並びます。既存 API の呼び方を確かめるのに、
+  ハンドラを開かずに済みます。
+  - `--json` と併せると、各要素に `spec` が増えます。既存のキー(`route` / `file` /
+    `dynamic` / `params`)はそのままなので、今の読み手を壊しません。
+  - 取れるのは**ソースを読んだだけの推定**です(`check` と同じく、アプリのコードを import も
+    実行もしません)。実行時に組み立てるキーや、ヘルパー関数の中に隠れた入出力は出てきません
+    ― 仕様の**下書き**であって契約ではありません。
+
+## v0.2.2
+
+`vantage add skill` が配置先を走査するようになり、チャートがスタイルシートの差し替えにも
+追従するようになりました。どちらも後方互換です。
+
+### 変更
+
+- **`vantage add skill` が配置済みの Skill を探してからコピーします** ― プロジェクト内を
+  走査して `<skill>/SKILL.md` を探し、**既にあればスキップして場所を報告**します。ルート直下
+  でも `.claude/skills/` でも `.squadbase/skills/` でも同じなので、**再実行しても二重に配置
+  されません**。エージェント側が置き場所の候補を覚えておく必要がなくなります。
+  - `--force` は**見つかった場所をその場で**書き換えます(`--dir` を明示したときは、そちらが
+    配置先として優先されます)。配置済みコピーの更新に、前回と同じ `--dir` を思い出す必要は
+    ありません。
+  - 名前を省いた `vantage add skill` は、**一覧と配置場所を出すだけ**の表示コマンドに
+    なりました(何も書き込まず exit 0)。
+  - 同梱の `AGENTS.md` も更新し、置き場所を `ls` で当てにいく手順を「CLI が探す」に
+    置き換えました(配置済みの `AGENTS.md` は `vantage upgrade` で同期されます)。
+
+### 修正
+
+- **[`EChart`](parts/echart) が CSS の更新に追従しない場合がありました** ―
+  トークンの変化を `html` / `body` の属性でしか見ていなかったため、**注入済みの `<style>` の
+  中身だけが差し替わる経路**(開発中の `styles.css` の書き換え、テーマプリセットの適用など)で
+  DOM のトークンは新しいのにチャートだけ前の色のまま残っていました(リロードで直るため
+  「プリセットが効いていない」と誤解しやすい状態でした)。スタイルシートの差し替えも監視
+  対象になり、**トークンの値が実際に変わったときだけ**描き直します。
+
 ## v0.2.1
 
 チャートをテーマトークンに追従させ、`Select` の値とラベルの対応を Vantage 側で組むように

package/docs/ja/cli-reference.md

@@ -12,8 +12,8 @@
 | `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` で上書き、`skill` は `--dir` で配置先を指定） |
+| `vantage routes` | ページ + API の URL マップを表示（`--pages` / `--apis` で片側だけ、`--detail` で仕様つき） |
+| `vantage add <kind> <name>` | `page` / `api` / `ui` / `block` / `skill` / `agents` を雛形生成・配置（`--force` で上書き、`skill` は配置済みを走査してスキップ・`--dir` で配置先を指定） |
 | `vantage docs [name]` | 同梱のガイド + コンポーネントリファレンスを表示 |
 | `vantage search <query>` | 同じリファレンスを全文検索（自然言語 or `--regex`） |
 | `vantage doctor` | 環境・インストールの健全性を診断 |
@@ -51,6 +51,57 @@ vantage check ./demo/index.tsx # ファイル指定でも親ディレクトリ
 > `add`・`docs`・`search` はパス引数ではなく positional を自分の引数（`add page dashboard`・
 > `docs button`・`search 日付の選択`）に使うため、この短縮形の対象外です。
 
+## `vantage routes` — URL マップと仕様
+
+引数なしで、ページ・レイアウト・API の URL マップを出します。フラグで**片側だけ**に絞ったり、
+各ルートの**静的な仕様**を足したりできます。
+
+| フラグ | 意味 |
+|---|---|
+| `--pages` | ページ（+ layout / 404 / error）だけを表示 |
+| `--apis` | API ルートだけを表示 |
+| `--detail` | 各ルートの仕様を併記（ページはパスパラメータと `definePage` のメタ、API はメソッド・リクエスト・レスポンス） |
+| `--json` | 機械可読出力（`--detail` を付けると各要素に `spec` が付く） |
+
+`--pages` と `--apis` は排他ではありません。両方付けても、どちらも付けなくても全部出ます。
+
+```bash
+vantage routes --pages           # ページだけ
+vantage routes --apis --detail   # API を仕様つきで
+vantage routes --detail --json   # 仕様つきの機械可読出力
+```
+
+```text
+Pages
+  /sales/:customerId           sales/[customerId].tsx
+      title    Customer detail
+      params   :customerId
+
+API
+  /api/customers/:id           server/api/customers/[id].ts
+      GET
+        path     :id
+        response 200 application/json
+        error    404 "Customer ${params.id} not found"
+```
+
+`--detail` が拾うのは次の書き方です。
+
+| 行 | 何を読むか |
+|---|---|
+| `title` / `nav` / `desc` | `definePage({ ... })` の文字列リテラル |
+| `params` | ファイル名の `[id]` / `[...rest]` |
+| メソッド | `export function GET` などの HTTP メソッド export |
+| `query` | `searchParams.get/getAll/has("x")` |
+| `body` | `request.json()` / `formData()` / `text()`（`const { a, b } = await request.json()` ならキーも） |
+| `response` | `Response.json(…)` / `json(…)` / `new Response(…)` の status・content-type・オブジェクトリテラルのキー |
+| `error` | `new HttpError(status, "message")` |
+
+> [!NOTE]
+> `--detail` は `check` と同じく**ソースを読むだけの静的解析**で、アプリのコードを import も実行も
+> しません。実行時に組み立てるキーや、ヘルパー関数の中に隠れた入出力は出てきません（出力は
+> 「仕様の下書き」であって契約ではありません）。
+
 ## `vantage docs` — ドキュメントを CLI で読む
 
 このサイトの内容は**パッケージに同梱**されていて、`vantage docs` でそのまま読めます。ネット接続も

package/docs/ja/parts/echart.md

@@ -27,8 +27,9 @@ import type { EChartsOption } from "@squadbase/vantage/components";
 
 既定ではテーマの `--chart-1` 〜 `--chart-5` がそのまま系列色になります。ECharts は**描画中**には
 CSS 変数を読めませんが、`EChart` は init のタイミングで `getComputedStyle` からトークンの実値を
-解決し、ECharts のテーマとして渡しています。`.dark` の付け外しを見張っていて、切り替われば
-読み直します。
+解決し、ECharts のテーマとして渡しています。**トークンが変わりうる操作は見張っていて**、値が
+実際に変わったときだけ読み直します ― `.dark` の付け外しだけでなく、**スタイルシートの差し替え**
+(開発中に `styles.css` を書き換えた・テーマプリセットを当てた、など)も拾います。
 
 系列に固有の色を当てたいときは `option.color`(または `series[].itemStyle.color`)で上書きします。
 option はテーマより優先されるので、**軸・凡例・ツールチップのトークン追従は残ります**。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squadbase/vantage",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Data dashboard framework for Squadbase Editor. Vite-powered, config-free, one-file first.",
   "type": "module",
   "license": "MIT",

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

@@ -133,11 +133,21 @@ 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 check --json    # { ok, errorCount, warningCount, diagnostics[] }
+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` が出しうる診断コード(参考):

package/skills/vantage-app/SKILL.md

@@ -57,7 +57,7 @@ API export・env 誤用)はユーザーコードを実行しないので速く
 vantage routes     # 既にあるページと API の URL マップ
 vantage check      # いま壊れていないか(これから出すエラーと切り分ける)
 ls server/         # あれば fullstack モード。無ければ SPA
-ls .claude/skills  # 配置済みの skill(このファイルの仲間)
+vantage add skill  # 配置済みの skill(このファイルの仲間)と、その場所
 ```
 
 ## Step 2 — ルートを決める

package/skills/vantage-pitfalls/SKILL.md

@@ -37,8 +37,9 @@ Base UI の `SelectValue` は選択中の **value をそのまま描き**、`Sel
 
 ## チャート:`EChart` の配色はトークン追従。上書きは `option.color`
 
-系列色は `--chart-1..5`、軸・凡例・ツールチップは文字色/境界色のトークンから組まれ、
-ライト / ダークの切り替えにも追従する(init 時にトークンの実値を解決している)。
+系列色は `--chart-1..5`、軸・凡例・ツールチップは文字色/境界色のトークンから組まれる
+(init 時にトークンの実値を解決している)。ライト / ダークの切り替えにも、`styles.css` の
+書き換えやテーマプリセットの適用にも追従する。
 
 - **`theme` プロップを渡すと追従は完全に止まる。** 系列の色だけ変えたいなら `option.color` を
   使う ― option はテーマより優先されるので、軸まわりの追従は残る。

package/templates/AGENTS.md

@@ -309,8 +309,10 @@ pnpm preview   # 本番ビルドをローカル実行
 ```
 
 `vantage-manifest.json` の `mode`(`spa` / `fullstack`)は `server/` の有無から自動で決まる
-(手で書かない)。`vantage check --json` / `vantage routes --json` はエージェント向けの機械
-可読出力。`console.*` とランタイムエラーは開発ターミナルに `[browser:…]` として転送される。
+(手で書かない)。`vantage routes` は `--pages` / `--apis` で片側だけに絞れ、`--detail` を足すと
+各ルートの静的な仕様(ページ: パスパラメータ + `definePage` のメタ / API: メソッド・query・
+body・レスポンスの status と形)まで出る。`vantage check --json` / `vantage routes --json` は
+エージェント向けの機械可読出力。`console.*` とランタイムエラーは開発ターミナルに `[browser:…]` として転送される。
 
 ## さらに詳しく(同梱 Skill)
 
@@ -318,18 +320,20 @@ pnpm preview   # 本番ビルドをローカル実行
 - **`vantage-add-feature`** — 既存アプリに page / api / ui を 1 つ足す定型
 - **`vantage-pitfalls`** — Base UI(≠ Radix)の癖など、静かに壊れる落とし穴のリファレンス
 
-**まず、このアプリに配置済みかを探す。** 手順書の本体は SKILL.md というファイルで、置き場所は
-アプリによって違う:
+手順書の本体は `SKILL.md` というファイルで、置き場所はアプリによって違う(ルート直下・
+`.claude/skills/`・`.squadbase/skills/` など)。**探す必要はない ― CLI が探す:**
 
 ```bash
-ls .claude/skills          # よくある置き場所
-ls -d vantage-*            # ルート直下に置くのが既定
+vantage add skill          # 同梱 skill の一覧と、それぞれの配置場所
 ```
 
-見つかったらその `SKILL.md` を読む(`vantage add skill` を再実行する必要はない)。**無いときだけ**
-配置する ― 一覧は名前を省いて実行すると出る:
+配置済みならその場所が出るので、その `SKILL.md` を読む。`not placed` のものだけ配置する:
 
 ```bash
-vantage add skill                              # 同梱されている skill 名の一覧
-vantage add skill --all --dir .claude/skills   # 配置(--dir を省くとルート直下)
+vantage add skill --all                        # 配置済みはスキップ(場所を報告するだけ)
+vantage add skill --all --dir .claude/skills   # 置き場所を指定(既定はルート直下)
 ```
+
+`add skill` はプロジェクト内を走査してから動くので、**再実行しても二重に配置されない**。
+配置済みのコピーを新しいバージョンに更新したいときだけ `--force` を付ける(見つかった場所を
+そのまま書き換える)。