@squadbase/vantage-template 0.0.1 → 0.0.2

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,11 @@ 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.
 
 ```bash
 npx @squadbase/vantage-template chart ocean

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/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` のトークンで行う。
@@ -39,6 +42,43 @@ UI キット・開発サーバー・API サーバー・ビルドはすべて Van
   ため、変数・関数呼び出し・テンプレート補間は使わない。`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 +122,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 +148,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 +168,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"
@@ -302,7 +346,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,7 +356,8 @@ 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)
 
@@ -337,3 +382,90 @@ vantage add skill --all --dir .claude/skills   # 置き場所を指定(既定は
 `add skill` はプロジェクト内を走査してから動くので、**再実行しても二重に配置されない**。
 配置済みのコピーを新しいバージョンに更新したいときだけ `--force` を付ける(見つかった場所を
 そのまま書き換える)。
+
+---
+
+# テンプレート固有の規約(Squadbase テンプレート)
+
+> ここから下は、Squadbase のテンプレートがフレームワーク正本に足した規約です。上の
+> フレームワーク規約と矛盾する場合は**こちらが優先**します。
+>
+> `vantage upgrade` はこのファイルをフレームワーク同梱の正本で丸ごと上書きするため、
+> このセクションは消えます。消えたら squadbase-templates リポジトリの `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" }),
+})
+```

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",
@@ -12,7 +12,8 @@
   },
   "dependencies": {
     "@squadbase/react": "^0.0.1",
-    "@squadbase/vantage": "^0.2.3",
+    "@squadbase/vantage": "^0.5.0",
+    "@squadbase/vantage-sdk": "^0.1.0-dev.0",
     "date-fns": "^4.1.0",
     "lucide-react": "^0.468.0",
     "react": "^19.2.7",

package/dist/index.js

@@ -4,12 +4,12 @@
 import { parseArgs } from "util";
 
 // src/commands/add.ts
-import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
-import { join as join4 } from "path";
+import { existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
+import { join as join5 } from "path";
 
 // src/ai/customize.ts
 import { readFileSync, writeFileSync } from "fs";
-import { join } from "path";
+import { join as join2 } from "path";
 
 // src/logger.ts
 var colors = {
@@ -24,6 +24,35 @@ function log(color, message) {
   console.log(`${colors[color]}${message}${colors.reset}`);
 }
 
+// src/project.ts
+import { existsSync } from "fs";
+import { join } from "path";
+var ROOT_LAYOUT_MARKERS = ["index.tsx", "_layout.tsx", "_404.tsx", "_error.tsx", "styles.css"];
+var AUTHORED_PAGE_PREFIX = "src/";
+function resolvePagePrefix(projectRoot) {
+  if (existsSync(join(projectRoot, "src"))) return AUTHORED_PAGE_PREFIX;
+  return findRootLayoutFiles(projectRoot).length > 0 ? "" : AUTHORED_PAGE_PREFIX;
+}
+function resolvePageRoot(projectRoot) {
+  return join(projectRoot, resolvePagePrefix(projectRoot));
+}
+function resolveStylesPath(projectRoot) {
+  return join(resolvePageRoot(projectRoot), "styles.css");
+}
+function resolveDest(entry, pagePrefix) {
+  return entry.scope === "root" ? entry.dest : pagePrefix + entry.dest;
+}
+function authoredDest(entry) {
+  return resolveDest(entry, AUTHORED_PAGE_PREFIX);
+}
+function findRootLayoutFiles(projectRoot) {
+  return ROOT_LAYOUT_MARKERS.filter((name) => existsSync(join(projectRoot, name)));
+}
+function findSplitLayoutFiles(projectRoot) {
+  if (!existsSync(join(projectRoot, "src"))) return [];
+  return findRootLayoutFiles(projectRoot);
+}
+
 // src/ai/diff.ts
 var ANSI = {
   reset: "\x1B[0m",
@@ -300,12 +329,13 @@ function buildUserPrompt(intent, files) {
   parts.push(`</FILES_TO_CUSTOMIZE>`);
   return parts.join("\n");
 }
-function readInputFiles(projectRoot, templateDir, entries, fromTemplate) {
+function readInputFiles(projectRoot, templateDir, entries, pagePrefix, fromTemplate) {
   const files = /* @__PURE__ */ new Map();
   for (const entry of entries) {
-    const path = fromTemplate ? join(templateDir, entry.src) : join(projectRoot, entry.dest);
+    const dest = resolveDest(entry, pagePrefix);
+    const path = fromTemplate ? join2(templateDir, entry.src) : join2(projectRoot, dest);
     try {
-      files.set(entry.dest, readFileSync(path, "utf-8"));
+      files.set(dest, readFileSync(path, "utf-8"));
     } catch (err) {
       throw new Error(
         `Failed to read ${path}: ${err instanceof Error ? err.message : String(err)}`
@@ -400,13 +430,14 @@ ${snippet}`);
   if (e.usage) parts.push(`Usage: ${JSON.stringify(e.usage)}`);
   return parts.join("\n");
 }
-async function customizeWithAI(projectRoot, manifest, templateDir, options) {
+async function customizeWithAI(projectRoot, manifest, templateDir, options, pagePrefix) {
   const relabelFiles = manifest.files.filter((f) => f.relabel !== false);
-  const allowedPaths = relabelFiles.map((f) => f.dest);
+  const allowedPaths = relabelFiles.map((f) => resolveDest(f, pagePrefix));
   const inputFiles = readInputFiles(
     projectRoot,
     templateDir,
     relabelFiles,
+    pagePrefix,
     options.dryRun
   );
   if (!options.json) {
@@ -515,7 +546,7 @@ ${edit.path}  (+${edit.added} -${edit.removed})`);
     }
   } else {
     for (const edit of edits) {
-      writeFileSync(join(projectRoot, edit.path), edit.after, "utf-8");
+      writeFileSync(join2(projectRoot, edit.path), edit.after, "utf-8");
       if (!options.json) {
         log("cyan", `  rewrote: ${edit.path} (+${edit.added} -${edit.removed})`);
       }
@@ -584,34 +615,34 @@ function parseEditsString(raw) {
 }
 
 // src/apply.ts
-import { copyFileSync, existsSync as existsSync2, mkdirSync } from "fs";
-import { dirname as dirname2, join as join3 } from "path";
+import { copyFileSync, existsSync as existsSync3, mkdirSync, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname2, join as join4, posix } from "path";
 
 // src/manifest.ts
-import { existsSync, readFileSync as readFileSync2, readdirSync } from "fs";
-import { dirname, join as join2 } from "path";
+import { existsSync as existsSync2, readFileSync as readFileSync2, readdirSync } from "fs";
+import { dirname, join as join3 } from "path";
 import { fileURLToPath } from "url";
 var __dirname = dirname(fileURLToPath(import.meta.url));
 function getTemplatesDir(source = "ui-templates") {
-  return join2(__dirname, "..", source);
+  return join3(__dirname, "..", source);
 }
 function getTemplateDir(templateName, source = "ui-templates") {
-  return join2(getTemplatesDir(source), templateName);
+  return join3(getTemplatesDir(source), templateName);
 }
 function listTemplateNames(source = "ui-templates") {
   const templatesDir = getTemplatesDir(source);
-  if (!existsSync(templatesDir)) {
+  if (!existsSync2(templatesDir)) {
     return [];
   }
   return readdirSync(templatesDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort();
 }
 function loadManifest(templateName, source = "ui-templates") {
   const templateDir = getTemplateDir(templateName, source);
-  if (!existsSync(templateDir)) {
+  if (!existsSync2(templateDir)) {
     throw new Error(`Template "${templateName}" not found.`);
   }
-  const manifestPath = join2(templateDir, "manifest.json");
-  if (!existsSync(manifestPath)) {
+  const manifestPath = join3(templateDir, "manifest.json");
+  if (!existsSync2(manifestPath)) {
     throw new Error(`Template "${templateName}" is missing manifest.json.`);
   }
   const raw = JSON.parse(readFileSync2(manifestPath, "utf-8"));
@@ -624,7 +655,8 @@ function loadManifest(templateName, source = "ui-templates") {
 // src/apply.ts
 function applyTemplate(projectRoot, manifest, options) {
   const templateDir = getTemplateDir(manifest.name, options.source ?? "ui-templates");
-  const conflicts = checkConflicts(projectRoot, manifest.files, options.force);
+  const pagePrefix = resolvePagePrefix(projectRoot);
+  const conflicts = checkConflicts(projectRoot, manifest.files, pagePrefix, options.force);
   if (conflicts.length > 0) {
     log("red", "File conflicts detected (use --force to overwrite):");
     for (const c of conflicts) {
@@ -633,36 +665,77 @@ function applyTemplate(projectRoot, manifest, options) {
     process.exit(1);
   }
   for (const file of manifest.files) {
-    const src = join3(templateDir, file.src);
-    const dest = join3(projectRoot, file.dest);
+    const src = join4(templateDir, file.src);
+    const destRel = resolveDest(file, pagePrefix);
+    const dest = join4(projectRoot, destRel);
     if (options.dryRun) {
       const label2 = file.action === "replace" ? "replace" : "add";
-      log("dim", `  [dry-run] ${label2}: ${file.dest}`);
+      log("dim", `  [dry-run] ${label2}: ${destRel}`);
       continue;
     }
     mkdirSync(dirname2(dest), { recursive: true });
-    copyFileSync(src, dest);
+    const authored = isRewritable(file.src) ? readFileSync3(src, "utf-8") : null;
+    const retargeted = authored === null ? null : retargetRelativeImports(authored, file, pagePrefix);
+    if (retargeted === null) {
+      copyFileSync(src, dest);
+    } else {
+      writeFileSync2(dest, retargeted, "utf-8");
+    }
     const label = file.action === "replace" ? "replaced" : "added";
-    log("cyan", `  ${label}: ${file.dest}`);
+    const note = retargeted !== null && retargeted !== authored ? " (imports retargeted)" : "";
+    log("cyan", `  ${label}: ${destRel}${note}`);
   }
 }
-function checkConflicts(projectRoot, files, force) {
+function checkConflicts(projectRoot, files, pagePrefix, force) {
   if (force) return [];
-  return files.filter((f) => f.action === "add" && existsSync2(join3(projectRoot, f.dest))).map((f) => f.dest);
+  return files.filter((f) => f.action === "add").map((f) => resolveDest(f, pagePrefix)).filter((dest) => existsSync3(join4(projectRoot, dest)));
+}
+var REWRITABLE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mts", ".mjs", ".cts", ".cjs"];
+function isRewritable(srcPath) {
+  return REWRITABLE_EXTENSIONS.some((ext) => srcPath.endsWith(ext));
+}
+var RELATIVE_SPECIFIER = /(\bfrom\s*|\bimport\s*\(\s*|\brequire\s*\(\s*|\bimport\s+)(["'])(\.{1,2}\/[^"']*)\2/g;
+function retargetRelativeImports(source, entry, pagePrefix) {
+  if (pagePrefix === AUTHORED_PAGE_PREFIX) return source;
+  const fromAuthored = posix.dirname(authoredDest(entry));
+  const fromActual = posix.dirname(resolveDest(entry, pagePrefix));
+  return source.replace(RELATIVE_SPECIFIER, (match, head, quote, spec) => {
+    const authoredTarget = posix.normalize(posix.join(fromAuthored, spec));
+    const actualTarget = retargetPath(authoredTarget, pagePrefix);
+    if (actualTarget === authoredTarget && fromActual === fromAuthored) return match;
+    let next = posix.relative(fromActual, actualTarget);
+    if (!next.startsWith(".")) next = `./${next}`;
+    return `${head}${quote}${next}${quote}`;
+  });
+}
+function retargetPath(authoredPath, pagePrefix) {
+  if (!authoredPath.startsWith(AUTHORED_PAGE_PREFIX)) return authoredPath;
+  return pagePrefix + authoredPath.slice(AUTHORED_PAGE_PREFIX.length);
 }
 
 // src/commands/add.ts
 function isVantageProject(projectRoot) {
-  const pkgPath = join4(projectRoot, "package.json");
-  if (!existsSync3(pkgPath)) return false;
+  const pkgPath = join5(projectRoot, "package.json");
+  if (!existsSync4(pkgPath)) return false;
   try {
-    const pkg = JSON.parse(readFileSync3(pkgPath, "utf-8"));
+    const pkg = JSON.parse(readFileSync4(pkgPath, "utf-8"));
     return Boolean(pkg.dependencies?.["@squadbase/vantage"] ?? pkg.devDependencies?.["@squadbase/vantage"]);
   } catch {
     return false;
   }
 }
-function findStaleTemplateFiles(projectRoot, appliedTemplate, source) {
+function refuseSplitLayout(projectRoot) {
+  const rootPages = findSplitLayoutFiles(projectRoot);
+  if (rootPages.length === 0) return;
+  log("red", "This project has pages both in src/ and at the project root.");
+  log("yellow", "  Vantage scans only src/ once it exists. Move these into src/, then re-run:");
+  for (const name of rootPages) log("dim", `    ${name}`);
+  log("dim", "  Any components/ hooks/ lib/ directories holding page code move with them.");
+  log("dim", "  server/ and public/ stay at the project root.");
+  log("dim", "  Leaving both sides in place fails `vantage check` with SRC_DIR_SPLIT.");
+  process.exit(1);
+}
+function findStaleTemplateFiles(projectRoot, appliedTemplate, source, pagePrefix) {
   const stale = [];
   for (const name of listTemplateNames(source)) {
     if (name === appliedTemplate) continue;
@@ -675,7 +748,8 @@ function findStaleTemplateFiles(projectRoot, appliedTemplate, source) {
     }
     for (const file of manifest.files) {
       if (file.action !== "add") continue;
-      if (existsSync3(join4(projectRoot, file.dest))) stale.push(file.dest);
+      const dest = resolveDest(file, pagePrefix);
+      if (existsSync4(join5(projectRoot, dest))) stale.push(dest);
     }
   }
   return [...new Set(stale)].sort();
@@ -688,6 +762,8 @@ async function addTemplate(templateName, options) {
     log("dim", "Run 'npx @squadbase/vantage-template init' first.");
     process.exit(1);
   }
+  refuseSplitLayout(projectRoot);
+  const pagePrefix = resolvePagePrefix(projectRoot);
   const available = listTemplateNames(source);
   if (!available.includes(templateName)) {
     log("red", `Template "${templateName}" not found in ${source}/.`);
@@ -704,13 +780,14 @@ async function addTemplate(templateName, options) {
       log("yellow", "(dry run \u2014 no files will be changed)");
     }
     const entry = manifest.files.find((f) => f.action === "replace");
-    if (entry && existsSync3(join4(projectRoot, entry.dest))) {
-      log("yellow", `  ${entry.dest} will be overwritten \u2014 commit first if it holds your work.`);
+    const entryDest = entry ? resolveDest(entry, pagePrefix) : void 0;
+    if (entryDest && existsSync4(join5(projectRoot, entryDest))) {
+      log("yellow", `  ${entryDest} will be overwritten \u2014 commit first if it holds your work.`);
     }
   }
   applyTemplate(projectRoot, manifest, options);
   if (!options.ai?.json) {
-    const stale = findStaleTemplateFiles(projectRoot, templateName, source);
+    const stale = findStaleTemplateFiles(projectRoot, templateName, source, pagePrefix);
     if (stale.length > 0) {
       log("yellow", "\nLeftovers from a previously applied template (nothing imports them):");
       for (const dest of stale) log("dim", `  ${dest}`);
@@ -718,7 +795,13 @@ async function addTemplate(templateName, options) {
     }
   }
   if (options.ai) {
-    const result = await customizeWithAI(projectRoot, manifest, templateDir, options.ai);
+    const result = await customizeWithAI(
+      projectRoot,
+      manifest,
+      templateDir,
+      options.ai,
+      pagePrefix
+    );
     if (options.ai.json) {
       console.log(
         JSON.stringify(
@@ -777,12 +860,12 @@ Run "git diff" to review the AI changes.`);
 }
 
 // src/commands/chart.ts
-import { existsSync as existsSync5 } from "fs";
-import { join as join6 } from "path";
+import { existsSync as existsSync6 } from "fs";
+import { relative as relative2 } from "path";
 
 // src/chart-presets.ts
-import { existsSync as existsSync4, readFileSync as readFileSync4, readdirSync as readdirSync2, writeFileSync as writeFileSync2 } from "fs";
-import { dirname as dirname3, join as join5 } from "path";
+import { existsSync as existsSync5, readFileSync as readFileSync5, readdirSync as readdirSync2, writeFileSync as writeFileSync3 } from "fs";
+import { dirname as dirname3, join as join6, relative } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 var __dirname2 = dirname3(fileURLToPath2(import.meta.url));
 var PRESET_DESCRIPTIONS = {
@@ -796,34 +879,34 @@ var PRESET_DESCRIPTIONS = {
 var BEGIN_MARKER = "/* vantage-template:chart-preset \u2014 regenerated by `chart`; edits here are lost */";
 var END_MARKER = "/* vantage-template:chart-preset:end */";
 function getChartPresetsDir() {
-  return join5(__dirname2, "..", "chart-presets");
+  return join6(__dirname2, "..", "chart-presets");
 }
 function listChartPresetNames() {
   const dir = getChartPresetsDir();
-  if (!existsSync4(dir)) return [];
+  if (!existsSync5(dir)) return [];
   return readdirSync2(dir).filter((f) => f.endsWith(".css")).map((f) => f.replace(/\.css$/, "")).sort();
 }
 function getChartPresetDescription(name) {
   return PRESET_DESCRIPTIONS[name] ?? "";
 }
 function getChartPresetPath(name) {
-  return join5(getChartPresetsDir(), `${name}.css`);
+  return join6(getChartPresetsDir(), `${name}.css`);
 }
 function applyChartPreset(projectRoot, presetName, options = {}) {
   const presetPath = getChartPresetPath(presetName);
-  if (!existsSync4(presetPath)) {
+  if (!existsSync5(presetPath)) {
     throw new Error(`Chart preset "${presetName}" not found.`);
   }
-  const targetPath = join5(projectRoot, "styles.css");
-  if (!existsSync4(targetPath)) {
-    throw new Error("styles.css not found in project.");
+  const targetPath = resolveStylesPath(projectRoot);
+  if (!existsSync5(targetPath)) {
+    throw new Error(`${relative(projectRoot, targetPath)} not found in project.`);
   }
-  const preset = readFileSync4(presetPath, "utf-8").trimEnd();
+  const preset = readFileSync5(presetPath, "utf-8").trimEnd();
   const block = `${BEGIN_MARKER}
 ${preset}
 ${END_MARKER}
 `;
-  const current = readFileSync4(targetPath, "utf-8");
+  const current = readFileSync5(targetPath, "utf-8");
   const begin = current.indexOf(BEGIN_MARKER);
   const end = current.indexOf(END_MARKER);
   let content;
@@ -835,7 +918,7 @@ ${END_MARKER}
 ${block}`;
   }
   if (!options.dryRun) {
-    writeFileSync2(targetPath, content, "utf-8");
+    writeFileSync3(targetPath, content, "utf-8");
   }
   return { targetPath, content };
 }
@@ -843,9 +926,10 @@ ${block}`;
 // src/commands/chart.ts
 function setChartPreset(presetName, options) {
   const projectRoot = process.cwd();
-  const stylesPath = join6(projectRoot, "styles.css");
-  if (!existsSync5(stylesPath)) {
-    log("red", "styles.css not found. Are you in a Squadbase Vantage project?");
+  const stylesPath = resolveStylesPath(projectRoot);
+  const stylesLabel = relative2(projectRoot, stylesPath);
+  if (!existsSync6(stylesPath)) {
+    log("red", `${stylesLabel} not found. Are you in a Squadbase Vantage project?`);
     process.exit(1);
   }
   const available = listChartPresetNames();
@@ -864,18 +948,19 @@ function setChartPreset(presetName, options) {
   if (options.dryRun) {
     log("yellow", "(dry run \u2014 no files will be changed)");
     const { content } = applyChartPreset(projectRoot, presetName, { dryRun: true });
-    log("dim", "\n--- styles.css (preview) ---");
+    log("dim", `
+--- ${stylesLabel} (preview) ---`);
     console.log(content);
     return;
   }
   applyChartPreset(projectRoot, presetName);
-  log("cyan", "  updated: styles.css");
+  log("cyan", `  updated: ${stylesLabel}`);
   log("green", "\nChart preset applied successfully!");
 }
 
 // src/commands/init.ts
 import { spawnSync } from "child_process";
-import { cpSync, existsSync as existsSync6, mkdirSync as mkdirSync2, readdirSync as readdirSync3 } from "fs";
+import { cpSync, existsSync as existsSync7, mkdirSync as mkdirSync2, readdirSync as readdirSync3 } from "fs";
 import { dirname as dirname4, join as join7 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 var __dirname3 = dirname4(fileURLToPath3(import.meta.url));
@@ -888,7 +973,7 @@ function getBaseTemplateDir() {
 function initProject(options) {
   const targetDir = process.cwd();
   const baseTemplateDir = getBaseTemplateDir();
-  if (!existsSync6(baseTemplateDir)) {
+  if (!existsSync7(baseTemplateDir)) {
     log("red", "Base template not found. The package may be corrupted.");
     process.exit(1);
   }
@@ -902,13 +987,16 @@ function initProject(options) {
       process.exit(1);
     }
   }
-  if (!options.force && existsSync6(join7(targetDir, "squadbase.yml"))) {
+  if (!options.force && existsSync7(join7(targetDir, "squadbase.yml"))) {
     log("red", "This directory already contains a Squadbase project (squadbase.yml exists).");
     log("yellow", "Use --force to overwrite.");
     process.exit(1);
   }
-  if (!options.force && existsSync6(join7(targetDir, "index.tsx"))) {
-    log("red", "This directory already contains an index.tsx.");
+  const existingEntry = ["src/index.tsx", "index.tsx"].find(
+    (rel) => existsSync7(join7(targetDir, rel))
+  );
+  if (!options.force && existingEntry) {
+    log("red", `This directory already contains a ${existingEntry}.`);
     log("yellow", "Use --force to overwrite.");
     process.exit(1);
   }
@@ -922,7 +1010,7 @@ function initProject(options) {
       mkdirSync2(dest, { recursive: true });
       cpSync(src, dest, { recursive: true, force: options.force });
     } else {
-      if (!options.force && existsSync6(dest)) {
+      if (!options.force && existsSync7(dest)) {
         log("yellow", `  skipped (exists): ${destName}`);
         continue;
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squadbase/vantage-template",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "CLI tool for initializing and customizing Squadbase Vantage projects.",
   "keywords": [
     "squadbase",
@@ -38,11 +38,14 @@
   "scripts": {
     "sync-base": "rsync -a --delete --exclude='node_modules' --exclude='dist' --exclude='.vantage' --exclude='package-lock.json' --exclude='*.tsbuildinfo' --exclude='*.log' ../vantage/ base-template/ && mv base-template/.gitignore base-template/_gitignore",
     "build": "npm run sync-base && tsup",
-    "prepublishOnly": "npm run build",
-    "release": "npm publish --@squadbase:registry=https://registry.npmjs.org"
+    "prepublishOnly": "npm --prefix .. run agents:check && npm run build",
+    "release": "npm publish --@squadbase:registry=https://registry.npmjs.org",
+    "dev": "node scripts/dev.mjs",
+    "screenshot": "node scripts/screenshot.mjs"
   },
   "devDependencies": {
     "@types/node": "^22.15.0",
+    "playwright": "^1.49.0",
     "tsup": "^8.4.0",
     "typescript": "~5.7.0"
   },

package/ui-templates/CLAUDE.md

@@ -6,7 +6,7 @@ UIパターン別テンプレート（KPI重視・チャート格子・テーブ
 
 このファイルは `vantage-template/ui-templates/` 配下のファイル構成ルールを定義する。デザイン要件・AI relabel・EN/JA・CLI の挙動は親 [`../CLAUDE.md`](../CLAUDE.md) に従う。
 
-> **Vite 版との差分**: 適用先が Vantage アプリ（`@squadbase/vantage`）になったため、(1) エントリは `src/pages/home.tsx` ではなく **ルートの `index.tsx`**、(2) テンプレ固有ファイルは `src/templates/<slug>/` ではなく **`components/<slug>/`**、(3) 全ての building block を `@squadbase/vantage/*` から import する（ローカルコピーは持たない）。
+> **Vite 版との差分**: 適用先が Vantage アプリ（`@squadbase/vantage`）になったため、(1) エントリは `src/pages/home.tsx` ではなく **`src/index.tsx`**、(2) テンプレ固有ファイルは `src/templates/<slug>/` ではなく **`src/components/<slug>/`**、(3) 全ての building block を `@squadbase/vantage/*` から import する（ローカルコピーは持たない）。
 
 ## 設計目標
 
@@ -20,21 +20,25 @@ UIパターン別テンプレート（KPI重視・チャート格子・テーブ
 
 ### 1. 1テンプレ = 1ディレクトリ（コロケーション）
 
-適用先では、`index.tsx`（エントリ）以外のテンプレ固有ファイルを **`components/<slug>/` 1ディレクトリに集約** する。
+適用先では、`src/index.tsx`（エントリ）以外のテンプレ固有ファイルを **`src/components/<slug>/` 1ディレクトリに集約** する。
 
 ```
 # 適用先（dest）レイアウト
-index.tsx                             # エントリ（ルート "/"）
-components/<slug>/
+src/index.tsx                         # エントリ（ルート "/"）
+src/components/<slug>/
   mock-data.ts                        # データ層（relabel:false / 差し替え対象）
   types.ts                            # 型（index と data で共有）
   ...（分割した場合のみ追加ファイル）
 ```
 
-- **探索**: `components/<slug>/` を見ればテンプレ由来が一覧完結
-- **削除**: `rm -rf components/<slug>/` で一掃
+- **探索**: `src/components/<slug>/` を見ればテンプレ由来が一覧完結
+- **削除**: `rm -rf src/components/<slug>/` で一掃
 
-**`components/` を使う理由（重要）**: Vantage は**ファイルベースルーティング**で、`.tsx` ファイルは原則すべてページ扱いになる。`components/` / `hooks/` / `lib/` / `server/` / `public/` だけがルート走査から除外される（`NON_ROUTE_DIRS`）ため、`templates/<slug>/` のようなディレクトリに `.tsx` を置くと **`/templates/<slug>/...` という意図しないルートが生え、`vantage check` が `MISSING_DEFAULT_EXPORT` で落ちる**。データファイル（`.ts`）も同じディレクトリに置いてコロケーションを保つ。
+**`src/` を使う理由（v0.3.0 以降）**: ページ探索ルートは `src/` の有無だけで決まる。ベーステンプレートは `src/` を持つので、ページとそれが import するものは**すべて `src/` の中**に置く。`src/` があるのにルート直下に `.tsx` や `styles.css` を残すと `vantage check` が `SRC_DIR_SPLIT` エラーにする。**例外は `server/` と `public/` で、これらは常にプロジェクトルート直下**（`src/server/` はスキャンされない）。
+
+**ただし manifest の `dest` に `src/` は書かない。** `dest` は**ページ探索ルート相対**（`index.tsx` / `components/<slug>/x.tsx`）で、`src/` を付けるかどうかは適用先のレイアウトを見て CLI が決める（ルート直下にページを置くプロジェクトにも適用できる）。`server/` `public/` だけ `"scope": "root"` を付けてプロジェクトルート固定にする。オーサリング側のファイルは**常に `src/` レイアウト前提**で書き、`src/` を跨ぐ相対 import は適用時に CLI が張り替える。
+
+**`components/` を使う理由（重要）**: Vantage は**ファイルベースルーティング**で、`.tsx` ファイルは原則すべてページ扱いになる。`components/` / `hooks/` / `lib/` / `server/` / `public/` だけがルート走査から除外される（`NON_ROUTE_DIRS`）ため、`src/templates/<slug>/` のようなディレクトリに `.tsx` を置くと **`/templates/<slug>/...` という意図しないルートが生え、`vantage check` が `MISSING_DEFAULT_EXPORT` で落ちる**（`SUSPICIOUS_ROUTE_DIR` 警告も出る）。データファイル（`.ts`）も同じディレクトリに置いてコロケーションを保つ。
 
 ### 2. インライン優先 — 薄いラッパ component を作らない
 
@@ -55,20 +59,21 @@ function areaOption(data: TimePoint[]): EChartsOption {
 
 ### 3. データ層（mock-data / types）は分離する
 
-`mock-data.ts` と `types.ts` は `index.tsx` に inline せず、`components/<slug>/` の別ファイルに保つ。表示ラベル（KPI名・軸名・stage名など）は描画側（`index.tsx`）の literal/const に置き、データ配列には値・id・generic な sample text のみ置く。
+`mock-data.ts` と `types.ts` は `src/index.tsx` に inline せず、`src/components/<slug>/` の別ファイルに保つ。表示ラベル（KPI名・軸名・stage名など）は描画側（`index.tsx`）の literal/const に置き、データ配列には値・id・generic な sample text のみ置く。
 
 ### 3-b. API 版テンプレ（`server/api` から配信する場合）
 
-`kpi-chart-simple` はモック配列を直読みせず、**`server/api` から `useApiQuery` で取る**構成になっている。実データ接続までの導線を1本コードで示すためのもので、この構成を採るテンプレは dest の置き場が変わる:
+`kpi-chart-simple` はモック配列を直読みせず、**`server/api` から `useApiQuery` で取る**構成になっている。実データ接続までの導線を1本コードで示すためのもので、この構成を採るテンプレは置き場が変わる（以下は `src/` レイアウトに適用したときの実配置。manifest の `dest` は `src/` を除いた形で書く）:
 
 ```
-index.tsx                                # useApiQuery + useSearchParam
-components/<slug>/*.tsx                  # 表示コンポーネント
-lib/<slug>/types.ts                      # ★ client と server が共有する型（relabel:false）
-server/api/<endpoint>.ts                 # ★ サンプルデータ + GET ハンドラ（relabel:false）
+src/index.tsx                            # useApiQuery + useSearchParam
+src/components/<slug>/*.tsx              # 表示コンポーネント
+src/lib/<slug>/types.ts                  # ★ client と server が共有する型（relabel:false）
+server/api/<endpoint>.ts                 # ★ サンプルデータ + GET ハンドラ（relabel:false）※ルート直下
 ```
 
-- **共有型は `components/` ではなく `lib/`** に置く。クライアントは `server/` を import できない（`CLIENT_IMPORTS_SERVER`）ので、両者が参照できる中立な場所が要る。`lib/` もルート走査対象外なので安全。
+- **共有型は `components/` ではなく `src/lib/`** に置く。クライアントは `server/` を import できない（`CLIENT_IMPORTS_SERVER`）ので、両者が参照できる中立な場所が要る。`lib/` もルート走査対象外なので安全。
+- **`server/` は `src/` の外**なので、ハンドラからの相対 import は `src/` を跨ぐ: `server/api/<endpoint>.ts` からは `../../src/lib/<slug>/types`。`src/components/<slug>/*.tsx` からは `../../lib/<slug>/types`（どちらも `src/` の中なので `src/` は出てこない）。
 - **サンプルデータはサーバー側に置く。** 「実装者が差し替える場所」がハンドラ1箇所に集約され、`KpiSummary` のような payload 型さえ保てばページを触らずに実データへ移行できる。
 - **絞り込みは `useSearchParam` + `useApiQuery` の `search`** で組む。`search` はクエリ文字列とキャッシュキーの両方に入るので、URL を変えれば再取得される。
 - クライアントに見せたいエラーは `HttpError(status, msg)` を throw する。`useApiQuery` の `error` は `ApiError` なのでキャスト不要で `.message` が読める。
@@ -81,7 +86,7 @@ server/api/<endpoint>.ts                 # ★ サンプルデータ + GET ハ
 
 ### 分割してよい例外
 
-**再利用される** / **内部 state・interaction を持つ** / **`index.tsx` が 400〜500 行を超える** のいずれかに当てはまる UI のみ、`components/<slug>/` 配下に切り出してよい。迷ったら inline。
+**再利用される** / **内部 state・interaction を持つ** / **`index.tsx` が 400〜500 行を超える** のいずれかに当てはまる UI のみ、`src/components/<slug>/` 配下に切り出してよい。迷ったら inline。
 
 ## import 規約（Vantage）
 
@@ -101,11 +106,14 @@ server/api/<endpoint>.ts                 # ★ サンプルデータ + GET ハ
 **相対 import は拡張子なしで書く**（`@squadbase/vantage` v0.2.0 で `.js` 指定子の規約は廃止。既存の `.js` 付き import も動くが、新規テンプレでは付けない）。
 
 ```tsx
-// index.tsx から
+// src/index.tsx から
 import { MOCK_SERIES } from "./components/<slug>/mock-data"
 
-// components/<slug>/detail-table.tsx から
+// src/components/<slug>/detail-table.tsx から
 import type { Row } from "./types"
+
+// server/api/<endpoint>.ts から（src/ の外なので src/ を跨ぐ）
+import type { Payload } from "../../src/lib/<slug>/types"
 ```
 
 `Placeholder` / `Sparkline` はローカルコピーではなく `@squadbase/vantage/components` から取る（v0.1.1 でフレームワークに入った）。
@@ -123,7 +131,7 @@ Vantage の UI キットは Radix ではなく **Base UI** ベース。移植時
 
 ## エントリの必須要件
 
-`index.tsx` は **default export の React component** が必須（無いと `vantage check` が `MISSING_DEFAULT_EXPORT`）。加えてタイトル/説明を `definePage` で宣言する:
+`src/index.tsx` は **default export の React component** が必須（無いと `vantage check` が `MISSING_DEFAULT_EXPORT`）。加えてタイトル/説明を `definePage` で宣言する:
 
 ```tsx
 import { definePage } from "@squadbase/vantage"
@@ -150,9 +158,11 @@ ui-templates/<slug>/
   lib/mock-data.ts      → dest: components/<slug>/mock-data.ts     (add, relabel:false)
   lib/types.ts          → dest: components/<slug>/types.ts         (add, relabel:false)
   components/*.tsx      → dest: components/<slug>/*.tsx            (add)  ※分割した場合のみ
-  server/*.ts           → dest: server/api/*.ts                    (add, relabel:false) ※API 版のみ
+  server/*.ts           → dest: server/api/*.ts, scope: "root"     (add, relabel:false) ※API 版のみ
 ```
 
+**オーサリング側のディレクトリ名（`pages/` `lib/` `components/` `server/`）は適用先の dest と一致しない。** dest だけが真実で、`manifest.json` に書く。**dest はページ探索ルート相対なので `src/` は付けない**（`scope: "root"` のものだけプロジェクトルート相対）。
+
 API 版（`kpi-chart-simple`）では `lib/types.ts` の dest が `lib/<slug>/types.ts` になり、`lib/mock-data.ts` は無く、代わりに `server/*.ts` を持つ。上の「3-b」を参照。
 
 ## manifest.json
@@ -172,6 +182,7 @@ API 版（`kpi-chart-simple`）では `lib/types.ts` の dest が `lib/<slug>/ty
 
 - `files[]` が manifest の全て（`nav[]` は無い）。ベーステンプレートのナビは `useRoutes()` からルート一覧を組むので、ページファイルをコピーすればナビにも載る
 - データファイルには `"relabel": false` を必ず付ける
+- `dest` に `src/` を書かない。`server/` `public/` にだけ `"scope": "root"` を付ける
 
 ## 見本市の例外ルール
 
@@ -189,7 +200,7 @@ API 版（`kpi-chart-simple`）では `lib/types.ts` の dest が `lib/<slug>/ty
 
 ## チェックリスト（テンプレ追加・改修時）
 
-1. テンプレ固有ファイルの `dest` は `components/<slug>/` 配下か（`templates/` に `.tsx` を置いていないか）
+1. テンプレ固有ファイルの `dest` は `components/<slug>/` 配下か（`templates/` に `.tsx` を置いていないか）。`dest` に `src/` を書いていないか。`server/*` だけ `dest: server/api/*` + `"scope": "root"` か
 2. `@/` エイリアスや `echarts` / `@tanstack/*` の直接 import、`Placeholder` / `Sparkline` のローカル import が残っていないか
 3. 相対 import に `.js` 拡張子が残っていないか（v0.2.0 で規約廃止）
 4. 薄いチャートラッパ component を作っていないか。チャートに色をハードコードしていないか（`option.color` / `itemStyle.color` / `theme`）
@@ -197,4 +208,4 @@ API 版（`kpi-chart-simple`）では `lib/types.ts` の dest が `lib/<slug>/ty
 6. 未使用の関数・型・import が残っていないか
 7. 適用先で `npx vantage check` と `npx tsc --noEmit` が通るか
 8. EN/JA 両方を同じ構成に揃えたか
-9. レイアウトを変えたなら `preview-wide.png` (1600x900) / `preview-square.png` (1200x1200) を撮り直したか
+9. レイアウトを変えたなら `preview-wide.png` (1600x900) / `preview-square.png` (1200x1200) を撮り直したか — `cd vantage-template && npm run screenshot <slug> <slug>-ja`（全部撮り直すなら引数なし）

package/ui-templates/kpi-chart-simple/manifest.json

@@ -6,6 +6,6 @@
     { "src": "pages/index.tsx", "dest": "index.tsx", "action": "replace" },
     { "src": "components/top-items-table.tsx", "dest": "components/kpi-chart-simple/top-items-table.tsx", "action": "add" },
     { "src": "lib/types.ts", "dest": "lib/kpi-chart-simple/types.ts", "action": "add", "relabel": false },
-    { "src": "server/kpi-summary.ts", "dest": "server/api/kpi-summary.ts", "action": "add", "relabel": false }
+    { "src": "server/kpi-summary.ts", "dest": "server/api/kpi-summary.ts", "scope": "root", "action": "add", "relabel": false }
   ]
 }

package/ui-templates/kpi-chart-simple/server/kpi-summary.ts

@@ -7,7 +7,7 @@ import type {
   RangeKey,
   TopItemRow,
   TrendPoint,
-} from "../../lib/kpi-chart-simple/types"
+} from "../../src/lib/kpi-chart-simple/types"
 
 /**
  * `GET /api/kpi-summary?range=7d|30d|90d`

package/ui-templates/kpi-chart-simple-ja/manifest.json

@@ -6,6 +6,6 @@
     { "src": "pages/index.tsx", "dest": "index.tsx", "action": "replace" },
     { "src": "components/top-items-table.tsx", "dest": "components/kpi-chart-simple/top-items-table.tsx", "action": "add" },
     { "src": "lib/types.ts", "dest": "lib/kpi-chart-simple/types.ts", "action": "add", "relabel": false },
-    { "src": "server/kpi-summary.ts", "dest": "server/api/kpi-summary.ts", "action": "add", "relabel": false }
+    { "src": "server/kpi-summary.ts", "dest": "server/api/kpi-summary.ts", "scope": "root", "action": "add", "relabel": false }
   ]
 }

package/ui-templates/kpi-chart-simple-ja/server/kpi-summary.ts

@@ -7,7 +7,7 @@ import type {
   RangeKey,
   TopItemRow,
   TrendPoint,
-} from "../../lib/kpi-chart-simple/types"
+} from "../../src/lib/kpi-chart-simple/types"
 
 /**
  * `GET /api/kpi-summary?range=7d|30d|90d`