@voltro/cli 0.15.0 → 0.17.0

package/dist/startEntry.js

@@ -1,3 +1,3 @@
-import { $ as e } from "./inspectMetrics-CYDSO3za.js";
-import { t } from "./start-BtgatJN3.js";
+import { Q as e } from "./inspectMetrics-DWh56Qas.js";
+import { t } from "./start-ksY0wMZG.js";
 export { e as loadDotEnv, t as runStartCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -62,22 +62,22 @@
     "@effect/platform-node": "^0.107.0",
     "@effect/sql": "^0.51.1",
     "@effect/workflow": "^0.18.2",
-    "@voltro/ai": "0.15.0",
-    "@voltro/cache": "0.15.0",
-    "@voltro/data-transfer": "0.15.0",
-    "@voltro/database": "0.15.0",
-    "@voltro/env": "0.15.0",
-    "@voltro/kv": "0.15.0",
-    "@voltro/logger": "0.15.0",
-    "@voltro/plugin-auth": "0.15.0",
-    "@voltro/plugin-broadcast": "0.15.0",
-    "@voltro/plugin-mail": "0.15.0",
-    "@voltro/plugin-storage": "0.15.0",
-    "@voltro/plugin-webhooks": "0.15.0",
-    "@voltro/protocol": "0.15.0",
-    "@voltro/runtime": "0.15.0",
-    "@voltro/serverless": "0.15.0",
-    "@voltro/workflow": "0.15.0",
+    "@voltro/ai": "0.17.0",
+    "@voltro/cache": "0.17.0",
+    "@voltro/data-transfer": "0.17.0",
+    "@voltro/database": "0.17.0",
+    "@voltro/env": "0.17.0",
+    "@voltro/kv": "0.17.0",
+    "@voltro/logger": "0.17.0",
+    "@voltro/plugin-auth": "0.17.0",
+    "@voltro/plugin-broadcast": "0.17.0",
+    "@voltro/plugin-mail": "0.17.0",
+    "@voltro/plugin-storage": "0.17.0",
+    "@voltro/plugin-webhooks": "0.17.0",
+    "@voltro/protocol": "0.17.0",
+    "@voltro/runtime": "0.17.0",
+    "@voltro/serverless": "0.17.0",
+    "@voltro/workflow": "0.17.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.core.md

@@ -219,7 +219,7 @@ a `web/` (frontend).
 │   │   └── rpcGroup.generated.ts   # codegen — do NOT edit
 │   └── web/
 │       ├── app.config.ts       # { type:'web', apis, theme, locales, … }
-│       └── src/pages/**/*.page.tsx  # file-based routing (only *.page.tsx)
+│       └── src/pages/**/page.tsx    # a DIRECTORY is a route segment
 ├── packages/                   # shared libs
 └── AGENTS.md / CLAUDE.md       # this file
 ```
@@ -249,7 +249,7 @@ public REST routes, declared via `restRoutes` in `app.config.ts`).
 | `*.agent.tsx` + `*.agent.server.tsx` | server-side LLM chat |
 | `*.tool.tsx` | tool an agent can call |
 | `*.entity.ts` / `*.schema.ts` / `schema.ts` | one table per file |
-| `*.page.tsx` (under `src/pages/`) | web page (file-based route) + `*.page.test.tsx` |
+| `page.tsx` (under `src/pages/`) | the route its DIRECTORY serves + `page.test.tsx` |
 | `*.component.tsx` | exactly ONE component (+ types) |
 | `*.component.ui.tsx` | presentational: one component, READS only — never writes |
 | `*.hook.ts` | exactly ONE `use*` hook (+ types) |
@@ -260,12 +260,27 @@ public REST routes, declared via `restRoutes` in `app.config.ts`).
 | `*.store.ts` | exactly ONE `defineStore` — client state, never server state |
 | `*.client.ts` | declares itself + its transitive imports browser-safe |
 
-**Only `*.page.tsx` is a route.** Everything else under `src/pages/` — components,
-hooks, tests — is ordinary code with no URL, so put it next to the page that uses
-it rather than in a distant `components/` directory. The suffix decides *whether*
-a file is a route; the path under `src/pages/` decides *which URL*. A `*.page.tsx`
-outside `src/pages/` never routes. A page MUST default-export its component —
-without it `voltro dev` refuses to boot and names the file.
+**A DIRECTORY is a route segment, and its route is `page.tsx`.**
+
+```
+src/pages/page.tsx                  → /
+src/pages/pricing/page.tsx          → /pricing
+src/pages/users/[id]/page.tsx       → /users/[id]
+src/pages/docs/[...slug]/page.tsx   → /docs/<anything>
+```
+
+A parameter is a DIRECTORY name (`[id]/`), never a filename. Beside `page.tsx`
+sit the other reserved names its segment owns — `layout.tsx`, `error.tsx`,
+`loading.tsx`, `not-found.tsx` — plus its `page.test.tsx` and any co-located
+components. **Anything in that folder that is not one of the reserved names is
+structurally not a route**, so put a component next to the page that uses it
+rather than in a distant `components/` directory.
+
+A `page.tsx` outside `src/pages/` never routes. A page MUST default-export its
+component — without it `voltro dev` refuses to boot and names the file.
+
+Do NOT write `x.page.tsx`, `index.page.tsx` or `[id].page.tsx` — those were the
+0.15.0 spelling and route nothing now.
 
 **Every suffix above is a CONTRACT, not a label.** Something else depends on each
 promise, and `voltro doctor` enforces all of them:
@@ -308,7 +323,7 @@ rules is that everything we author follows them.
 
 **Write the test in the same step as the code — always, for every primitive.**
 Not "afterwards", not in a cleanup pass: the filename is derivable
-(`users/[id].page.tsx` → `users/[id].page.test.tsx`,
+(`users/[id]/page.tsx` → `users/[id]/page.test.tsx`,
 `Card.component.tsx` → `Card.component.test.tsx`,
 `order.mutation.server.ts` → `order.mutation.server.test.ts`), so there is
 nothing to decide. A change is not finished until its test exists and passes.

package/templates/AGENTS.md

@@ -219,7 +219,7 @@ a `web/` (frontend).
 │   │   └── rpcGroup.generated.ts   # codegen — do NOT edit
 │   └── web/
 │       ├── app.config.ts       # { type:'web', apis, theme, locales, … }
-│       └── src/pages/**/*.page.tsx  # file-based routing (only *.page.tsx)
+│       └── src/pages/**/page.tsx    # a DIRECTORY is a route segment
 ├── packages/                   # shared libs
 └── AGENTS.md / CLAUDE.md       # this file
 ```
@@ -249,7 +249,7 @@ public REST routes, declared via `restRoutes` in `app.config.ts`).
 | `*.agent.tsx` + `*.agent.server.tsx` | server-side LLM chat |
 | `*.tool.tsx` | tool an agent can call |
 | `*.entity.ts` / `*.schema.ts` / `schema.ts` | one table per file |
-| `*.page.tsx` (under `src/pages/`) | web page (file-based route) + `*.page.test.tsx` |
+| `page.tsx` (under `src/pages/`) | the route its DIRECTORY serves + `page.test.tsx` |
 | `*.component.tsx` | exactly ONE component (+ types) |
 | `*.component.ui.tsx` | presentational: one component, READS only — never writes |
 | `*.hook.ts` | exactly ONE `use*` hook (+ types) |
@@ -260,12 +260,27 @@ public REST routes, declared via `restRoutes` in `app.config.ts`).
 | `*.store.ts` | exactly ONE `defineStore` — client state, never server state |
 | `*.client.ts` | declares itself + its transitive imports browser-safe |
 
-**Only `*.page.tsx` is a route.** Everything else under `src/pages/` — components,
-hooks, tests — is ordinary code with no URL, so put it next to the page that uses
-it rather than in a distant `components/` directory. The suffix decides *whether*
-a file is a route; the path under `src/pages/` decides *which URL*. A `*.page.tsx`
-outside `src/pages/` never routes. A page MUST default-export its component —
-without it `voltro dev` refuses to boot and names the file.
+**A DIRECTORY is a route segment, and its route is `page.tsx`.**
+
+```
+src/pages/page.tsx                  → /
+src/pages/pricing/page.tsx          → /pricing
+src/pages/users/[id]/page.tsx       → /users/[id]
+src/pages/docs/[...slug]/page.tsx   → /docs/<anything>
+```
+
+A parameter is a DIRECTORY name (`[id]/`), never a filename. Beside `page.tsx`
+sit the other reserved names its segment owns — `layout.tsx`, `error.tsx`,
+`loading.tsx`, `not-found.tsx` — plus its `page.test.tsx` and any co-located
+components. **Anything in that folder that is not one of the reserved names is
+structurally not a route**, so put a component next to the page that uses it
+rather than in a distant `components/` directory.
+
+A `page.tsx` outside `src/pages/` never routes. A page MUST default-export its
+component — without it `voltro dev` refuses to boot and names the file.
+
+Do NOT write `x.page.tsx`, `index.page.tsx` or `[id].page.tsx` — those were the
+0.15.0 spelling and route nothing now.
 
 **Every suffix above is a CONTRACT, not a label.** Something else depends on each
 promise, and `voltro doctor` enforces all of them:
@@ -308,7 +323,7 @@ rules is that everything we author follows them.
 
 **Write the test in the same step as the code — always, for every primitive.**
 Not "afterwards", not in a cleanup pass: the filename is derivable
-(`users/[id].page.tsx` → `users/[id].page.test.tsx`,
+(`users/[id]/page.tsx` → `users/[id]/page.test.tsx`,
 `Card.component.tsx` → `Card.component.test.tsx`,
 `order.mutation.server.ts` → `order.mutation.server.test.ts`), so there is
 nothing to decide. A change is not finished until its test exists and passes.
@@ -526,7 +541,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.14.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.16.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |

package/templates/agent-docs/_index.md

@@ -9,7 +9,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.14.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.16.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |

package/templates/agent-docs/cli.md

@@ -1211,8 +1211,8 @@ A page is listed when ALL of these hold:
 
 ```text
 •  renderMode:'spa' candidates (2 pages — loader-free, under a layout, currently ssr/default):
-   src/pages/dashboard/index.page.tsx  (/dashboard) — default renderMode
-   src/pages/admin/settings.page.tsx  (/admin/settings) — renderMode:'ssr'
+   src/pages/dashboard/page.tsx  (/dashboard) — default renderMode
+   src/pages/admin/settings/page.tsx  (/admin/settings) — renderMode:'ssr'
      → renderMode:'spa' skips this page's SSR compile while its layout shell still renders server-side — adopt it if the page BODY does not need SSR (internal/authenticated pages); keep 'ssr' if the page content needs SEO or server first-paint.
 ```
 

package/templates/agent-docs/data.md

@@ -927,7 +927,15 @@ try {
 
 **Trace id for debugging.** An error caught from `useMutation` / `useAction` carries a **non-enumerable `__voltroTraceId`** — the bridge to the server logs for that exact call:
 
-```ts
+```
+`errorTag` lives in `@voltro/protocol` rather than in the client for a reason
+worth knowing before you decide where your own error handling goes: **`_tag` is a
+wire concept, and protocol owns the wire.** So a shared error handler in a package
+that has no business depending on `@voltro/client` — a UI kit, an i18n layer —
+can read a tag without taking that dependency. `instanceof` is the thing that
+does NOT survive the wire: what arrives in the browser was decoded from JSON and
+never constructed, so match on the tag, not on the class.
+ts
 const traceId = (err as { __voltroTraceId?: string }).__voltroTraceId
 // → `voltro logs --trace <traceId>` to see the server-side span
 ```

package/templates/agent-docs/database/migrations.md

@@ -2316,7 +2316,7 @@ If multiple apps target the same database, they're showing the same `_voltro_mig
 
 ## Source code
 
-The shared component lives in `voltro/packages/devtools-ui/src/pages/MigrationsPage.page.tsx`. The local devtools wiring is in `voltro-devtools/apps/dashboard/src/pages/apps/[appId]/migrations.page.tsx`. Both repos are open to extension.
+The shared component lives in `voltro/packages/devtools-ui/src/pages/MigrationsPage/page.tsx`. The local devtools wiring is in `voltro-devtools/apps/dashboard/src/pages/apps/[appId]/migrations/page.tsx`. Both repos are open to extension.
 
 
 
@@ -2504,8 +2504,8 @@ server enforces this regardless of which buttons the UI renders.
 
 ## Source code
 
-- Component: `voltro/packages/devtools-ui/src/pages/MigrationsPage.page.tsx` — shared
-- Cloud wiring: `voltro-cloud/apps/voltro-cloud/dashboard/src/pages/_/p/[orgSlug]/[projectSlug]/apps/[appSlug]/migrations.page.tsx`
+- Component: `voltro/packages/devtools-ui/src/pages/MigrationsPage/page.tsx` — shared
+- Cloud wiring: `voltro-cloud/apps/voltro-cloud/dashboard/src/pages/_/p/[orgSlug]/[projectSlug]/apps/[appSlug]/migrations/page.tsx`
 - Cloud-api proxy: `voltro-cloud/apps/voltro-cloud/api/queries/apps.inspectMigrationsStatus.query.ts` + `.query.server.ts`
 - Approval schema: `voltro-cloud/apps/voltro-cloud/api/database/migrationPlans.entity.ts` + `migrationApprovals.entity.ts`
 - Approval rpc: `migrations.submitPlan` + `migrations.approve` (mutations), `migrations.pendingApprovals` (query), `migrations.reviewByToken` (action)

package/templates/agent-docs/internationalization.md

@@ -423,7 +423,7 @@ export default function Layout({ children }) {
 }
 ```
 
-Pair this with locale-prefixed page files: `src/pages/[locale]/index.page.tsx`, `src/pages/[locale]/docs/[...slug].page.tsx`, etc. Each re-exports the default-locale query's component, which reads `useUrlLocale()` to decide which catalog data to query.
+Pair this with locale-prefixed page files: `src/pages/[locale]/page.tsx`, `src/pages/[locale]/docs/[...slug]/page.tsx`, etc. Each re-exports the default-locale query's component, which reads `useUrlLocale()` to decide which catalog data to query.
 
 Reference implementations: `voltro-dev/apps/voltro-dev/docs/` (URL-prefix on dynamic + static content) and `voltro-dev/apps/voltro-dev/landing/` (URL-prefix on a pure static marketing site — 10 default-locale pages, 10 locale-prefixed mirrors, one combined `voltro build` run).
 
@@ -441,7 +441,7 @@ dist/de/features/foo/index.html        ← de mirror
 Each variant ships with the right `<I18nProvider>`-wrapped body **and** the right per-locale `<title>` / `<meta description>` / `<link rel="canonical">` / OG tags — **if** the page's `meta` is exported as a function of `({ locale })`. With a plain static `meta: PageMeta` object, the body is correctly localised but the head tags stay default-locale on every variant.
 
 ```tsx
-// src/pages/features/foo.page.tsx — meta as a function of locale
+// src/pages/features/foo/page.tsx — meta as a function of locale
 import { getCatalog } from '../lib/locale'
 import { localeCanonicalUrl, ogTags, standardLinks } from '../lib/seo'
 
@@ -472,7 +472,7 @@ The `[locale]/…` mirror is the trigger for SSG **output** — without mirror f
 12 lines per page. Re-export the canonical page's `default`, `renderMode`, `interactive`, `meta`, plus a `getStaticPaths` that enumerates non-default locales:
 
 ```tsx
-// src/pages/[locale]/features/foo.page.tsx
+// src/pages/[locale]/features/foo/page.tsx
 import { SUPPORTED_LOCALES, DEFAULT_LOCALE } from '../../../lib/locale'
 export { default } from '../../features/foo'
 export { renderMode, interactive, meta } from '../../features/foo'

package/templates/agent-docs/introduction.md

@@ -404,7 +404,7 @@ An unmarked file makes no claim, and that is fine: `*.client.ts` is for the shar
 
 | Path | What it is |
 |---|---|
-| `src/pages/*.tsx` | A page. URL is the file path; `[id].page.tsx` -> `/:id`, `[...slug].page.tsx` -> catch-all. |
+| `src/pages/**/page.tsx` | A page. URL is the file path; `[id]/page.tsx` -> `/:id`, `[...slug]/page.tsx` -> catch-all. |
 | `src/pages/layout.tsx` | Outer layout — wraps every page. |
 | `src/pages/error.tsx` | Error boundary for the whole subtree. |
 | `src/pages/not-found.tsx` | Fallback rendered when no page matches. |
@@ -415,7 +415,7 @@ An unmarked file makes no claim, and that is fine: `*.client.ts` is for the shar
 Each page can opt into a render strategy via two exports:
 
 ```tsx
-// src/pages/blog/[slug].page.tsx
+// src/pages/blog/[slug]/page.tsx
 export const renderMode = 'isr' as const           // 'static' | 'spa' | 'ssr' | 'isr'
 export const interactive = 'islands' as const      // 'none' | 'islands' | 'full'
 ```

package/templates/agent-docs/plugins.md

@@ -126,7 +126,7 @@ Order matters: the framework composes outer→inner, so the rate-limit intercept
 | `extendSchema` | Contribute tables + custom SQL migrations (tracked in `_voltro_plugin_migrations`). |
 | `services` | Provide an Effect `Layer` whose Tags every handler can `yield*` (e.g. `MailService`, `StorageService`). |
 | `routes` | Register plugin-owned rpc queries / mutations / actions (alias-prefixed tags). |
-| `httpRoutes` | Serve public raw-HTTP endpoints on the framework listener (e.g. `GET /_voltro/storage/:id`). |
+| `httpRoutes` | Serve public raw-HTTP endpoints on the framework listener (e.g. `GET /_voltro/storage/:id`). The request carries `store` — the app's DataStore — for a route that must read or write (a login endpoint minting a session row cannot be an rpc mutation). Not tenant-scoped: raw HTTP has no resolved Subject, so scope it yourself. |
 | `inspectEndpoints` | Mount tooling under `/_voltro/inspect/plugins/<alias>/…`. |
 | `onScheduleFire` / `onWorkflowStep` / `onHttpRequest` | Wrap every cron firing, every workflow `step()`, every pre-auth HTTP request. |
 | `onInstall` / `onActivate` / `onDeactivate` / `onUninstall` | Lifecycle hooks at first-install, boot, shutdown, and removal. |

package/templates/agent-docs/reference.md

@@ -482,7 +482,7 @@ className={pathname.startsWith('/dashboard') ? 'active' : ''}
 URL params from `[name]` segments. Typed via the generic.
 
 ```tsx
-// src/pages/users/[id].page.tsx
+// src/pages/users/[id]/page.tsx
 import { useParams } from '@voltro/web'
 
 const { id } = useParams<{ id: string }>()
@@ -491,7 +491,7 @@ const { id } = useParams<{ id: string }>()
 For catch-all queries:
 
 ```tsx
-// src/pages/docs/[...slug].page.tsx
+// src/pages/docs/[...slug]/page.tsx
 const { slug } = useParams<{ slug: string }>()
 // /docs/intro/getting-started → slug = "intro/getting-started"
 ```
@@ -499,7 +499,7 @@ const { slug } = useParams<{ slug: string }>()
 For multi-segment dynamic paths:
 
 ```tsx
-// src/pages/orgs/[orgId]/projects/[projectId].page.tsx
+// src/pages/orgs/[orgId]/projects/[projectId]/page.tsx
 const { orgId, projectId } = useParams<{ orgId: string; projectId: string }>()
 ```
 
@@ -604,7 +604,7 @@ Idempotent — multiple calls for the same path fire one loader. The prefetched
 Page's loader output, typed.
 
 ```tsx
-// src/pages/notes/[id].page.tsx
+// src/pages/notes/[id]/page.tsx
 import { useLoaderData } from '@voltro/web'
 
 interface Note {

package/templates/agent-docs/routing.md

@@ -11,7 +11,7 @@
 
 _Voltro's file-based router — pages, layouts, render modes, loaders, navigation, islands. The web side of the framework._
 
-The web side of a Voltro app uses **file-based routing**: drop a `*.page.tsx` file under `src/pages/`, the CLI discovers it on every boot + save, and the file becomes a route. No router config, no manual `<Route>` declarations, no codegen step.
+The web side of a Voltro app uses **file-based routing**: drop a `page.tsx` file under `src/pages/`, the CLI discovers it on every boot + save, and the file becomes a route. No router config, no manual `<Route>` declarations, no codegen step.
 
 The suffix is what makes a file a route — the directory tree only decides *which URL*. Anything else under `src/pages/` (components, hooks, tests) is ordinary code and gets no URL, so it can live beside the page that uses it.
 
@@ -25,18 +25,18 @@ src/pages/
 ├── error.tsx               # error boundary
 ├── loading.tsx             # pending UI
 ├── not-found.tsx           # 404 fallback
-├── index.page.tsx               # /
-├── about.page.tsx               # /about
+├── page.tsx               # /
+├── about/page.tsx               # /about
 ├── (marketing)/            # route group — no URL segment
 │   ├── layout.tsx          # marketing-scoped layout
-│   └── pricing.page.tsx         # /pricing
+│   └── pricing/page.tsx         # /pricing
 ├── users/
 │   ├── layout.tsx          # users-scoped layout
 │   ├── error.tsx           # users-scoped error boundary
-│   ├── [id].page.tsx            # /users/:id
-│   └── index.page.tsx           # /users
+│   ├── [id]/page.tsx            # /users/:id
+│   └── page.tsx           # /users
 └── docs/
-    └── [...slug].page.tsx       # /docs/<anything>  (catch-all)
+    └── [...slug]/page.tsx       # /docs/<anything>  (catch-all)
 ```
 
 That's the whole router. No `<Route>`, no `<Switch>`, no `useRoutes`.
@@ -52,7 +52,7 @@ That's the whole router. No `<Route>`, no `<Switch>`, no `useRoutes`.
 
 ## Architecture in one paragraph
 
-The framework generates a `.framework/app.tsx` on every boot that imports each `*.page.tsx` file under `src/pages/` (excluding `node_modules`), wraps them in their layout chains, and produces a `<Router routes={…} />` element. A `mount(App, { group })` call in `.framework/main.tsx` mounts it via `react-dom/client`'s `createRoot` (or `hydrateRoot` for SSR pages). The router watches `window.location` + intercepts `<Link>` clicks for client-side nav.
+The framework generates a `.framework/app.tsx` on every boot that imports each `page.tsx` file under `src/pages/` (excluding `node_modules`), wraps them in their layout chains, and produces a `<Router routes={…} />` element. A `mount(App, { group })` call in `.framework/main.tsx` mounts it via `react-dom/client`'s `createRoot` (or `hydrateRoot` for SSR pages). The router watches `window.location` + intercepts `<Link>` clicks for client-side nav.
 
 You don't write any of this. The CLI regenerates it on every save in dev; the build pipeline freezes it for production.
 
@@ -125,7 +125,7 @@ A **page** is any `*.tsx` file under `src/pages/` that's not a special file (`la
 ## A static page
 
 ```tsx
-// src/pages/about.page.tsx → /about
+// src/pages/about/page.tsx → /about
 import type { ReactNode } from 'react'
 
 export default function About(): ReactNode {
@@ -145,9 +145,9 @@ That's it. Save the file, the CLI's discovery sees it on next save, the page is
 `index.tsx` maps to the directory's URL:
 
 ```text
-src/pages/index.page.tsx         → /
-src/pages/users/index.page.tsx   → /users
-src/pages/admin/index.page.tsx   → /admin
+src/pages/page.tsx         → /
+src/pages/users/page.tsx   → /users
+src/pages/admin/page.tsx   → /admin
 ```
 
 ## Dynamic segments
@@ -155,7 +155,7 @@ src/pages/admin/index.page.tsx   → /admin
 Brackets in the filename are dynamic. The captured value comes through `useParams<T>()`:
 
 ```tsx
-// src/pages/users/[id].page.tsx → /users/:id
+// src/pages/users/[id]/page.tsx → /users/:id
 import { useParams } from '@voltro/web'
 
 export default function User() {
@@ -167,7 +167,7 @@ export default function User() {
 Multiple dynamic segments in one path:
 
 ```text
-src/pages/orgs/[orgId]/projects/[projectId].page.tsx
+src/pages/orgs/[orgId]/projects/[projectId]/page.tsx
 // → /orgs/:orgId/projects/:projectId
 
 const { orgId, projectId } = useParams<{ orgId: string; projectId: string }>()
@@ -178,7 +178,7 @@ const { orgId, projectId } = useParams<{ orgId: string; projectId: string }>()
 `[...name]` captures one OR more URL segments as a single param value (joined by `/`):
 
 ```tsx
-// src/pages/docs/[...slug].page.tsx → /docs/<anything>
+// src/pages/docs/[...slug]/page.tsx → /docs/<anything>
 const { slug } = useParams<{ slug: string }>()
 // /docs/intro/getting-started → slug = "intro/getting-started"
 ```
@@ -186,7 +186,7 @@ const { slug } = useParams<{ slug: string }>()
 **Optional** catch-all (matches the base URL too):
 
 ```tsx
-// src/pages/docs/[[...slug]].page.tsx
+// src/pages/docs/[[...slug]]/page.tsx
 // /docs       → slug = ""
 // /docs/foo   → slug = "foo"
 // /docs/foo/bar → slug = "foo/bar"
@@ -201,10 +201,10 @@ When multiple files could match (static, dynamic, catch-all), priority is:
 3. Optional catch-all (`[[...slug]]`) wins over required catch-all (`[...slug]`) — the optional form scores as more specific, so it matches first.
 
 ```text
-src/pages/users/index.page.tsx     # /users → wins for /users
-src/pages/users/[id].page.tsx       # /users/:id → wins for /users/42
-src/pages/users/new.page.tsx        # /users/new → wins (static beats dynamic)
-src/pages/[...rest].page.tsx        # everything else
+src/pages/users/page.tsx     # /users → wins for /users
+src/pages/users/[id]/page.tsx       # /users/:id → wins for /users/42
+src/pages/users/new/page.tsx        # /users/new → wins (static beats dynamic)
+src/pages/[...rest]/page.tsx        # everything else
 ```
 
 ## Query strings
@@ -242,14 +242,14 @@ Parse the query string explicitly via `useServerRequest()` on the server and `wi
 
 ## Co-locating components, hooks and tests
 
-Only `*.page.tsx` is a route. Everything else under `src/pages/` is ordinary code and may sit next to the page that uses it:
+Only `page.tsx` is a route. Everything else under `src/pages/` is ordinary code and may sit next to the page that uses it:
 
 ```text
 src/pages/
 ├── users/
-│   ├── index.page.tsx        # → /users
-│   ├── index.page.test.tsx   # its test
-│   ├── [id].page.tsx         # → /users/:id
+│   ├── page.tsx        # → /users
+│   ├── page.test.tsx   # its test
+│   ├── [id]/page.tsx         # → /users/:id
 │   ├── UserCard.tsx          # a component — no URL
 │   └── useFilters.ts         # a hook — no URL
 ```
@@ -319,11 +319,11 @@ Conventions:
 ```text
 src/pages/
 ├── layout.tsx                # outer (every page)
-├── about.page.tsx                 # /about → wrapped in outer layout
+├── about/page.tsx                 # /about → wrapped in outer layout
 └── dashboard/
     ├── layout.tsx            # nested (only /dashboard/*)
-    ├── index.page.tsx             # /dashboard
-    └── settings.page.tsx          # /dashboard/settings
+    ├── page.tsx             # /dashboard
+    └── settings/page.tsx          # /dashboard/settings
 ```
 
 For `/dashboard/settings`, the React tree is:
@@ -346,13 +346,13 @@ A directory in `(parentheses)` does NOT contribute a URL segment, but its layout
 src/pages/
 ├── (marketing)/
 │   ├── layout.tsx            # marketing-scoped chrome
-│   ├── index.page.tsx             # /
-│   ├── pricing.page.tsx           # /pricing
-│   └── about.page.tsx             # /about
+│   ├── page.tsx             # /
+│   ├── pricing/page.tsx           # /pricing
+│   └── about/page.tsx             # /about
 └── (app)/
     ├── layout.tsx            # authenticated app chrome
-    ├── dashboard.page.tsx         # /dashboard
-    └── settings.page.tsx          # /settings
+    ├── dashboard/page.tsx         # /dashboard
+    └── settings/page.tsx          # /settings
 ```
 
 Marketing pages get one layout; authenticated app pages get another; the URLs stay flat.
@@ -496,7 +496,7 @@ Those four are the **complete** set. An unrecognised value is a hard error namin
 ## static (SSG)
 
 ```tsx
-// src/pages/about.page.tsx
+// src/pages/about/page.tsx
 export const renderMode = 'static' as const
 ```
 
@@ -509,7 +509,7 @@ At `voltro build`:
 For dynamic patterns, export `getStaticPaths` to enumerate every URL to pre-render:
 
 ```tsx
-// src/pages/blog/[slug].page.tsx
+// src/pages/blog/[slug]/page.tsx
 export const renderMode = 'static' as const
 
 export const getStaticPaths = async () => [
@@ -734,7 +734,7 @@ Both are static module exports — the framework discovers them, the build pipel
 ## A loader
 
 ```tsx
-// src/pages/notes/[id].page.tsx
+// src/pages/notes/[id]/page.tsx
 import { useLoaderData } from '@voltro/web'
 
 interface Note {
@@ -844,7 +844,7 @@ splits the loader's result into data that blocks the shell and data that
 soon as the promise settles.
 
 ```tsx
-// src/pages/dashboard.page.tsx
+// src/pages/dashboard/page.tsx
 import { Await, defer, useLoaderData } from '@voltro/web'
 
 export const renderMode = 'ssr' as const   // required — see below
@@ -964,7 +964,7 @@ Use `signal` for any fetch that could outlive the request — pass it to `fetch(
 Instead of hand-rolling a `fetch(INTERNAL_API/...)`, a server-side loader can call the backend rpc directly through `ctx.query` — the same query tags the client subscribes to, resolved to their initial snapshot:
 
 ```tsx
-// src/pages/notes/[id].page.tsx
+// src/pages/notes/[id]/page.tsx
 import { useSubscription } from '@voltro/client'
 import { useLoaderData, type PageMeta } from '@voltro/web'
 
@@ -1136,7 +1136,7 @@ export const meta = ({ locale }: { locale: string }): PageMeta => {
 ### Authenticated dashboard with cookie-driven loader
 
 ```tsx
-// src/pages/dashboard/index.page.tsx
+// src/pages/dashboard/page.tsx
 import { useLoaderData } from '@voltro/web'
 
 export const renderMode = 'ssr' as const
@@ -1162,7 +1162,7 @@ export default function Dashboard() {
 `getStaticPaths` has no framework store — it reads its own content source (a CMS client, the filesystem, an API). The loader runs server-side and fetches via `query` (the backend rpc, resolved to its first snapshot):
 
 ```tsx
-// src/pages/blog/[slug].page.tsx
+// src/pages/blog/[slug]/page.tsx
 import { listPostSlugs, type Post } from '../../content/posts'
 
 export const renderMode = 'static' as const
@@ -1563,7 +1563,7 @@ export default island(LikeButton, { name: 'LikeButton', hydrate: 'visible' })
 Use it in a page:
 
 ```tsx
-// src/pages/blog/[slug].page.tsx
+// src/pages/blog/[slug]/page.tsx
 import LikeButton from '../../components/LikeButton.island'
 
 export const renderMode = 'static' as const