@voltro/cli 0.13.0 → 0.15.0

package/dist/startEntry.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.13.0",
+  "version": "0.15.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.13.0",
-    "@voltro/cache": "0.13.0",
-    "@voltro/data-transfer": "0.13.0",
-    "@voltro/database": "0.13.0",
-    "@voltro/env": "0.13.0",
-    "@voltro/kv": "0.13.0",
-    "@voltro/logger": "0.13.0",
-    "@voltro/plugin-auth": "0.13.0",
-    "@voltro/plugin-broadcast": "0.13.0",
-    "@voltro/plugin-mail": "0.13.0",
-    "@voltro/plugin-storage": "0.13.0",
-    "@voltro/plugin-webhooks": "0.13.0",
-    "@voltro/protocol": "0.13.0",
-    "@voltro/runtime": "0.13.0",
-    "@voltro/serverless": "0.13.0",
-    "@voltro/workflow": "0.13.0",
+    "@voltro/ai": "0.15.0",
+    "@voltro/cache": "0.15.0",
+    "@voltro/data-transfer": "0.15.0",
+    "@voltro/database": "0.15.0",
+    "@voltro/env": "0.15.0",
+    "@voltro/kv": "0.15.0",
+    "@voltro/logger": "0.15.0",
+    "@voltro/plugin-auth": "0.15.0",
+    "@voltro/plugin-broadcast": "0.15.0",
+    "@voltro/plugin-mail": "0.15.0",
+    "@voltro/plugin-storage": "0.15.0",
+    "@voltro/plugin-webhooks": "0.15.0",
+    "@voltro/protocol": "0.15.0",
+    "@voltro/runtime": "0.15.0",
+    "@voltro/serverless": "0.15.0",
+    "@voltro/workflow": "0.15.0",
     "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/**/*.tsx  # file-based routing
+│       └── src/pages/**/*.page.tsx  # file-based routing (only *.page.tsx)
 ├── packages/                   # shared libs
 └── AGENTS.md / CLAUDE.md       # this file
 ```
@@ -249,7 +249,77 @@ 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 |
-| `src/pages/**/*.tsx` | web page (file-based route) |
+| `*.page.tsx` (under `src/pages/`) | web page (file-based route) + `*.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) |
+| `*.types.ts` | types only — zero runtime exports |
+| `*.internal.ts` | only its own directory subtree may import it |
+| `*.fixture.ts` | test material — no production path may reach it |
+| `*.tracking.ts` | the ONLY place analytics may be called from |
+| `*.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.
+
+**Every suffix above is a CONTRACT, not a label.** Something else depends on each
+promise, and `voltro doctor` enforces all of them:
+
+- `*.component.ui.tsx` may read (`useT`, `useCan`, `usePermissions`) but must
+  never import a write hook (`useMutation`, `useAction`, `useUpload`, …). That is
+  what lets a caller render it ten thousand times in a list, reuse it across
+  features, and prerender it without reading its source. Lift the write into the
+  owning `*.component.tsx` and pass a handler down.
+- `*.internal.ts` is the promise that refactoring inside that directory breaks
+  nobody. An import from another subtree revokes it.
+- `*.types.ts` having no runtime export is what makes importing it free and makes
+  it impossible for it to sit in a runtime import cycle.
+- `*.store.ts` holds ONE `defineStore`. Reads go through a selector
+  (`wizard.use((s) => s.step)`) — there is no whole-state read, because a
+  component holding all of it re-renders on every field. Scope a per-entity
+  instance with a KEY (`{ key: orderId }`), never a Provider. Seed it for SSR
+  from a loader with `seedStore(...)`; it rides the hydration payload the router
+  already writes. An action that writes SEVERAL fields wraps them in
+  `store.batch('label', () => …)` — one notification, one devtools entry, one
+  undo step, and a rollback if it throws; `await` first, then batch (an async
+  callback is an error). `{ persist: { key } }` survives a reload.
+  NEVER put server data in a store: a subscription is already
+  live, and a copy is not — the page then shows the stale one.
+- `*.tracking.ts` is where every `defineTracking(...)` spec lives — the event
+  catalogue, so "what do we send to third parties" is a file listing rather than
+  archaeology. A component wires one up with `useTracking(spec, props, sink)`; it
+  NAMES a spec, it never declares one. (`useTracking` is a hook, so it is not
+  confined — only the declaration is.)
+- Do NOT rename a file to `*.component.ui.tsx` just because it happens not to
+  write today. The suffix is a promise about what it MAY do.
+
+**These rules apply to code YOU write — never to vendored code.** A shadcn
+component (`npx shadcn add`) follows shadcn's conventions and is overwritten by
+the next `add`; renaming it breaks their convention and is undone next run. A
+directory is exempt when the app's `components.json` names it (`aliases.ui`) or
+it carries a `.voltro-vendored` file whose first line says where the code came
+from. Never add that marker to a directory of your own code — the point of the
+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`,
+`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.
+
+Two traps worth naming, because a green run can hide both:
+
+- **`voltro test` transpiles without type-checking.** A type error in a TEST file
+  passes the suite and fails the package's `typecheck`. Run both.
+- **Never fake a service to make a test pass.** A test that only re-asserts its
+  own mock's return value is worse than no test — it reports coverage it does not
+  have. Assert the descriptor shape instead and cover the real path elsewhere.
 
 ## app.config.ts
 
@@ -344,9 +414,13 @@ declare it). Mixins compose via `.with(...)` and auto-stamp bookkeeping columns:
 ```ts
 export const todos = table('todos', { id: id(), title: text(), done: boolean().default(false) })
   .with(softDelete(), tenant())   // tenant() transitively requires audit()
-  .reactive()                     // opt into the matcher engine (subscriptions)
 ```
 
+- Every table is REACTIVE by default — nothing to opt into. `.nonReactive()`
+  turns reactivity OFF for a table entirely: no subscriber fires, locally or
+  across instances (the write still happens). Use it for a hot table nobody
+  subscribes to; never for one a query reads — that subscription never fires,
+  and `voltro dev` warns.
 - `id()` defaults to a branded **TypeID** (`todo_…`). Insert auto-injects it.
 - Indexes are **table-level** (`.index('name', [...])`) — there is NO
   column-level `.index()`. Declare `.index([...])` AFTER `.with(...)` to address

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/**/*.tsx  # file-based routing
+│       └── src/pages/**/*.page.tsx  # file-based routing (only *.page.tsx)
 ├── packages/                   # shared libs
 └── AGENTS.md / CLAUDE.md       # this file
 ```
@@ -249,7 +249,77 @@ 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 |
-| `src/pages/**/*.tsx` | web page (file-based route) |
+| `*.page.tsx` (under `src/pages/`) | web page (file-based route) + `*.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) |
+| `*.types.ts` | types only — zero runtime exports |
+| `*.internal.ts` | only its own directory subtree may import it |
+| `*.fixture.ts` | test material — no production path may reach it |
+| `*.tracking.ts` | the ONLY place analytics may be called from |
+| `*.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.
+
+**Every suffix above is a CONTRACT, not a label.** Something else depends on each
+promise, and `voltro doctor` enforces all of them:
+
+- `*.component.ui.tsx` may read (`useT`, `useCan`, `usePermissions`) but must
+  never import a write hook (`useMutation`, `useAction`, `useUpload`, …). That is
+  what lets a caller render it ten thousand times in a list, reuse it across
+  features, and prerender it without reading its source. Lift the write into the
+  owning `*.component.tsx` and pass a handler down.
+- `*.internal.ts` is the promise that refactoring inside that directory breaks
+  nobody. An import from another subtree revokes it.
+- `*.types.ts` having no runtime export is what makes importing it free and makes
+  it impossible for it to sit in a runtime import cycle.
+- `*.store.ts` holds ONE `defineStore`. Reads go through a selector
+  (`wizard.use((s) => s.step)`) — there is no whole-state read, because a
+  component holding all of it re-renders on every field. Scope a per-entity
+  instance with a KEY (`{ key: orderId }`), never a Provider. Seed it for SSR
+  from a loader with `seedStore(...)`; it rides the hydration payload the router
+  already writes. An action that writes SEVERAL fields wraps them in
+  `store.batch('label', () => …)` — one notification, one devtools entry, one
+  undo step, and a rollback if it throws; `await` first, then batch (an async
+  callback is an error). `{ persist: { key } }` survives a reload.
+  NEVER put server data in a store: a subscription is already
+  live, and a copy is not — the page then shows the stale one.
+- `*.tracking.ts` is where every `defineTracking(...)` spec lives — the event
+  catalogue, so "what do we send to third parties" is a file listing rather than
+  archaeology. A component wires one up with `useTracking(spec, props, sink)`; it
+  NAMES a spec, it never declares one. (`useTracking` is a hook, so it is not
+  confined — only the declaration is.)
+- Do NOT rename a file to `*.component.ui.tsx` just because it happens not to
+  write today. The suffix is a promise about what it MAY do.
+
+**These rules apply to code YOU write — never to vendored code.** A shadcn
+component (`npx shadcn add`) follows shadcn's conventions and is overwritten by
+the next `add`; renaming it breaks their convention and is undone next run. A
+directory is exempt when the app's `components.json` names it (`aliases.ui`) or
+it carries a `.voltro-vendored` file whose first line says where the code came
+from. Never add that marker to a directory of your own code — the point of the
+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`,
+`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.
+
+Two traps worth naming, because a green run can hide both:
+
+- **`voltro test` transpiles without type-checking.** A type error in a TEST file
+  passes the suite and fails the package's `typecheck`. Run both.
+- **Never fake a service to make a test pass.** A test that only re-asserts its
+  own mock's return value is worse than no test — it reports coverage it does not
+  have. Assert the descriptor shape instead and cover the real path elsewhere.
 
 ## app.config.ts
 
@@ -344,9 +414,13 @@ declare it). Mixins compose via `.with(...)` and auto-stamp bookkeeping columns:
 ```ts
 export const todos = table('todos', { id: id(), title: text(), done: boolean().default(false) })
   .with(softDelete(), tenant())   // tenant() transitively requires audit()
-  .reactive()                     // opt into the matcher engine (subscriptions)
 ```
 
+- Every table is REACTIVE by default — nothing to opt into. `.nonReactive()`
+  turns reactivity OFF for a table entirely: no subscriber fires, locally or
+  across instances (the write still happens). Use it for a hot table nobody
+  subscribes to; never for one a query reads — that subscription never fires,
+  and `voltro dev` warns.
 - `id()` defaults to a branded **TypeID** (`todo_…`). Insert auto-injects it.
 - Indexes are **table-level** (`.index('name', [...])`) — there is NO
   column-level `.index()`. Declare `.index([...])` AFTER `.with(...)` to address
@@ -452,7 +526,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.13.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.14.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | 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.13.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.14.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | 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/_manifest.json

@@ -53,7 +53,7 @@
       "group": null,
       "description": "How Voltro's reactive data layer works — queries, mutations, actions, streams, all over one WebSocket with typed errors and tracked dependencies.",
       "path": "agent-docs/data.md",
-      "files": 16
+      "files": 17
     },
     {
       "id": "database/advancedqueries",
@@ -179,7 +179,7 @@
       "group": null,
       "description": "Scaffold a Voltro project and boot it locally in under a minute.",
       "path": "agent-docs/introduction.md",
-      "files": 5
+      "files": 6
     },
     {
       "id": "multi-tenancy",

package/templates/agent-docs/authentication.md

@@ -525,6 +525,7 @@ interface AuthStrategy {
 interface AuthStrategyInput {
   readonly headers: Readonly<Record<string, string | undefined>>
   readonly clientId: number                    // per-connection id (for soft re-auth)
+  readonly store?: DataStore                   // the app's store, for a DB-backed strategy
 }
 ```
 
@@ -540,6 +541,34 @@ The `failed`-stops-the-chain rule is a **security** decision, not an ergonomic o
 
 > Strategies must be **fast on the no-match path** — a cookie-name substring check, no IO — because every strategy runs on every request until one matches. Do JWKS fetches / DB lookups only *after* you've confirmed the request is yours, and cache them.
 
+### Reading your database — `input.store`
+
+A strategy that identifies the caller from a row — a session, an API key, a PAT
+— gets the app's `DataStore` on its input:
+
+```ts
+const dbSession: AuthStrategy = {
+  id: 'db-session',
+  resolve: async ({ headers, store }) => {
+    const token = headers.authorization?.slice('Bearer '.length)
+    if (token === undefined) return { kind: 'skip' }
+    if (store === undefined) return { kind: 'skip' }
+    const [row] = await store.query(sessions.byToken(token))
+    return row ? { kind: 'matched', subject: toSubject(row) } : { kind: 'failed', reason: 'unknown token' }
+  },
+}
+```
+
+It is the **boot** store, not a request-scoped one — strategies resolve before a
+request store exists — and the same value `auth.resolveScopes` receives.
+`undefined` only while the store is still being built (`voltro dev` builds it
+after the auth chain) and on an app with no store, so a strategy should `skip`
+rather than throw.
+
+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.
+
 ## Composing the chain
 
 `composeAuthStrategies` turns an ordered list of strategies into a single resolver. First `matched` wins; first `failed` short-circuits to anonymous.
@@ -573,8 +602,9 @@ If your authorization is a database ROLE rather than a scope on the token, the f
 // app.config.ts
 export default defineApiConfig({
   auth: {
-    resolveScopes: async (subject) => {
-      const role = await roleCache.get(subject.id)   // cache it — see below
+    resolveScopes: async (subject, { store }) => {
+      if (store === undefined) return []            // still booting — claim nothing
+      const role = await roleCache.get(subject.id, store)   // cache it — see below
       return role === 'admin' ? ['employee:admin', 'employee:read'] : ['employee:read']
     },
   },
@@ -591,6 +621,8 @@ export const payrollList = defineQuery({
 })
 ```
 
+**You get the app's DataStore.** A role lives in the database, and without it the only way to reach one was a second connection path beside the framework's — to the same database the request store opens a moment later. It is the BOOT store, not a request-scoped one: strategies resolve before a request store exists, so it is `undefined` while the store is still being built. Return `[]` then rather than guessing.
+
 **Scopes only — never a Subject.** The hook cannot change `id` or `tenantId`: identity belongs to the auth strategy, and a hook that could rewrite it would be a forgery surface. The returned scopes are UNIONED with whatever the strategy already set, so a resolver can grant authority but never revoke it.
 
 **It does not run for anonymous callers** — there is no identity to look a role up for.

package/templates/agent-docs/cli.md

@@ -154,6 +154,20 @@ requiring a scope no role grants, which makes that procedure permanently and
 silently uncallable. (With a custom `resolvePermissions` the vocabulary isn't
 exhaustive, so the rule stays quiet rather than flagging correct code.)
 
+`rbac/unenforced-scope` is the same registry read in the other direction: a
+scope a role GRANTS that no handler ever guards on. That direction has no
+artefact to inspect — you cannot grep for an authorization check that was never
+written, which is exactly why it survives review. One app modelled
+`api-keys:write` in its role catalogue, complete and reviewed, and no handler
+checked it: any member could mint a shared credential, and nothing failed.
+Tests pass when an authorization check is missing.
+
+It is a **warning**, because three innocent explanations exist: a plugin route
+enforces it internally (the graph cannot see inside a plugin), a REST route
+carries its own guards, or it is a UI-affordance scope that `useCan` reads to
+hide a button and no server check backs on purpose. All three are fine. Not
+knowing which is not.
+
 #### Declared vs OBSERVED — reconciled against reality
 
 A query's `source` and a mutation's `targets` are not documentation: the
@@ -466,6 +480,26 @@ The cleaner fix is on your side and worth doing anyway: start the container as
 the workspace owner, `docker run --user $(id -u):$(id -g)`. Then nothing needs
 handing over at all.
 
+### What the boot tells you
+
+Three checks run at boot and print one line each when they have something to say
+— never fatal, and silent when the answer is fine:
+
+- **A reactive table with no change trigger** (postgres). The schema fingerprint
+  covers columns, not triggers, so a restored dump or a hand-run `DROP TRIGGER`
+  leaves the schema "up to date" and the subscription silently not reaching other
+  instances. The reverse is reported too: a `.nonReactive()` table still carrying
+  a trigger pays `REPLICA IDENTITY FULL` and a NOTIFY per write for nothing.
+- **A `.nonReactive()` table that a query reads.** That subscription will never
+  fire — first snapshot, then silence forever.
+- **`apiKeys: true` with no `apikeys:issue:*` scope declared.** The capability is
+  on and reachable by nobody; every issue request fails its guard.
+
+`voltro doctor` adds a fourth, over your source: an executor that writes
+`ctx.request.subject.id` while naming no guard, which is how an anonymous caller
+reaches a NOT NULL column and gets a raw statement failure instead of a typed
+refusal.
+
 ## `voltro dev <appDir>`
 
 ```bash
@@ -684,6 +718,45 @@ The restart is a full re-exec — there is no in-process hot-reload of a
 handler body; editing a query's executor respawns the child (debounced
 80ms, so a burst of saves collapses into one restart).
 
+## When the dev server stops
+
+A restart replaces the child; the supervisor keeps watching. When the dev
+server exits **on its own** — an aborted boot, or you stopping it — what
+happens next depends on whether anyone is there to react.
+
+**In a terminal**, a crashed boot is something you are about to fix, so
+the supervisor keeps watching and tells you:
+
+```text
+dev server crashed — waiting for a file change   exitCode=1
+```
+
+Fix the cause and save. The watcher restarts the server exactly as it
+would for any other edit; you don't retype the command.
+
+**Piped, backgrounded or in CI** — anywhere stdout is not a TTY — nobody
+is going to fix anything, so `voltro dev` exits with the child's code:
+
+```text
+dev server exited — supervisor stopping   exitCode=1
+```
+
+That half matters because the supervisor used to keep watching in *both*
+cases: a shell that had long since closed still had a `voltro dev` behind
+it holding a watcher, and a CI job that had "finished" kept its runner
+busy. A failed boot is now a failed command wherever no one is looking.
+
+A **clean** exit always stops the supervisor, watched or not — a dev
+server ending on purpose is not something to wait out.
+
+| Env | Effect |
+|---|---|
+| `VOLTRO_DEV_KEEP_ALIVE=1` | Wait for a fix even without a TTY — a CI runner with a TTY allocated, or a wrapper that pipes output while you watch it. |
+| `VOLTRO_DEV_KEEP_ALIVE=0` | Exit on a crash even in a terminal. |
+
+Neither can keep a clean exit alive; that would turn a deliberate
+shutdown into a hang.
+
 The `.env` trigger applies to **both api and web** apps — `process.env` is
 parsed once at boot, so editing a `.env` (or re-pulling secrets, e.g.
 `doppler secrets download > .env`) needs a full re-exec. `voltro dev` watches
@@ -1138,8 +1211,8 @@ A page is listed when ALL of these hold:
 
 ```text
 •  renderMode:'spa' candidates (2 pages — loader-free, under a layout, currently ssr/default):
-   src/pages/dashboard/index.tsx  (/dashboard) — default renderMode
-   src/pages/admin/settings.tsx  (/admin/settings) — renderMode:'ssr'
+   src/pages/dashboard/index.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.
 ```
 
@@ -2221,6 +2294,7 @@ voltro update                 # bump to the latest published version, install, r
 voltro update --to 0.4.0      # pin an explicit target version
 voltro update --dry-run       # preview the bump + which codemods would run — writes nothing
 voltro update --force         # allow a dirty working tree (not recommended)
+voltro update --only 0.14.0/03_pages-suffix   # run just these codemod(s), comma-separated
 voltro update --exact         # pin exact versions (drop the ^ / ~ range prefix)
 voltro update --help          # every flag — always answered, even on a dirty tree
 
@@ -2229,6 +2303,26 @@ voltro update --codemods-only --from 0.3.0            # re-run codemods 0.3.0
 voltro update --codemods-only --from 0.3.0 --to 0.4.0 # explicit delta
 ```
 
+### Taking only part of the jump — `--only`
+
+Ids are what `--dry-run` prints:
+
+```bash
+voltro update --dry-run
+voltro update --codemods-only --from 0.13.0 --only 0.14.0/03_pages-suffix,0.14.0/02_reactive-by-default
+```
+
+Useful when part of a jump is load-bearing (without it the app does not build or
+its routes 404) and part is elective: take the necessary ones, get back to a
+committable tree, then run the rest. An id that matches nothing in the jump is an
+error listing the ids that do — "it did nothing" and "you typed it wrong" would
+otherwise look identical.
+
+There is no `--required` flag, deliberately. "Required" would have to mean *this
+app does not run without it*, and that is a property of your app rather than of
+the codemod: the pages rename is unavoidable for a project with pages and
+irrelevant to an api-only one. You know which ones you need; we would be guessing.
+
 ## In a workspace, the whole workspace moves
 
 Run `voltro update` anywhere inside a workspace — a `pnpm-workspace.yaml`, or a
@@ -2299,6 +2393,26 @@ voltro update --codemods-only --from 0.5.0 --to 0.6.0
 
 Every `@voltro/*` entry in `dependencies` and `devDependencies` — in every workspace member, see above — with the range style preserved (`^0.3.0` stays caret, `~0.3.0` stays tilde) unless you pass `--exact`. Non-registry specs (`workspace:*`, `catalog:`, `link:`, …) are left untouched — they're already resolved by your monorepo or catalog.
 
+## When the install cannot run on this host
+
+Some projects install in a container with their own store, from an offline
+mirror, or in a locked-down CI image. `voltro update` runs your package manager
+on the machine you invoke it from, so on those hosts the install step fails —
+and it fails *after* the version bump is written, which leaves the tree
+half-upgraded.
+
+`--no-install` splits the command where those projects need it split:
+
+```bash
+voltro update --no-install --to 0.14.0   # writes the bump, stops, says what is left
+# ...install however this project installs...
+voltro update --codemods-only --from 0.13.0 --to 0.14.0
+```
+
+Step two is not optional and the command says so: the codemods for a jump ship
+**inside** the target version, so nothing can run them until the install has put
+that version on disk.
+
 ## Which package manager
 
 `voltro update` never assumes npm. It resolves your project's package manager in this order, starting in the app directory and walking **up to the repo root**: