@voltro/cli 0.17.0 → 0.19.0

package/dist/serveEntry.js

@@ -1,5 +1,5 @@
-import { Q as e } from "./inspectMetrics-DWh56Qas.js";
+import { Q as e } from "./inspectMetrics-D1DmLeJs.js";
 import { c as t } from "./seedRunner-D6eu-u5U.js";
 import { r as n } from "./appModuleLoader-C9r9mxZt.js";
-import { t as r } from "./serveCommand-DO6qr5Ok.js";
+import { t as r } from "./serveCommand-vPF5ucXC.js";
 export { e as loadDotEnv, n as registerAppModules, t as registerDriver, r as runServe };

package/dist/{start-ksY0wMZG.js → start-Clvz4IJb.js}

@@ -1,4 +1,4 @@
-import { A as e, B as t, C as n, E as r, G as i, I as a, K as o, N as s, O as c, U as l, W as ee, X as u, Y as d, _ as f, a as p, b as m, c as h, et as g, f as _, g as te, h as v, i as ne, it as y, j as b, k as x, m as S, nt as C, o as re, p as ie, q as w, r as ae, rt as T, s as E, st as D, t as O, tt as k, ut as A, v as j, w as oe, y as M } from "./inspectMetrics-DWh56Qas.js";
+import { A as e, B as t, C as n, E as r, G as i, I as a, K as o, N as s, O as c, U as l, W as ee, X as u, Y as d, _ as f, a as p, b as m, c as h, et as g, f as _, g as te, h as v, i as ne, it as y, j as b, k as x, m as S, nt as C, o as re, p as ie, q as w, r as ae, rt as T, s as E, st as D, t as O, tt as k, ut as A, v as j, w as oe, y as M } from "./inspectMetrics-D1DmLeJs.js";
 import { D as se, E as ce, T as le, a as N, p as ue, w as de } from "./inspect-Dwx0_tUj.js";
 import { t as fe } from "./bootTiming-BdyP9nYw.js";
 import { dirname as pe, extname as P, join as F, resolve as I } from "node:path";

package/dist/startEntry.js

@@ -1,3 +1,3 @@
-import { Q as e } from "./inspectMetrics-DWh56Qas.js";
-import { t } from "./start-ksY0wMZG.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.17.0",
+  "version": "0.19.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.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",
+    "@voltro/ai": "0.19.0",
+    "@voltro/cache": "0.19.0",
+    "@voltro/data-transfer": "0.19.0",
+    "@voltro/database": "0.19.0",
+    "@voltro/env": "0.19.0",
+    "@voltro/kv": "0.19.0",
+    "@voltro/logger": "0.19.0",
+    "@voltro/plugin-auth": "0.19.0",
+    "@voltro/plugin-broadcast": "0.19.0",
+    "@voltro/plugin-mail": "0.19.0",
+    "@voltro/plugin-storage": "0.19.0",
+    "@voltro/plugin-webhooks": "0.19.0",
+    "@voltro/protocol": "0.19.0",
+    "@voltro/runtime": "0.19.0",
+    "@voltro/serverless": "0.19.0",
+    "@voltro/workflow": "0.19.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.core.md

@@ -103,30 +103,41 @@ line below replaces something real apps write by hand hundreds of times.
    in-handler for checks that need LOADED data. A hand-written `requireScope(...)`
    at the top of every executor — or a hand-kept map from rpc tag to policy rule,
    which is fail-open by omission — is what `guards:` exists to delete.
-6. **Storing a token, secret, or credential in a column?** → **`.encrypted()`**
+6. **Which ROWS may the caller see** (not: may they make the call)? →
+   **`setRowFilter`** — a predicate derived from the Subject, AND-merged into
+   EVERY read of that table, including every subscription delivery. `guards:`
+   and this answer different questions and the pair is easy to conflate:
+   - `guards:` → *may I call this procedure?* → a typed `ScopeError`.
+   - `setRowFilter` → *which rows may I see?* → the rows are simply absent.
+   A `WHERE ownerId = me` in the list handler covers the query and **NOT** the
+   stream, which is the failure this deletes. Register it from a
+   `*.startup.tsx`; its `load` must read through an UNFILTERED store (the boot
+   store / the `database` handle) — reading through the filtered one applies the
+   filter to itself and blows the stack. Depth → **`authentication`**.
+7. **Storing a token, secret, or credential in a column?** → **`.encrypted()`**
    on the column. Boot fails loudly if no cipher is configured, so an
    `.encrypted()` column can never silently persist plaintext.
-7. **Writing an Effect-form handler?** → `const store = yield* EffectStore` —
+8. **Writing an Effect-form handler?** → `const store = yield* EffectStore` —
    its failures land on the typed error channel. `Effect.promise(() =>
    ctx.store.query(…))` throws that channel away and turns a store failure into
    a defect.
-8. **Cursor pagination?** → **`paginateBy(descriptor, column, cursor, limit,
+9. **Cursor pagination?** → **`paginateBy(descriptor, column, cursor, limit,
    direction?)`** (or **`paginateById`**, its `id`-column shorthand). Not a
    hand-rolled limit+1 / slice / `hasMore` triple. `direction` flips the
    COMPARISON as well as the sort — a `desc` feed pages with `<`.
-9. **Assembling data whose SHAPE depends on the data** (a tree walk where each
+10. **Assembling data whose SHAPE depends on the data** (a tree walk where each
    level's ids come from the level above)? → **`ctx.load` / `ctx.loadMany`** —
    same-tick reads of one table coalesce into one `WHERE id IN (...)`, so the
    walk costs one query per LEVEL. Use `relations()` + `.with()` whenever the
    shape IS static; this is the fallback, not the default.
-10. **A mutation must cause an EXTERNAL side effect** (webhook, Jira sync,
+11. **A mutation must cause an EXTERNAL side effect** (webhook, Jira sync,
    payment)? → **`ctx.outbox.enqueue(effect, payload)`** + a
    **`defineOutboxHandler`** in a `*.outbox.ts`. The enqueue writes through the
    mutation's TRANSACTION, so the intent commits with the write or not at all;
    delivery happens after commit, with backoff and a dead-letter. Do NOT call
    the remote from the mutation (not transactional), and do not hand-build a
    deliveries table + drain cron — that IS this primitive.
-11. **Calling a third party ON BEHALF OF A USER** (their Jira token, their Slack
+12. **Calling a third party ON BEHALF OF A USER** (their Jira token, their Slack
    grant)? → **`defineConnection({ id, kind: 'oauth2' | 'pat' })`** in a
    `*.connection.ts`, then **`ctx.connections.get(id)`**. One declaration yields
    the encrypted per-user token store, the OAuth authorize/callback pair,
@@ -140,6 +151,7 @@ line below replaces something real apps write by hand hundreds of times.
 | `const rows = …; if (!rows[0]) throw new NotFound()` | `.one()` |
 | 3+ sequential `store.query` to assemble related data | `relations()` + `.with()` |
 | a notify/webhook helper called at the end of a mutation | `defineSubscriber` / `defineReaction` |
+| `WHERE ownerId = me` in every list handler | `setRowFilter` (covers the SUBSCRIPTION too) |
 | a counter recomputed by scanning rows on every read | `defineAggregate` (+ `incremental:`) |
 | `requireScope(...)` as the first line of every executor | `guards:` on the descriptor |
 | a token/secret column written as plain text | `.encrypted()` |
@@ -449,6 +461,48 @@ 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? | **`voltro serve` fails to boot; `voltro doctor` exits non-zero.** `voltro dev` only warns |
+| `.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 reach production:
+  `voltro serve` refuses to boot and `voltro doctor` exits non-zero, so the
+  failure happens at deploy time rather than in a bundle. `voltro dev` only
+  WARNS — mid-edit a refused boot is worse than the bug — so do not read a green
+  dev boot as a clean audit. `VOLTRO_SERVER_ONLY=strict` makes dev fail too;
+  put `voltro doctor` in CI if you want one gate that covers both.
+- **`.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

@@ -103,30 +103,41 @@ line below replaces something real apps write by hand hundreds of times.
    in-handler for checks that need LOADED data. A hand-written `requireScope(...)`
    at the top of every executor — or a hand-kept map from rpc tag to policy rule,
    which is fail-open by omission — is what `guards:` exists to delete.
-6. **Storing a token, secret, or credential in a column?** → **`.encrypted()`**
+6. **Which ROWS may the caller see** (not: may they make the call)? →
+   **`setRowFilter`** — a predicate derived from the Subject, AND-merged into
+   EVERY read of that table, including every subscription delivery. `guards:`
+   and this answer different questions and the pair is easy to conflate:
+   - `guards:` → *may I call this procedure?* → a typed `ScopeError`.
+   - `setRowFilter` → *which rows may I see?* → the rows are simply absent.
+   A `WHERE ownerId = me` in the list handler covers the query and **NOT** the
+   stream, which is the failure this deletes. Register it from a
+   `*.startup.tsx`; its `load` must read through an UNFILTERED store (the boot
+   store / the `database` handle) — reading through the filtered one applies the
+   filter to itself and blows the stack. Depth → **`authentication`**.
+7. **Storing a token, secret, or credential in a column?** → **`.encrypted()`**
    on the column. Boot fails loudly if no cipher is configured, so an
    `.encrypted()` column can never silently persist plaintext.
-7. **Writing an Effect-form handler?** → `const store = yield* EffectStore` —
+8. **Writing an Effect-form handler?** → `const store = yield* EffectStore` —
    its failures land on the typed error channel. `Effect.promise(() =>
    ctx.store.query(…))` throws that channel away and turns a store failure into
    a defect.
-8. **Cursor pagination?** → **`paginateBy(descriptor, column, cursor, limit,
+9. **Cursor pagination?** → **`paginateBy(descriptor, column, cursor, limit,
    direction?)`** (or **`paginateById`**, its `id`-column shorthand). Not a
    hand-rolled limit+1 / slice / `hasMore` triple. `direction` flips the
    COMPARISON as well as the sort — a `desc` feed pages with `<`.
-9. **Assembling data whose SHAPE depends on the data** (a tree walk where each
+10. **Assembling data whose SHAPE depends on the data** (a tree walk where each
    level's ids come from the level above)? → **`ctx.load` / `ctx.loadMany`** —
    same-tick reads of one table coalesce into one `WHERE id IN (...)`, so the
    walk costs one query per LEVEL. Use `relations()` + `.with()` whenever the
    shape IS static; this is the fallback, not the default.
-10. **A mutation must cause an EXTERNAL side effect** (webhook, Jira sync,
+11. **A mutation must cause an EXTERNAL side effect** (webhook, Jira sync,
    payment)? → **`ctx.outbox.enqueue(effect, payload)`** + a
    **`defineOutboxHandler`** in a `*.outbox.ts`. The enqueue writes through the
    mutation's TRANSACTION, so the intent commits with the write or not at all;
    delivery happens after commit, with backoff and a dead-letter. Do NOT call
    the remote from the mutation (not transactional), and do not hand-build a
    deliveries table + drain cron — that IS this primitive.
-11. **Calling a third party ON BEHALF OF A USER** (their Jira token, their Slack
+12. **Calling a third party ON BEHALF OF A USER** (their Jira token, their Slack
    grant)? → **`defineConnection({ id, kind: 'oauth2' | 'pat' })`** in a
    `*.connection.ts`, then **`ctx.connections.get(id)`**. One declaration yields
    the encrypted per-user token store, the OAuth authorize/callback pair,
@@ -140,6 +151,7 @@ line below replaces something real apps write by hand hundreds of times.
 | `const rows = …; if (!rows[0]) throw new NotFound()` | `.one()` |
 | 3+ sequential `store.query` to assemble related data | `relations()` + `.with()` |
 | a notify/webhook helper called at the end of a mutation | `defineSubscriber` / `defineReaction` |
+| `WHERE ownerId = me` in every list handler | `setRowFilter` (covers the SUBSCRIPTION too) |
 | a counter recomputed by scanning rows on every read | `defineAggregate` (+ `incremental:`) |
 | `requireScope(...)` as the first line of every executor | `guards:` on the descriptor |
 | a token/secret column written as plain text | `.encrypted()` |
@@ -449,6 +461,48 @@ 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? | **`voltro serve` fails to boot; `voltro doctor` exits non-zero.** `voltro dev` only warns |
+| `.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 reach production:
+  `voltro serve` refuses to boot and `voltro doctor` exits non-zero, so the
+  failure happens at deploy time rather than in a bundle. `voltro dev` only
+  WARNS — mid-edit a refused boot is worse than the bug — so do not read a green
+  dev boot as a clean audit. `VOLTRO_SERVER_ONLY=strict` makes dev fail too;
+  put `voltro doctor` in CI if you want one gate that covers both.
+- **`.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
@@ -541,7 +595,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **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. |
+| **What's new in 0.19.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.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. |
+| **What's new in 0.19.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,63 @@ 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.
+
+**The soft-delete row is the one to read twice if you are porting raw SQL onto
+this store.** A read here behaves the way your SQL did and returns tombstones —
+the store does *not* start appending `deletedAt IS NULL` behind you. So a lookup
+that must see a soft-deleted row (a login that revives a returning user, say)
+needs no opt-out and no `.withDeleted()`; that opt-out belongs to `ctx.store`,
+which *does* apply the filter. Assuming the filter is present is the more
+expensive mistake of the two: it turns a working login into a "not found →
+insert → unique violation on email", and nothing about the code says so.
+
+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
 

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

@@ -248,9 +248,32 @@ Enforcement: the [`crud.*` read helpers](/docs/data/crud) strip `.serverOnly()`
 columns from every returned row **automatically** — you declare the exposure
 policy once at the schema and can't forget it on a handler. For a hand-written
 query, omit the column from the `output` schema (and don't put it in the returned
-object) — and `voltro dev` **warns at boot**, naming the query and column, if a
-wire-reachable query's output declares a `.serverOnly()` column of its `source`
-table, so a secret can't ship on the wire by omission-mistake.
+object).
+
+A hand-written output is the case `crud.*` cannot cover, so an audit checks it:
+a wire-reachable query whose `source` table carries a `.serverOnly()` column that
+its `output` **declares**. What that costs is different per command, on purpose:
+
+| Command | On a leak |
+|---|---|
+| `voltro serve` | **the boot fails** |
+| `voltro doctor` | **exits non-zero** — put it in CI |
+| `voltro dev` | warns, naming the query and column |
+
+Dev only warns because a refused boot between two keystrokes is worse than the
+bug; production is the opposite, so that is where the gate is. **Do not read a
+green `voltro dev` boot as a clean audit** — the warning sits in the boot log
+among everything else. `voltro doctor` is the check to automate.
+
+`VOLTRO_SERVER_ONLY` moves the line in both directions: `strict` makes `voltro
+dev` fail too, `warn` downgrades `voltro serve` to a warning, `off` silences it
+entirely. The downgrades are documented rather than hidden because the
+alternative to a stated escape hatch is deleting the marker — and a check whose
+only way out is to disable it gets disabled.
+
+(`voltro check` does **not** run this audit. It has a live-api mode that has no
+access to your table definitions, and a rule that fires in one of its two modes
+would be worse than one that fires in neither.)
 
 Distinct from `.encrypted()` on purpose: encryption at rest says nothing about
 who may receive the plaintext — a private note you decrypt *for its owner* is a

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

@@ -105,11 +105,17 @@ 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.
+
+> **Writing an in-memory store for tests? Do not reimplement these.** `evaluatePredicate` is exported from `@voltro/database` and is the same function the memory store runs, so a test double built on it agrees with a real database by construction. Hand-rolling the switch is where a stub quietly diverges — a `case 'contains'` written as `String(a).includes(b)` is case-SENSITIVE where the real one folds case, and coerces a number where the real one returns `false`. That stub passes queries a live dialect fails, which is the worst direction for a test double to be wrong in.
+
 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/introduction.md

@@ -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/routing.md

@@ -262,6 +262,8 @@ No naming trick is needed to keep something out of the router: the absence of th
 
 The canonical form is **no trailing slash** — always link with `<Link to="/about">`, not `<Link to="/about/">`.
 
+`Link` forwards every prop it does not consume itself to the underlying `<a>`, `ref` included — so it drops straight into a polymorphic slot (`<Button component={Link} to={url}>`) without a wrapper.
+
 The framework does NOT emit a trailing-slash redirect on its own. If you need `/about/` → `/about` normalisation (for SEO), configure a 301 redirect at your reverse proxy.
 
 ## What pages CAN'T do

package/templates/agent-docs/schema-driven-ui.md

@@ -903,9 +903,12 @@ that affordance read-only rather than binding to a tag that does not resolve. Th
 [`useCan`](/docs/ui/client-utilities/use-can); map them to your app's real RBAC
 scopes.
 
-The inspect surface is open in dev. When a deploy sets an inspect token the
-manifest GET is bearer-gated, so an admin UI pointed at a locked-down api has to
-supply that token — a deployment concern, not something this hook handles.
+The manifest GET is bearer-gated wherever it runs — `/_voltro/inspect/*` is
+fail-closed, so no configured `VOLTRO_INSPECT_TOKEN` means `401`, not "everyone".
+Under `voltro dev` that is handled for you (the dev server mints a token and its
+proxy attaches it server-side). An admin UI pointed at a deployed api has to
+supply the token itself — a deployment concern, not something this hook
+handles.