@voltro/cli 0.16.0 → 0.18.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-D1DmLeJs.js";
+import { t } from "./start-Clvz4IJb.js";
 export { e as loadDotEnv, t as runStartCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.16.0",
+  "version": "0.18.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.16.0",
-    "@voltro/cache": "0.16.0",
-    "@voltro/data-transfer": "0.16.0",
-    "@voltro/database": "0.16.0",
-    "@voltro/env": "0.16.0",
-    "@voltro/kv": "0.16.0",
-    "@voltro/logger": "0.16.0",
-    "@voltro/plugin-auth": "0.16.0",
-    "@voltro/plugin-broadcast": "0.16.0",
-    "@voltro/plugin-mail": "0.16.0",
-    "@voltro/plugin-storage": "0.16.0",
-    "@voltro/plugin-webhooks": "0.16.0",
-    "@voltro/protocol": "0.16.0",
-    "@voltro/runtime": "0.16.0",
-    "@voltro/serverless": "0.16.0",
-    "@voltro/workflow": "0.16.0",
+    "@voltro/ai": "0.18.0",
+    "@voltro/cache": "0.18.0",
+    "@voltro/data-transfer": "0.18.0",
+    "@voltro/database": "0.18.0",
+    "@voltro/env": "0.18.0",
+    "@voltro/kv": "0.18.0",
+    "@voltro/logger": "0.18.0",
+    "@voltro/plugin-auth": "0.18.0",
+    "@voltro/plugin-broadcast": "0.18.0",
+    "@voltro/plugin-mail": "0.18.0",
+    "@voltro/plugin-storage": "0.18.0",
+    "@voltro/plugin-webhooks": "0.18.0",
+    "@voltro/protocol": "0.18.0",
+    "@voltro/runtime": "0.18.0",
+    "@voltro/serverless": "0.18.0",
+    "@voltro/workflow": "0.18.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.
@@ -434,6 +449,44 @@ aggregations, FTS, vectors/RAG, migrations, dialect parity → the **`database/*
 docs (see index). Async-vs-Effect handlers, `EffectStore`, typed store errors →
 **`data.md`**.
 
+## What may cross the wire (three ORTHOGONAL markers — do not substitute one for another)
+
+A column is not "protected" or "unprotected". Three separate questions get three
+separate markers, and using one to answer another's question is the mistake:
+
+| Marker | Answers | Enforced by |
+|---|---|---|
+| `.serverOnly()` | may this value leave the server AT ALL? | **the boot audit — it FAILS the boot**, it does not warn |
+| `.sensitive('class')` / `.safe()` | may it appear in a `voltro data export`? | the export's masking profile, **fail-closed** |
+| `.encrypted()` | is it encrypted AT REST? | the store's codec |
+
+```ts
+export const users = table('users', {
+  id:       id(),
+  email:    text().sensitive('pii'),      // exportable only through a profile
+  pinHash:  text().serverOnly(),          // never reaches a client, ever
+  ssn:      text().encrypted().serverOnly(),  // both — they are not the same claim
+})
+```
+
+- **`.serverOnly()` is the one that decides "leak / no leak".** A wire-reachable
+  query that declares such a column in its OUTPUT does not start: the boot audit
+  refuses. That is a feature — the failure happens at boot, not in a bundle.
+- **`.encrypted()` is NOT an exposure marker.** It says the bytes at rest are
+  encrypted; the runtime decrypts them for a handler, so an encrypted column
+  flows to the client exactly like any other unless it is ALSO `.serverOnly()`.
+  Reading `.encrypted()` as "safe to expose" is a category error, and a plausible
+  one — say both when you mean both.
+- **Masking is fail-closed**: an unclassified column blocks the export rather
+  than passing through, so `.sensitive()` / `.safe()` is a decision you make once
+  per column, not a filter you remember to apply.
+- `crud.list` / `getById` / `create` / `update` are **redacted by construction** —
+  they strip `serverOnly` columns for you. Hand-rolling the same CRUD is where
+  that stripping gets forgotten.
+
+Depth (classes, profiles, the export flow) → **`database/sensitivity`**; the
+redacted CRUD surface → **`data/crud`**.
+
 ## Naming / RPC tags
 
 - **camelCase** for vars, files, schemas, and rpc tags. The tag IS the wire

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.
@@ -434,6 +449,44 @@ aggregations, FTS, vectors/RAG, migrations, dialect parity → the **`database/*
 docs (see index). Async-vs-Effect handlers, `EffectStore`, typed store errors →
 **`data.md`**.
 
+## What may cross the wire (three ORTHOGONAL markers — do not substitute one for another)
+
+A column is not "protected" or "unprotected". Three separate questions get three
+separate markers, and using one to answer another's question is the mistake:
+
+| Marker | Answers | Enforced by |
+|---|---|---|
+| `.serverOnly()` | may this value leave the server AT ALL? | **the boot audit — it FAILS the boot**, it does not warn |
+| `.sensitive('class')` / `.safe()` | may it appear in a `voltro data export`? | the export's masking profile, **fail-closed** |
+| `.encrypted()` | is it encrypted AT REST? | the store's codec |
+
+```ts
+export const users = table('users', {
+  id:       id(),
+  email:    text().sensitive('pii'),      // exportable only through a profile
+  pinHash:  text().serverOnly(),          // never reaches a client, ever
+  ssn:      text().encrypted().serverOnly(),  // both — they are not the same claim
+})
+```
+
+- **`.serverOnly()` is the one that decides "leak / no leak".** A wire-reachable
+  query that declares such a column in its OUTPUT does not start: the boot audit
+  refuses. That is a feature — the failure happens at boot, not in a bundle.
+- **`.encrypted()` is NOT an exposure marker.** It says the bytes at rest are
+  encrypted; the runtime decrypts them for a handler, so an encrypted column
+  flows to the client exactly like any other unless it is ALSO `.serverOnly()`.
+  Reading `.encrypted()` as "safe to expose" is a category error, and a plausible
+  one — say both when you mean both.
+- **Masking is fail-closed**: an unclassified column blocks the export rather
+  than passing through, so `.sensitive()` / `.safe()` is a decision you make once
+  per column, not a filter you remember to apply.
+- `crud.list` / `getById` / `create` / `update` are **redacted by construction** —
+  they strip `serverOnly` columns for you. Hand-rolling the same CRUD is where
+  that stripping gets forgotten.
+
+Depth (classes, profiles, the export flow) → **`database/sensitivity`**; the
+redacted CRUD surface → **`data/crud`**.
+
 ## Naming / RPC tags
 
 - **camelCase** for vars, files, schemas, and rpc tags. The tag IS the wire
@@ -526,7 +579,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.15.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.18.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.15.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.18.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/authentication.md

@@ -569,6 +569,54 @@ Read users, sessions, keys. A strategy that runs domain writes while deciding
 who the caller is has the two jobs the wrong way round; nothing in the type
 stops you, and it is still wrong.
 
+#### What the boot store carries, and what it does not
+
+The line is **everything that does not need a Subject** — not "less than
+`ctx.store`":
+
+| | Boot store (`input.store`, `req.store`) | Request store (`ctx.store`) |
+|---|---|---|
+| `.encrypted()` columns decrypt / encrypt | ✓ | ✓ |
+| Array columns round-trip on non-native dialects | ✓ | ✓ |
+| Tenant scope | — | ✓ |
+| Soft-delete filter | — | ✓ |
+| Audit-column stamping | — | ✓ |
+| Row-level security | — | ✓ |
+
+The right-hand four need a resolved Subject, and a strategy runs *before* one
+exists — so a read of tenant-owned rows here must derive and apply that scope
+itself. The first two do not, and getting them wrong is silent: a `.encrypted()`
+column read raw hands back the string `enc:v1:…`, which compares, concatenates,
+renders and logs perfectly well, and simply never matches the token you compare
+it to.
+
+This is also what changes when you move a read **off** hand-written SQL and onto
+the store. Raw SQL sees ciphertext and you decrypt it yourself — `decryptField`
+from `@voltro/runtime` is the escape hatch for exactly that. Through either
+store you get plaintext, so a hand-rolled `decryptField` on the way out will now
+be handed a plaintext value; `decryptField` passes a non-ciphertext value
+through unchanged, so the double call is harmless, but the manual step is no
+longer doing anything.
+
+#### Reading a plugin's own tables
+
+A plugin's tables are declared through `extendSchema` like any others, so they
+are in the same registry and the same store reads them. A public route that
+needs a row a plugin wrote — a storage reference for an avatar proxy, say —
+reads it directly:
+
+```ts
+const [ref] = await req.store.query(
+  queryFor(storageObjects).where(eq('id', objectId)).descriptor,
+)
+```
+
+Two things to keep in mind. The table is the plugin's contract with itself, not
+with you, so it can change shape in any release — pin the version if you depend
+on it. And this store applies no tenant scope, so a route reading a
+tenant-owned plugin table must filter by tenant itself, from something the
+request proves rather than something it claims.
+
 ## Composing the chain
 
 `composeAuthStrategies` turns an ordered list of strategies into a single resolver. First `matched` wins; first `failed` short-circuits to anonymous.

package/templates/agent-docs/cli.md

@@ -600,19 +600,23 @@ export default {
 }
 ```
 
-#### Inspect token (token-gated deploys)
+#### Inspect token
 
-The overlay's webhooks / traces / indexes panels poll each api's `/_voltro/inspect/*` endpoints. Under `voltro dev` that surface is open, so no auth is needed. A token-gated deploy (`voltro start` with `VOLTRO_INSPECT_TOKEN` set) requires the same `Authorization: Bearer <token>` the CLI sends — otherwise the panels 401 to their empty state.
+The overlay's webhooks / traces / indexes panels poll each api's `/_voltro/inspect/*` endpoints, and that surface is **fail-closed everywhere**: with no `VOLTRO_INSPECT_TOKEN` configured, nobody is authorised — `voltro dev` included.
 
-The overlay reads that token from `VITE_VOLTRO_INSPECT_TOKEN` (only `VITE_`-prefixed vars reach the browser bundle). A foreign-host mount can also pass it explicitly:
+**Under `voltro dev` you configure nothing.** The dev server mints a token per project and its proxy attaches the `Authorization: Bearer` header server-side, on the `/_voltro/api/<name>` route the panels fetch through. The token stays in the dev server's process; the browser never holds it.
+
+That is deliberate rather than convenient. A token compiled into the client bundle is a live credential published to everyone who loads the page, so there is no env-var channel for it — `voltro dev` and `voltro build` set vite's `envPrefix` to a sentinel precisely so nothing leaks through `import.meta.env`.
+
+For an api the dev proxy does not front — a `voltro start` deploy with `VOLTRO_INSPECT_TOKEN` set, say — pass the token explicitly, and note that whatever you pass ships in the bundle:
 
 ```tsx
 import { VoltroDevtools } from '@voltro/devtools'
 
-<VoltroDevtools inspectToken={import.meta.env.VITE_VOLTRO_INSPECT_TOKEN} />
+<VoltroDevtools inspectToken={myToken} />
 ```
 
-When neither the prop nor the env var is set, no `Authorization` header is sent — local dev is unaffected. (The indexes panel's live SSE stream can't carry a header; a token-gated deploy falls back to token-carrying HTTP polling for that panel.)
+Without the prop the overlay sends no `Authorization` header of its own, which is correct: under `voltro dev` the proxy has already added one. (The indexes panel's live SSE stream can't carry a header at all; against an api reached without the proxy it falls back to token-carrying HTTP polling.)
 
 #### Overriding the overlay's labels
 
@@ -1211,8 +1215,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/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/database/querying.md

@@ -105,11 +105,15 @@ ctx.store.select('notes')
 .where('col', '>',  value)
 .where('col', '>=', value)
 .where('col', 'in',  [a, b, c])
-.where('col', 'like',  'abc%')
-.where('col', 'contains', 'needle')        // case-insensitive substring (ILIKE '%…%')
+.where('col', 'contains',   'needle')      // case-INsensitive substring (ILIKE '%…%')
+.where('col', 'startsWith', 'awb_')        // case-SENSITIVE prefix (LIKE 'awb\_%')
 .where('col', 'fts', 'query string')       // full-text fallback (LIKE-based here)
 ```
 
+`contains` folds case because it is a search primitive — a human typing into a box means `hello` to find `Hello`. `startsWith` does not, because a prefix is a namespace: `awb_` and `AWB_` are two different key spaces, and quietly merging them is a bug. `startsWith` is also the only one of the two a database can answer from an index — `LIKE 'literal%'` is a btree range scan, `%…%` is not. `%` and `_` inside either value are escaped, so they match literally.
+
+There is no `'like'`. It used to be here, and it was a lie: it mapped to `contains`, so `.where('path', 'like', '/api/%')` matched only rows literally containing the characters `/api/%` and the wildcard you wrote did nothing. An operator named after SQL's must honour your wildcards or not exist.
+
 These are the only operators the ergonomic `.where(col, op, value)` form accepts. For `IS NULL` / `NOT IN` / `IS NOT NULL`, pass a predicate built with the `@voltro/database` helpers:
 
 ```ts

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'
 ```
@@ -473,7 +473,7 @@ If yes, the promise belongs in the name — you cannot see a contract before you
 
 | Suffix | Promise | Enforced by |
 |---|---|---|
-| `*.component.tsx` | exactly one component (+ types) | `component/one-per-file`, `component/no-hook-export` |
+| `*.component.tsx` | exactly one component | `component/one-per-file`, `component/no-hook-export` |
 | `*.component.ui.tsx` | one component, **reads only** | `ui/no-write`, `ui/orphaned`, `ui/unlinked` |
 | `*.hook.ts` | exactly one `use*` hook (+ types) | `hook/one-per-file`, `hook/no-component-export` |
 | `*.types.ts` | zero runtime exports | `types/runtime-export` |
@@ -483,6 +483,10 @@ If yes, the promise belongs in the name — you cannot see a contract before you
 | `*.client.ts` | it and its imports are browser-safe | boot-time import walk, `client/not-browser-safe` |
 | `*.store.ts` | exactly one `defineStore`, no server state | `store/one-per-file`, `store/mirrors-server-state` |
 
+A `*.component.tsx` promises exactly ONE component. It does not promise to export nothing else: types, and plain module-local values a `const COLUMNS = […]` beside the table that renders them, are fine and always were. What the rule counts is components — a declaration that renders — so an object, an array, a string or a `new` beside your component is not a second one, and neither is `export default Card` next to `export const Card`.
+
+The BOUNDARY rules (`internal/foreign-import`, `fixture/production-import`, `ui/unlinked`) are assertions about your import graph, so it is worth knowing which edges they follow: relative specifiers, your tsconfig `paths` aliases (read from the nearest `tsconfig.json`, so a per-app `@/*` works when you run `voltro doctor` at the repo root), `export … from` re-exports, and dynamic `import()`. A package import is a leaf — the walk stops at the edge of your app.
+
 ## `*.component.ui.tsx` — reads, never writes
 
 ```tsx
@@ -536,6 +540,16 @@ A component then wires it up with `useTracking(checkoutTracking, props, sink)`
 
 The payoff is not tidiness. "What do we send to third parties" becomes a file listing instead of an archaeology project — which is the only form in which that question can be answered on demand when someone asks about personal data.
 
+## `convention/missing-test` — why a shallow test is still worth writing
+
+Every suffix that declares a runtime contract also expects a test beside it, named mechanically: `Card.component.tsx` → `Card.component.test.tsx`. It is an advisory, not an error.
+
+The usual objection is that a per-component test at any real size is low value, and for *assertions* that is often true. That is not what the rule buys. What it buys is that something **mounts** the component — and a render loop, a crashing effect, a missing provider or a broken context is invisible until something does.
+
+That is not hypothetical. One app adopting the taxonomy wrote 251 of these, deliberately shallow (it mounts, it performs no domain write, it renders no raw catalogue key). The first run found a page whose breadcrumb effect rebuilt a fresh array literal on every render — effect → context state → re-render → new literal, without end. That one test took 423 seconds and exhausted the heap. Ten sibling pages memoised; exactly one did not, and in a browser the screen had looked usable. After the fix the whole web suite went from 645 s to 57 s.
+
+So write them shallow if you like. The mount is the point.
+
 ## What deliberately has NO suffix
 
 A generic "one component per file" rule would be worth enforcing everywhere, so tying it to a rename would make it opt-in — less coverage for more cost. The shape rules above fire only on files that *declared* the contract, because declaring it is what makes the promise mean something.

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 {