@squadbase/vantage 0.6.1 → 0.6.2-dev1.0017a4d

package/skills/vantage-slide/SKILL.md

@@ -43,20 +43,36 @@ export default function JuneDeck() {
 
 - **1 ファイル = 1 デッキ = 1 ルート。** `export default` は `<SlideDeck>` を返す React コンポーネント
   （通常のページと同じ契約なので、`vantage check` も `vantage routes` も特別扱いをしません）。
-- **スライドは `<SlideDeck>` の直下の `<Slide>`。** 深くネストした `<Slide>` は拾われません。
-- `definePage` の `title` / `navLabel` はビルド時に静的抽出されるので**リテラルで書く**（変数・
-  テンプレート補間は不可）。ナビの表示名はこれで決まります。
+- **ファイル形式の MUST / SHOULD（`<Slide>` は `<SlideDeck>` の直下、`<Step>` は `<Steps>` の直下、
+  `definePage` はリテラル など）は `agents/slide.md` と `agents/page.md` が正本**です。ここでは繰り返しません。
 - **`.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 ファイル
   追わせることになります。
 
+## まず block を探す
+
+1 枚分の中身は、手で組む前に `@squadbase/vantage/slide` の block（`SlideCover` `SlideExecSummary`
+`SlideKpiHero` `SlideKpiGrid` `SlideChartInsight` `SlideScorecardTable` `SlideNextActions`）に
+合うものがないか探します。`<Slide>` の**中**に置き、props は `vantage docs <name>`（例:
+`vantage docs slide-cover`）で引く。一覧は `agents/slide.md` が正本です。
+- props は block 間で共通: `value: number | null` + `format`（上書きだけ `display`）、`delta: { value, format? }` + `betterWhen` + `comparisonLabel`、`target: number`、`source` は文字列、`asOf` は日付だけ（「時点」は block が付ける）。
+
+- block は `@squadbase/vantage/slide` から import する。**新しい import 元は増えない**（下の
+  「import してよいもの」と矛盾しない）。`vantage add` でコピーするものでもない。
+- block が合わない**1 枚だけ**を、この下の規約で手書きする。デッキ全体を手書きに切り替えない。
+- デッキ以外のファイルは作らない。block を使っても、デッキは 1 ファイルのままで、独自の
+  ヘルパーコンポーネントは同じ `.slide.tsx` に書く。
+
 ## import してよいもの
 
 - `@squadbase/vantage/slide` — `SlideDeck` `Slide` `Steps` `Step` `MorphElement` `useSlideNumber`
-  `useIsActiveSlide` `SlideCanvas` と、その型
+  `useIsActiveSlide` `SlideCanvas`、1 枚分の block（`SlideCover` ほか上の 7 つ）と、その型
 - `@squadbase/vantage` — `definePage`
 - `@squadbase/vantage/components` の `EChart` — **チャートを載せるときはこれ**（→「チャート」）
 - `lucide-react` のアイコン
@@ -74,21 +90,25 @@ export default function JuneDeck() {
 - 各スライドのルート要素はキャンバスを埋める（`width: "100%"; height: "100%"`）
 - インライン `style={{ … }}` を使う。読み込んだ CSS はグローバルです
 
-### タイプスケール（ここから始めて調整する）
+以下の値がスライドの規約です。ヒーローと本文は `var(--slide-size-hero)` /
+`var(--slide-size-body)` としても読めます（→ `references/tokens.md`）。
+
+### タイプスケール
 
 | 要素 | サイズ |
 | --- | --- |
-| ヒーロータイトル | 140–200px |
-| セクション見出し | 80–120px |
-| ページ見出し | 56–80px |
-| 本文 | 32–44px |
-| キャプション / ラベル | 22–28px |
+| ヒーロータイトル | 168px |
+| セクション見出し | 88px |
+| ページ見出し | 64px |
+| 本文 | 36px |
+| キャプション / ラベル | 24px |
 
-### 余白
+### 余白とグリッド
 
-- コンテンツの padding: キャンバス端から **100–160px**。文字を端に触れさせない
-- line-height: 見出し 1.2、本文 1.5–1.7
-- 要素間: 32–64px
+- セーフエリア: キャンバス端から **左右 160px・上下 120px**。中身はこの内側の **1600 × 840px** に置き、文字を端に触れさせない
+- グリッド: 内容幅 1600px を **12 列**（列幅 104px・溝 32px）に割る
+- line-height: 見出し 1.2、本文 1.6
+- 要素間: 32 / 48 / 64px のどれか
 
 ### 縦方向の予算 — 中身は 1080px に収まらなければならない
 
@@ -96,33 +116,32 @@ export default function JuneDeck() {
 計算して収まることを確かめること。**これがスライドが壊れる原因の第 1 位**で、確かめない限り
 溢れていると思ってください。
 
-**使える高さ** = `1080 − 上 padding − 下 padding`。上下 120px なら **840px**、160px なら **760px**。
-先に padding を決めて、その予算の中で設計します。
+**使える高さ** = `1080 − 上下のセーフエリア（120px × 2）` = **840px**。この予算の中で設計します。
 
 **要素の高さ** = `文字サイズ × line-height × 行数`。2 行に折り返す箇条書きは 2 行と数えます。
-次の要素を足す前に、その下の gap（32–64px）を加算してください。
+次の要素を足す前に、その下の gap（32 / 48 / 64px）を加算してください。
 
-**計算例 — 本文 1 枚、padding 120px（予算 840px）:**
+**計算例 — 本文 1 枚（予算 840px）:**
 
 | 要素 | 高さ |
 | --- | --- |
-| 見出し: 80px × 1.2 × 1 行 | 96px |
+| ページ見出し: 64px × 1.2 × 1 行 | 76.8px |
 | gap | 64px |
-| 本文: 40px × 1.6 × 3 行 | 192px |
+| 本文: 36px × 1.6 × 3 行 | 172.8px |
 | gap | 48px |
-| 箇条書き 5 行: 40px × 1.6 × 1 行 | 320px（5 × 64px） |
-| 箇条書き間の gap 4 つ: 24px | 96px |
-| **合計** | **816px ✅ 840 に収まる** |
+| 箇条書き 5 行: 36px × 1.6 × 1 行 | 288px（5 × 57.6px） |
+| 箇条書き間の gap 4 つ: 32px | 128px |
+| **合計** | **777.6px ✅ 840 に収まる** |
 
-見出しを 120px にするか箇条書きを 6 つにすると溢れます。**書く前に毎ページこの検算をすること。**
+箇条書きを 6 つにすると 867.2px で溢れます。**書く前に毎ページこの検算をすること。**
 
 **ページ単位の規則:**
 
 - 「見出し + 本文」か「見出し + 5 つ以内の短い箇条書き」のどちらか。両方は載せない
 - 箇条書きは選んだ文字サイズで 1 行に収まること。折り返すなら短くするか別ページに割る
-- ヒーロータイトル（140–200px）はタイトル + サブタイトル 1 行 + アイブロウまで。それ以外は載せない
-- セクション見出し（80–120px）のページにはほとんど何も足さない
-- 収めるために padding を上げる・スケールの下限より小さい文字にする・本文の line-height を 1.4 未満に
+- ヒーロータイトル（168px）はタイトル + サブタイトル 1 行 + アイブロウまで。それ以外は載せない
+- セクション見出し（88px）のページにはほとんど何も足さない
+- 収めるためにセーフエリアを削る・タイプスケールより小さい文字にする・本文の line-height を 1.6 未満に
   詰める、をやりたくなったら**ページを 2 枚に割る**。予算が厳しいときは分割が常に正解
 
 **`overflow: auto/scroll`・負のマージン・transform で溢れを隠さないこと。** キャンバスは固定で、
@@ -136,7 +155,7 @@ export default function JuneDeck() {
   それ以外はプレーンな const にする（→ `references/tokens.md`）
 - **書体** — ディスプレイ 1 + 本文 1。指定がなければシステムスタック。見出しは太く（800–900）、
   本文は通常（400–500）
-- **レイアウトグリッド** — padding を 1 つ決めて（例: 120px）貫く。左揃えは編集的、中央揃えは儀礼的
+- **レイアウトグリッド** — セーフエリアと 12 列グリッド（→「余白とグリッド」）を全ページで貫く。左揃えは編集的、中央揃えは儀礼的
 - **美学のコミットメント** — 1 つ選ぶ: ミニマル / マキシマル / エディトリアル / レトロ /
   ブルータリスト / ソフト・パステル / ネオン / 紙・印刷。混ぜない
 
@@ -149,12 +168,12 @@ export default function JuneDeck() {
 // ✅ 各カードが独自の JSX ノードを持つ
 const Card = ({ label, value }: { label: string; value: string }) => (
   <div style={{ flex: 1 }}>
-    <div style={{ fontSize: 28, opacity: 0.6 }}>{label}</div>
-    <div style={{ fontSize: 120, fontWeight: 800 }}>{value}</div>
+    <div style={{ fontSize: 24, opacity: 0.6 }}>{label}</div>
+    <div style={{ fontSize: 88, fontWeight: 800 }}>{value}</div>
   </div>
 )
 
-<div style={{ display: "flex", gap: 96 }}>
+<div style={{ display: "flex", gap: 64 }}>
   <Card label="売上" value="¥5.2億" />
   <Card label="解約率" value="1.4%" />
 </div>
@@ -166,6 +185,8 @@ const Card = ({ label, value }: { label: string; value: string }) => (
 
 これは**視覚要素が繰り返すとき**の話で、データが繰り返すときの話ではありません。純粋な
 テキストの箇条書き（`<ul><li>`）は各 `<li>` が既に独立した JSX ノードなので、そのままで正しい。
+`<SlideDeck>` の直下に `<Slide>` を配列で渡すこと自体はファイル形式として可能です（`agents/slide.md`）が、
+1 枚ごとの文言・図を変えるスライドは 1 枚ずつ書きます。
 
 ## ページ番号
 
@@ -194,6 +215,17 @@ pptx 書き出しのために描き終わりを待たせる必要があります
 チャートに色をハードコードしないこと（`option.color` / `itemStyle.color` / `theme`）。
 `EChart` はテーマトークンに追従します。
 
+## 説明と図表を同じデータ時点へ揃える
+
+分析を共有するデッキでは、本文・数値・図表が**同じ対象期間と同じ取得時点の結果**を参照していることを
+確かめます。
+
+- 対象期間とデータ取得時点を、該当ページかフッターに短く表示する（例: 「2026年6月 / 7月1日 9:00 取得」）
+- **固定した説明文に対して図表だけが最新値へ変わる構成を避ける。** ライブ更新を意図するなら、本文の
+  数値・結論も同じ取得結果から導いて、図表と一緒に変わる構成にする
+- 同一時点の結果を保持・参照できない場合は、スナップショットとして保存できたとは報告しない。
+  必要な保持の仕組みと、現在保証できない範囲（例: 再表示すると図表だけ最新値になる）を伝える
+
 ## 実行時に無料で付いてくるもの
 
 - `src/june.slide.tsx` → `/june`。ナビ（`useRoutes()`）に通常のページと同格で並ぶ
@@ -236,14 +268,15 @@ pptx 書き出しのために描き終わりを待たせる必要があります
 - [ ] `export default` が `<SlideDeck>` を返している
 - [ ] `<Slide>` が `<SlideDeck>` の直下にある
 - [ ] 各スライドのルート要素が `100% × 100%` を埋めている
-- [ ] 文字が padding の内側にある（端に触れていない）
-- [ ] **全ページで（文字サイズ × line-height × 行数）+ gap + padding×2 ≤ 1080px。** 際どいなら分割
+- [ ] 文字がセーフエリア（左右 160px・上下 120px）の内側にある
+- [ ] **全ページで（文字サイズ × line-height × 行数）+ gap ≤ 840px。** 際どいなら分割
 - [ ] 箇条書きが 2 行目に折り返していない
 - [ ] 配色とタイプスケールが全ページで一貫している
 - [ ] 1 ページ 1 メッセージ
 - [ ] 繰り返す視覚要素が `array.map` ではなく明示的な `<Component />` になっている
 - [ ] ページ番号が `useSlideNumber()` から来ている（ハードコードしていない）
 - [ ] チャートが `data-waitfor="canvas"` で包まれている
+- [ ] 本文・数値・図表が同じ対象期間と取得時点の結果を参照し、その期間と時点が表示されている
 - [ ] `<Steps>` を使ったページが、`?p=` で直接開いても完成した絵として読める
 - [ ] トランジションを宣言したなら、全ページが 1 つの family に収まっている（→ `references/transitions.md`）
 - [ ] `definePage` の値がリテラルである
@@ -252,13 +285,15 @@ pptx 書き出しのために描き終わりを待たせる必要があります
 ## アンチパターン
 
 - ❌ 文字の壁。1 ページ 40 語を超えたら分割する
-- ❌ キャンバス全面を本文で使う。padding 100–160px を守る
+- ❌ キャンバス全面を本文で使う。セーフエリア（左右 160px・上下 120px）を守る
 - ❌ 縦に 1080px を溢れさせる。切れた中身は見えない — 分割する
 - ❌ `overflow: auto` / `scroll` / `hidden` で溢れを「隠す」。バグを隠しただけ
-- ❌ 詰め込むためにスケールの下限より小さい文字にする・padding を 100px 未満にする
-- ❌ 本文 28px 未満。プロジェクタで読めない
+- ❌ 詰め込むためにタイプスケールより小さい文字にする・セーフエリアを削る
+- ❌ 本文を 36px 未満にする。プロジェクタで読めない
 - ❌ `@squadbase/vantage/ui` のプリミティブをスライドに置く（縮小されて読めなくなる）
 - ❌ 依存を追加する。使えるのは `@squadbase/vantage/*` と `lucide-react` と標準 Web API だけ
 - ❌ スライド用のコンポーネントを別ファイルに切り出す
 - ❌ チャートに `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/slide` | `SlideDeck`・`Slide`・`Steps`・`Step`・`MorphElement`・`useSlideNumber`・`useIsActiveSlide`、1 枚分の block `SlideCover`・`SlideExecSummary`・`SlideKpiHero`・`SlideKpiGrid`・`SlideChartInsight`・`SlideScorecardTable`・`SlideNextActions`(スライド専用。1920×1080 の固定キャンバス) |
+| `@squadbase/vantage/doc` | `Document`、ドキュメント用の block `DocReportHeader`・`DocExecutiveSummary`・`DocKpiScorecard`・`DocFigure`・`DocDataTable`・`DocCallout`・`DocKeyFindings`・`DocActionItems`(ドキュメント専用。中の素の 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,9 +12,16 @@
 
 ```tsx
 import { definePage } from "@squadbase/vantage"
-import { EChart } from "@squadbase/vantage/components"
+import { BarChart } from "@squadbase/vantage/components"
 import { Document } from "@squadbase/vantage/doc"
 
+const weekly = [
+  { week: "第1週", 売上: 1180 },
+  { week: "第2週", 売上: 1240 },
+  { week: "第3週", 売上: 1210 },
+  { week: "第4週", 売上: 1620 },
+]
+
 export const page = definePage({ title: "6月度サマリー", navLabel: "6月度サマリー" })
 export default function JuneSummary() {
   return (
@@ -23,7 +30,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,11 +49,35 @@ export default function JuneSummary() {
   見た目を変えたいときはユーティリティを並べず、下の `--doc-*` を変えます。
 - **数値はコードに直接書く。** ドキュメントは書いた時点の内容を残すページです。
   `useApiQuery` などで読み込むと、開くたびに値が変わります。
-- **チャートは `EChart`(`@squadbase/vantage/components`)を文中に置く。** `figure` で囲めば
+- **チャートは型付きチャート(`BarChart`・`LineChart` など。`@squadbase/vantage/components`)を
+  文中に置く**(選び方は `agents/page.md` の「グラフはまず型付きチャートで描く」)。`figure` で囲めば
   `figcaption` がキャプションになります。
+- **PDF の保存ボタンは作らない。** `<Document>` が右下に PDF 保存のボタンを出し、印刷時は
+  本文だけをライトの配色で出します。
 - **ページ全体を包むのは `<Document>` だけ。** `PageShell` などのダッシュボード用の枠で包まない
   (本文の幅と余白は `<Document>` が決めます)。
 
+## まず block を探す
+
+1 節分の中身は、手で組む前に `@squadbase/vantage/doc` の block から探します(`<Document>` の直下に
+並べる。多くは 1 block = 1 節。`DocCallout`・`DocFigure`・`DocDataTable` は節ではなく、節の中(本文の間)に置く部品)。props は `vantage docs <name>`(例: `vantage docs doc-kpi-scorecard`)で引く。
+
+| block | 用途 |
+| --- | --- |
+| `DocReportHeader` | レポートの冒頭(タイトル・サブタイトル・対象期間・データ時点・作成者・出典) |
+| `DocExecutiveSummary` | 結論を先に述べる要約の節 |
+| `DocKpiScorecard` | 主要指標をまとめたスコアカード |
+| `DocFigure` | 図表 1 つとキャプション(チャートは children で渡す) |
+| `DocDataTable` | 素の `table` による表 |
+| `DocCallout` | 補足・示唆・注意・決定の囲み(`kind`: `note` / `insight` / `warning` / `decision`) |
+| `DocKeyFindings` | 主要な発見の箇条 |
+| `DocActionItems` | 次のアクション(担当・期限つき) |
+
+**props の渡し方は block 間で共通。** 数値は `value: number | null` と `format`(整形は block がする。表示を上書きするときだけ `display`。`null` は「—」)。前期比などは `delta: { value, format? }` と `comparisonLabel`(例 `"前年同期比"`)、良し悪しは指標ごとの `betterWhen`(`"up"` が既定、コストなど下がるほど良いものは `"down"`。向きは block が符号から出す)。目標は `target: number`。出典は `source`、時点は `asOf` に**日付だけ**(例 `"2026-09-30"`。「データ時点」は block が付けるので「時点」を書かない)。時系列は、単一系列なら `{ x, y }[]`(`trend`)。
+
+block が合わない**1 節だけ**を素の HTML 要素で手で書く。import 元は `@squadbase/vantage/doc` のままで、
+block のための新しい import 元はありません。本文は文字列か ReactNode で渡し、Markdown 文字列は渡さない。
+
 ## 見た目を変える
 
 配色・書体・本文の幅は `--doc-*` の CSS 変数です。既定値はアプリのトークンへの別名なので、
@@ -71,3 +102,20 @@ export default function JuneSummary() {
 `.doc` を付けられるのはルートになるページモジュールだけで、`_layout.doc.tsx` などは
 `INVALID_PAGE_VARIANT` エラーになります。`june.doc.tsx` と `june.tsx` は同じ URL に解決するので
 `ROUTE_CONFLICT` です。
+
+## ファイル形式の規約
+
+置き場所・URL・default export・`definePage` の書き方は全ページ共通(`agents/page.md` の
+「ページファイルの規約」)。ここではドキュメント固有のものだけを挙げます。
+
+**MUST**
+
+- ファイル名は `<name>.doc.tsx`(`.jsx` も可)。サフィックスは小文字で 1 つだけ。`.doc.mdx` は
+  `INVALID_PAGE_VARIANT`、`.DOC.tsx`・二重サフィックスは黙って通常ページになる
+- default export は `<Document>` をルートに返す。フレームワークは包まない
+- ドキュメントの部品は `@squadbase/vantage/doc` から import する
+
+**SHOULD**
+
+- `PageShell` で包まない・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"
   }
 }
 ```
@@ -71,6 +71,7 @@ URL になる。各ページは**デフォルトエクスポートの React コ
 | `_404.tsx` | Not Found ページ |
 | `_error.tsx` | ルートが throw したときのエラーページ |
 | `monthly-report.slide.tsx` | `/monthly-report`(スライドデッキ。詳しくは `agents/slide.md`) |
+| `june-summary.doc.tsx` | `/june-summary`(ドキュメント。詳しくは `agents/doc.md`) |
 | `sales-export.csv` | `/sales-export`(詳しくは `agents/csv.md`) |
 | `data/june.xlsx` | `/data/june`(詳しくは `agents/xlsx.md`) |
 
@@ -89,6 +90,26 @@ export default function MonthlyAnalysis() {
 }
 ```
 
+### ページファイルの規約(`.tsx` / `.slide.tsx` / `.doc.tsx` 共通)
+
+**MUST**
+
+- ページルートの配下に置く。`components/` などの走査対象外のディレクトリに置いたファイルはページに
+  ならず、エラーも出ない。`_` 始まりの名前は予約名(`_layout` / `_404` / `_error`)にだけ使う
+  (それ以外の `_` 始まりはページにならない。予約名にサフィックスを付けると `INVALID_PAGE_VARIANT`)
+- URL はサフィックスと拡張子を除いたパスで決まる。同じ URL になる別ファイル(`june.tsx` /
+  `june.slide.tsx` / `june.doc.tsx` / `june.csv`)を並べない(`ROUTE_CONFLICT`)。テンプレートの
+  未編集の `index.tsx` だけは例外で、`index.slide.tsx` / `index.doc.tsx` が `/` を取れる
+- default export は React の関数コンポーネント(無いと `MISSING_DEFAULT_EXPORT`。関数かどうかは
+  検査されない)
+- `definePage({ ... })` にはオブジェクトリテラルを直接渡し、`title` / `description` / `navLabel` は
+  文字列リテラルで書く。ビルド時に静的抽出されるので、変数・関数呼び出し・spread・shorthand・
+  `${}` を含むテンプレート文字列は**エラーにならず黙ってメタなし**になる
+
+**SHOULD**
+
+- `definePage` に `title` と `navLabel` を書く(ナビの表示名とブラウザのタブ名になる)
+
 ### ナビはルート一覧から組む
 
 `useRoutes()` がページルート一覧(スキャン順)を返すので、リンク配列を手で持たない。
@@ -109,7 +130,7 @@ routes.map((r) => (
 ```
 
 `RouteInfo`: `path`(`/sales/:id`)・`to`(`/sales/$id`)・`params`・`dynamic`・`index`・`label`・
-`title`・`description`・`navLabel`・`kind`(`"module"` | `"file"`)・`variant`(`"slide"`)。
+`title`・`description`・`navLabel`・`kind`(`"module"` | `"file"`)・`variant`(`"slide"` | `"doc"`)。
 後ろの 2 つで、ナビをダッシュボード / スライド / データに分けたりアイコンを変えたりできます。
 
 ### フィルタ状態は URL に置く
@@ -164,17 +185,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,7 +11,15 @@
 `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 { definePage } from "@squadbase/vantage"
 import { Slide, SlideDeck } from "@squadbase/vantage/slide"
 
 export const page = definePage({ title: "6月度レビュー", navLabel: "6月度" })
@@ -27,15 +35,72 @@ export default function Deck() {
 
 **`<Slide>` は `<SlideDeck>` の直接の子に書く。** `SlideDeck` は直下の `<Slide>` 要素だけを数えるので、
 `<Slide>` を自作コンポーネント(`<Slide1 />` など)や Fragment で包むと 1 枚も数えられず「1 / 0」に
-なります(`{items.map((x) => <Slide key={x.id}>…</Slide>)}` のような配列は可)。共通の部品は
-`<Slide>` の**中**に置くコンポーネントとして切り出します(`<Slide><CoverPage /></Slide>`)。
+なります(`{items.map((x) => <Slide key={x.id}>…</Slide>)}` のような配列はファイル形式としては可。
+1 枚の中で視覚要素を `map` で量産しない方針は `vantage-slide` skill の「繰り返す要素は `map` ではなく
+コンポーネント」)。共通の部品は `<Slide>` の**中**に置くコンポーネントとして切り出します
+(`<Slide><CoverPage /></Slide>`)。
 
 1920×1080 の固定キャンバスに絶対 px で書き、画面サイズに合わせて縮小されます。キー / クリックで
 送れ、左のスライド一覧(サムネイル列)は `L` で開閉、`F` で全画面、ツールバーから pptx を
 書き出せます。**書き方の作法は同梱 Skill の
 `vantage-slide`** にあります(キャンバスの縦方向の予算、段階表示、トランジション、モーフ、
-pptx が壊れる条件)。
+pptx が壊れる条件、説明と図表のデータ時点の揃え方)。
+
+**分析を共有するデッキでは、本文・数値・図表を同じ対象期間と同じ取得時点の結果に揃え、その期間と
+時点を短く表示する。** 説明文を固定したまま図表だけが最新値へ変わる構成にしない(ライブ更新を
+意図するなら本文も同じ取得結果から導く)。同一時点の結果を保持できない場合は、スナップショットとして
+保存できたとは報告せず、必要な保持の仕組みと保証できない範囲を伝える。
 
 `.slide` を付けられるのはルートになるページモジュールだけで、`_layout.slide.tsx` などは
 `INVALID_PAGE_VARIANT` エラーになります。`june.slide.tsx` と `june.tsx` は同じ URL に解決するので
 `ROUTE_CONFLICT` です。
+
+## まず block を探す
+
+1 枚分の中身は、手で組む前に `@squadbase/vantage/slide` の block から探します(`<Slide>` の**中**に
+置く。ルートは 100% で、`<Slide>` 自体は持たない)。props は `vantage docs <name>`(例:
+`vantage docs slide-kpi-hero`)で引く。
+
+| block | 用途 |
+| --- | --- |
+| `SlideCover` | 表紙(タイトル・サブタイトル・期間) |
+| `SlideExecSummary` | 結論を先に述べるエグゼクティブサマリー |
+| `SlideKpiHero` | 主要な KPI 1 つを大きく見せる |
+| `SlideKpiGrid` | 複数の KPI を並べる |
+| `SlideChartInsight` | チャート 1 つと、そこから読み取れること |
+| `SlideScorecardTable` | 指標と目標・達成度を表にしたスコアカード |
+| `SlideNextActions` | 次のアクション(担当・期限つき) |
+
+```tsx
+import { Slide, SlideDeck, SlideCover, SlideExecSummary } from "@squadbase/vantage/slide"
+// <SlideDeck><Slide><SlideCover … /></Slide><Slide><SlideExecSummary … /></Slide></SlideDeck>
+```
+
+**props の渡し方は block 間で共通。** 数値は `value: number | null` と `format`(整形は block がする。表示を上書きするときだけ `display`。`null` は「—」)。前期比などは `delta: { value, format? }` と `comparisonLabel`(例 `"前年同期比"`)、良し悪しは指標ごとの `betterWhen`(`"up"` が既定、コストなど下がるほど良いものは `"down"`。向きは block が符号から出す)。目標は `target: number`。出典は `source`(文字列)、時点は `asOf` に**日付だけ**(例 `"2026-09-30"`。「時点」は block が付けるので書かない)。時系列は、単一系列なら `{ x, y }[]`(kpi-hero・scorecard の `trend`)、複数系列なら `{ categories, series }`(chart-insight の `chart`)。
+
+block が合わない**1 枚だけ**を手で書く(デッキ全体を手書きに切り替えない)。import 元は
+`@squadbase/vantage/slide` のままで、block のための新しい import 元はありません。
+
+## ファイル形式の規約
+
+置き場所・URL・default export・`definePage` の書き方は全ページ共通(`agents/page.md` の
+「ページファイルの規約」)。ここではスライド固有のものだけを挙げます。**中身の値(キャンバス・
+セーフエリア・グリッド・文字サイズ・余白)は `vantage-slide` skill を参照。**
+
+**MUST**(破ると黙って壊れるものが多い。`vantage check` が拾うのは名前の誤りだけ)
+
+- ファイル名は `<name>.slide.tsx`(`.jsx` も可)。サフィックスは小文字で 1 つだけ。`.slide.ts` は
+  `INVALID_PAGE_VARIANT`、`.SLIDE.tsx`・二重サフィックス・`.slide.test.tsx` は黙って通常ページになる
+- default export は `<SlideDeck>` をルートに返す。フレームワークは包まない
+- `<Slide>` は `<SlideDeck>` の直接の子(配列は可。Fragment・自作コンポーネントで包まない)
+- `<Step>` は `<Steps>` の直接の子(包むと常に表示される)
+- スライドの部品は `@squadbase/vantage/slide` から import する
+
+**SHOULD**
+
+- 1 ファイル = 1 デッキ。ヘルパーコンポーネント・定数も同じ `.slide.tsx` に書く
+- 各 `<Slide>` のルート要素は `width: "100%"; height: "100%"` でキャンバスを埋める
+- canvas に描くチャート(`EChart`)は `data-waitfor="canvas"` で包む(無いと pptx でそのスライドが白紙になりうる)
+- pptx に出る中身をアプリの Context(router / query / テーマ)に依存させない
+- `MorphElement` の `id` はページ内で一意にし、入れ子にしない。遷移先の `<Slide>` で `transition.morph` を有効にする
+- pptx 用などの依存を追加しない(html-to-image / fflate は自動で入る)

package/templates/agents/xlsx.md

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