@squadbase/vantage 0.5.3 → 0.6.1-dev.2d25e94

package/docs/en/agent-skills.md

@@ -14,6 +14,8 @@ All of these target an agent that is **building a Vantage app**.
 |---|---|
 | `vantage-app` | Creating an app, and growing a single-file `index.tsx` SPA into a fullstack app with `server/api`, nested layouts, dynamic routes, and 404/error pages |
 | `vantage-add-feature` | Adding a page / API / UI / block (`vantage add` through to `check` / `routes`) |
+| `vantage-slide` | Writing a slide deck in `.slide.tsx` (the 1920×1080 canvas's vertical budget, the type scale, stepped reveals, transitions and morph, what a pptx export needs) |
+| `vantage-design` | Creating / updating `DESIGN.md` (the design intent) and `styles.css` (the values) together — colors, chart palette, fonts, matching a brand from a URL, logo, document, or an external DESIGN.md, and checking contrast |
 | `vantage-pitfalls` | A pitfalls reference (Base UI ≠ Radix, `SelectValue` behavior, never importing `server/` from the client, and more) |
 | `project-storage` | Working with Squadbase Project Storage (uploaded files) from the browser — listing, embedding images / video / PDFs, uploading. For apps running on Squadbase |
 
@@ -41,7 +43,9 @@ Bundled skills:
   project-storage      .claude/skills/project-storage/
   vantage-add-feature  .claude/skills/vantage-add-feature/
   vantage-app          .claude/skills/vantage-app/
+  vantage-design       not placed
   vantage-pitfalls     not placed
+  vantage-slide        not placed
 ```
 
 With `--force`, the copies that were found are rewritten **where they are** (an explicit `--dir`
@@ -58,7 +62,9 @@ your-app/
     └── skills/
         ├── vantage-app/SKILL.md
         ├── vantage-add-feature/SKILL.md
+        ├── vantage-design/SKILL.md     (its references/ and scripts/ ride along)
         ├── vantage-pitfalls/SKILL.md
+        ├── vantage-slide/SKILL.md      (its references/ ride along)
         └── project-storage/SKILL.md
 ```
 
@@ -79,25 +85,28 @@ skill based on the task at hand. For other agents, pass whatever directory that
 - **The Squadbase template ships them pre-placed.** Apps created from the template already contain
   `.claude/skills/`. For a hand-made app, add them with `vantage add skill`.
 
-## `AGENTS.md` (the app map)
+## `AGENTS.md` + `agents/*.md` (the app map and knowledge files)
 
 If a skill is a procedure, `AGENTS.md` is **the map an agent reads first**. It gathers Vantage's
-invariants, the import-subpath map, routing conventions, and the minimal data-fetching / API / env
-recipes onto a single page — enough to **build a minimal app from that page alone**. Deeper
-procedures are delegated to the skills above by name, so nothing is duplicated.
+invariants, the import-subpath map, directory layout, and env conventions onto a single page, and
+points into `agents/` via a "what are you writing → which file to read" table.
+`agents/page.md` (regular pages), `agents/api.md` (`server/`), `agents/slide.md`
+(`.slide.tsx`), `agents/xlsx.md`, and `agents/csv.md` are static, per-artifact-type references —
+each is only needed when writing that kind of file. Deeper procedures are delegated to the skills
+above by name, so nothing is duplicated.
 
-Like the skills, its **source of truth lives in the package**, and `vantage add agents` places it
-into the app root.
+Like the skills, its **source of truth lives in the package**, and `vantage add agents` places
+`AGENTS.md` together with `agents/*.md` into the app root.
 
 ```bash
-vantage add agents           # place AGENTS.md into the app root
+vantage add agents           # place AGENTS.md + agents/*.md into the app root
 vantage add agents --force    # overwrite an existing copy
 ```
 
-A placed `AGENTS.md` is kept in sync by `vantage upgrade` (it rewrites only when the content
-differs, and never creates the file in an app that hasn't opted in). When a framework convention
-changes, a **single source-of-truth edit** reaches apps through `upgrade`. The Squadbase template
-ships it pre-placed.
+A placed `AGENTS.md` + `agents/*.md` are kept in sync by `vantage upgrade` (it rewrites only the
+files whose content differs, and never creates them in an app that hasn't opted in). When a
+framework convention changes, a source-of-truth edit reaches apps through `upgrade`. The Squadbase
+template ships them pre-placed.
 
 ## Separation of concerns
 
@@ -108,6 +117,7 @@ the following:
   An agent without a browser reads the same content through [`vantage docs`](cli-reference)
   (`vantage docs button` for the prop table, `vantage docs --json` for machine-readable output,
   `vantage search <what you want>` when the name is unknown).
-- **`AGENTS.md`** (a static map) — where things live and how the project is laid out; placed with `vantage add agents`.
+- **`AGENTS.md`** (a static map) — where things live and how the project is laid out; placed
+  together with `agents/*.md` (static, per-artifact-type references) via `vantage add agents`.
 - **Each other** — shared material like pitfalls is not copied into every skill; skills
   **cross-reference by name** instead (e.g. `vantage-app`'s procedure points at `vantage-pitfalls`).

package/docs/en/changelog.md

@@ -9,6 +9,113 @@ 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.6.2
+
+The dev server can now run behind a reverse proxy (2026-09-23).
+
+### Added
+
+- **`--host [addr]` and `--allowed-hosts <list|true>`** on `vantage dev` / SPA `vantage preview`.
+  Vite rejects with 403 any request whose `Host` header is not `localhost`, so anything with
+  **another hostname in front of the server** — a sandbox preview proxy, a tunnel — could not reach
+  it before. `--allowed-hosts` can also come from the **`VANTAGE_ALLOWED_HOSTS`** environment
+  variable (the flag wins). With neither, nothing changes. See the
+  [CLI reference](cli-reference).
+
+## v0.6.1
+
+Pages can now be written as documents (2026-09-25).
+
+### Added
+
+- **`<name>.doc.tsx` becomes a document page.** Wrap it in `Document` from
+  `@squadbase/vantage/doc` and the headings, paragraphs, lists, tables, quotes and code inside are
+  styled with no classes. Colour, type and column width come from the `--doc-*` tokens. See
+  [Routing](routing) and [UI & theming](ui-and-theming).
+
+## v0.6.0
+
+What you can drop in `src/` is no longer just `.tsx`. A `.csv` or `.xlsx` becomes a page you can
+read as a table, and `<name>.slide.tsx` becomes a slide deck — both sitting in the nav alongside
+your dashboard pages.
+
+### Added
+
+- **`.csv` / `.xlsx` become pages.** Drop `src/data/june.xlsx`, open `/data/june`, and the sheet
+  is readable in the browser — no download, no spreadsheet app. URLs are built exactly the way a
+  `.tsx` page's are (`index.csv` maps to its directory), and the page appears in `vantage routes`
+  and in a `useRoutes()` nav alongside everything else. An `.xlsx` with several sheets gets tabs,
+  and every file page offers the original file for download.
+
+  The title is derived from the file name (`june.xlsx` → "June"). Parsing happens in the browser,
+  so dev, the build output and the deployed app all return the same thing for the same URL.
+  Formulas, charts and cell formatting are not reproduced — readable as values is the contract.
+  Prefix a file with `_` to keep it out of routing.
+
+  It is drawn **as a spreadsheet**: column letters across the top, row numbers down the side, the
+  file's first row frozen as the header, sheet tabs along the bottom, and ruling that runs past
+  the data. Read-only — no toolbar and no sorting (a selected cell copies with `Cmd/Ctrl+C`).
+
+- **A new `@squadbase/vantage/table` subpath.** The table viewer behind those pages. Use
+  `FilePageView` directly to render a file you kept out of routing from a page of your own, with
+  your own `definePage` (`TableViewer` takes one parsed sheet, `SheetGrid` is the grid itself).
+
+- **`<name>.slide.tsx` becomes a slide deck.** `.slide` is a page-kind suffix and never reaches the
+  URL (`src/june.slide.tsx` → `/june`). The file is an ordinary React component returning a
+  `<SlideDeck>`, so `definePage` and the nav work as they do for any other page.
+
+  Slides are authored against a fixed 1920×1080 canvas in absolute pixels and scaled to fit.
+  Keyboard and click navigate, the current slide lives in the URL as `?p=`, and the toolbar
+  **exports the deck as a pptx**. The export bakes each slide as an image, so the file needs no
+  font on the receiving machine and non-Latin text survives intact.
+
+  A reader picks one of three views: **list + slide** (the default, a thumbnail rail down the
+  left), **the slide alone** (`L` closes the rail), and **fullscreen** (`F`, where the rail steps
+  aside). The rail's state rides in `?rail=`, so a link can hand someone either one; only a deck
+  that should start closed says so, with `<SlideDeck rail={false}>`.
+
+- **A new `@squadbase/vantage/slide` subpath.** `SlideDeck`, `Slide`, `Steps`, `Step`,
+  `MorphElement`, `useSlideNumber`, `useIsActiveSlide` — including stepped reveals, page
+  transitions, and morphing a shared element across two slides (Keynote's "Magic Move"). The
+  runtime is ported from [open-slide](https://github.com/1weiho/open-slide) (MIT); attribution
+  ships in the package's `NOTICE`.
+
+- **A `vantage-slide` skill now ships with Vantage.** How to budget the canvas vertically, the type
+  scale, stepped reveals, the design principles behind transitions, the rules morph rests on, and
+  what breaks a pptx export. Place it like any other skill with `vantage add skill --all`.
+
+- **New `--slide-*` theme tokens.** They default to aliases of the app's own tokens, so a deck
+  follows light and dark without doing anything. Override them per deck with
+  `<SlideDeck theme={{ … }}>`.
+
+- **Three more static diagnostics** (eleven in total: seven errors, four warnings).
+  `UNSUPPORTED_PAGE_FILE` (warning — an extension with no viewer never becomes a route, so this is
+  what tells you why the file never showed up), `FILE_PAGE_TOO_LARGE` (warning — over 25 MB), and
+  `INVALID_PAGE_VARIANT` (error — a suffix on a file that cannot be a route, like
+  `_layout.slide.tsx`).
+
+- **`AGENTS.md` is now a map, plus `agents/*.md` per-artifact-type knowledge files.** One file
+  each for regular pages, API, slides, xlsx, and csv (`agents/page.md` / `agents/api.md` /
+  `agents/slide.md` / `agents/xlsx.md` / `agents/csv.md`); `AGENTS.md` keeps only the
+  invariants and a "what are you writing → which file to read" index table. An agent only needs
+  to open the one file for the kind it's about to write. `vantage add agents` places the whole
+  set (`AGENTS.md` + `agents/`) into the app root, and `vantage upgrade` re-syncs it (files not
+  in the bundle are never deleted).
+
+- **`DESIGN.md` and a `vantage-design` skill.** Describe the design intent (color roles, charts,
+  type, layout) by token name in a `DESIGN.md` at the project root, and agents read it before
+  writing any UI (`AGENTS.md` / `agents/page.md` / `agents/slide.md` now point to it).
+  `DESIGN.md` belongs to you — `vantage upgrade` never touches it. Requests like "match our brand"
+  go through the `vantage-design` skill, which updates `DESIGN.md` and `styles.css` together.
+
+### Changed
+
+- The `RouteInfo` returned by `useRoutes()` gained **`kind`** (`"module"` | `"file"`) and
+  **`variant`** (`"slide"`), so a nav can group or badge by what a page is. Existing nav code keeps
+  working unchanged.
+- `vantage routes` now labels file pages and slide decks by kind (`--json` gains `kind`, `variant`
+  and `unrouted`).
+
 ## v0.5.3
 
 Adds a bundled skill for working with Squadbase Project Storage from the browser.

package/docs/en/cli-reference.md

@@ -13,11 +13,11 @@
 | `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 (`--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 add <kind> <name>` | Scaffold or place a `page` / `api` / `ui` / `block` / `skill` / `agents` (`AGENTS.md` + `agents/*.md`) (`--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`) |
 | `vantage doctor` | Diagnose environment / installation health |
-| `vantage upgrade` | Regenerate artifacts and sync a placed `AGENTS.md` from the canonical copy |
+| `vantage upgrade` | Regenerate artifacts and sync a placed `AGENTS.md` + `agents/*.md` from the canonical copies |
 
 ## Quick mode (pass a path directly)
 
@@ -357,6 +357,36 @@ vantage dev --strict-port                  # will not start unless 5173 is free
 > default silently. A fullstack `preview` binds its Node server to exactly one port, so it is **always**
 > strict and `--no-strict-port` has no effect there.
 
+## `--host` / `--allowed-hosts` — running behind a reverse proxy
+
+By default `vantage dev` and a SPA `vantage preview` bind to `localhost` only and **reject with 403**
+any request whose `Host` header is not `localhost` or the bound address (Vite's DNS-rebinding
+protection). When something with **another hostname** sits in front of the server — a sandbox
+preview proxy, a tunnel, a container network — these two flags let it through.
+
+```bash
+vantage dev --host                              # listen on every interface
+vantage dev --host 0.0.0.0                      # or on one address (--host=:: works too)
+vantage dev --allowed-hosts preview.example.com # allow the hostname the proxy presents (comma-separated for several)
+vantage dev --allowed-hosts true                # disable the Host check altogether
+```
+
+| Flag | Meaning |
+|---|---|
+| `--host [addr]` | Without a value, bind to **every interface**; with one, bind to that address (Vite's `server.host`) |
+| `--allowed-hosts <list\|true>` | The `Host` headers to accept, comma-separated. `true` disables the check (Vite's `server.allowedHosts`) |
+
+`--allowed-hosts` can also come from the environment variable **`VANTAGE_ALLOWED_HOSTS`** (same
+format), which suits a supervisor that starts the server and knows the hostname. When both are
+present, **the flag wins**. With neither, Vite's default applies and only `localhost` is accepted,
+exactly as before.
+
+> [!NOTE]
+> `--host` takes the next token as its value, so `vantage --host dev` would read `dev` as the
+> address — write `--host=<addr>` or put `--host` last when a command or path follows it. A fullstack
+> `preview` runs the Node server, which listens on every interface and does no `Host` check, so
+> neither flag has an effect there (the command says so).
+
 ## Browser output in dev — forwarding and the overlay
 
 `vantage dev` **forwards what happens in the browser to the dev terminal**. By default that means
@@ -418,7 +448,7 @@ phases are `scan` (route discovery), `diagnostics` (the static checks),
 
 ## Static diagnostics (`check`)
 
-`vantage check` detects these eight diagnostics (six errors, two warnings).
+`vantage check` detects these thirteen diagnostics (seven errors, six warnings).
 
 | Code | Severity | Meaning |
 |---|---|---|
@@ -428,11 +458,18 @@ phases are `scan` (route discovery), `diagnostics` (the static checks),
 | `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/` |
+| `INVALID_PAGE_VARIANT` | error | A page-kind suffix such as `.slide` sits on a file that cannot be a route (`_layout.slide.tsx`, …) |
 | `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 |
+| `UNSUPPORTED_PAGE_FILE` | warning | A file with an extension Vantage has no viewer for (`.xls`, `.ods`, …); it does not become a route |
+| `FILE_PAGE_TOO_LARGE` | warning | A data-file page is over 25 MB, so it will render an error instead of a table |
+| `HARDCODED_COLOR` | warning | A `.ts`/`.tsx` file hard-codes a color (`#hex`, `rgb()`/`hsl()`/`oklch()`, …, `bg-[#…]`, or a Tailwind palette class like `bg-blue-500`); reported per file as `path:line` with a suggested token |
+| `DESIGN_MD_TOO_LONG` | warning | The root `DESIGN.md` is over 150 lines; keep values in `styles.css` and reference them by token name |
 
 None of them import or run your code — the checks are purely static.
 
+`HARDCODED_COLOR` never reads `.css` (`styles.css` is where values belong). When a color carries data meaning (map fills, say), put `// vantage-ignore-color` (`{/* vantage-ignore-color */}` inside JSX) on that line or the line above it; `vantage-ignore-color-file` within the first five lines exempts the whole file.
+
 ## Build output
 
 Inside `dist/`:
@@ -454,4 +491,5 @@ That's the end of the app-author guide. Start from the smallest `index.tsx` and
 UI as you need them.
 
 To hand those procedures to an AI agent, place the bundled [Agents and Skills](agent-skills)
-with `vantage add skill`, and place the app map `AGENTS.md` with `vantage add agents`.
+with `vantage add skill`, and place the app map `AGENTS.md` plus its per-artifact-type
+knowledge files `agents/*.md` with `vantage add agents`.

package/docs/en/pages-and-metadata.md

@@ -43,6 +43,23 @@ export default function MonthlyAnalysis() {
 > The **export name must be `page`** in `export const page = definePage({...})`. A different name means
 > the metadata is not read.
 
+## Titles for data-file pages
+
+A `.csv` / `.xlsx` [file page](routing#pages-that-are-not-tsx) cannot carry a `definePage`, so
+its title is **derived from the file name**.
+
+| File | `title` |
+|---|---|
+| `june.xlsx` | `June` |
+| `sales_by_region.csv` | `Sales By Region` |
+| `salesByRegion.csv` | `Sales By Region` |
+| `kpi/index.csv` | `KPI` (`index` borrows its directory; an all-caps token is kept as an acronym) |
+| `index.csv` at the root | none — same as a root `index.tsx` with no `definePage` |
+
+No `navLabel` is set, so the nav shows the same string. To change it, **rename the file** — or
+prefix it with `_` to stop it routing and render it from a `.tsx` page with `FilePageView`, where a
+`definePage` of your own applies.
+
 ## Relationship to Fast Refresh
 
 Even with a non-component export like `page`, Vantage handles it internally so React Fast Refresh

package/docs/en/routing.md

@@ -1,6 +1,6 @@
 # File-based routing
 
-> Dropping a file creates a route. Conventions for pages, layouts, dynamic params, and 404/error.
+> Dropping a file creates a route. Conventions for pages, layouts, dynamic params and 404/error, plus the pages that are not .tsx (csv / xlsx / slides / documents).
 
 In Vantage, **where you place a file is its URL**. You never configure a router.
 
@@ -36,11 +36,106 @@ The "File" column below is relative to the page-scan root above.
 | `_layout.tsx` | Layout for that directory (nestable) |
 | `_404.tsx` | Not-found UI (**root only**) |
 | `_error.tsx` | Error UI (**root only**) |
+| `monthly-report.slide.tsx` | `/monthly-report` (a slide deck) |
+| `june-summary.doc.tsx` | `/june-summary` (a document) |
+| `sales-export.csv` | `/sales-export` (drawn as a table) |
+| `data/june.xlsx` | `/data/june` (same) |
 
 - `[name]` → dynamic param, `[...name]` → catchall.
 - `index` maps to its own directory (the name drops from the URL).
 - Files starting with `_` are reserved (`_layout`/`_404`/`_error`) or private (not routed).
 
+## Pages that are not `.tsx`
+
+Routes do not come only from `.tsx` / `.jsx`. **`.csv` and `.xlsx`** become pages you can read as a
+table, **`<name>.slide.tsx`** becomes a slide deck, and **`<name>.doc.tsx`** becomes a document. All
+of them build their URL exactly the way a `.tsx` page does, and all appear in `vantage routes` and in a `useRoutes()` nav alongside it.
+
+### Data files (`.csv` / `.xlsx`)
+
+Drop `src/data/june.xlsx`, open `/data/june`, and the sheet is readable in the browser — no
+download, no spreadsheet app. An `.xlsx` with several sheets gets tabs, and every file page offers
+the original file for download.
+
+It is drawn **as a spreadsheet** — column letters across the top, row numbers down the side, the
+file's first row frozen as the header, ruling that runs past the data, and sheet tabs along the
+bottom. It is read-only: no editing and no sorting (though a selected cell copies with
+`Cmd/Ctrl+C`). Data that needs sorting or filtering belongs behind `server/api/`, rendered with
+`DataTable`.
+
+- **The title is derived from the file name** (`june.xlsx` → "June"; `index.csv` borrows its
+  directory). A data file cannot carry a `definePage`, so renaming the file is how you rename
+  the page.
+- **Parsing happens in the browser.** Dev, the build output and the deployed app all run the same
+  code over the same bytes, which is what makes the same URL return the same thing. A file over
+  25 MB shows an error on its own page (`vantage check` warns first, with `FILE_PAGE_TOO_LARGE`).
+- Formulas, charts and cell formatting are not reproduced. **Readable as values** is the contract.
+- Prefix a file with `_` to keep it out of routing (`_june.xlsx`). That is also how you render one
+  yourself: stop it routing, then use `FilePageView` from `@squadbase/vantage/table`.
+
+> [!WARNING]
+> **An extension with no viewer does not become a route.** Dropping `.xls`, `.ods` or `.tsv` does not
+> even produce a 404 — the file appears in neither the nav nor `vantage routes`. The
+> `UNSUPPORTED_PAGE_FILE` warning from `vantage check` is the only place that says so.
+
+### Slides (`.slide.tsx`)
+
+`.slide` is a **page-kind suffix** and never reaches the URL (`src/june.slide.tsx` → `/june`). The
+file itself is an ordinary React component returning a `<SlideDeck>`, so `definePage` and the nav
+work exactly as they do for any other page.
+
+```tsx
+import { definePage } from "@squadbase/vantage";
+import { Slide, SlideDeck } from "@squadbase/vantage/slide";
+
+export const page = definePage({ title: "June review", navLabel: "June" });
+
+export default function Deck() {
+  return (
+    <SlideDeck>
+      <Slide>…</Slide>
+      <Slide>…</Slide>
+    </SlideDeck>
+  );
+}
+```
+
+Slides are authored against a fixed 1920×1080 canvas and scaled to fit. Keyboard and click
+navigate, `L` toggles the slide list beside it, `F` goes fullscreen, and the toolbar exports the
+deck as a pptx. See
+[UI & theming](ui-and-theming).
+
+> [!WARNING]
+> Only a page module that becomes a route may carry `.slide`. `_layout.slide.tsx` and
+> `deck.slide.ts` raise `INVALID_PAGE_VARIANT`. And since `june.slide.tsx` and `june.tsx` — like
+> `sales.csv` and `sales.tsx` — resolve to the same URL, having both is a `ROUTE_CONFLICT`.
+
+### Documents (`.doc.tsx`)
+
+`.doc` is a **page-kind suffix** too (`src/june-summary.doc.tsx` → `/june-summary`). A document is
+prose read top to bottom; the file is an ordinary React component returning a `<Document>`.
+
+```tsx
+import { definePage } from "@squadbase/vantage";
+import { Document } from "@squadbase/vantage/doc";
+
+export const page = definePage({ title: "June summary" });
+
+export default function JuneSummary() {
+  return (
+    <Document>
+      <h1>June summary</h1>
+      <p>June revenue came in 5% above target.</p>
+      <table>…</table>
+    </Document>
+  );
+}
+```
+
+Headings, paragraphs, lists, tables, quotes and code inside `<Document>` are styled with no classes
+written. See [UI & theming](ui-and-theming). As with `.slide`, only a page module that becomes a
+route may carry `.doc`.
+
 ## Directories that are never routed
 
 These directories are never scanned, at any depth. Put whatever code you like here.
@@ -150,6 +245,8 @@ Each entry is a `RouteInfo`:
 | `index` | `boolean` | Whether it is a directory's index route |
 | `label` | `string` | Display name: `navLabel`, else `title`, else `path` |
 | `title` / `description` / `navLabel` | `string \| undefined` | Values from [`definePage`](pages-and-metadata) |
+| `kind` | `"module" \| "file"` | What the page is drawn from; `"file"` is a `.csv` / `.xlsx` |
+| `variant` | `"slide" \| "doc" \| undefined` | The page-kind suffix the file carried |
 
 `useCurrentRoute()` returns the route being rendered, or `undefined` on the 404 route. Beyond the
 "you are here" check above, it fits breadcrumbs and page headings.
@@ -191,8 +288,10 @@ setSegments((prev) => [...prev, "enterprise"]);
 
 ## HMR and route regeneration
 
-Adding or removing a `.tsx` page or a `server/api` file regenerates routes and triggers a full
-reload. Editing a page body applies in place via React Fast Refresh.
+Adding or removing a `.tsx` page, a data file or a `server/api` file regenerates routes and triggers
+a full reload. Editing a page body applies in place via React Fast Refresh. Editing the *contents*
+of a `.csv` / `.xlsx` also triggers a full reload — it is fetched at runtime from a fixed URL, so
+nothing in the module graph changes when its bytes do.
 
 ## What to read next
 

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

@@ -40,6 +40,108 @@ In `/components` (a selection): `PageShell`, `AppShell`, `DashboardCard`, `DataT
 
 Props and usage for every component live in the [Components](components) tab.
 
+## UI behind its own subpath
+
+Three pieces carry heavy dependencies, so they live behind their own subpath and only reach the
+apps that import them.
+
+| Subpath | What it holds |
+|---|---|
+| `@squadbase/vantage/markdown` | `MarkdownRenderer` (isolated because Shiki pulls in every language grammar) |
+| `@squadbase/vantage/table` | `TableViewer` / `FilePageView` (the csv/xlsx parsers, loaded dynamically) |
+| `@squadbase/vantage/slide` | The slide primitives (pptx export, loaded dynamically) |
+
+Re-exporting them from the `/components` barrel would put an import edge on every app that only
+wanted `DataTable`, and a bundler cannot drop that.
+
+### The table viewer (`/table`)
+
+A `.csv` or `.xlsx` under `src/` [becomes a page on its own](routing). Reach for this directly
+only when you want to set the title yourself, or embed a table inside a dashboard page.
+
+```tsx
+import { FilePageView, TableViewer, SheetGrid, loadWorkbook } from "@squadbase/vantage/table";
+```
+
+| Name | What it does |
+|---|---|
+| `FilePageView` | The file page itself: give it a URL and it fetches, parses and renders |
+| `TableViewer` | One sheet in a frame — fills the rest of the viewport, sheet tabs and counts along the bottom |
+| `SheetGrid` | The spreadsheet grid itself. Put it in a parent with a definite height |
+| `loadWorkbook` | URL → parsed sheets |
+
+It looks **like a spreadsheet**: column letters across the top, row numbers down the side, the
+file's first row frozen as the header, ruling that runs past the data. It is read-only — no
+toolbar, no sorting, no pagination (a selected cell copies with `Cmd/Ctrl+C`). Sorting and
+filtering are [`DataTable`](parts/data-table)'s job, not the viewer's. Colours come
+from the app's theme tokens, so dark mode follows.
+
+### Slides (`/slide`)
+
+A `<name>.slide.tsx` [becomes a slide-deck page](routing).
+
+```tsx
+import {
+  MorphElement, Slide, SlideDeck, Step, Steps, useSlideNumber,
+} from "@squadbase/vantage/slide";
+```
+
+| Name | Role |
+|---|---|
+| `SlideDeck` | The deck. `theme` overrides tokens; `embedded` renders it in the page flow; `rail={false}` starts with the slide list closed |
+| `Slide` | One slide. `transition` declares its enter/exit |
+| `Steps` / `Step` | Stepped reveals — `→` opens one at a time |
+| `MorphElement` | Carries the same object across two slides (same `id` on both) |
+| `useSlideNumber` | `{ current, total }`, for a page-number footer |
+| `useIsActiveSlide` | Whether this is the instance the audience is watching; gate entrance animations on it |
+
+A reader picks one of three views — **list + slide** (the default: a thumbnail rail down the left),
+**the slide alone** (`L` closes the rail and the slide fills the viewport), and **fullscreen** (`F`,
+where the rail steps aside). None of them is decided in code, and the rail's state rides in
+`?rail=`, so a link can hand someone either one. Only a deck that should start closed says so, with
+`<SlideDeck rail={false}>`; an `embedded` deck starts closed already, having no width to spare. The
+rail is painted purely from mixes of the deck's own `--slide-bg` and `--slide-fg`, so it carries no
+colour of its own.
+
+Slides are authored against a **fixed 1920×1080 canvas** in absolute pixels and scaled to fit.
+Colour and type come from the `--slide-*` tokens, which default to aliases of the app's own tokens
+under "Override theme tokens" below — so **a deck follows dark mode without doing anything**.
+
+How to actually write one — the canvas's vertical budget, the type scale, the design principles
+behind transitions, the rules morph rests on, and what breaks a pptx export — lives in the bundled
+**`vantage-slide` skill** ([Agent skills](agent-skills)).
+
+> [!NOTE]
+> Do not use `@squadbase/vantage/ui` primitives inside a slide. The kit is built in rem against
+> Tailwind for dashboards, so projecting a scaled 1920×1080 canvas leaves a `text-sm` button at an
+> effective 8px — unreadable.
+
+## Documents (`/doc`)
+
+A `<name>.doc.tsx` [becomes a document page](routing). Wrap it in `Document` and the plain HTML
+elements written inside (`h1`–`h4`, `p`, `ul`/`ol`, `table`, `blockquote`, `pre`/`code`, `hr`, `a`,
+`figure`/`figcaption`, `img`) get their heading sizes, spacing and rules. A
+[`EChart`](parts/echart) can sit in the text as it is.
+
+```tsx
+import { Document } from "@squadbase/vantage/doc";
+```
+
+Colour, type and the width of the text column are `--doc-*` tokens. By default they alias the app's
+tokens, so **they follow dark mode on their own**.
+
+| Token | Default | What it styles |
+|---|---|---|
+| `--doc-fg` / `--doc-muted` | `--foreground` / `--muted-foreground` | Body text / quotes and captions |
+| `--doc-accent` | `--primary` | Links |
+| `--doc-border` / `--doc-subtle` | `--border` / `--muted` | Rules / background of code and table headers |
+| `--doc-font-body` / `--doc-font-heading` / `--doc-font-mono` | The app's type | Body / headings / code |
+| `--doc-size-body` / `--doc-line-height` / `--doc-max-width` | `1rem` / `1.8` / `48rem` | Type size / line height / column width |
+
+Override them app-wide on `:root` in `styles.css`, or for one document with
+`<Document theme={{ accent: "#2563eb" }}>`. A Tailwind utility on an element through `className`
+wins over the default styling.
+
 ## Tailwind just works
 
 Write Tailwind utilities in `className` and they apply. You never write `tailwind.config` or

package/docs/index.json

@@ -28,7 +28,7 @@
       "section": "guide",
       "sectionTitle": "ガイド",
       "title": "ファイルベースルーティング",
-      "description": "ファイルを置くだけでルートが生まれる。ページ・レイアウト・動的パラメータ・404/error の規約。",
+      "description": "ファイルを置くだけでルートが生まれる。ページ・レイアウト・動的パラメータ・404/error の規約と、tsx 以外のページ（csv / xlsx / スライド / ドキュメント）。",
       "file": "ja/routing.md",
       "order": 1
     },
@@ -720,7 +720,7 @@
       "section": "guide",
       "sectionTitle": "Guide",
       "title": "File-based routing",
-      "description": "Dropping a file creates a route. Conventions for pages, layouts, dynamic params, and 404/error.",
+      "description": "Dropping a file creates a route. Conventions for pages, layouts, dynamic params and 404/error, plus the pages that are not .tsx (csv / xlsx / slides / documents).",
       "file": "en/routing.md",
       "order": 1
     },

package/docs/ja/agent-skills.md

@@ -14,6 +14,8 @@ Vantage は **Claude Code の Agent Skills** を同梱しています。Skill
 |---|---|
 | `vantage-app` | アプリの新規作成と、`index.tsx` 単体の SPA から `server/api`・ネストレイアウト・動的ルート・404/error を備えた fullstack への拡張 |
 | `vantage-add-feature` | ページ / API / UI / ブロックの追加(`vantage add` + `check` / `routes` までの一連) |
+| `vantage-slide` | `.slide.tsx` でスライドデッキを書く(1920×1080 キャンバスの縦方向の予算、タイプスケール、段階表示、トランジションとモーフ、pptx 書き出しの前提) |
+| `vantage-design` | 見た目の意図 `DESIGN.md` と値を持つ `styles.css` をまとめて作る / 更新する(配色・チャートの色・書体・ブランド合わせ。URL・ロゴ・資料・外部の DESIGN.md からの取り込み、コントラストの確認) |
 | `vantage-pitfalls` | 落とし穴リファレンス(Base UI ≠ Radix、`SelectValue` の挙動、クライアントから `server/` を import しない など) |
 | `project-storage` | Squadbase の Project Storage(アップロード済みファイル)をブラウザから扱う(一覧、画像 / 動画 / PDF の埋め込み、アップロード)。Squadbase 上で動くアプリ向け |
 
@@ -41,7 +43,9 @@ Bundled skills:
   project-storage      .claude/skills/project-storage/
   vantage-add-feature  .claude/skills/vantage-add-feature/
   vantage-app          .claude/skills/vantage-app/
+  vantage-design       not placed
   vantage-pitfalls     not placed
+  vantage-slide        not placed
 ```
 
 `--force` を付けると、**見つかった場所をそのまま**新しい内容で書き換えます(`--dir` を明示した
@@ -58,7 +62,9 @@ your-app/
     └── skills/
         ├── vantage-app/SKILL.md
         ├── vantage-add-feature/SKILL.md
+        ├── vantage-design/SKILL.md     (references/ と scripts/ も一緒に配られる)
         ├── vantage-pitfalls/SKILL.md
+        ├── vantage-slide/SKILL.md      (references/ も一緒に配られる)
         └── project-storage/SKILL.md
 ```
 
@@ -79,24 +85,27 @@ Skill の手順を読み込んで実行します。他のエージェントに
 - **Squadbase テンプレートには配置済み**です。テンプレートから作ったアプリには、最初から
   `.claude/skills/` が入っています。手で作ったアプリには `vantage add skill` で足してください。
 
-## `AGENTS.md`(アプリの地図)
+## `AGENTS.md` + `agents/*.md`(アプリの地図と知識ファイル)
 
 Skill が「手順書」なら、`AGENTS.md` は**エージェントが最初に読む「地図」**です。Vantage の
-不変条件・import サブパスの地図・ルーティング規約・データ取得/API/env の最小レシピを 1 ページに
-まとめてあり、**それだけ読んで最小アプリを組める**ことを狙っています。手順の深掘りは上の Skill へ
-名前で誘導し、内容は重複させません。
+不変条件・import サブパスの地図・ディレクトリ構造・env の最小レシピを 1 ページにまとめ、
+「何を書くか → どのファイルを読むか」という表で `agents/` 配下の知識ファイルへ誘導します。
+`agents/page.md`(通常ページ)・`agents/api.md`(`server/`)・`agents/slide.md`
+(`.slide.tsx`)・`agents/xlsx.md`・`agents/csv.md` は、それぞれの種類のファイルを書くときだけ
+読めばよい種類ごとの静的リファレンスです。手順の深掘りは上の Skill へ名前で誘導し、内容は
+重複させません。
 
-Skill と同じく **source-of-truth はパッケージ内**にあり、`vantage add agents` でアプリルートへ
-配置します。
+Skill と同じく **source-of-truth はパッケージ内**にあり、`vantage add agents` で `AGENTS.md` と
+`agents/*.md` をまとめてアプリルートへ配置します。
 
 ```bash
-vantage add agents           # AGENTS.md をアプリルートに配置
+vantage add agents           # AGENTS.md + agents/*.md をアプリルートに配置
 vantage add agents --force    # 既存を上書き
 ```
 
-配置済みの `AGENTS.md` は `vantage upgrade` で正本と同期されます(差分があるときだけ書き換え、
-まだ配置していないアプリには作りません)。フレームワークの規約が変わっても、**正本 1 箇所の更新**が
-`upgrade` でアプリへ反映されます。Squadbase テンプレートには最初から配置済みです。
+配置済みの `AGENTS.md` + `agents/*.md` は `vantage upgrade` で正本と同期されます(差分がある
+ファイルだけ書き換え、まだ配置していないアプリには作りません)。フレームワークの規約が変わっても、
+**正本の更新**が `upgrade` でアプリへ反映されます。Squadbase テンプレートには最初から配置済みです。
 
 ## 責務の切り分け
 
@@ -106,6 +115,7 @@ Skill は「**手順を伴うワークフロー**」だけを担います。次
   エージェントには、同じ内容が [`vantage docs`](cli-reference) でそのまま読めます
   (`vantage docs button` で props の表、`vantage docs --json` で機械可読。名前が
   分からなければ `vantage search <やりたいこと>`)。
-- **`AGENTS.md`**(静的な地図)― 構成やファイルの居場所。`vantage add agents` で配置します。
+- **`AGENTS.md`**(静的な地図)― 構成やファイルの居場所。`agents/*.md`(種類ごとの静的
+  リファレンス)と合わせて `vantage add agents` で配置します。
 - Skill 同士 ― 落とし穴などの共通内容は各 Skill に写経せず、**名前で相互参照**します
   (例: `vantage-app` の手順中から `vantage-pitfalls` を指す)。