@squadbase/vantage 0.6.1-dev2.5f947f1 → 0.6.2-dev1.25d59a0

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

@@ -16,7 +16,7 @@ CLI は雛形を出すだけで、規約の遵守はこちらの責任。**追
 ```bash
 vantage add page  <name>    # ルートページ(.tsx)
 vantage add api   <name>    # server/api/**.ts の API モジュール
-vantage add ui    <name>    # registry から UI ソースを components/ui/ にコピー(src/ があればその中)
+vantage add ui    <name>    # /ui・/components の部品ソースを components/ui/ にコピー(src/ があればその中)
 vantage add block <name>    # registry からブロックを components/blocks/ にコピー(同上)
 ```
 
@@ -121,15 +121,17 @@ 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**するのが基本(コピー不要)。
+- **基本はコピーせず import する。** プリミティブは `@squadbase/vantage/ui` から、複合パーツと
+  チャートは `@squadbase/vantage/components` から**そのまま import**する。
   ```tsx
   import { Button, Loading, ErrorState } from "@squadbase/vantage/ui"
-  import { DashboardCardPreset, DataTablePreset, EChart } from "@squadbase/vantage/components"
+  import { DashboardCardPreset, DataTablePreset, LineChart } from "@squadbase/vantage/components"
   ```
+- `add ui` は**改造したいときだけ**使う。`/ui` と `/components` の部品はすべて kebab-case 名で
+  コピーできる(`add ui bar-chart`・`add ui combobox`)。未知の名前を渡すと利用可能な名前一覧を
+  出して失敗する。
+- グラフは型付きチャート(`LineChart`・`BarChart` など)から選ぶ。選び方は `agents/page.md` の
+  「グラフはまず型付きチャートで描く」。
 - **props は `vantage docs <name>` で確認してから書く**(`vantage docs button`・
   `vantage docs parts/data-table`。名前が分からなければ `vantage search <やりたいこと>` で
   探してから `vantage docs` に渡す)。

package/skills/vantage-design/SKILL.md

@@ -77,17 +77,27 @@ Vantage アプリの見た目は 2 つのファイルで決まる。
 
      ```css
      body {
-       font-family: "<Font>", ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+       font-family: "<Font>", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Hiragino Sans", "Hiragino Kaku Gothic ProN", "Noto Sans JP", Meiryo, ui-sans-serif, system-ui, sans-serif;
      }
      :root {
-       --slide-font-display: "<Font>", system-ui, -apple-system, "Hiragino Kaku Gothic ProN", "Hiragino Sans", "Yu Gothic", Meiryo, sans-serif;
+       --slide-font-display: "<Font>", -apple-system, BlinkMacSystemFont, "Segoe UI", "Hiragino Kaku Gothic ProN", "Hiragino Sans", "Yu Gothic", Meiryo, system-ui, sans-serif;
        --slide-font-body: var(--slide-font-display);
      }
      ```
 
+  欧文の Web フォントだけを先頭に足すときも、日本語の system face(`"Hiragino Sans"` 〜 `Meiryo`)は
+  必ず残す。消すとカナ・漢字がブラウザ任せのフォールバックになり、細く表示される。
+  `ui-sans-serif` / `system-ui` は日本語の face より**後ろ**に置く。日本語の Windows ではどちらも
+  Yu Gothic UI(UI のリサイズを避けるために字幅を詰めた書体)に解決され、カナがここで決まって
+  半角風に見える。macOS の Chrome は `-apple-system` を解釈しないので `BlinkMacSystemFont` も並べる。
+  既存アプリの `styles.css` に `ui-sans-serif, system-ui, …` が先頭にある、または `"Yu Gothic UI"` が
+  残っているときは、`body` の `font-family` を上の並びに直す(ほかの行は書き換えない)。
   日本語の Web フォントは face が 100 を超えるので原則使わない(pptx 書き出しも壊れる。
   `vantage-slide` の `references/tokens.md` 参照)。
 
+長い表(ダッシュボード): カードに `max-h-*` + `overflow-y-auto` の縦スクロール領域を作らず、
+ページング付きの `DataTablePreset`(`enablePagination`)にする(ホイールや End キーがページに届かなくなるため)。
+
 `DESIGN.md`: `references/format.md` の書式で書く。**色コードを書かない**(トークン名だけ)。
 150 行を超えない(超えると `vantage check` が `DESIGN_MD_TOO_LONG` を出す)。ロゴなどの素材は
 `public/brand/logo.svg` のように `public/` 配下のパスで「ブランド素材」行に書く。

package/skills/vantage-design/references/format.md

@@ -119,7 +119,7 @@ DESIGN.md — このアプリの「見た目の意図」を書くファイルで
 
 | 用途 | 指定 | 備考 |
 | --- | --- | --- |
-| 見出し・本文 | システムフォント(`body` の `font-family`) | Web フォントは使わない |
+| 見出し・本文 | 日本語を含むシステムフォント(`body` の `font-family`) | Web フォントは使わない |
 | 数字 | 同上 + `tabular-nums` | 桁がそろうように必ず付ける |
 | スライドの見出し | `--slide-font-display` | 既定は日本語を含むシステムフォント |
 | スライドの本文 | `--slide-font-body` | 既定は見出しと同じ |

package/skills/vantage-pitfalls/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vantage-pitfalls
-description: Vantage(@squadbase/vantage)アプリを書くときに静かに壊れる落とし穴のリファレンス。Base UI は Radix ではない(asChild 無し・render プロップ)、Select の value/label、クライアントから server/ を import しない、EChart の配色と高さ、動的パラメータの3綴り同期、PUBLIC_ env、HttpError、csv/xlsx ページの URL 衝突とサイズ上限、スライドの data-waitfor など。Vantage の UI コンポーネントやルーティングが思った通りに動かないとき、ビルドやスタイルが静かに欠落するときに参照する。
+description: Vantage(@squadbase/vantage)アプリを書くときに静かに壊れる落とし穴のリファレンス。Base UI は Radix ではない(asChild 無し・render プロップ)、Select の value/label、クライアントから server/ を import しない、チャートの色指定と EChart の配色・高さ、動的パラメータの3綴り同期、PUBLIC_ env、HttpError、csv/xlsx ページの URL 衝突とサイズ上限、スライドの data-waitfor など。Vantage の UI コンポーネントやルーティングが思った通りに動かないとき、ビルドやスタイルが静かに欠落するときに参照する。
 ---
 
 # Vantage アプリの落とし穴リファレンス
@@ -59,6 +59,10 @@ Base UI の `SelectValue` は選択中の **value をそのまま描き**、`Sel
 
 ## チャート:`EChart` の配色はトークン追従。上書きは `option.color`
 
+ふつうの推移・比較・構成比は型付きチャート(`LineChart`・`BarChart` など。→ `agents/page.md`)で
+描く。その `colors` に渡すのはトークン名 `"chart-1"`〜`"chart-5"` か CSS 色で、Tailwind クラス
+(`"bg-blue-500"` など)は効かない。以下は `EChart` を直接使うときの話。
+
 系列色は `--chart-1..5`、軸・凡例・ツールチップは文字色/境界色のトークンから組まれる
 (init 時にトークンの実値を解決している)。ライト / ダークの切り替えにも、`styles.css` の
 書き換えやテーマプリセットの適用にも追従する。

package/skills/vantage-slide/SKILL.md

@@ -49,6 +49,9 @@ export default function JuneDeck() {
 - **`.slide` を付けられるのはルートになるページモジュールだけ。** `_layout.slide.tsx` や
   `deck.slide.ts` は `INVALID_PAGE_VARIANT` エラーになります。
 - **`june.slide.tsx` と `june.tsx` は同じ URL** になるので `ROUTE_CONFLICT` です。どちらかを消すこと。
+- **ルート `/` がすでに他のページ（`index.tsx` など）で使われている場合、スライドは `index.slide.tsx` ではなく、タイトルから作った slug でファイル名を付ける。** `index.slide.tsx` と `index.tsx` は同じ `/` に解決して `ROUTE_CONFLICT` になる。
+  - 例: "Label check" → `src/label-check.slide.tsx` → `/label-check`
+  - 例: "Monthly Report" → `src/monthly-report.slide.tsx` → `/monthly-report`
 - **デッキファイル以外を作らない。** ヘルパーコンポーネントも定数も同じ `.slide.tsx` の中に書く。
   スライド専用のコンポーネントを `components/` に切り出すと、デッキ 1 本を読むのに 2 ファイル
   追わせることになります。
@@ -194,6 +197,17 @@ pptx 書き出しのために描き終わりを待たせる必要があります
 チャートに色をハードコードしないこと（`option.color` / `itemStyle.color` / `theme`）。
 `EChart` はテーマトークンに追従します。
 
+## 説明と図表を同じデータ時点へ揃える
+
+分析を共有するデッキでは、本文・数値・図表が**同じ対象期間と同じ取得時点の結果**を参照していることを
+確かめます。
+
+- 対象期間とデータ取得時点を、該当ページかフッターに短く表示する（例: 「2026年6月 / 7月1日 9:00 取得」）
+- **固定した説明文に対して図表だけが最新値へ変わる構成を避ける。** ライブ更新を意図するなら、本文の
+  数値・結論も同じ取得結果から導いて、図表と一緒に変わる構成にする
+- 同一時点の結果を保持・参照できない場合は、スナップショットとして保存できたとは報告しない。
+  必要な保持の仕組みと、現在保証できない範囲（例: 再表示すると図表だけ最新値になる）を伝える
+
 ## 実行時に無料で付いてくるもの
 
 - `src/june.slide.tsx` → `/june`。ナビ（`useRoutes()`）に通常のページと同格で並ぶ
@@ -244,6 +258,7 @@ pptx 書き出しのために描き終わりを待たせる必要があります
 - [ ] 繰り返す視覚要素が `array.map` ではなく明示的な `<Component />` になっている
 - [ ] ページ番号が `useSlideNumber()` から来ている（ハードコードしていない）
 - [ ] チャートが `data-waitfor="canvas"` で包まれている
+- [ ] 本文・数値・図表が同じ対象期間と取得時点の結果を参照し、その期間と時点が表示されている
 - [ ] `<Steps>` を使ったページが、`?p=` で直接開いても完成した絵として読める
 - [ ] トランジションを宣言したなら、全ページが 1 つの family に収まっている（→ `references/transitions.md`）
 - [ ] `definePage` の値がリテラルである
@@ -262,3 +277,5 @@ pptx 書き出しのために描き終わりを待たせる必要があります
 - ❌ スライド用のコンポーネントを別ファイルに切り出す
 - ❌ チャートに `data-waitfor="canvas"` を付け忘れる（pptx が白紙になる）
 - ❌ プリミティブを `references/*.md` を読まずに使う
+- ❌ 説明文を固定したまま図表だけライブデータで描く（再表示すると本文と図表の時点がずれる）
+- ❌ 同一時点の結果を保持できていないのに「スナップショットとして保存した」と報告する

package/templates/AGENTS.md

@@ -93,13 +93,25 @@ root/
 | `@squadbase/vantage/router` | `Link`・`Outlet`・`useParams`・`useSearch`・`useNavigate`・`redirect`・`notFound`・`useRoutes`・`useCurrentRoute`・`useSearchParam`・`useSearchState` |
 | `@squadbase/vantage/query` | `useApiQuery`・`useApiMutation`・`apiJson`・`apiFetch`・`apiUrl`・`ApiError`、ほか `useQuery`/`useMutation` など TanStack Query の再エクスポート |
 | `@squadbase/vantage/ui` | shadcn/ui(Base UI バリアント)プリミティブ(`Button`・`Loading`・`ErrorState`・`Empty` ほか) |
-| `@squadbase/vantage/components` | 複合パーツ(`PageShell`・`DashboardCardPreset`・`DataTablePreset`・`EChart` ほか) |
+| `@squadbase/vantage/components` | 複合パーツ(`PageShell`・`DashboardCardPreset`・`DataTablePreset`、KPI の `KpiCard`・`Delta`、型付きチャート `LineChart`・`BarChart`・`AreaChart`・`DonutChart`・`BarList` ほか、`EChart`、書式の `formatValue`) |
 | `@squadbase/vantage/table` | `FilePageView`・`TableViewer`(データファイルページの表ビューア) |
 | `@squadbase/vantage/slide` | `SlideDeck`・`Slide`・`Steps`・`Step`・`MorphElement`・`useSlideNumber`・`useIsActiveSlide`(スライド専用。1920×1080 の固定キャンバス) |
 | `@squadbase/vantage/doc` | `Document`(ドキュメント専用。中の素の HTML 要素に見出し・表などのスタイルが当たる) |
 | `@squadbase/vantage/markdown` | `MarkdownRenderer`(Shiki を隔離するための専用サブパス) |
 | `@squadbase/vantage/server` | `ApiContext`・`ApiHandler`・`HttpError`・`isHttpError`・`json`(server/ 側でのみ使う) |
 
+**KPI は `KpiCard`、増減は `Delta`(`comparison` と `polarity` を渡す)。** 向き・率・色は値から計算
+されるので手で渡さない。`TrendIndicator` は非推奨(`direction` を手で渡すので値と食い違いうる)。props は
+`vantage docs kpi-card` / `vantage docs delta` を引く。
+
+```tsx
+import { KpiCard, Delta } from "@squadbase/vantage/components";
+
+<KpiCard label="売上" value={48_200_000} format="currency"
+  comparison={{ previous: 42_900_000, vs: "prior-period" }} />
+<Delta value={0.021} comparison={{ previous: 0.026, vs: "prior-period" }} polarity="lower-is-better" />
+```
+
 ## モードは 2 つ、切り替えるのは `server/` の有無だけ
 
 `server/` ディレクトリがあれば **fullstack**、無ければ **SPA**。`vantage-manifest.json` の
@@ -137,6 +149,15 @@ root/
 | `.xlsx` ページ | `agents/xlsx.md` |
 | `.csv` ページ | `agents/csv.md` |
 
+**ページになるのは `.tsx` / `.jsx`(`.slide.tsx`・`.doc.tsx` を含む)・`.csv`・`.xlsx` だけ。**
+
+- `.xls`・`.xlsm`・`.xlsb`・`.ods`・`.tsv`・`.numbers`・`.parquet` はルートにならず、404 にもならない。
+  `vantage check` の `UNSUPPORTED_PAGE_FILE` 警告だけが知らせる。`.xlsx` / `.csv` に変換して置く
+- `.md`・`.json`・`.txt` は何も言わずに無視される。Markdown を見せたいときは `.tsx` のページで
+  `MarkdownRenderer`(`@squadbase/vantage/markdown`)に渡す
+- `.csv` / `.xlsx` はブラウザでパースする。25MB を超えるとそのページにエラーが出る
+  (`FILE_PAGE_TOO_LARGE` 警告)。20 万行を超えるシートは先頭 20 万行だけが表示される
+
 ## 環境変数
 
 - **クライアントで読めるのは `import.meta.env.PUBLIC_*` と `MODE`/`DEV`/`PROD`/`SSR`/`BASE_URL`

package/templates/agents/api.md

@@ -25,6 +25,11 @@ export async function GET({ params, env }: ApiContext) {
   エクスポートする。それ以外の名前は `INVALID_API_EXPORT` エラー。
 - 動的 API も `[id].ts` 記法: `server/api/customers/[id].ts` → `GET /api/customers/:id`。
   `params.id` で取り出す(`noUncheckedIndexedAccess` が効くので narrowing が要る)。
+- **`noUncheckedIndexedAccess` は配列・レコードの添字すべてに効く。** `arr[0]` も `obj[key]` も
+  `T | undefined` になる。最初に書く前に、添字アクセスと `useApiQuery` の `data` が
+  undefined を扱っているかを頭の中で型検査してから書く。上流の生の応答の値は
+  `Number(row.metricValues?.[0]?.value ?? "0")` のように `?.` と `??` で取り出す
+  (`!` で黙らせない)。
 - **クライアントに見せたいエラーは `HttpError(status, msg)` を throw する。** それ以外の throw は
   ログに記録され汎用の 500 に丸められる。
 - **シークレットは `ApiContext.env` にだけ届く**(クライアントには決して届かない)。
@@ -34,9 +39,12 @@ export async function GET({ params, env }: ApiContext) {
 
 ```tsx
 import { useApiQuery, useApiMutation } from "@squadbase/vantage/query"
+import { Loading, ErrorState } from "@squadbase/vantage/ui"
 
 const q = useApiQuery<Customer>(`/api/customers/${customerId}`)
+if (q.isPending) return <Loading />
 if (q.isError) return <ErrorState message={q.error.message} />  // HttpError のメッセージ
+q.data  // ここで初めて Customer(undefined ではない)
 
 // クエリ文字列は search で。undefined の項目は落ちる
 const rows = useApiQuery<Row[]>("/api/customers", { search: { segment } })
@@ -45,5 +53,26 @@ const rows = useApiQuery<Row[]>("/api/customers", { search: { segment } })
 const save = useApiMutation<Customer, Payload>("/api/customers", { method: "POST" })
 ```
 
+**`data` は、同じ結果オブジェクトで `isPending` と `isError` を判定したあとでしか
+narrowing されない。** 判定前や、配列の `.find` などでまとめた判定のあとでは `T | undefined` のまま。
+複数のクエリは 1 本ずつ判定してから `data` を使う(`data!` で黙らせない):
+
+```tsx
+const sessions = useApiQuery<SessionsDaily[]>("/api/sessions-daily")
+const metrics = useApiQuery<MetricsDaily[]>("/api/metrics-daily")
+
+if (sessions.isPending || metrics.isPending) return <Loading />
+if (sessions.isError) return <ErrorState message={sessions.error.message} />
+if (metrics.isError) return <ErrorState message={metrics.error.message} />
+// ここから sessions.data: SessionsDaily[] / metrics.data: MetricsDaily[]
+return <Chart sessions={sessions.data} metrics={metrics.data} />
+
+// NG: const failed = [sessions, metrics].find((q) => q.isError) のように配列でまとめて判定すると
+// 各 q.data は narrowing されず、`T[] | undefined` を T[] の props に渡して型エラーになる
+```
+
+カードごとに別々に読み込み中・エラーを出すなら、`data` を渡す側で `q.data ?? []` にするか、
+カードのコンポーネントの中で上と同じ判定をする。
+
 `ApiError` は `message`・`status`・`body`・`requestId` を持つ。hook が使えない場所では
 `apiJson(path, init)`、生の `Response` が要るときは `apiFetch`。

package/templates/agents/csv.md

@@ -27,6 +27,7 @@
   ```
 - 数式・グラフ・セル書式といった概念は csv には無いので、値がそのまま読めます。ブラウザで
   パースするので 25MB を超えるファイルはそのページにエラーが出ます —— 大きいデータは
-  `server/api/` から配って `DataTable` で描いてください
+  `server/api/` から配って `DataTable` で描いてください。20 万行を超えると先頭
+  20 万行だけが表示されます(残りはダウンロードして見る)
 - **ビューアの無い拡張子(`.tsv` など)はルートになりません。** `vantage check` の
   `UNSUPPORTED_PAGE_FILE` 警告が知らせます

package/templates/agents/doc.md

@@ -12,7 +12,7 @@
 
 ```tsx
 import { definePage } from "@squadbase/vantage"
-import { EChart } from "@squadbase/vantage/components"
+import { BarChart } from "@squadbase/vantage/components"
 import { Document } from "@squadbase/vantage/doc"
 
 export const page = definePage({ title: "6月度サマリー", navLabel: "6月度サマリー" })
@@ -23,7 +23,7 @@ export default function JuneSummary() {
       <p>6月の売上は <strong>5,250 万円</strong>で、目標を 5% 上回りました。</p>
       <h2>週次の売上</h2>
       <figure>
-        <EChart option={option} height={280} ariaLabel="6月の週次売上" />
+        <BarChart data={weekly} index="week" categories={["売上"]} height={280} ariaLabel="6月の週次売上" />
         <figcaption>第4週はキャンペーン初週</figcaption>
       </figure>
       <table>…</table>
@@ -42,7 +42,8 @@ export default function JuneSummary() {
   見た目を変えたいときはユーティリティを並べず、下の `--doc-*` を変えます。
 - **数値はコードに直接書く。** ドキュメントは書いた時点の内容を残すページです。
   `useApiQuery` などで読み込むと、開くたびに値が変わります。
-- **チャートは `EChart`(`@squadbase/vantage/components`)を文中に置く。** `figure` で囲めば
+- **チャートは型付きチャート(`BarChart`・`LineChart` など。`@squadbase/vantage/components`)を
+  文中に置く**(選び方は `agents/page.md` の「グラフはまず型付きチャートで描く」)。`figure` で囲めば
   `figcaption` がキャプションになります。
 - **PDF の保存ボタンは作らない。** `<Document>` が右下に PDF 保存のボタンを出し、印刷時は
   本文だけをライトの配色で出します。

package/templates/agents/page.md

@@ -26,8 +26,8 @@
   },
   "dependencies": {
     "@squadbase/vantage": "^0.5.0",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7"
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1"
   }
 }
 ```
@@ -164,17 +164,41 @@ refetchOnWindowFocus false・networkMode "always")。挙動を変えたいとき
 ## 組み込み UI / コンポーネントの入口
 
 - **プリミティブ**は `@squadbase/vantage/ui` から import する(`Button`・`Loading`・
-  `ErrorState`・`Empty`・`Select`・`Checkbox` ほか)。
+  `ErrorState`・`Empty`・`Select`・`Checkbox`・`RadioGroup`・`Field`・`Combobox`・`Pagination`・
+  `Avatar`・`Kbd`・`HoverCard`・`AlertDialog`・`Drawer`・`Toaster` + `toast.add()` ほか)。
 - **複合パーツ**は `@squadbase/vantage/components` から(`PageShell`・`DashboardCardPreset`・
-  `DataTablePreset`・`EChart` ほか)。
+  `DataTablePreset`・型付きチャート(下の「グラフ」)・`EChart` ほか)。
 - **どの名前が import 可能か / props の詳細は `vantage docs` で引く。** ガイドとコンポーネント
   リファレンスはパッケージに同梱されていて、オフラインでも読める(→ `AGENTS.md` の
   「ドキュメントを引く」)。**名前が分からないとき**はやりたいことで `vantage search` する
   (→ 同節)。
-- **UI は import して使うのが既定。取り出す(eject)必要はない。** `vantage add ui|block` は
-  ソースを手元にコピーして**改造したいとき専用**のコマンドで、取り出せるのは
-  `ui: data-table` と `block: sales-overview` の 2 つだけ。それ以外の名前は import 専用で
-  `add` の対象ではない(未知名で実行すると候補が一覧表示される)。
+- **UI は import して使うのが既定。取り出す(eject)必要はない。** `vantage add ui <name>` は
+  ソースを手元にコピーして**改造したいとき専用**のコマンド。`/ui` のプリミティブも
+  `/components` の複合パーツも全部取り出せる(名前は kebab-case: `add ui bar-chart`。
+  ブロックは `add block sales-overview`。未知名で実行すると候補が一覧表示される)。
+
+### 長い表はページングする(縦スクロール箱を作らない)
+
+- 行が多い表は `DataTablePreset`(または `DataTable`)に `enablePagination` を付けて**ページング**する
+  (既定は 10 行 / ページ。ページングは既定で無効なので、付け忘れると全行が並ぶ)。素の `<table>` を
+  手書きして全行を流し込まない。
+- カードの中に `max-h-*` + `overflow-y-auto` の**縦スクロール領域を作らない**。ホイールやキー
+  (End / Space)がその箱に吸われ、ページ全体がスクロールしなくなる。高さは内容に任せる。
+- 横に広い表の `overflow-x-auto` は構わない。`SheetGrid`(`.csv` / `.xlsx` のビューア)は
+  グリッドとして意図した入れ子スクロールなので対象外。
+
+### グラフはまず型付きチャートで描く
+
+- 推移は `LineChart` / `AreaChart`、比較は `BarChart`、構成比は `DonutChart`。`data`(行の配列)・
+  `index`(x 軸の列)・`categories`(系列の列)を渡すだけで、option は書かない
+  (`DonutChart` は `category` / `value`)。
+- 上位 N 件は `BarList`、判定帯や予算消化は `CategoryBar`、達成率は `ProgressCircle`、
+  日ごとの状態は `Tracker`。
+- `EChart` + `EChartsOption` は、二軸・散布図・ヒートマップ・注釈線など型付きチャートの props で
+  表せないときだけ使う。
+- 色は省略してテーマトークンに任せる。指定するなら `"chart-1"`〜`"chart-5"` か
+  `"var(--destructive)"` などの CSS 色。hex の直書きや Tailwind クラスは使わない。
+- 数値の書式(`¥`・`%`・桁区切り)は `valueFormatter` に渡す。
 
 ### ダークモードは opt-in
 

package/templates/agents/slide.md

@@ -11,6 +11,13 @@
 `src/monthly-report.slide.tsx` → `/monthly-report`。中身は `<SlideDeck>` を返す普通の React
 コンポーネントで、`definePage` もナビも通常のページと同じように効きます。
 
+**ファイル名の決め方:**
+
+- **ルート `/` がすでに他のページ（`index.tsx`など）で使われている場合は、スライドのタイトルから slug を作ってファイル名にする。** `index.slide.tsx` は `index.tsx` と同じ `/` に解決するので `ROUTE_CONFLICT` になる。
+  - 例: "Label check" というスライド → `src/label-check.slide.tsx` → `/label-check`
+  - 例: "Monthly Report" というスライド → `src/monthly-report.slide.tsx` → `/monthly-report`
+- 新規プロジェクトでまだ `/` が空いている場合のみ、`index.slide.tsx` を使ってよい。
+
 ```tsx
 import { Slide, SlideDeck } from "@squadbase/vantage/slide"
 
@@ -34,7 +41,12 @@ export default function Deck() {
 送れ、左のスライド一覧(サムネイル列)は `L` で開閉、`F` で全画面、ツールバーから pptx を
 書き出せます。**書き方の作法は同梱 Skill の
 `vantage-slide`** にあります(キャンバスの縦方向の予算、段階表示、トランジション、モーフ、
-pptx が壊れる条件)。
+pptx が壊れる条件、説明と図表のデータ時点の揃え方)。
+
+**分析を共有するデッキでは、本文・数値・図表を同じ対象期間と同じ取得時点の結果に揃え、その期間と
+時点を短く表示する。** 説明文を固定したまま図表だけが最新値へ変わる構成にしない(ライブ更新を
+意図するなら本文も同じ取得結果から導く)。同一時点の結果を保持できない場合は、スナップショットとして
+保存できたとは報告せず、必要な保持の仕組みと保証できない範囲を伝える。
 
 `.slide` を付けられるのはルートになるページモジュールだけで、`_layout.slide.tsx` などは
 `INVALID_PAGE_VARIANT` エラーになります。`june.slide.tsx` と `june.tsx` は同じ URL に解決するので

package/templates/agents/xlsx.md

@@ -28,6 +28,7 @@
 - **複数シートに対応**しています。シートのタブは下端に並び、切り替えて閲覧できます。
 - 数式・グラフ・セル書式は再現されません(値として読めれば十分、という設計)。ブラウザでパースするので
   25MB を超えるファイルはそのページにエラーが出ます —— 大きいデータは `server/api/` から配って
-  `DataTable` で描いてください
+  `DataTable` で描いてください。20 万行を超えると先頭
+  20 万行だけが表示されます(残りはダウンロードして見る)
 - **ビューアの無い拡張子(`.xls`・`.ods` など)はルートになりません。** `vantage check` の
   `UNSUPPORTED_PAGE_FILE` 警告が知らせます