@squadbase/vantage 0.2.3 → 0.3.0

package/dist/index.d.ts

@@ -10,6 +10,6 @@ import 'react';
  */
 
 /** Framework version, kept in sync with package.json at build time. */
-declare const VERSION = "0.2.3";
+declare const VERSION = "0.3.0";
 
 export { VERSION };

package/dist/index.js

@@ -6,7 +6,7 @@ function definePage(config) {
 }
 
 // src/index.ts
-var VERSION = "0.2.3";
+var VERSION = "0.3.0";
 
 export { VERSION, definePage };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/runtime/define-page.ts","../src/index.ts"],"names":[],"mappings":";;;AAyCO,SAAS,WAAW,MAAA,EAAgC;AACzD,EAAA,OAAO,MAAA;AACT;;;AChCO,IAAM,OAAA,GAAU","file":"index.js","sourcesContent":["import type { ComponentType, ReactNode } from \"react\"\n\n/**\n * Optional per-page configuration. The only required part of a page module is\n * its default-exported component; `definePage` covers everything else.\n */\nexport interface PageConfig {\n  /** Document title applied when this route is active. */\n  title?: string\n  /** Description metadata for the page. */\n  description?: string\n  /**\n   * Short label for navigation built from `useRoutes()`. Defaults to `title`,\n   * which is often too long for a nav (\"Overview · Acme Analytics\").\n   */\n  navLabel?: string\n  /**\n   * Component rendered while the route is loading.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  pendingComponent?: ComponentType\n  /**\n   * Component rendered when the route throws.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  errorComponent?: ComponentType<{ error: unknown }>\n  /**\n   * Validate/transform the URL search params for this route.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  validateSearch?: (search: Record<string, unknown>) => Record<string, unknown>\n}\n\n/**\n * Declare optional page configuration.\n *\n * ```tsx\n * export const page = definePage({ title: \"Monthly Analysis\" })\n * export default function MonthlyAnalysis() { return <div/> }\n * ```\n */\nexport function definePage(config: PageConfig): PageConfig {\n  return config\n}\n\n/** Convenience type for a Vantage page component. */\nexport type PageComponent = ComponentType & { (): ReactNode }\n","/**\n * `@squadbase/vantage` — public runtime surface.\n *\n * The only import most pages need. Server state lives in\n * `@squadbase/vantage/query`, navigation in `@squadbase/vantage/router`,\n * UI in `@squadbase/vantage/ui`, and API types in `@squadbase/vantage/server`.\n */\nexport { definePage } from \"./runtime/define-page\"\nexport type { PageConfig, PageComponent } from \"./runtime/define-page\"\n\n/** Framework version, kept in sync with package.json at build time. */\nexport const VERSION = \"0.2.3\"\n"]}
+{"version":3,"sources":["../src/runtime/define-page.ts","../src/index.ts"],"names":[],"mappings":";;;AAyCO,SAAS,WAAW,MAAA,EAAgC;AACzD,EAAA,OAAO,MAAA;AACT;;;AChCO,IAAM,OAAA,GAAU","file":"index.js","sourcesContent":["import type { ComponentType, ReactNode } from \"react\"\n\n/**\n * Optional per-page configuration. The only required part of a page module is\n * its default-exported component; `definePage` covers everything else.\n */\nexport interface PageConfig {\n  /** Document title applied when this route is active. */\n  title?: string\n  /** Description metadata for the page. */\n  description?: string\n  /**\n   * Short label for navigation built from `useRoutes()`. Defaults to `title`,\n   * which is often too long for a nav (\"Overview · Acme Analytics\").\n   */\n  navLabel?: string\n  /**\n   * Component rendered while the route is loading.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  pendingComponent?: ComponentType\n  /**\n   * Component rendered when the route throws.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  errorComponent?: ComponentType<{ error: unknown }>\n  /**\n   * Validate/transform the URL search params for this route.\n   * (Reserved — not yet applied to Vantage's code-split routes in the prototype.)\n   */\n  validateSearch?: (search: Record<string, unknown>) => Record<string, unknown>\n}\n\n/**\n * Declare optional page configuration.\n *\n * ```tsx\n * export const page = definePage({ title: \"Monthly Analysis\" })\n * export default function MonthlyAnalysis() { return <div/> }\n * ```\n */\nexport function definePage(config: PageConfig): PageConfig {\n  return config\n}\n\n/** Convenience type for a Vantage page component. */\nexport type PageComponent = ComponentType & { (): ReactNode }\n","/**\n * `@squadbase/vantage` — public runtime surface.\n *\n * The only import most pages need. Server state lives in\n * `@squadbase/vantage/query`, navigation in `@squadbase/vantage/router`,\n * UI in `@squadbase/vantage/ui`, and API types in `@squadbase/vantage/server`.\n */\nexport { definePage } from \"./runtime/define-page\"\nexport type { PageConfig, PageComponent } from \"./runtime/define-page\"\n\n/** Framework version, kept in sync with package.json at build time. */\nexport const VERSION = \"0.3.0\"\n"]}

package/dist/vite/index.js

@@ -1,4 +1,4 @@
-export { vantagePlugin } from '../chunk-3QKPNWKJ.js';
+export { vantagePlugin } from '../chunk-5UGRNXHC.js';
 import '../chunk-46QI6GFC.js';
 import '../chunk-B7LLBNLV.js';
 //# sourceMappingURL=index.js.map

package/docs/en/changelog.md

@@ -9,6 +9,53 @@ What changed in each Vantage release. Newest is on top.
 > minor release may include backwards-incompatible changes. A patch is limited to
 > backwards-compatible additions and bug fixes.
 
+## v0.3.0
+
+Vantage now recognises `src/` as a place to put pages. This carries a
+backwards-incompatible change (what gets scanned in a project that has a `src/`),
+so per the 0.x policy it goes out as a minor.
+
+Apps pinned to `"@squadbase/vantage": "^0.2.0"` will not pick up 0.3.0 — bump the
+range to `^0.3.0`.
+
+> [!WARNING]
+> **In a project with a `src/`, only `src/` is scanned for pages.** `src/` used to be
+> an ordinary directory, so `src/App.tsx` served `/src/App`. From 0.3.0, `src/`
+> becomes the page-scan root and drops out of the URL (`src/sales/index.tsx` →
+> `/sales`). **Pages and `styles.css` left at the project root are no longer
+> scanned**, and `vantage check` reports them as `SRC_DIR_SPLIT`. Projects without a
+> `src/` behave exactly as before.
+
+### Changed
+
+- **The page-scan root is decided by whether `src/` exists**
+  (see [File-based routing](routing)) — pages live inside `<root>/src` when it
+  exists, at the project root otherwise. Nothing is configured; it is detected. A
+  one-file app can stay at the root and move into `src/` once it grows. `server/`
+  and `public/` always stay at the project root, and `src/server/` is never scanned.
+- **`styles.css` is read from the same side as the pages** — `src/styles.css` when
+  the project has a `src/`.
+- **`vantage add page` / `add ui` / `add block` write relative to the page-scan
+  root** (`src/reports/index.tsx`, `src/components/ui/data-table.tsx`).
+- **Quick mode given a page file** now resolves the root by walking up to the
+  nearest `package.json` — `vantage ./demo/src/index.tsx` runs in `./demo` (it used
+  to take the parent directory, landing in `./demo/src`).
+
+### Added
+
+- **`SRC_DIR_SPLIT` (error)** — raised when `src/` exists but pages or `styles.css`
+  were left at the project root, or when `src/server/` exists. Each of those is a
+  "you placed it and nothing happened" failure, so it is an error rather than a
+  warning.
+- **`SUSPICIOUS_ROUTE_DIR` (warning)** — raised when a URL comes out of a
+  scaffolding-looking directory such as `pages/`, `app/` or `utils/`
+  (`pages/report.tsx` → `/pages/report`). Page scanning works off a deny list, so
+  any name not on it silently becomes a URL. Scanning is not stopped, so you can
+  ignore the warning when the URL is intentional.
+- The bundled `AGENTS.md` gained a "directory structure" section, and the skills
+  (`vantage-app`, `vantage-add-feature`) follow it. Placed copies of `AGENTS.md`
+  are synced by `vantage upgrade`.
+
 ## v0.2.3
 
 `vantage routes` can be narrowed to one side of the map, and can print the spec of

package/docs/en/cli-reference.md

@@ -26,8 +26,9 @@ first argument isn't a known command but points at a filesystem path, Vantage st
 path as the root (printing `quick dev → <path>`).
 
 ```bash
-vantage ./demo             # folder → run dev inside it
-vantage ./demo/index.tsx   # page file → use its parent folder as the root
+vantage ./demo                 # folder → run dev inside it
+vantage ./demo/index.tsx       # page file → the folder holding its package.json
+vantage ./demo/src/index.tsx   # same with a src/ layout (the root is ./demo)
 ```
 
 Path resolution rules:
@@ -35,7 +36,7 @@ Path resolution rules:
 | Path you pass | Root that's used |
 |---|---|
 | A directory | the directory itself |
-| A `.tsx` / `.jsx` page file | its parent directory |
+| A `.tsx` / `.jsx` page file | the nearest directory above it with a `package.json` (its parent otherwise) |
 | A missing path / anything else | none (`Unknown command` error) |
 
 Every root-scoped command except `add`, `docs` and `search` may also take a trailing path positional. You can spell out
@@ -325,15 +326,17 @@ relative paths). See [Build & deploy](build-and-deploy) for details.
 
 ## Static diagnostics (`check`)
 
-`vantage check` detects these six diagnostics (five errors, one warning).
+`vantage check` detects these eight diagnostics (six errors, two warnings).
 
 | Code | Severity | Meaning |
 |---|---|---|
 | `FORBIDDEN_FILE` | error | A forbidden config file exists at the root |
+| `SRC_DIR_SPLIT` | error | `src/` exists but pages or `styles.css` were left at the project root (or `src/server/` exists) |
 | `ROUTE_CONFLICT` | error | Two files resolve to the same route |
 | `MISSING_DEFAULT_EXPORT` | error | A page has no default export |
 | `INVALID_API_EXPORT` | error | An API exports no valid HTTP method |
 | `CLIENT_IMPORTS_SERVER` | error | Client code imports from `server/` |
+| `SUSPICIOUS_ROUTE_DIR` | warning | A scaffolding-looking directory (`pages/`, `app/`, `utils/`, …) shows up in a URL |
 | `PUBLIC_ENV_MISUSE` | warning | Client reads a non-`PUBLIC_` env variable |
 
 None of them import or run your code — the checks are purely static.

package/docs/en/components.md

@@ -209,7 +209,8 @@ export default function Overview() {
 ## Theming
 
 The look is decided by CSS variables (design tokens). To change colours or radii, override just the
-variables in a `styles.css` at the project root — see [UI & theming](ui-and-theming).
+variables in a `styles.css` placed on the same side as your pages (`src/styles.css` when the project
+has a `src/`) — see [UI & theming](ui-and-theming).
 
 ## When you want to edit the source
 

package/docs/en/getting-started.md

@@ -20,7 +20,9 @@ pnpm add @squadbase/vantage
 ### Write index.tsx
 
 Put a single `index.tsx` at the project root. The **default-exported component** becomes the
-route `/`.
+route `/`. To keep pages under `src/`, write `src/index.tsx` instead — **once `src/` exists it
+is the only page-scan root**, and `src/` never shows up in a URL
+(→ [Where pages live](routing)).
 
 ```tsx
 // index.tsx
@@ -67,8 +69,9 @@ Instead of `cd`-ing into a project, you can pass its **path directly** to start
 Point at a folder or an entry file and `dev` boots on it.
 
 ```bash
-vantage ./demo             # folder → run dev inside it
-vantage ./demo/index.tsx   # page file → use its parent folder as the root
+vantage ./demo                 # folder → run dev inside it
+vantage ./demo/index.tsx       # page file → use the folder holding its package.json
+vantage ./demo/src/index.tsx   # same with a src/ layout (the root is ./demo)
 ```
 
 When the first argument isn't a known command but points at a path, Vantage runs `dev` with that

package/docs/en/routing.md

@@ -4,8 +4,28 @@
 
 In Vantage, **where you place a file is its URL**. You never configure a router.
 
+## Where pages live
+
+There are two layouts, and which one applies is decided by **whether `src/` exists** — detected,
+never configured.
+
+| Project | Page-scan root | The file that becomes `/` |
+|---|---|---|
+| Has `src/` | Inside `src/` only | `src/index.tsx` |
+| No `src/` | The project root | `index.tsx` |
+
+`src/` itself never appears in a URL (`src/sales/index.tsx` → `/sales`). A one-file app can stay at
+the root; once it grows, create `src/` and move the pages in.
+
+> [!WARNING]
+> **The two layouts cannot be mixed.** Once `src/` exists, `.tsx` files at the project root are not
+> scanned and `vantage check` reports `SRC_DIR_SPLIT`. `server/` and `public/` always stay at the
+> project root (`src/server/` is never scanned), and `styles.css` belongs on the same side as the pages.
+
 ## Page conventions
 
+The "File" column below is relative to the page-scan root above.
+
 | File | Route |
 |---|---|
 | `index.tsx` | `/` |
@@ -23,7 +43,7 @@ In Vantage, **where you place a file is its URL**. You never configure a router.
 
 ## Directories that are never routed
 
-These directories are never scanned. Put whatever code you like here.
+These directories are never scanned, at any depth. Put whatever code you like here.
 
 ```text
 components/   Reusable React components
@@ -33,6 +53,12 @@ server/       API (its presence enables the server)
 public/       Static assets
 ```
 
+> [!WARNING]
+> **Every other directory name becomes a URL segment.** `pages/report.tsx` serves `/pages/report`,
+> `utils/format.tsx` serves `/utils/format`. When routes come out of scaffolding directories like
+> `pages/`, `app/` or `utils/`, `vantage check` raises a `SUSPICIOUS_ROUTE_DIR` warning — move
+> non-page modules into one of the three directories above.
+
 ## The three spellings of a dynamic param
 
 The same param appears in three spellings depending on where it is. **They must match.**

package/docs/en/ui-and-theming.md

@@ -53,8 +53,10 @@ import { cn } from "@squadbase/vantage/ui";
 
 ## Override theme tokens
 
-Design tokens like colors and radii are CSS variables. To override them, place a `styles.css` at the
-project root and override **only CSS variables**. The file is auto-imported after the theme.
+Design tokens like colors and radii are CSS variables. To override them, place a `styles.css` **on the
+same side as your pages** — `src/styles.css` if the project has a `src/`, at the project root
+otherwise (→ [Where pages live](routing)) — and override **only CSS variables**. The file is
+auto-imported after the theme.
 
 ```css
 /* styles.css — CSS variable overrides only */

package/docs/ja/changelog.md

@@ -8,6 +8,49 @@ Vantage のリリースごとの変更点です。新しいものが上に来ま
 > まだプロトタイプ(**0.x**)です。0.x の間は **minor が実質のメジャー**扱いで、後方互換性の
 > ない変更は minor で入ることがあります。patch は後方互換の機能追加とバグ修正のみです。
 
+## v0.3.0
+
+ページの置き場所として `src/` を認識するようになりました。後方互換でない変更(`src/` を持つ
+プロジェクトの走査範囲)を含むため、0.x の方針に従って minor を上げています。
+
+依存を `"@squadbase/vantage": "^0.2.0"` と書いているアプリには 0.3.0 は入りません。
+`^0.3.0` に上げてください。
+
+> [!WARNING]
+> **`src/` があるプロジェクトでは、ページ走査が `src/` の中だけになります。** これまで `src/` は
+> ただのディレクトリで、`src/App.tsx` は `/src/App` というルートになっていました。0.3.0 では
+> `src/` があればそこがページ探索ルートになり、`src/` は URL から落ちます
+> (`src/sales/index.tsx` → `/sales`)。**ルート直下に残ったページと `styles.css` は走査されなく
+> なる**ので、`vantage check` が `SRC_DIR_SPLIT` エラーで指摘します。`src/` を持たないアプリの
+> 挙動は変わりません。
+
+### 変更
+
+- **ページ探索ルートが `src/` の有無だけで決まるようになりました**
+  (→ [ファイルベースルーティング](routing))― `<root>/src` があればページはその中だけ、
+  無ければルート直下。設定は無く、検出されるだけです。1 ファイルのアプリは直下のままでよく、
+  育ったら `src/` を作ってまとめて移せます。`server/` と `public/` は常にプロジェクトルート
+  直下で、`src/server/` はスキャンされません。
+- **`styles.css` はページと同じ側から読まれます** ― `src/` があれば `src/styles.css`。
+- **`vantage add page` / `add ui` / `add block` の書き込み先**もページ探索ルート基準になりました
+  (`src/reports/index.tsx`・`src/components/ui/data-table.tsx`)。
+- **クイックモードにページファイルを渡したときの root** が、そのファイルから上に辿って最初に
+  `package.json` があるディレクトリになりました ― `vantage ./demo/src/index.tsx` の root は
+  `./demo` です(これまでは親ディレクトリ固定で `./demo/src` になっていました)。
+
+### 追加
+
+- **`SRC_DIR_SPLIT`(エラー)** ― `src/` があるのにルート直下にページや `styles.css` が残って
+  いる、または `src/server/` がある場合に指摘します。いずれも「置いたのに動かない」形の事故に
+  なるため、警告ではなくエラーです。
+- **`SUSPICIOUS_ROUTE_DIR`(警告)** ― `pages/`・`app/`・`utils/` のような足場に見えるディレクトリ
+  から URL が生まれたときに知らせます(`pages/report.tsx` → `/pages/report`)。ページ走査は除外
+  リスト方式なので、リストに無い名前は黙って URL になります。走査自体は止めないので、意図して
+  その URL を作っている場合は無視できます。
+- 同梱の `AGENTS.md` に「ディレクトリ構造」の節が入り、Skill(`vantage-app` /
+  `vantage-add-feature`)も追随しました。配置済みの `AGENTS.md` は `vantage upgrade` で
+  同期されます。
+
 ## v0.2.3
 
 `vantage routes` を片側だけに絞れるようになり、各ルートの仕様も出せるようになりました。

package/docs/ja/cli-reference.md

@@ -26,8 +26,9 @@
 （ターミナルに `quick dev → <path>` と表示されます）。
 
 ```bash
-vantage ./demo             # ディレクトリ → その中で dev を起動
-vantage ./demo/index.tsx   # ページファイル → 親ディレクトリを root にして dev
+vantage ./demo                 # ディレクトリ → その中で dev を起動
+vantage ./demo/index.tsx       # ページファイル → その `package.json` があるディレクトリで dev
+vantage ./demo/src/index.tsx   # src/ レイアウトでも同じ（root は ./demo）
 ```
 
 パスの解決ルール:
@@ -35,7 +36,7 @@ vantage ./demo/index.tsx   # ページファイル → 親ディレクトリを
 | 渡したパス | root になるもの |
 |---|---|
 | ディレクトリ | そのディレクトリ自身 |
-| `.tsx` / `.jsx` のページファイル | その親ディレクトリ |
+| `.tsx` / `.jsx` のページファイル | そこから上に辿って最初に `package.json` があるディレクトリ（無ければ親ディレクトリ） |
 | 存在しないパス・その他 | 該当なし（`Unknown command` エラー） |
 
 `add`・`docs`・`search` を除く root スコープの各コマンドも、末尾に path positional を取れます。`dev` を明示しても
@@ -319,15 +320,17 @@ vantage build --api-base-url https://api.example.com
 
 ## 静的診断（`check`）
 
-`vantage check` が検出する診断は次の 6 種類です（エラー 5・警告 1）。
+`vantage check` が検出する診断は次の 8 種類です（エラー 6・警告 2）。
 
 | コード | 深刻度 | 意味 |
 |---|---|---|
 | `FORBIDDEN_FILE` | エラー | 禁止された設定ファイルがルートに存在する |
+| `SRC_DIR_SPLIT` | エラー | `src/` があるのに、ページ・`styles.css` がルート直下に残っている（または `src/server/`） |
 | `ROUTE_CONFLICT` | エラー | 2 つのファイルが同じルートに解決される |
 | `MISSING_DEFAULT_EXPORT` | エラー | ページに default export がない |
 | `INVALID_API_EXPORT` | エラー | API が有効な HTTP メソッドをエクスポートしていない |
 | `CLIENT_IMPORTS_SERVER` | エラー | クライアントが `server/` から import している |
+| `SUSPICIOUS_ROUTE_DIR` | 警告 | `pages/`・`app/`・`utils/` など、足場に見えるディレクトリ名が URL に出ている |
 | `PUBLIC_ENV_MISUSE` | 警告 | クライアントが `PUBLIC_` 以外の env を読んでいる |
 
 いずれもユーザーコードを import・実行しません（純粋に静的な検査です）。

package/docs/ja/components.md

@@ -208,8 +208,9 @@ export default function Overview() {
 
 ## テーマ
 
-見た目は CSS 変数（デザイントークン）で決まります。色や角丸を変えたいときは、プロジェクトルートの
-`styles.css` で変数だけを上書きします — 詳しくは [UI とテーマ](ui-and-theming) を参照してください。
+見た目は CSS 変数（デザイントークン）で決まります。色や角丸を変えたいときは、ページと同じ側に置いた
+`styles.css`（`src/` があれば `src/styles.css`）で変数だけを上書きします — 詳しくは
+[UI とテーマ](ui-and-theming) を参照してください。
 
 ## ソースを編集したいとき
 

package/docs/ja/getting-started.md

@@ -20,7 +20,9 @@ pnpm add @squadbase/vantage
 ### index.tsx を書く
 
 プロジェクトルートに `index.tsx` を 1 つ置きます。**default export されたコンポーネント**が
-ルート `/` になります。
+ルート `/` になります。ページを `src/` にまとめたい場合は `src/index.tsx` にします ―
+**`src/` があるとページ走査はその中だけ**になり、`src/` は URL に現れません
+（→ [ページを置く場所](routing)）。
 
 ```tsx
 // index.tsx
@@ -67,8 +69,9 @@ React Fast Refresh がその場で反映します。
 エントリファイルをそのまま指すだけで `dev` が立ち上がります。
 
 ```bash
-vantage ./demo             # フォルダ → その中で dev を起動
-vantage ./demo/index.tsx   # ページファイル → 親フォルダを root にして dev
+vantage ./demo                 # フォルダ → その中で dev を起動
+vantage ./demo/index.tsx       # ページファイル → その `package.json` があるフォルダで dev
+vantage ./demo/src/index.tsx   # src/ レイアウトでも同じ（root は ./demo）
 ```
 
 第 1 引数が既知コマンドでなくパスを指すとき、Vantage はそれを root として `dev` を起動します

package/docs/ja/routing.md

@@ -4,8 +4,27 @@
 
 Vantage のルーティングは **ファイルの配置がそのまま URL** になります。ルーターの設定は書きません。
 
+## ページを置く場所
+
+置き場所は 2 通りあり、**`src/` があるかどうか**だけで決まります。設定ではなく検出です。
+
+| プロジェクト | ページ走査のルート | `/` になるファイル |
+|---|---|---|
+| `src/` がある | `src/` の中だけ | `src/index.tsx` |
+| `src/` が無い | プロジェクトルート直下 | `index.tsx` |
+
+`src/` 自体は URL に現れません（`src/sales/index.tsx` → `/sales`）。1 ファイルのアプリはそのまま
+直下に置け、育ったら `src/` を作ってまとめて移せます。
+
+> [!WARNING]
+> **2 つを混ぜることはできません。** `src/` があるとルート直下の `.tsx` は走査されず、
+> `vantage check` が `SRC_DIR_SPLIT` エラーで指摘します。`server/` と `public/` は常にプロジェクト
+> ルート直下（`src/server/` はスキャンされません）、`styles.css` はページと同じ側に置きます。
+
 ## ページの規約
 
+以下の「ファイル」列は、上のページ走査ルートからの相対パスです。
+
 | ファイル | ルート |
 |---|---|
 | `index.tsx` | `/` |
@@ -23,7 +42,7 @@ Vantage のルーティングは **ファイルの配置がそのまま URL**
 
 ## ルーティングされないディレクトリ
 
-次のディレクトリは決して走査されません。ここには自由にコードを置けます。
+次のディレクトリは（どの階層でも）決して走査されません。ここには自由にコードを置けます。
 
 ```text
 components/   再利用する React コンポーネント
@@ -33,6 +52,12 @@ server/       API（存在するとサーバーが有効になる）
 public/       静的アセット
 ```
 
+> [!WARNING]
+> **それ以外のディレクトリ名は URL のセグメントになります。** `pages/report.tsx` は
+> `/pages/report` に、`utils/format.tsx` は `/utils/format` になります。`pages/`・`app/`・
+> `utils/` のような足場ディレクトリからルートが生まれると `vantage check` が
+> `SUSPICIOUS_ROUTE_DIR` 警告を出すので、ページでないモジュールは上の 3 つに移してください。
+
 ## 動的パラメータの 3 つの綴り
 
 同じパラメータが、場所によって 3 つの綴りで現れます。**必ず一致させます。**

package/docs/ja/ui-and-theming.md

@@ -53,8 +53,10 @@ import { cn } from "@squadbase/vantage/ui";
 
 ## テーマトークンを上書きする
 
-色や角丸などのデザイントークンは CSS 変数です。上書きしたいときは、プロジェクトルートに
-`styles.css` を置き、**CSS 変数だけ**を上書きします。このファイルはテーマの後に自動 import されます。
+色や角丸などのデザイントークンは CSS 変数です。上書きしたいときは、**ページと同じ側**に
+`styles.css` を置き、**CSS 変数だけ**を上書きします ― `src/` があれば `src/styles.css`、
+無ければプロジェクトルート直下（→ [ページを置く場所](routing)）。このファイルはテーマの後に
+自動 import されます。
 
 ```css
 /* styles.css — CSS 変数の上書きのみ */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squadbase/vantage",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Data dashboard framework for Squadbase Editor. Vite-powered, config-free, one-file first.",
   "type": "module",
   "license": "MIT",

package/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)
 

package/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.3.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(このファイルの仲間)と、その場所
 ```

package/templates/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.3.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   # 本番ビルドをローカル実行