@squadbase/vantage 0.2.2 → 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.2";
+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.2";
+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.2\"\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-UHZ7XSAN.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,77 @@ 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
+every route. Additions only, so it is backwards-compatible.
+
+### Added
+
+- **`vantage routes` takes `--pages` / `--apis`** (see
+  [CLI reference](cli-reference)) — pages only (plus layout / 404 / error), or
+  API routes only. They are not exclusive: passing both, or neither, prints
+  everything exactly as before.
+- **`--detail` adds each route's static spec** — for a page, the `definePage`
+  title / navLabel / description and its path params; for an API, **per method**,
+  the query keys read through `searchParams`, the request body (`json` /
+  `formData` / `text`, with its keys when destructured), the response status,
+  content type and object keys, and the status and message of every `HttpError`.
+  It answers "how do I call this endpoint?" without opening the handler.
+  - With `--json`, every entry gains a `spec`. The existing keys (`route`,
+    `file`, `dynamic`, `params`) are untouched, so current readers keep working.
+  - Everything is **inferred by reading the source** — like `check`, your code is
+    never imported or executed. Keys assembled at runtime, or input and output
+    hidden inside helper functions, will not show up: treat the output as a
+    **draft** of the spec, not a contract.
+
 ## v0.2.2
 
 `vantage add skill` now scans for where the skills already are, and charts follow

package/docs/en/cli-reference.md

@@ -12,7 +12,7 @@
 | `vantage build` | Build client + optional server → `dist/` |
 | `vantage preview` | Run the production build locally (fullstack default `:4173`; spa via Vite preview) |
 | `vantage check` | Static checks (routes, boundaries, forbidden files). Exit 1 on error |
-| `vantage routes` | Print the page + API URL map |
+| `vantage routes` | Print the page + API URL map (`--pages` / `--apis` for one side only, `--detail` for each route's spec) |
 | `vantage add <kind> <name>` | Scaffold or place a `page` / `api` / `ui` / `block` / `skill` / `agents` (`--force` to overwrite; `skill` scans for copies already placed and skips them, `--dir` picks the destination) |
 | `vantage docs [name]` | Show the bundled guide and component reference |
 | `vantage search <query>` | Search that same reference in full text (natural language or `--regex`) |
@@ -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
@@ -51,6 +52,57 @@ vantage check ./demo/index.tsx # a file argument still checks its parent directo
 > `add`, `docs` and `search` use their positionals for their own arguments (`add page dashboard`,
 > `docs button`, `search date picker`) rather than a path, so they are excluded from this shortcut.
 
+## `vantage routes` — the URL map, with specs
+
+With no flags it prints the URL map of pages, layouts and API routes. Flags narrow it to **one
+side** or add the **static spec** of every route.
+
+| Flag | Meaning |
+|---|---|
+| `--pages` | Pages only (plus layout / 404 / error) |
+| `--apis` | API routes only |
+| `--detail` | Add each route's spec (pages: path params + `definePage` metadata; APIs: methods, request, response) |
+| `--json` | Machine-readable output (with `--detail`, every entry gains a `spec`) |
+
+`--pages` and `--apis` are not exclusive — passing both, or neither, prints everything.
+
+```bash
+vantage routes --pages           # pages only
+vantage routes --apis --detail   # APIs with their specs
+vantage routes --detail --json   # machine-readable, specs included
+```
+
+```text
+Pages
+  /sales/:customerId           sales/[customerId].tsx
+      title    Customer detail
+      params   :customerId
+
+API
+  /api/customers/:id           server/api/customers/[id].ts
+      GET
+        path     :id
+        response 200 application/json
+        error    404 "Customer ${params.id} not found"
+```
+
+`--detail` reads these shapes:
+
+| Line | Where it comes from |
+|---|---|
+| `title` / `nav` / `desc` | String literals in `definePage({ ... })` |
+| `params` | `[id]` / `[...rest]` in the filename |
+| Method | HTTP method exports such as `export function GET` |
+| `query` | `searchParams.get/getAll/has("x")` |
+| `body` | `request.json()` / `formData()` / `text()` (plus the keys of `const { a, b } = await request.json()`) |
+| `response` | Status, content type and object-literal keys of `Response.json(…)` / `json(…)` / `new Response(…)` |
+| `error` | `new HttpError(status, "message")` |
+
+> [!NOTE]
+> Like `check`, `--detail` is **static text analysis** — your code is never imported or executed. Keys
+> assembled at runtime, or input/output hidden inside helper functions, will not show up. Treat the
+> output as a draft of the spec, not a contract.
+
 ## `vantage docs` — read the docs from the CLI
 
 The content of this site is **bundled into the package**, so `vantage docs` prints it as plain
@@ -274,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,71 @@ 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` を片側だけに絞れるようになり、各ルートの仕様も出せるようになりました。
+すべて追加のみで後方互換です。
+
+### 追加
+
+- **`vantage routes` に `--pages` / `--apis` が付きました**(→ [CLI リファレンス](cli-reference))
+  ― ページ(+ layout / 404 / error)だけ、API ルートだけに絞れます。排他ではないので、両方
+  付けても、どちらも付けなくても今までどおり全部出ます。
+- **`--detail` で各ルートの静的な仕様を併記します** ― ページは `definePage` の
+  title / navLabel / description とパスパラメータ、API は**メソッドごと**に
+  `searchParams` で読むクエリキー・リクエストボディ(`json` / `formData` / `text`。
+  分割代入していればキーも)・レスポンスの status と content-type とオブジェクトのキー・
+  `HttpError` の status とメッセージが並びます。既存 API の呼び方を確かめるのに、
+  ハンドラを開かずに済みます。
+  - `--json` と併せると、各要素に `spec` が増えます。既存のキー(`route` / `file` /
+    `dynamic` / `params`)はそのままなので、今の読み手を壊しません。
+  - 取れるのは**ソースを読んだだけの推定**です(`check` と同じく、アプリのコードを import も
+    実行もしません)。実行時に組み立てるキーや、ヘルパー関数の中に隠れた入出力は出てきません
+    ― 仕様の**下書き**であって契約ではありません。
+
 ## v0.2.2
 
 `vantage add skill` が配置先を走査するようになり、チャートがスタイルシートの差し替えにも

package/docs/ja/cli-reference.md

@@ -12,7 +12,7 @@
 | `vantage build` | クライアント + オプションのサーバーをビルド → `dist/` |
 | `vantage preview` | 本番ビルドをローカルで起動（fullstack は既定 `:4173`、spa は Vite プレビュー） |
 | `vantage check` | 静的検査（ルート・境界・禁止ファイル）。エラーがあれば exit 1 |
-| `vantage routes` | ページ + API の URL マップを表示 |
+| `vantage routes` | ページ + API の URL マップを表示（`--pages` / `--apis` で片側だけ、`--detail` で仕様つき） |
 | `vantage add <kind> <name>` | `page` / `api` / `ui` / `block` / `skill` / `agents` を雛形生成・配置（`--force` で上書き、`skill` は配置済みを走査してスキップ・`--dir` で配置先を指定） |
 | `vantage docs [name]` | 同梱のガイド + コンポーネントリファレンスを表示 |
 | `vantage search <query>` | 同じリファレンスを全文検索（自然言語 or `--regex`） |
@@ -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` を明示しても
@@ -51,6 +52,57 @@ vantage check ./demo/index.tsx # ファイル指定でも親ディレクトリ
 > `add`・`docs`・`search` はパス引数ではなく positional を自分の引数（`add page dashboard`・
 > `docs button`・`search 日付の選択`）に使うため、この短縮形の対象外です。
 
+## `vantage routes` — URL マップと仕様
+
+引数なしで、ページ・レイアウト・API の URL マップを出します。フラグで**片側だけ**に絞ったり、
+各ルートの**静的な仕様**を足したりできます。
+
+| フラグ | 意味 |
+|---|---|
+| `--pages` | ページ（+ layout / 404 / error）だけを表示 |
+| `--apis` | API ルートだけを表示 |
+| `--detail` | 各ルートの仕様を併記（ページはパスパラメータと `definePage` のメタ、API はメソッド・リクエスト・レスポンス） |
+| `--json` | 機械可読出力（`--detail` を付けると各要素に `spec` が付く） |
+
+`--pages` と `--apis` は排他ではありません。両方付けても、どちらも付けなくても全部出ます。
+
+```bash
+vantage routes --pages           # ページだけ
+vantage routes --apis --detail   # API を仕様つきで
+vantage routes --detail --json   # 仕様つきの機械可読出力
+```
+
+```text
+Pages
+  /sales/:customerId           sales/[customerId].tsx
+      title    Customer detail
+      params   :customerId
+
+API
+  /api/customers/:id           server/api/customers/[id].ts
+      GET
+        path     :id
+        response 200 application/json
+        error    404 "Customer ${params.id} not found"
+```
+
+`--detail` が拾うのは次の書き方です。
+
+| 行 | 何を読むか |
+|---|---|
+| `title` / `nav` / `desc` | `definePage({ ... })` の文字列リテラル |
+| `params` | ファイル名の `[id]` / `[...rest]` |
+| メソッド | `export function GET` などの HTTP メソッド export |
+| `query` | `searchParams.get/getAll/has("x")` |
+| `body` | `request.json()` / `formData()` / `text()`（`const { a, b } = await request.json()` ならキーも） |
+| `response` | `Response.json(…)` / `json(…)` / `new Response(…)` の status・content-type・オブジェクトリテラルのキー |
+| `error` | `new HttpError(status, "message")` |
+
+> [!NOTE]
+> `--detail` は `check` と同じく**ソースを読むだけの静的解析**で、アプリのコードを import も実行も
+> しません。実行時に組み立てるキーや、ヘルパー関数の中に隠れた入出力は出てきません（出力は
+> 「仕様の下書き」であって契約ではありません）。
+
 ## `vantage docs` — ドキュメントを CLI で読む
 
 このサイトの内容は**パッケージに同梱**されていて、`vantage docs` でそのまま読めます。ネット接続も
@@ -268,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.2",
+  "version": "0.3.0",
   "description": "Data dashboard framework for Squadbase Editor. Vite-powered, config-free, one-file first.",
   "type": "module",
   "license": "MIT",