@voltro/cli 0.18.0 → 0.20.0

package/dist/startEntry.js

@@ -1,3 +1,3 @@
-import { Q as e } from "./inspectMetrics-D1DmLeJs.js";
-import { t } from "./start-Clvz4IJb.js";
+import { et as e } from "./inspectMetrics-BL8kZOv3.js";
+import { t } from "./start-IVgQe2YD.js";
 export { e as loadDotEnv, t as runStartCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.18.0",
+  "version": "0.20.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.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",
+    "@voltro/ai": "0.20.0",
+    "@voltro/cache": "0.20.0",
+    "@voltro/data-transfer": "0.20.0",
+    "@voltro/database": "0.20.0",
+    "@voltro/env": "0.20.0",
+    "@voltro/kv": "0.20.0",
+    "@voltro/logger": "0.20.0",
+    "@voltro/plugin-auth": "0.20.0",
+    "@voltro/plugin-broadcast": "0.20.0",
+    "@voltro/plugin-mail": "0.20.0",
+    "@voltro/plugin-storage": "0.20.0",
+    "@voltro/plugin-webhooks": "0.20.0",
+    "@voltro/protocol": "0.20.0",
+    "@voltro/runtime": "0.20.0",
+    "@voltro/serverless": "0.20.0",
+    "@voltro/workflow": "0.20.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()` |
@@ -456,7 +468,7 @@ 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 |
+| `.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 |
 
@@ -470,8 +482,12 @@ export const users = table('users', {
 ```
 
 - **`.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.
+  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()`.

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()` |
@@ -456,7 +468,7 @@ 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 |
+| `.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 |
 
@@ -470,8 +482,12 @@ export const users = table('users', {
 ```
 
 - **`.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.
+  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()`.
@@ -579,7 +595,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **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. |
+| **What's new in 0.20.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.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. |
+| **What's new in 0.20.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

@@ -590,6 +590,15 @@ 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

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

@@ -1937,6 +1937,19 @@ source of truth. Just restoring the snapshot brings the data back
 but the declared schema still says the column shouldn't exist; the
 next apply would re-drop it.
 
+## The differ leaves snapshots alone
+
+A soft drop leaves an object in the database that no schema declares —
+that is the whole point of it. The planner treats every
+`<name>__dropped_<ts>` as framework-managed and never plans a drop for
+it, the same way it skips `_voltro_*` and the cluster engine's tables.
+This holds for columns and for tables.
+
+You do not need `VOLTRO_DB_IGNORE_TABLES` for a snapshot, and you should
+not add one: that list is for YOUR unmanaged infra tables, and an entry
+there would still be in your config long after `gc-snapshots` reclaimed
+the snapshot.
+
 ## GC
 
 Snapshot columns aren't automatically dropped. They survive until
@@ -2612,7 +2625,15 @@ export default migration({
 // VOLTRO_DESTRUCTIVE_OK=1 voltro db apply --note 'retiring oldUsersTable per ticket #...'
 ```
 
-**Two tables this never proposes dropping:**
+**Delete the entity and drop the table in the SAME change.** The intuitive
+order — remove the code first, sort the schema out after — is the broken one:
+with `VOLTRO_AUTO_MIGRATE=1` the very next boot sees an undeclared table,
+refuses, and the app crashloops until the drop is authorised. There is nothing
+to recover from, but the app is down while you work it out. Take the entity out
+together with the `VOLTRO_DESTRUCTIVE_OK` apply that removes its table, or leave
+the entity in place until you are ready to run both.
+
+**Three tables this never proposes dropping:**
 
 - **`actors`** — the framework-provided audit subject. You don't declare an
   `actors.entity.ts`; `db plan` / `db apply` auto-include the built-in `actors`
@@ -2633,6 +2654,10 @@ export default migration({
   Strapi→Voltro `_strapi_id_map` sitting in the DB won't refuse-to-boot on a
   `drop-table`. (The framework already self-excludes its own `_voltro_*` /
   `cluster_*` runtime tables; this is the user list on top of that.)
+- **Soft-drop snapshots** — a `<name>__dropped_<ts>` left behind by
+  `VOLTRO_SOFT_DROP=1`. The differ treats it as framework-managed until
+  `voltro db gc-snapshots` reclaims it, so do NOT add one to
+  `VOLTRO_DB_IGNORE_TABLES`.
 
 ## A migrate / apply DDL statement failed — find which one
 
@@ -2699,7 +2724,15 @@ it now is, must have nothing left to do.
 
 **It is a framework bug, not a mistake in your schema.** The named operations
 emit DDL that does not take effect. Report the operation kinds plus the column
-types involved. In the meantime the schema is unchanged and safe — nothing was
+types involved.
+
+**Read the named operations before you trust the "no-op" wording**, though —
+the message states a CAUSE, and a cause can be wrong. One release told users
+`drop-table <name>__dropped_<ts>` was a no-op when the DDL had worked perfectly:
+`VOLTRO_SOFT_DROP=1` had renamed the table, and the planner then read its own
+snapshot as one more undeclared table and proposed dropping it again. Fixed, and
+worth knowing as the shape to look for: an operation naming an object that the
+PREVIOUS operation created or renamed is a planner blind spot, not dead DDL. In the meantime the schema is unchanged and safe — nothing was
 half-applied, and no fingerprint was written, so `voltro db plan` still shows you
 the truth.
 

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

@@ -248,9 +248,48 @@ 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.
+
+### Gate CI on the audit having RUN, not on its silence
+
+`voltro doctor` can only run this audit if it can load your descriptors. When it
+cannot, it says so instead of claiming a pass:
+
+```
+•  serverOnly: NOT CHECKED — the app's descriptors could not be loaded (not a pass)
+   reason: Transform failed with 1 error:
+   src/queries/broken.query.ts:2:5: ERROR: Expected ";" but found "is"
+```
+
+`voltro doctor --json` carries the same answer as `serverOnly: { checked, reason?, leaks? }`.
+Assert on `checked` — an app that leans on `.serverOnly()` should treat a
+persistent skip as a failure, because a skipped audit and a clean one look
+identical from the outside.
+
+(`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

@@ -114,6 +114,8 @@ ctx.store.select('notes')
 
 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/routing.md

@@ -258,6 +258,19 @@ No naming trick is needed to keep something out of the router: the absence of th
 
 > Before this convention, every `.tsx` under `src/pages/` became a route, so a co-located component silently got a URL. That route rendered nothing and nobody visited it in dev; the failure surfaced at the first production build. If you are upgrading, `voltro update` renames your pages for you.
 
+## Two routes, one screen
+
+When two URLs must render the same component — a versioned path kept alive because devices in the field are configured against it, say — re-export it instead of copying it:
+
+```tsx
+// src/pages/v2/page.tsx → /v2, rendering exactly what / renders
+export { default, renderMode } from '../page'
+```
+
+`export { default } from '…'` satisfies the page contract: the module has a default export, it just did not declare it here. Forwarding `renderMode` alongside it is what keeps the two routes from drifting apart — the build follows the forward when it computes the render profile, so `/v2` is classified the same as `/`, not silently as `static`.
+
+`export { default as Screen } from '../page'` is the opposite: it renames the default away, leaving this module without one. That still fails the contract.
+
 ## Trailing slashes
 
 The canonical form is **no trailing slash** — always link with `<Link to="/about">`, not `<Link to="/about/">`.