@squadbase/vantage-template 0.0.1 → 0.0.2-dev.7c29258

package/README.md

@@ -14,7 +14,7 @@ npx @squadbase/vantage-template <command> [options]
 
 #### `init`
 
-Initialize a new Vantage project in the current directory. Copies the base template — `index.tsx`, `_layout.tsx`, `_404.tsx`, `_error.tsx`, `server/api/`, `styles.css`, `tsconfig.json`, `squadbase.yml`, plus the agent guidance in `AGENTS.md` and `.squadbase/skills/` — and installs dependencies.
+Initialize a new Vantage project in the current directory. Copies the base template — `src/index.tsx`, `src/_layout.tsx`, `src/_404.tsx`, `src/_error.tsx`, `src/styles.css`, `server/api/`, `tsconfig.json`, `squadbase.yml`, plus the agent guidance in `AGENTS.md` and `.squadbase/skills/` — and installs dependencies.
 
 ```bash
 npx @squadbase/vantage-template init
@@ -26,17 +26,23 @@ npx @squadbase/vantage-template init --chart sunset           # Apply a chart pr
 After initialization:
 
 ```bash
-npm run dev      # vantage dev — dev server + API on :5173
+npm run dev      # vantage dev --no-overlay — dev server + API on :5173
 npm run build    # vantage build → dist/
 npm run check    # vantage check — static diagnostics
 npm run routes   # vantage routes — page/API route map
 ```
 
-There is no `vite.config.ts`, no `main.tsx`, and no route table: adding a file adds a route (`index.tsx` → `/`, `sales/[id].tsx` → `/sales/:id`), and `_layout.tsx` builds the nav from `useRoutes()`.
+There is no `vite.config.ts`, no `main.tsx`, and no route table: adding a file under `src/` adds a route (`src/index.tsx` → `/`, `src/sales/[id].tsx` → `/sales/:id`), and `src/_layout.tsx` builds the nav from `useRoutes()`.
+
+Since `@squadbase/vantage` v0.3.0, `src/` is the page-scan root and does not appear in URLs. `server/` and `public/` stay at the project root — `src/server/` is never scanned.
+
+Since `@squadbase/vantage` v0.5.0, the dev terminal receives only `console.warn` / `console.error` and uncaught errors (with source-mapped positions and a code frame) — `console.log` is not forwarded. The generated `dev` script passes `--no-overlay`, keeping errors in the terminal instead of behind the full-screen browser overlay; remove the flag (or pass `--overlay`) to restore it.
 
 #### `add <template-name>`
 
-Apply a UI-pattern template to an existing Vantage project. The entry page lands on `index.tsx`, and template-owned files go under `components/<slug>/` (plus `server/api/` for API-backed templates).
+Apply a UI-pattern template to an existing Vantage project. The entry page lands on `src/index.tsx`, and template-owned files go under `src/components/<slug>/` (plus `server/api/` at the project root for API-backed templates).
+
+Both layouts are supported: Vantage scans `src/` when that directory exists and the project root otherwise, and `add` follows whichever one the project already uses — a project keeping its pages at the root gets `index.tsx` and `components/<slug>/` there instead, with relative imports that cross the boundary rewritten to match. `server/` and `public/` always stay at the project root.
 
 ```bash
 npx @squadbase/vantage-template add kpi-chart-simple
@@ -44,11 +50,13 @@ npx @squadbase/vantage-template add funnel --dry-run    # Preview without writin
 npx @squadbase/vantage-template add funnel --force      # Overwrite existing files
 ```
 
-`add` replaces `index.tsx`, so it warns before overwriting it, and it lists leftover files from a previously applied template (it never deletes them — you may have edited them).
+`add` replaces the entry page, so it warns before overwriting it, and it lists leftover files from a previously applied template (it never deletes them — you may have edited them). A project with pages on *both* sides — `src/` present but `index.tsx` / `_layout.tsx` / `styles.css` still at the root — is refused with the list of files to move into `src/` first: Vantage ignores the root ones, so `vantage check` already fails there with `SRC_DIR_SPLIT`.
 
 #### `chart <preset-name>`
 
-Switch the chart color preset. Rewrites a marked block of `--chart-1`–`--chart-5` inside the project's `styles.css`, leaving any other overrides in that file intact. Re-running replaces the block rather than stacking.
+Switch the chart color preset. Rewrites a marked block of `--chart-1`–`--chart-5` inside the project's `styles.css` (under `src/` when that layout is in use), leaving any other overrides in that file intact. Re-running replaces the block rather than stacking.
+
+A new project starts on the `blue` preset — the base template ships that block already written, so `init` and the gallery previews show the same colors. This command swaps it for another preset.
 
 ```bash
 npx @squadbase/vantage-template chart ocean

package/base-template/.squadbase/skills/project-storage/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: project-storage
+description: Squadbase の Project Storage(アップロード済みファイル)を @squadbase/react の useStorage() でブラウザから扱う手順。ファイル一覧、画像 / 動画 / PDF の埋め込み、中身の読み取り、アップロードと削除・移動。ページやコンポーネントがアップロード済みファイルを表示・埋め込み・アップロードするときに参照する。
+---
+
+# Project Storage(ブラウザ側)
+
+Squadbase の **Project Storage** を React コンポーネントから読み書きする手順。Squadbase 上で
+動くアプリでは資格情報も設定も要らず、そのまま動く。サーバー(`server/api/**`)からストレージを
+触る API は別物で、ここでは扱わない。
+
+## import は `@squadbase/react` から直接
+
+「import は `@squadbase/vantage` のサブパス経由」はフレームワークが所有するものの話。
+**`@squadbase/react` は Squadbase プラットフォームの SDK なので直接 import する**
+(`SquadbaseProvider` / `useUser` と同じ)。
+
+```tsx
+import { useStorage } from "@squadbase/react"
+
+const storage = useStorage()
+// 呼び出しはすべて storage.uploads.* の下
+```
+
+`useStorage()` が返すクライアントは安定なので、コンポーネント先頭で呼んで `useQuery` /
+`useMutation` の中で使ってよい。データ取得のフックは `@squadbase/vantage/query` から取る
+(`@tanstack/*` は直接 import しない)。
+
+## API
+
+すべて async。`key` はストレージ内の**相対**パス(例: `reports/2025-q1.pdf`)で、先頭に
+スラッシュを付けない。
+
+読み取り:
+
+- `list(prefix?, options?)` → `{ objects, commonPrefixes, nextCursor? }`。`objects` は
+  `{ key, size, lastModified }[]`。`options.delimiter = "/"` でフォルダ表示(サブフォルダが
+  `commonPrefixes` に入る)、省略すると再帰的なフラット一覧。`options.limit` / `options.cursor`
+  でページング(`cursor` は前回の `nextCursor`)
+- `head(key)` → `{ key, size, contentType, createdAt }`。メタ情報だけで本体は取らない
+- `getUrl(key)` → `{ url, expiresAt }`。埋め込み用の一時 URL
+- `get(key)` → 生の `Response`。`.json()` / `.text()` / `.blob()` / `.arrayBuffer()` で読む
+
+書き込み:
+
+- `put(key, data, options?)` → `void`。`data` は `Blob`(`File` を含む) / `ArrayBuffer` /
+  `Uint8Array` / `string`
+- `delete(key)` → `void`
+- `copy(srcKey, destKey, options?)` / `move(srcKey, destKey, options?)` → `void`
+
+## 一覧を出す
+
+```tsx
+import { useStorage } from "@squadbase/react"
+import { useQuery } from "@squadbase/vantage/query"
+
+const storage = useStorage()
+const { data, isPending, isError } = useQuery({
+  queryKey: ["storage", "list", prefix],
+  queryFn: () => storage.uploads.list(prefix, { delimiter: "/" }),
+})
+```
+
+`data.commonPrefixes` をフォルダ、`data.objects` をファイルとして描く。プレフィックス配下を
+まとめて出すなら `delimiter` を省く。
+
+## 画像 / 動画 / PDF を埋め込む
+
+埋め込みには URL が要るので `getUrl` を使う。**URL には期限がある**ので、切れる前に取り直す:
+
+```tsx
+import { useStorage } from "@squadbase/react"
+import { useQuery } from "@squadbase/vantage/query"
+
+function useStorageUrl(key: string) {
+  const storage = useStorage()
+  return useQuery({
+    queryKey: ["storage", "url", key],
+    queryFn: () => storage.uploads.getUrl(key),
+    refetchInterval: (query) => {
+      const expiresAt = query.state.data?.expiresAt
+      if (!expiresAt) return false
+      // 期限の 60 秒前に取り直す
+      return Math.max(0, new Date(expiresAt).getTime() - Date.now() - 60_000)
+    },
+  })
+}
+```
+
+```tsx
+import { ErrorState, Loading } from "@squadbase/vantage/ui"
+
+const { data, isPending, isError } = useStorageUrl("reports/cover.png")
+if (isPending) return <Loading />
+if (isError) return <ErrorState message="ファイルを読み込めませんでした" />
+return <img src={data.url} alt="" className="w-full rounded-lg" />
+```
+
+動画は `<video src={data.url} controls className="w-full rounded-lg" />`、PDF は
+`<iframe src={data.url} className="h-[80vh] w-full rounded-lg border border-border" />`。
+
+## 中身を JS で読む
+
+```tsx
+const { data } = useQuery({
+  queryKey: ["storage", "content", key],
+  queryFn: async () => {
+    const res = await storage.uploads.get(key)
+    return (await res.json()) as Row[] // または res.text()
+  },
+})
+```
+
+## アップロードする
+
+```tsx
+import { useStorage } from "@squadbase/react"
+import { useMutation, useQueryClient } from "@squadbase/vantage/query"
+
+const storage = useStorage()
+const queryClient = useQueryClient()
+const upload = useMutation({
+  mutationFn: (file: File) =>
+    storage.uploads.put(`uploads/${file.name}`, file, { contentType: file.type }),
+  onSuccess: () => queryClient.invalidateQueries({ queryKey: ["storage", "list"] }),
+})
+
+<input
+  type="file"
+  onChange={(e) => {
+    const file = e.target.files?.[0]
+    if (file) upload.mutate(file)
+  }}
+/>
+```
+
+`File` はそのまま `put` に渡す。書き込み後は該当する `["storage", "list", …]` を invalidate して
+UI を追従させる。
+
+## 落とし穴
+
+- **`getUrl` の URL は短命。** 結果を永続化したり長寿命のキャッシュに入れたりしない。
+  `expiresAt` の前に取り直す(上のフック)。`<img src>` に一度入れて放置すると、開いたままの
+  画面で後から読み込まれた分が失敗する
+- **`put` の `contentType` の既定は `application/octet-stream`。** 後で埋め込むもの(画像・動画・
+  PDF)には `file.type` を必ず渡す。付けないとブラウザが表示せずダウンロードに落ちる
+- **`key` は相対パス。** 先頭にスラッシュを付けない。`getUrl` を通さず `<img src="/foo.png">` の
+  ような静的パスで参照しない ― ストレージはアプリの `public/` ではない
+- **`copy` / `move` は既定で既存の宛先を上書きする。** 残したいときは `{ overwrite: false }`
+- **サーバー(`server/api/**`)からは呼ばない。** `useStorage` はブラウザ側の API
+
+---
+
+## 関連スキル
+
+- `vantage-add-feature` — ページ / API / コンポーネントを 1 つ足す手順
+- `vantage-pitfalls` — UI・配色・ルーティングの落とし穴

package/base-template/.squadbase/skills/vantage-add-feature/SKILL.md

@@ -16,8 +16,8 @@ CLI は雛形を出すだけで、規約の遵守はこちらの責任。**追
 ```bash
 vantage add page  <name>    # ルートページ(.tsx)
 vantage add api   <name>    # server/api/**.ts の API モジュール
-vantage add ui    <name>    # registry から UI ソースを components/ui/ にコピー
-vantage add block <name>    # registry からブロックを components/blocks/ にコピー
+vantage add ui    <name>    # registry から UI ソースを components/ui/ にコピー(src/ があればその中)
+vantage add block <name>    # registry からブロックを components/blocks/ にコピー(同上)
 ```
 
 `--force` で既存ファイルを上書き。`add` の雛形は import に `@squadbase/vantage` を焼き込む。
@@ -25,12 +25,18 @@ vantage add block <name>    # registry からブロックを components/blocks/
 ## ページを追加する
 
 ```bash
-vantage add page monthly-analysis        # → ./monthly-analysis.tsx  → ルート /monthly-analysis
-vantage add page sales/index             # → ./sales/index.tsx       → ルート /sales
+vantage add page monthly-analysis        # → monthly-analysis.tsx  → ルート /monthly-analysis
+vantage add page sales/index             # → sales/index.tsx       → ルート /sales
 vantage add page "sales/[customerId]"    # → 動的ルート /sales/:customerId
 ```
 
-出力される雛形は `definePage` + デフォルトエクスポートのコンポーネント。ファイル名の規約:
+**引数はページルートからの相対パス**(= ルートそのもの)。`add` は置き場所を自分で判断する ―
+プロジェクトに `src/` があれば `src/monthly-analysis.tsx`、無ければ直下に書く。手でファイルを
+作るときも同じ規則で、**混ぜてはならない**(`src/` があるのに直下に置くと `SRC_DIR_SPLIT`
+エラー。詳細は AGENTS.md の「ディレクトリ構造」)。
+
+出力される雛形は `definePage` + デフォルトエクスポートのコンポーネント。ファイル名の規約
+(ページルートからの相対パス):
 
 | ファイル | ルート | 用途 |
 | --- | --- | --- |
@@ -51,6 +57,9 @@ vantage add page "sales/[customerId]"    # → 動的ルート /sales/:customerI
    - 表示ルート `/foo/:id`
    - リンク `to="/foo/$id"` + `params={{ id }}`、取り出しは `const { id } = useParams()`
 4. `components/`・`hooks/`・`lib/`・`server/`・`public/` はページにならない(ルート走査対象外)。
+   **それ以外のディレクトリ名はそのまま URL のセグメントになる** ― `pages/`・`app/`・`utils/`
+   のような足場ディレクトリを切ると `/pages/report` のような URL ができる
+   (`SUSPICIOUS_ROUTE_DIR` 警告)。ページでないモジュールは上の 3 つに置く。
 
 ## API を追加する(fullstack)
 
@@ -130,7 +139,7 @@ vantage add block sales-overview # → components/blocks/sales-overview.tsx
 ```bash
 vantage routes    # 追加したページ/API が意図した URL に出ているか
 vantage check     # 規約違反が無いか(exit 1 ならエラーあり)
-vantage dev       # 実際に動くか(console は開発ターミナルに [browser:…] で転送)
+vantage dev       # 実際に動くか(warn/error と未捕捉エラーは開発ターミナルへ転送される)
 ```
 
 `vantage routes` は `--pages` / `--apis` で片側だけに絞れる。`--detail` を足すと各ルートの静的な

package/base-template/.squadbase/skills/vantage-app/SKILL.md

@@ -19,14 +19,17 @@ description: Vantage(@squadbase/vantage)ダッシュボードアプリを一か
 3. **データを繋ぐ** — 外部 API か、自前の `server/api` か
 4. **仕上げ** — `check` → `build` → `preview`
 
-**各段階の終わりに `vantage check` を通す。** 静的診断(禁止ファイル・ルート衝突・境界違反・
-API export・env 誤用)はユーザーコードを実行しないので速く、エラーがあれば exit 1 になる。
+**各段階の終わりに `vantage check` を通す。** 静的診断(禁止ファイル・`src/` の分裂・ルート
+衝突・境界違反・API export・env 誤用)はユーザーコードを実行しないので速く、エラーがあれば
+exit 1 になる。
 まとめて最後に回すと、原因の切り分けが難しくなる。
 
 ## Step 1 — 骨組み
 
 新規なら `package.json` と `index.tsx` の 2 ファイルだけ。設定ファイルは**作らない**
-(`vite.config.*` 等は `vantage check` がエラーにする)。
+(`vite.config.*` 等は `vantage check` がエラーにする)。ページを `src/` にまとめたいなら
+`src/index.tsx` にする ― **`src/` があればページ走査はその中だけ**になり、直下に残した `.tsx`
+は無視される(`SRC_DIR_SPLIT` エラー)。どちらか一方に寄せること。
 
 ```json
 {
@@ -41,7 +44,7 @@ API export・env 誤用)はユーザーコードを実行しないので速く
     "routes": "vantage routes"
   },
   "dependencies": {
-    "@squadbase/vantage": "^0.2.0",
+    "@squadbase/vantage": "^0.5.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7"
   }
@@ -54,8 +57,9 @@ API export・env 誤用)はユーザーコードを実行しないので速く
 **既存アプリに合流したときは、作る前に現状を読む:**
 
 ```bash
-vantage routes     # 既にあるページと API の URL マップ
+vantage routes     # 既にあるページと API の URL マップ(file 列がページの置き場所)
 vantage check      # いま壊れていないか(これから出すエラーと切り分ける)
+ls src/            # あればページは src/ の中だけ。無ければプロジェクトルート直下
 ls server/         # あれば fullstack モード。無ければ SPA
 vantage add skill  # 配置済みの skill(このファイルの仲間)と、その場所
 ```
@@ -112,8 +116,9 @@ pnpm preview   # 本番ビルドをローカルで動かす
 
 ## 詰まったら
 
-- ブラウザの `console.*` とランタイムエラーは、**開発ターミナルに `[browser:…]` として転送
-  される**。ブラウザの devtools を開かなくても読める。
+- ブラウザの `console.warn` / `console.error` とランタイムエラーは、**開発ターミナルへ転送
+  される**(`[console.warn] …` / `[Unhandled error] …` + コードフレーム)。devtools を開かずに
+  読める。`console.log` は転送されないので、**ターミナルで見たいログは `console.warn`** で出す。
 - `vantage check --json` / `vantage routes --json` は機械可読出力。
 - props や規約を確かめたいときは `vantage docs <name>`、名前が思い出せないときは
   `vantage search <やりたいこと>`。**推測で props を書かない。**

package/base-template/.squadbase/skills/vantage-pitfalls/SKILL.md

@@ -35,6 +35,28 @@ Base UI の `SelectValue` は選択中の **value をそのまま描き**、`Sel
 
 トリガーに `kanto` や `/sales` と生の値が出たら、まずこれを疑う。
 
+## 配色:素のパレット + `dark:` ではなく、セマンティックトークンで書く
+
+色は `text-foreground` / `text-muted-foreground` / `bg-card` / `border-border` などの
+トークンで書く。トークンはライト / ダークの両方を持っているので、`dark:` を並べる必要が無い。
+
+`text-slate-900 dark:text-slate-100` のような素の Tailwind パレット + `dark:` の組は、
+**トークンで塗られた周囲と食い違う**。ダークトークンが効くのは祖先に `.dark` /
+`[data-theme="dark"]` が付いているときだけで、`dark:` ユーティリティも同じスイッチに
+繋がっている(`theme.css` の `@custom-variant dark`)。つまり自分でクラスを付けない限り
+アプリは常にライトで動くのに、素のパレットを使うとその 1 か所だけ手動で両モードを
+管理することになる。
+
+```tsx
+// ✗ 手動で 2 モードを管理することになる
+<div className="font-medium text-slate-900 dark:text-slate-100">{name}</div>
+// ✓ トークンなら 1 つで済む
+<div className="font-medium text-foreground">{name}</div>
+```
+
+`--muted` / `--accent` / `--secondary` / `--border` は**背景・境界用**で、ライトではほぼ白。
+文字色に使うと読めなくなる ― 弱い文字色は `text-muted-foreground`。
+
 ## チャート:`EChart` の配色はトークン追従。上書きは `option.color`
 
 系列色は `--chart-1..5`、軸・凡例・ツールチップは文字色/境界色のトークンから組まれる

package/base-template/AGENTS.md

@@ -22,6 +22,9 @@ UI キット・開発サーバー・API サーバー・ビルドはすべて Van
 
 ## 不変条件(破ると静かに壊れる)
 
+- **ページは `src/` の中か、プロジェクトルート直下か、どちらか一方。** `src/` があれば走査は
+  `src/` だけになり、ルート直下に残した `.tsx` は無視される(`SRC_DIR_SPLIT` エラー)。
+  新しいファイルは既にある側に置く(→「ディレクトリ構造」)。
 - **設定ファイルを作らない。** `vite.config.*`・`tailwind.config.*`・`postcss.config.*`・
   `components.json`・`vantage.config.*` はすべて禁止。存在すると `vantage check` がエラーにする
   (`FORBIDDEN_FILE`)。テーマ調整は `styles.css` のトークンで行う。
@@ -33,12 +36,54 @@ UI キット・開発サーバー・API サーバー・ビルドはすべて Van
 - **クライアントに届く env は `PUBLIC_` 接頭辞のものだけ。** `import.meta.env.PUBLIC_FOO`。
   それ以外を `import.meta.env` で読むと `PUBLIC_ENV_MISUSE` 警告。シークレットは
   `ApiContext.env`(server/ 内)にだけ届く。
+- **色はセマンティックトークンで書く。** `text-foreground`・`text-muted-foreground`・`bg-card`・
+  `border-border`。トークンがライト / ダークの両方を持つので `dark:` を並べる必要が無い。
+  素のパレット + `dark:`(`text-slate-900 dark:text-slate-100`)を混ぜると、その 1 か所だけ
+  手動で 2 モードを管理することになる(→「ダークモードは opt-in」)。`--muted`・`--accent`・
+  `--secondary`・`--border` は背景・境界用で、文字色に使うと読めない。
 - **`.vantage/` と `dist/` は生成物。** 編集しない・読みにいかない(gitignore 済み)。任意の CLI
   コマンド、または `vantage upgrade` で再生成される。
 - **`definePage` の値はリテラルで書く。** title/description/navLabel はビルド時に静的抽出される
   ため、変数・関数呼び出し・テンプレート補間は使わない。`page` エクスポートはランタイムでは
   読まれない。
 
+## ディレクトリ構造(ページをどこに置くか)
+
+**ページの置き場所は 2 通りあり、`src/` があるかどうかだけで決まる。混ぜてはならない。**
+
+- `src/` が**ある** → ページは `src/` の中だけ。ルート直下に置いた `.tsx` はルートにならず、
+  `SRC_DIR_SPLIT` エラーになる。
+- `src/` が**無い** → ページはプロジェクトルート直下。
+
+**ファイルを足す前に `src/` の有無を確認し、既にある側に置く**(`ls` するだけでよい)。URL は
+どちらでも同じで、`src/` は URL に現れない(`src/sales/index.tsx` → `/sales`)。
+
+```text
+root/
+├── src/                    # ある場合、ページはこの中だけ(無ければ以下が root 直下)
+│   ├── index.tsx           # /
+│   ├── monthly-analysis.tsx  # /monthly-analysis
+│   ├── sales/index.tsx     # /sales
+│   ├── _layout.tsx         # ルートレイアウト
+│   ├── components/         # ページ走査の対象外(URL にならない)
+│   ├── hooks/  lib/        # 同上
+│   └── styles.css          # 任意のグローバル CSS
+├── server/                 # 常にプロジェクトルート直下。src/ の中ではない
+│   ├── api/…               # /api/*
+│   └── utils.ts
+├── public/                 # 静的ファイル。常にプロジェクトルート直下
+├── package.json            # managed
+└── tsconfig.json           # managed
+```
+
+- **`server/` と `public/` は常にプロジェクトルート直下。** `src/server/` は決してスキャン
+  されない(`SRC_DIR_SPLIT` エラー)。
+- **`styles.css` はページと同じ側**に置く(`src/` があれば `src/styles.css`)。
+- **ディレクトリ名はそのまま URL のセグメントになる。** `pages/`・`app/`・`utils/` のような
+  足場ディレクトリを切ると、その名前が URL に出る(`pages/report.tsx` → `/pages/report`)。
+  `SUSPICIOUS_ROUTE_DIR` 警告で知らされる。ページでないモジュールは `components/`・`hooks/`・
+  `lib/` に置く ― この 3 つ(と `server/`・`public/`)はどの階層でも走査されない。
+
 ## import サブパスの地図
 
 | import 元 | 提供するもの |
@@ -82,7 +127,7 @@ UI キット・開発サーバー・API サーバー・ビルドはすべて Van
     "routes": "vantage routes"
   },
   "dependencies": {
-    "@squadbase/vantage": "^0.2.0",
+    "@squadbase/vantage": "^0.5.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7"
   }
@@ -108,12 +153,15 @@ pnpm check    # 静的診断(エラーがあれば exit 1)
 pnpm routes   # ページ/API の URL マップ
 ```
 
-`server/` ディレクトリが無いので、この構成は **SPA モード**。
+`server/` ディレクトリが無いので、この構成は **SPA モード**。ページを直下に置く形だが、
+`src/` を作ってその中に集めてもよい(テンプレートから始めた場合は最初から `src/` がある)。
+どちらか一方に寄せること(→「ディレクトリ構造」)。
 
 ## ルーティング規約(ファイル名 → ルート)
 
-ルートディレクトリ直下の `.tsx`/`.jsx` がそのままページになる。各ページは**デフォルト
-エクスポートの React コンポーネントが必須**(無いと `MISSING_DEFAULT_EXPORT`)。
+ページルート(`src/` があればその中、無ければプロジェクトルート)からの相対パスが、そのまま
+URL になる。各ページは**デフォルトエクスポートの React コンポーネントが必須**(無いと
+`MISSING_DEFAULT_EXPORT`)。以下の「ファイル」列はページルートからの相対パス。
 
 | ファイル | ルート |
 | --- | --- |
@@ -125,7 +173,8 @@ pnpm routes   # ページ/API の URL マップ
 | `_404.tsx` | Not Found ページ |
 | `_error.tsx` | ルートが throw したときのエラーページ |
 
-`components/`・`hooks/`・`lib/`・`server/`・`public/` はルート走査の対象外(ページにならない)。
+`components/`・`hooks/`・`lib/`・`server/`・`public/` はどの階層でもルート走査の対象外
+(ページにならない)。それ以外のディレクトリ名は URL のセグメントになる(→「ディレクトリ構造」)。
 
 ```tsx
 import { definePage } from "@squadbase/vantage"
@@ -274,6 +323,16 @@ const save = useApiMutation<Customer, Payload>("/api/customers", { method: "POST
   `ui: data-table` と `block: sales-overview` の 2 つだけ。それ以外の名前は import 専用で
   `add` の対象ではない(未知名で実行すると候補が一覧表示される)。
 
+### ダークモードは opt-in
+
+ダークのトークンが効くのは、祖先に `.dark` か `[data-theme="dark"]` が付いているときだけ。
+**OS / ブラウザの設定(`prefers-color-scheme`)は見ない。** `dark:` ユーティリティも同じ
+スイッチに繋いであるので(`theme.css` の `@custom-variant dark`)、自分でクラスを付けない限り
+アプリは常にライトで描かれる ― `dark:` を書いてもそこだけダークになることはない。
+
+明暗を切り替えたいときは、レイアウトのルート要素などに `.dark` / `data-theme="dark"` を
+自分で付ける。
+
 ## ドキュメントを引く(`vantage docs` / `vantage search`)
 
 ```bash
@@ -302,7 +361,7 @@ vantage search テーブル --limit 5 --json    # 機械可読(slug + score + sn
 ## 検証・ビルド・プレビュー
 
 ```bash
-pnpm check     # 静的診断(禁止ファイル・ルート衝突・境界・API export・env 誤用)
+pnpm check     # 静的診断(禁止ファイル・src/ の分裂・ルート衝突・境界・API export・env 誤用)
 pnpm routes    # ページ + API の URL マップ
 pnpm build     # dist/ に client(+ server)+ vantage-manifest.json
 pnpm preview   # 本番ビルドをローカル実行
@@ -312,13 +371,15 @@ pnpm preview   # 本番ビルドをローカル実行
 (手で書かない)。`vantage routes` は `--pages` / `--apis` で片側だけに絞れ、`--detail` を足すと
 各ルートの静的な仕様(ページ: パスパラメータ + `definePage` のメタ / API: メソッド・query・
 body・レスポンスの status と形)まで出る。`vantage check --json` / `vantage routes --json` は
-エージェント向けの機械可読出力。`console.*` とランタイムエラーは開発ターミナルに `[browser:…]` として転送される。
+エージェント向けの機械可読出力。dev では `console.warn` / `console.error` とランタイムエラーが開発ターミナルへ
+転送される(`console.log` は転送されない)。エラーの全画面オーバーレイは `vantage dev --no-overlay` で消せる。
 
 ## さらに詳しく(同梱 Skill)
 
 - **`vantage-app`** — アプリを一から作る / 構成を広げるときの進め方と検証の順序
 - **`vantage-add-feature`** — 既存アプリに page / api / ui を 1 つ足す定型
 - **`vantage-pitfalls`** — Base UI(≠ Radix)の癖など、静かに壊れる落とし穴のリファレンス
+- **`project-storage`** — Squadbase の Project Storage(アップロード済みファイル)をブラウザから読み書きする
 
 手順書の本体は `SKILL.md` というファイルで、置き場所はアプリによって違う(ルート直下・
 `.claude/skills/`・`.squadbase/skills/` など)。**探す必要はない ― CLI が探す:**
@@ -337,3 +398,121 @@ vantage add skill --all --dir .claude/skills   # 置き場所を指定(既定は
 `add skill` はプロジェクト内を走査してから動くので、**再実行しても二重に配置されない**。
 配置済みのコピーを新しいバージョンに更新したいときだけ `--force` を付ける(見つかった場所を
 そのまま書き換える)。
+
+---
+
+# テンプレート固有の規約(Squadbase テンプレート)
+
+> ここから下は、Squadbase のテンプレートがフレームワーク正本に足した規約です。上の
+> フレームワーク規約と矛盾する場合は**こちらが優先**します。
+>
+> `vantage upgrade` はこのファイルをフレームワーク同梱の正本で丸ごと上書きするため、
+> このセクションは消えます。消えたら squadbase-monorepo の
+> `packages/vantage-template/agents/vantage/` から貼り直してください
+> (リポジトリ側では `npm run agents` が正本と結合して再生成します)。
+
+## Squadbase の Connection / Query からデータを読む
+
+**`server/api/**` のハンドラが実データを取りにいく唯一の方法**が `@squadbase/vantage-sdk`
+(`@squadbase/vantage-sdk/server` の `connection`)。資格情報・接続先・SQL は Squadbase 側の
+**Connection** と **Query** が持ち、ハンドラは「どの Query を、どの引数で回すか」だけを知る。
+
+### 追加の不変条件
+
+- **`server/` からデータを読むときは `connection` を使う。** ハンドラに SQL・接続文字列・
+  DB クライアント・上流サービスの URL や API キーを書かない。データソース用のライブラリを
+  `package.json` に足すのも不要(足す前に、その接続が Connection にできないか疑う)。
+- **`connection` は `server/` の中でしか呼べない。** クライアントから import すると
+  `CLIENT_IMPORTS_SERVER` エラー(フレームワーク側の不変条件と同じ)。
+- **CONNECTION_ID / QUERY_ID を推測で埋めない。** 値はアプリを動かす Squadbase プロジェクト側の
+  設定なので、分からなければユーザーに聞く。実データがまだ無い段階は `lib/mock-data.ts` の
+  モックで進め、id が確定したらハンドラだけ差し替える(クライアントの `useApiQuery` は変わらない)。
+
+### 追加の import サブパス
+
+| import 元 | 提供するもの |
+| --- | --- |
+| `@squadbase/vantage-sdk/server` | `connection`(Connection の宛先と認証を解決する。server/ 側でのみ使う) |
+
+### 使い方
+
+`connection(ctx, connectionId)` は**宛先(`baseUrl`)と認証ヘッダー(`headers`)を解決するだけ**で、
+リクエストは自分で `fetch` する。
+
+```ts
+import type { ApiContext } from "@squadbase/vantage/server"
+import { HttpError } from "@squadbase/vantage/server"
+import { connection } from "@squadbase/vantage-sdk/server"
+
+const CONNECTION_ID = "..."
+const QUERY_ID = "..."
+
+export async function GET(ctx: ApiContext) {
+  const { baseUrl, headers } = await connection(ctx, CONNECTION_ID)
+
+  const res = await fetch(`${baseUrl}/queries/${QUERY_ID}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", ...headers },
+    body: JSON.stringify({ params: {} }),
+  })
+  if (!res.ok) throw new HttpError(502, `query execution failed: ${res.status}`)
+
+  const { columns, rows } = await res.json()
+  return Response.json({ columns, rows })
+}
+```
+
+- **`ctx` をそのまま渡す。** `connection` が読むのは `ctx.request` と `ctx.env` だけなので、
+  `ApiContext` をそのまま渡せる(第 1 引数を自作しない)。
+- **`baseUrl` はバージョン接頭辞込み・末尾スラッシュ無し。** そのままパスを繋ぐ。
+- **`headers` は必ずスプレッドする**(`{ "Content-Type": "application/json", ...headers }`)。
+- **Query は id だけで指す**: `POST {baseUrl}/queries/{queryId}`。Connection は Query 側から
+  解決されるので、**パスに connection id を入れない**(`connection` の引数として渡すだけ)。
+- **プレビューでもデプロイ済みアプリでも同じコードが動く。** Squadbase の外で走らせると
+  `connection` は throw する。
+
+### SQL Query と HTTP Query で body の形が違う
+
+| Query 種別 | リクエスト | レスポンス |
+| --- | --- | --- |
+| SQL Query | 引数は `{ params: { … } }` に入れる | `{ columns: [{ name, type? }], rows: [{ … }] }` |
+| HTTP Query | Query が宣言した形をそのまま(`params` で包まない)。クエリ文字列は URL に載せる | 上流サービスのレスポンスをそのまま通す(非 2xx も来るので `res.ok` を必ず見る) |
+
+```ts
+// HTTP Query — クエリ文字列は URL、body は Query の宣言どおり
+const res = await fetch(`${baseUrl}/queries/${QUERY_ID}?since=2026-01-01`, {
+  method: "POST",
+  headers: { "Content-Type": "application/json", ...headers },
+  body: JSON.stringify({ customerId: "c_123" }),
+})
+```
+
+## 構築中の一時的なエラーを「進行中」に見せる(`components/build-recovery.tsx`)
+
+ページを書いている途中は、ファイルが書き終わる順番の都合で一瞬だけページが throw する
+(まだ存在しないモジュールの import、書きかけのコンポーネント)。これを受け止めるのは
+**Vantage の既定エラー画面**(`Something went wrong`)で、**テンプレートからは差し替えられない** —
+`_error.tsx` はルートルート専用で、ページごとの `errorComponent` は現行プロトタイプでは
+まだ結線されていない。しかも掴んでいるのは TanStack の CatchBoundary なので、HMR で
+ソースが差し替わってもリセットされず、**リロードするまでエラー画面が貼り付く**。
+
+`components/build-recovery.tsx` の `BuildRecovery` が、その画面を DOM から検知して
+`Working on it…` 表示を被せ、dev では 1.2 秒待ってから自動でリロードして復帰させる
+(上限 3 回。使い切ったら「再読み込み」の案内に降格し、無事に描けたら残数が戻る)。
+降格した画面にはエラー本文をそのまま出し、`Copy log` でコピーできるようにしてある —
+自力で直らないときに本文をそのまま貼り戻してもらうため。
+`_error.tsx` も同じ `RecoveringState` を描くので、ルートレイアウトが throw したときの
+見た目と復帰の仕方は揃っている。
+
+### 追加の不変条件
+
+- **`_layout.tsx` の `<BuildRecovery>` を外さない。** `<Outlet />` を包む形で 1 回だけ使う。
+  外すと、書き込み途中の一瞬のエラーが `Something went wrong` のまま残る。
+- **`components/build-recovery.tsx` と `_error.tsx` を消さない・作り直さない。** ページ側に
+  独自のエラー UI を足す必要はない(足しても既定エラー画面より内側には入れない)。
+- **`role="alert"` の中に `h2` を置かない。** これが既定エラー画面の目印なので、ページが
+  同じ形を描くと `BuildRecovery` が誤検知して中身を覆ってしまう。UI キットの `Alert` /
+  `ErrorState` は見出しを `div` / `p` で描くのでそのまま使ってよい。
+- **データ取得の失敗は各ページが `ErrorState` で出す。** `BuildRecovery` が拾うのは
+  「レンダリングが throw した」場合だけで、`useApiQuery` の `isError` はページの責任
+  (→ フレームワーク規約の「データ取得」)。

package/base-template/package.json

@@ -3,7 +3,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "vantage dev",
+    "dev": "vantage dev --no-overlay",
     "build": "vantage build",
     "start": "node dist/server/index.mjs",
     "preview": "vantage preview",
@@ -11,8 +11,9 @@
     "routes": "vantage routes"
   },
   "dependencies": {
-    "@squadbase/react": "^0.0.1",
-    "@squadbase/vantage": "^0.2.3",
+    "@squadbase/react": "^0.1.0",
+    "@squadbase/vantage": "^0.5.3",
+    "@squadbase/vantage-sdk": "^0.1.0",
     "date-fns": "^4.1.0",
     "lucide-react": "^0.468.0",
     "react": "^19.2.7",

package/base-template/src/_error.tsx

@@ -0,0 +1,10 @@
+import { RecoveringState } from "./components/build-recovery"
+
+/**
+ * ルートルート(= `_layout.tsx`)が throw したときの画面。ページのレンダリングエラーは
+ * ここには来ない — フレームワークの既定エラー画面が受け止め、その上を `BuildRecovery` が
+ * 覆う(→ `components/build-recovery.tsx`)。どちらも見た目と復帰の仕方は揃えてある。
+ */
+export default function RouteError({ error }: { error: unknown }) {
+  return <RecoveringState error={error} />
+}