@squadbase/vantage-template 0.1.1 → 0.2.0-dev1.0c40f36

package/base-template/AGENTS.md

@@ -7,8 +7,8 @@
 > このファイルと `agents/*.md` は、いずれも **Vantage フレームワークが所有する正本**の
 > コピーです。手で書き換えても、`vantage upgrade` を実行するとフレームワーク同梱の正本から
 > 再同期されて上書きされます。アプリ固有のメモは別ファイル(例: `README.md`)に書いてください。
-> 例外はプロジェクトルートの `DESIGN.md` で、これは**ユーザーが所有**します(`vantage upgrade` も
-> `vantage add agents` も触らない。→「デザインの意図(DESIGN.md)」)。
+> 例外はプロジェクトルートの任意の `DESIGN.md` で、これは**ユーザーが所有**します(`vantage upgrade` も
+> `vantage add agents` も触らない。→「見た目の規約」)。
 >
 > 手順を伴う踏み込んだワークフローは、同梱の Claude Code Skill に分かれています。このファイルは
 > 「地図」、`agents/*.md` は「種類ごとの静的リファレンス」、Skill は「手順書」という役割分担です。
@@ -47,6 +47,9 @@ UI キット・開発サーバー・API サーバー・ビルドはすべて Van
 - **`definePage` の値はリテラルで書く。** title/description/navLabel はビルド時に静的抽出される
   ため、変数・関数呼び出し・テンプレート補間は使わない。`page` エクスポートはランタイムでは
   読まれない。
+- **アプリの表示言語は、ルート `_layout.tsx` の `export const lang = "en"`(リテラル。BCP 47)で指定する。**
+  `<html lang>` になり、日本語の文節改行とスライドの文言切り替えに効く。未指定は `"en"`。
+  画面の文言・docs・コメントは、ユーザーが使う言語に合わせる(`lang` もその言語にする)。
 
 ## ディレクトリ構造(ページをどこに置くか)
 
@@ -93,13 +96,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`・`SlideSection`・`SlideComparison`・`SlideChartFull`、手書きの 1 枚に使う部品 `SlideHeading`・`SlideSourceLine`・`SlideColumns`・`SlideColumn`・`DeltaText`(スライド専用。1920×1080 の固定キャンバス) |
+| `@squadbase/vantage/doc` | `Document`、ドキュメント用の block `DocReportHeader`・`DocExecutiveSummary`・`DocKpiScorecard`・`DocFigure`・`DocDataTable`・`DocCallout`・`DocKeyFindings`・`DocActionItems`・`DocNotesAndSources`、部品 `DeltaText`(ドキュメント専用。中の素の HTML 要素に見出し・表などのスタイルが当たる) |
 | `@squadbase/vantage/markdown` | `MarkdownRenderer`(Shiki を隔離するための専用サブパス) |
 | `@squadbase/vantage/server` | `ApiContext`・`ApiHandler`・`HttpError`・`isHttpError`・`json`(server/ 側でのみ使う) |
 
+**KPI は `KpiCard`、増減は `Delta`(`comparison` を渡し、下がって良い指標は `betterWhen="down"`)。** 向き・率・色は値から計算
+されるので手で渡さない。KPI カードを自作しない。`TrendIndicator` は非推奨(`direction` を手で渡すので値と食い違いうる)。props は
+`vantage docs kpi-card` / `vantage docs delta`、数値の書式は `vantage docs format` を引く。
+
+```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` の
@@ -111,17 +126,31 @@ root/
 - `server/` が**無い** → 外部 API を直接叩くなら `useQuery`(→ `agents/page.md`)。自前の API が
   要るようになったら `server/api/*.ts` を足すだけでよい(設定変更は不要)。
 
-## デザインの意図(DESIGN.md)
+## 見た目の規約
+
+色・書体・角丸などの**値と色の割り当ては、テーマ(`styles.css` の `/* theme: <name> */` マーカー以降の
+上書き)だけが持つ。** ここには値を書かず、使い分けの規則だけを置く。UI(ページ・スライド・
+コンポーネント)はこの規則に従い、色は必ずトークンで指定する(色コード・素のパレットクラスは書かない)。
+
+- **意味トークン:** 良い = `positive`、悪い = `negative`、注意 = `warning`、情報 = `info`、
+  中立 = `neutral`。系列色は `chart-1`〜`chart-5` を番号順に使う(5 系列まで。超えるなら「その他」に
+  まとめる)。増減の良否は指標の性質(コスト減・解約率減は良い)で決めて
+  positive / negative に分け(`KpiCard` / `Delta` の `betterWhen`。下がって良い指標は `betterWhen="down"`)、向きは ▲▼ や符号で表す。
+- **レイアウト:** 内容はカードで包む(ページのチャートはタイトル付きの `DashboardCardPreset` に入れる。
+  `EChart` は親の幅に追従する)。順序は KPI → チャート → 表。値が 1 つなら KPI にする
+  (1 本の棒グラフにしない)。強調は 1 画面(スライドは 1 枚)に 1 か所。数値には単位と比較対象を添える。
+- **Do:** トークンで色を指定する / 色の意味をアプリ全体でそろえる / チャートのタイトルに結論を書く。
+- **Don't:** 色コードや素のパレットクラスを書く / `dark:` を並べる / 3D・装飾目的のグラデーション・
+  円グラフの多用 / 同じチャートで `negative` を普通の系列色に使う。
+- スライド固有の規則は `agents/slide.md`。
 
-プロジェクトルートに `DESIGN.md` があれば、**UI(ページ・スライド・コンポーネント)を書く前に
-読む。** 色・チャート・書体・レイアウトの使い分けがトークン名で書いてあるので、それに従って
-トークンで書く(値は `styles.css` にあり、`DESIGN.md` には色コードを書かない)。
+**任意の `DESIGN.md`:** プロジェクトルートにあれば読んで従う(密度・スライドの見出し方針・
+ブランド素材などユーザー固有の意図)。AGENTS.md の規則に加えて従うが、**色の割り当てはテーマを優先**
+する。新規には作らない。ユーザーの持ち物で、`vantage upgrade` は書き換えも削除もしない。
 
-- **会話中の指示は `DESIGN.md` より優先する。** 同じ指示が繰り返されたら、`DESIGN.md` への
-  反映をユーザーに提案する。
-- **「色を変えて」「ブランドに合わせて」などデザイン全体の変更は、ファイルごとに直さない。**
-  Skill `vantage-design` の手順で `DESIGN.md` と `styles.css` をまとめて更新する。
-- `DESIGN.md` はユーザーの持ち物。`vantage upgrade` は書き換えない。
+**サイト全体のデザイン変更の依頼**(「もっと落ち着いた色に」「ブランドに合わせて」、配色・フォントの変更など)は、
+ファイルごとに直さず、テーマの切り替えかスタイルシートの上書きで完結させる。`DESIGN.md` には記録しない。今のテーマ名は
+`styles.css` の `/* theme: <name> */` マーカーから読む。手順は Skill `vantage-design` に従う。
 
 ## 何を書くか → どのファイルを読むか
 
@@ -137,6 +166,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`
@@ -151,7 +189,7 @@ vantage docs button           # 1 ページ表示(短縮名。ui/button に解
 vantage docs parts/data-table # 完全な slug でも引ける
 vantage docs data-table --json  # { slug, title, description, section, content }
 vantage docs --all            # 全ページを連結(まとめて読み込む用)
-vantage docs routing --lang en  # 英語版(既定は ja)
+vantage docs routing --lang en  # 英語版(`--lang` 省略時は ja。アプリの文言の言語とは無関係)
 ```
 
 props の表・使用例・落とし穴はコンポーネントのページに載っている。**推測で props を書く前に
@@ -189,7 +227,7 @@ body・レスポンスの status と形)まで出る。`vantage check --json` /
 - **`vantage-app`** — アプリを一から作る / 構成を広げるときの進め方と検証の順序
 - **`vantage-add-feature`** — 既存アプリに page / api / ui を 1 つ足す定型
 - **`vantage-slide`** — `.slide.tsx` でスライドデッキを書く(キャンバスの予算・段階表示・pptx 書き出し)
-- **`vantage-design`** — `DESIGN.md` と `styles.css` をまとめて作る / 直す(配色・書体・ブランド合わせ)
+- **`vantage-design`** — テーマの切り替え・`styles.css` の上書きで見た目を直す(配色・書体・ブランド合わせ)
 - **`vantage-pitfalls`** — Base UI(≠ Radix)の癖など、静かに壊れる落とし穴のリファレンス
 - **`project-storage`** — Squadbase の Project Storage(アップロード済みファイル)をブラウザから読み書きする
 
@@ -224,7 +262,7 @@ vantage add skill --all --dir .claude/skills   # 置き場所を指定(既定は
 > `vantage upgrade` はこのファイルをフレームワーク同梱の正本で丸ごと上書きするため、
 > このセクションは消えます。消えたら squadbase-monorepo の
 > `packages/vantage-template/agents/vantage/` から貼り直してください
-> (リポジトリ側では `npm run agents` が正本と結合して再生成します)。
+> (リポジトリ側では `pnpm run agents` が正本と結合して再生成します)。
 
 ## Squadbase の Connection / Query からデータを読む
 
@@ -302,6 +340,34 @@ const res = await fetch(`${baseUrl}/queries/${QUERY_ID}?since=2026-01-01`, {
 })
 ```
 
+### 生の応答から行を取り出す(`noUncheckedIndexedAccess`)
+
+テンプレートの `tsconfig.json` は `noUncheckedIndexedAccess: true`。**配列の添字はすべて
+`T | undefined`** なので、HTTP Query が通す上流の生の応答(GA4 の `rows[].metricValues[]` など)を
+`row.metricValues[0].value` と書くと `Object is possibly 'undefined'.` で落ちる。書く前に添字
+アクセスを頭の中で型検査し、応答の型と行の変換関数を先に決めて `?.` と `??` で取り出す:
+
+```ts
+type Ga4Row = {
+  dimensionValues?: { value?: string }[]
+  metricValues?: { value?: string }[]
+}
+type SessionsDaily = { date: string; sessions: number; pageViews: number }
+
+const toSessionsDaily = (row: Ga4Row): SessionsDaily => ({
+  date: row.dimensionValues?.[0]?.value ?? "",
+  sessions: Number(row.metricValues?.[0]?.value ?? "0"),
+  pageViews: Number(row.metricValues?.[1]?.value ?? "0"),
+})
+
+const report = (await res.json()) as { rows?: Ga4Row[] }
+return Response.json((report.rows ?? []).map(toSessionsDaily))
+```
+
+- 値が欠けた行を落としたいときは `if (!date) throw new HttpError(502, …)` ではなく、変換後に
+  `.filter((r) => r.date !== "")` で除く。`date!` のような非 null 断言で黙らせない。
+- SQL Query の `rows` も同じ。`rows[0]` を使うなら `const first = rows[0]; if (!first) …` で先に絞る。
+
 ## 構築中の一時的なエラーを「進行中」に見せる(`components/build-recovery.tsx`)
 
 ページを書いている途中は、ファイルが書き終わる順番の都合で一瞬だけページが throw する
@@ -314,6 +380,10 @@ const res = await fetch(`${baseUrl}/queries/${QUERY_ID}?since=2026-01-01`, {
 `components/build-recovery.tsx` の `BuildRecovery` が、その画面を DOM から検知して
 `Working on it…` 表示を被せ、dev では 1.2 秒待ってから自動でリロードして復帰させる
 (上限 3 回。使い切ったら「再読み込み」の案内に降格し、無事に描けたら残数が戻る)。
+**ただし `window.__VANTAGE_DRAFT__?.active` が `true` の間(AI の書きかけのファイルを下書きとして
+プレビューに出している間)は、覆わず・リロードもしない。** 下書き中の描画エラーはフレームワークが
+直前に通った版へ戻すので、ここで覆うとその版の表示まで隠れ、リロードすると下書きの表示ごと消える。
+下書きが終わった時点でエラー画面が残っていれば、通常どおり覆う。
 降格した画面にはエラー本文をそのまま出し、`Copy log` でコピーできるようにしてある —
 自力で直らないときに本文をそのまま貼り戻してもらうため。
 `_error.tsx` も同じ `RecoveringState` を描くので、ルートレイアウトが throw したときの
@@ -331,3 +401,140 @@ const res = await fetch(`${baseUrl}/queries/${QUERY_ID}?since=2026-01-01`, {
 - **データ取得の失敗は各ページが `ErrorState` で出す。** `BuildRecovery` が拾うのは
   「レンダリングが throw した」場合だけで、`useApiQuery` の `isError` はページの責任
   (→ `agents/page.md` の「データ取得」)。
+
+## 依存の追加とスクリプトの実行は bun で
+
+このプロジェクトの package manager は **bun** です(`squadbase.yml` の `package_manager: bun`、
+lockfile は `bun.lock`)。Squadbase のサンドボックスは bun と依存のキャッシュを持っており、
+`bun install` はキャッシュだけで終わります。上のフレームワーク規約に出てくる
+`pnpm install` / `pnpm dev` / `pnpm check` は、そのまま `bun install` / `bun run dev` /
+`bun run check` に読み替えてください。
+
+### 追加の不変条件
+
+- **依存を足すときは `bun add <pkg>`(開発用は `bun add -d <pkg>`)。** `npm install` や
+  `pnpm add` を使わない — `package-lock.json` / `pnpm-lock.yaml` が生えて `bun.lock` と別の断面に
+  なり、次回起動時の install が lockfile を作り直す。
+- **`bun.lock` を消さない・手で編集しない。** `package.json` の依存を直接書き換えたときは
+  `bun install` を一度走らせて `bun.lock` を追従させ、両方を同じコミットに入れる。
+- スクリプトは `bun run <script>`(`bun run dev` / `bun run build` / `bun run check` /
+  `bun run routes`)。`npm run <script>` でも動くが、install に npm を使わないこと。
+- **公開から 48 時間未満の版は入らない。** `bunfig.toml` の `minimumReleaseAge`(サプライチェーン対策)で
+  弾かれる。`bun add` / `bun install` が「バージョンが見つからない」で落ちたら、直近の版を避けて
+  少し前の版を指定する。`bunfig.toml` の設定を緩めたり `@squadbase/*` 以外の除外を足したりしない。
+
+## このアプリで作れるもの
+
+ユーザーの目的に合わせて、どの形にするかを選ぶ。ここに書かれていない形は約束しない。
+
+- **ダッシュボード** — 数字を繰り返し見に来て、変化に気づきたいとき。指標と推移・内訳を 1 画面に
+  置き、`server/api/` で実データを取る。
+  - 書き込む場所: `src/<slug>.tsx`, `server/api/<slug>/**`
+  - ページ: あり
+  - 作り方: `src/` にページ(`.tsx`)を置く。書く前に `agents/page.md`(API は `agents/api.md`)を読む。
+- **スライド** — 分析の示唆をまとめて誰かに伝えるとき(調査結果の報告、会議資料、施策の提案)。
+  結論 → 根拠 → 次の一手の順にまとめる。
+  - 書き込む場所: `src/<slug>.slide.tsx`, `vantage-slide/**`
+  - ページ: あり
+  - 作り方: `src/<slug>.slide.tsx` に `<SlideDeck>` を返すページを置く(`@squadbase/vantage/slide`。
+    ルートは `.slide` を除いた `/<slug>`)。
+    書く前に `agents/slide.md` を読み、`vantage-slide` Skill が未配置なら
+    `vantage add skill vantage-slide` で置いてから読む。
+- **ドキュメント** — 報告書・調査のまとめ・説明資料のように、文章と図表を上から読む形で残し
+  共有したいとき。
+  - 書き込む場所: `src/<slug>.doc.tsx`
+  - ページ: あり
+  - 作り方: `src/<slug>.doc.tsx` に `<Document>` を返すページを置く(`@squadbase/vantage/doc`。
+    ルートは `.doc` を除いた `/<slug>`)。数値はコードに直接書き、チャートは `@squadbase/vantage/components` のチャート部品を文中に置く。
+    書く前に `agents/doc.md` を読む。
+- **オートメーション** — 決まった時刻に集計・通知・定期レポートを回したいとき、しきい値で
+  アラートしたいとき。
+  - 書き込む場所: `automations/<slug>/**`, `pipelines/**`
+  - ページ: なし
+  - 作り方: `automations/<名前>/automation.yml` に定義し、処理のコードは `pipelines/` に置く。
+    書く前に Automation のガイド(`readAutomationGuide`)を読む。
+
+CSV / Excel(`.csv` / `.xlsx`)は上の項目とは別で、書いて作るものではない。受け取ったファイルを
+`src/` に置くだけで表として読めるページになる(`src/data/june.xlsx` → `/data/june`。置く前に
+`agents/csv.md` / `agents/xlsx.md` を読む)。値だけが表示され、数式・書式は再現されない。25MB を
+超えるとエラー、20 万行を超えると先頭 20 万行だけが出る。`.xls`・`.ods`・`.tsv` などはページにならない
+(`vantage check` の `UNSUPPORTED_PAGE_FILE` 警告)。
+
+## 表示領域に安定 ID を付ける(`data-sq-ref`)
+
+Squadbase のチャットは、回答の根拠になったグラフ・表・KPI カードを
+`squadbase://page/<path>#<ref>`(スライド内なら `?p=<N>#<ref>`)のリンクで指し、その領域を開く。
+`<ref>` はページのソースに書かれた `data-sq-ref` の値で、過去の回答のリンクもこの値で今の画面を開く。
+
+```tsx
+<DashboardCardPreset data-sq-ref="revenue-trend" title="売上の推移">
+  <EChart option={trendOption(data)} height="320px" />
+</DashboardCardPreset>
+
+{kpis.map((kpi) => (
+  <DashboardCard key={kpi.id} data-sq-ref={kpi.id}>...</DashboardCard>
+))}
+```
+
+### 追加の不変条件
+
+- **意味のまとまった表示領域(グラフ・表・KPI カードなど)のルート要素に付ける。** 通常は
+  `DashboardCard` / `DashboardCardPreset` のように props を DOM に流す部品。`EChart` と ECharts で描く
+  チャート部品(`LineChart` / `BarChart` / `AreaChart` / `DonutChart`)・`DataTable` / `SectionHeader` は
+  付けた属性を DOM に流さないので、それらを包むカード(または `div`)に付ける。
+- **値の形式は `^[A-Za-z0-9][A-Za-z0-9_-]{0,99}$`**(ASCII の英数字・ハイフン・アンダースコア、先頭は英数字、
+  100 文字以内)。これ以外の値はリンクから開けない。推奨は意味を表す小文字 kebab-case の名前
+  (例: `revenue-trend`, `churn-by-segment`)。表示順・ソース上の位置・index・連番から作らない。
+- **`.map` で描く領域は、データの安定したキー(`kpi.id` など)がこの形式を満たすときだけ `data-sq-ref={kpi.id}`
+  のように使う。** 日本語や空白を含むキーはそのまま使わず、変換もしない(変換規則が変わると値が変わる)。
+  その場合は静的な意味名を付けるか、付けない。
+- **ページ内で一意にする。**
+- **新しく作った・直した画面では付ける。更新では既存の値を変えない** — 領域の意味が変わったときだけ変える
+  (値を変えると、それを指していた過去のリンクが開けなくなる)。触っていない画面へ遡って付けることはしない。
+
+## ファイル内の書く順序(値 → 画面本体 → 子の部品)
+
+ページ・部品のファイルは、上から次の順に書く。
+
+1. `import`(と `definePage(...)`)
+2. **値** — データ・定数・列定義・小さな関数。短く
+3. **画面本体** — `export default` のコンポーネント
+4. **子の部品** — 大文字始まりの部品。`function` 宣言で書く
+
+理由: ファイルは上から順に書かれ、書きかけでもプレビューに反映される。**本体が書かれた時点で画面が出る。**
+値を本体より後ろに書くと、本体はまだ無い値を読むので、その値が書かれるまで画面が出ない。
+子の部品は後ろでよい — 未定義の部品はプレビューが仮の枠で埋める。
+
+```tsx
+import { definePage } from "@squadbase/vantage"
+
+export const page = definePage({ title: "売上" })
+
+const KPI_ITEMS: Kpi[] = [/* … */]           // 値は本体より上
+type Kpi = { label: string; value: number }
+
+export default function SalesPage() {         // 本体
+  return <KpiRow items={KPI_ITEMS} />
+}
+
+function KpiRow({ items }: { items: Kpi[] }) { /* … */ }  // 子の部品は下
+```
+
+### 追加の不変条件
+
+- **子の部品は `function` 宣言で書く。** 宣言は巻き上げられるので、本体より後ろでも安全。
+  `const Foo = () => …` のアロー関数は後ろに置くと、モジュール評価時に参照された瞬間に TDZ(初期化前参照)で落ちる。
+- **値(定数・データ・列定義・小さな関数)は本体より上。** 小文字の関数・hook も値として上に置く。
+- 型は消えるのでどこでもよい。値のそばに置く。
+- 順序だけのために、既に並んでいるファイルを書き換えない。
+
+## アプリの表示言語(`lang`)
+
+ルートの `src/_layout.tsx` の `export const lang = "en"` が `<html lang>` になる。**アプリの内容の言語に合わせて書き換える**
+(ユーザーが日本語で依頼している・画面の文言が日本語なら `"ja"`)。
+
+- `lang` は**リテラル文字列**(BCP 47。`"ja"` / `"en"` / `"ja-JP"`)。変数・テンプレート補間は読まれない。
+- 読まれるのは**ルートの `src/_layout.tsx` だけ**。入れ子の `_layout.tsx` やページには書かない。
+- 日本語アプリで `"en"` のままだと、スライドの文節改行(`word-break: auto-phrase`)が効かず、見出しが単語の途中で折れる。
+  スライドのツールバー文言も `lang` で切り替わる(`"ja"` なら日本語、`en*` なら英語)。
+- 値は消さない。指定が無いと `"en"` 扱いになる。

package/base-template/agents/api.md

@@ -25,8 +25,16 @@ 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 に丸められる。
+- **入力の誤りは 400 で返し、`msg` には何がどう誤りかを書く。** `msg` はそのまま `ErrorState` に
+  出る。「開始日(10/20)が終了日(10/01)より後です」のように、利用者が条件を直せる文にする。
+  許す範囲だけを並べた文(「最大366日で指定」)では、どこを直せばよいか伝わらない。
 - **シークレットは `ApiContext.env` にだけ届く**(クライアントには決して届かない)。
 
 クライアント側からは `useApiQuery` で `/api/*` を叩く。ベース URL の解決・JSON パース・
@@ -34,9 +42,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 +56,30 @@ 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 ?? []` にするか、
+カードのコンポーネントの中で上と同じ判定をする。
+
+期間などの絞り込みを持つページでは、上の早期 return をページの先頭に置かない。失敗したときに
+絞り込みの欄まで消え、条件を直せなくなる。判定はデータを描く子コンポーネントの中で行う
+(→ `agents/page.md` の「絞り込みの欄は、読み込み中も失敗したときも出し続ける」)。
+
 `ApiError` は `message`・`status`・`body`・`requestId` を持つ。hook が使えない場所では
 `apiJson(path, init)`、生の `Response` が要るときは `apiFetch`。

package/base-template/agents/csv.md

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

package/base-template/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,13 +49,38 @@ 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` | 次のアクション(担当・期限つき) |
+| `DocNotesAndSources` | 末尾の注記・用語の定義・データソースをまとめた節 |
+
+**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`)。
+
+本文の中で増減を書くときは `DeltaText`(部品。「▲ +3.2%」の形で、文字サイズは持たず置かれた行に従う。`value` `format` `betterWhen` `comparisonLabel`)を使う。節ではなく文の中に置く。
+
+block が合わない**1 節だけ**を素の HTML 要素で手で書く。import 元は `@squadbase/vantage/doc` のままで、
+block のための新しい import 元はありません。本文は文字列か ReactNode で渡し、Markdown 文字列は渡さない。
+
 ## 見た目を変える
 
 配色・書体・本文の幅は `--doc-*` の CSS 変数です。既定値はアプリのトークンへの別名なので、
@@ -73,3 +105,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/base-template/agents/page.md

@@ -4,7 +4,7 @@
 (ダッシュボード)を書くときに読んでください。前提となる不変条件・ディレクトリ構造は
 `AGENTS.md` を先に読んでいる想定です。
 
-プロジェクトルートに `DESIGN.md` があれば、書き始める前に読んで配色・書体・レイアウトの規則に従う。
+書き始める前に `AGENTS.md` の「見た目の規約」(と、あればプロジェクトルートの `DESIGN.md`)に従う。
 
 ## 最小アプリ(2 ファイル)
 
@@ -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 に置く
@@ -126,6 +147,42 @@ const [segments, setSegments] = useSearchState<string[]>("segments", []) // JSON
 デフォルト値(または `null`)を書くとキーは URL から消える。履歴は既定で `replace`
 (`{ replace: false }` で push)。
 
+### 絞り込みの欄は、読み込み中も失敗したときも出し続ける
+
+ページの先頭で `if (q.isError) return <ErrorState …/>` と書くと、取得に失敗したときに
+期間などの絞り込みの欄まで消える。利用者は条件を直せず、初期値に戻すしかなくなる。
+絞り込みの欄はページに置いたままにし、取得と `Loading` / `ErrorState` はデータを描く
+子コンポーネントに入れる:
+
+```tsx
+export default function Traffic() {
+  const [from, setFrom] = useSearchParam("from", DEFAULT_FROM)
+  const [to, setTo] = useSearchParam("to", DEFAULT_TO)
+  return (
+    <>
+      {/* 失敗しても消えない。ここから条件を直せる */}
+      <PeriodFilter from={from} to={to} onChange={…} />
+      <TrafficBody from={from} to={to} />
+    </>
+  )
+}
+
+function TrafficBody({ from, to }: { from: string; to: string }) {
+  const q = useApiQuery<Row[]>("/api/traffic", { search: { from, to } })
+  if (q.isPending) return <Loading />
+  if (q.isError) return <ErrorState message={q.error.message} />
+  return <BarChart data={q.data} index="channel" categories={["sessions"]} />
+}
+```
+
+- **期間は `DateRangePicker`(`@squadbase/vantage/components`)で選ばせる。** カレンダーで
+  範囲を選ぶので開始と終了が逆にならず、選べる日を `minDate` / `maxDate` で絞れる。
+  `<input type="date">` を 2 つ並べて自前で組まない。
+- 値をそのまま打ち込める欄を置くなら、開始が終了より後・選べる範囲の外といった誤りは、
+  API へ送る前に欄のそばで理由を出す。誤りがあるあいだはデータの子コンポーネントを描かない
+  (送れば失敗するだけで、`ErrorState` には直し方が出ない)。
+- サーバー側の検証で弾くときも、`HttpError(400, …)` の文で何がどう誤りかを言う(→ `agents/api.md`)。
+
 ### 動的パラメータの「3 つの綴り」を同期させる
 
 崩すと静かにマッチしなくなる不変条件:
@@ -164,17 +221,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