@voltro/cli 0.6.0 → 0.8.0

package/dist/startEntry.d.ts

@@ -0,0 +1,5 @@
+export declare const loadDotEnv: (argv: ReadonlyArray<string>) => void;
+
+export declare const runStartCommand: (args: ReadonlyArray<string>) => Promise<number>;
+
+export { }

package/dist/startEntry.js

@@ -0,0 +1,3 @@
+import { P as e } from "./inspectMetrics-EK0CcHyu.js";
+import { t } from "./start-DuyBQxW3.js";
+export { e as loadDotEnv, t as runStartCommand };

package/package.json

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

package/templates/AGENTS.core.md

@@ -313,10 +313,21 @@ helper from a `lib/` file that ALSO imports the `database` handle drags the whol
 server graph (and any `node:crypto` behind it) into the browser bundle. Keep
 browser-safe symbols (typed errors, Schemas, pure helpers) in files with ZERO
 server imports; put DB-backed guards/helpers in `.server.ts` or a server-only
-module. Some plugins ship a browser-safe subpath for exactly this (e.g.
-`@voltro/plugin-multitenancy/guard`, `@voltro/plugin-webhooks/errors`,
-`@voltro/ai/events`) — import typed errors / Schemas from there in descriptors,
-never from the package root.
+module. Several packages ship a browser-safe subpath for exactly this (e.g.
+`@voltro/database/wire`, `@voltro/plugin-multitenancy/guard`,
+`@voltro/plugin-webhooks/errors`, `@voltro/ai/events`) — import typed errors /
+Schemas from there in descriptors, never from the package root.
+
+A consequence worth stating, because it is not obvious: a descriptor's `output`
+can never be **derived from a table**. `rowSchema(table)` / `columnSchema(def)`
+take the table as a VALUE, so reaching one means importing your
+`database/schema.ts`, which imports `@voltro/database` — the boot aborts with
+the import chain. Write `output` as your own `Schema.Struct` and take the field
+schemas from `@voltro/database/wire` (`timestampMs` for a `timestamp()` column,
+`timestampMsOrNull` when it is `.nullable()`, `Schema.optional(timestampMs)`
+when the field may be absent). `rowSchema` is a row CODEC for server-only code
+(`*.server.ts`, `*.seed.ts`, jobs, scripts) — file exports, queue payloads,
+validating seed data — not a descriptor helper.
 
 **Symptom of a leak:** the web app fires hundreds of module requests / tens of MB
 on first load, or crashes with `Module "node:crypto" has been externalized for

package/templates/AGENTS.md

@@ -313,10 +313,21 @@ helper from a `lib/` file that ALSO imports the `database` handle drags the whol
 server graph (and any `node:crypto` behind it) into the browser bundle. Keep
 browser-safe symbols (typed errors, Schemas, pure helpers) in files with ZERO
 server imports; put DB-backed guards/helpers in `.server.ts` or a server-only
-module. Some plugins ship a browser-safe subpath for exactly this (e.g.
-`@voltro/plugin-multitenancy/guard`, `@voltro/plugin-webhooks/errors`,
-`@voltro/ai/events`) — import typed errors / Schemas from there in descriptors,
-never from the package root.
+module. Several packages ship a browser-safe subpath for exactly this (e.g.
+`@voltro/database/wire`, `@voltro/plugin-multitenancy/guard`,
+`@voltro/plugin-webhooks/errors`, `@voltro/ai/events`) — import typed errors /
+Schemas from there in descriptors, never from the package root.
+
+A consequence worth stating, because it is not obvious: a descriptor's `output`
+can never be **derived from a table**. `rowSchema(table)` / `columnSchema(def)`
+take the table as a VALUE, so reaching one means importing your
+`database/schema.ts`, which imports `@voltro/database` — the boot aborts with
+the import chain. Write `output` as your own `Schema.Struct` and take the field
+schemas from `@voltro/database/wire` (`timestampMs` for a `timestamp()` column,
+`timestampMsOrNull` when it is `.nullable()`, `Schema.optional(timestampMs)`
+when the field may be absent). `rowSchema` is a row CODEC for server-only code
+(`*.server.ts`, `*.seed.ts`, jobs, scripts) — file exports, queue payloads,
+validating seed data — not a descriptor helper.
 
 **Symptom of a leak:** the web app fires hundreds of module requests / tens of MB
 on first load, or crashes with `Module "node:crypto" has been externalized for

package/templates/agent-docs/authentication.md

@@ -351,6 +351,29 @@ if (ctx.subject.type === 'anonymous') {
 }
 ```
 
+## App metadata — `subjectFromUser(user, { metadata })`
+
+`metadata` is the free-form slot the framework itself never reads. It is where a provider credential captured at login belongs — a plugin's `credentialsResolver` reads it back per request (`@voltro/plugin-atlassian` looks for `subject.metadata.jiraToken`, say), so nothing has to be re-fetched or stored server-side per call.
+
+Pass it when you build the Subject:
+
+```ts
+import { subjectFromUser } from '@voltro/plugin-auth'
+
+const subject = subjectFromUser(user, {
+  memberships,                              // → metadata.memberships
+  metadata: { jiraToken: atlassianPat },    // → metadata.jiraToken
+})
+```
+
+The two merge — neither clobbers the other. **When a `memberships` key appears in both,** the dedicated `memberships` option wins: it is the typed input, and it is the one projected into the `{ tenantId, role }` shape `subjectMemberships()` and the tenant switcher read. Without the option, a `memberships` key inside `metadata` passes through unchanged. A Subject built with neither option has no `metadata` key at all.
+
+Keys set this way survive the login paths: the sign-in / sign-up / magic-link / passkey handlers merge `sessionId` onto the existing slot, and the password strategy merges `provider` — they add, they don't replace. The one exception is naming a key `sessionId` or `provider` yourself; those two are overwritten by design.
+
+**It survives a tenant switch too.** A switch rebuilds the Subject from the user record, so the built-in `/switch-tenant` route passes the caller's current `subject.metadata` through to `handleSwitchTenant` — a credential parked here keeps working after the user changes tenant. Calling `handleSwitchTenant` yourself? Pass `metadata` or the credential is dropped, and the symptom is unpleasant to diagnose: the user stays signed in while every call to the provider starts failing. `memberships` is deliberately *not* carried — it is re-derived for the target tenant, and a carried copy would report a role the user does not hold there.
+
+Two things not to put here. **Anything the caller could benefit from changing** — the slot rides the signed session cookie, so it is tamper-evident, but it is also stale by design: it reflects the moment of sign-in, not the current database. And **anything large** — it is re-serialised into every session cookie.
+
 ## Resolution
 
 `AuthMiddleware` resolves a `Subject` on every request by running the [strategy chain](/docs/authentication/strategies) — `composeAuthStrategies` evaluates each strategy in order, first `matched` wins, first `failed` short-circuits to anonymous. A typical chain resolves, in order:
@@ -1010,12 +1033,12 @@ const result = await handleSignIn(
 What it does:
 
 1. `userStore.findByEmail(email)` — fetch the user (or pretend, see [timing oracle](/docs/authentication/passwords#timing-oracle-defence)).
-2. `verifyPassword(password, user.passwordHash)` — always run, even on unknown email.
+2. `verifyPassword(password, user.passwordHash)` — always run, even on unknown email, and even when the user exists but has **no** stored hash.
 3. On success: `issueSession(subject, config.secret, {...})` → set the `Set-Cookie` header.
 4. If `redirectAfter` is true (form POST): 302 to `AUTH_CONFIG.successRedirect`.
 5. If `redirectAfter` is false (XHR / fetch): 200 + JSON `{ ok: true, subject }`.
 
-Failures return a 401 `HandlerResult` with a generic `{ error: 'invalid credentials' }` body — no email-existence disclosure. The handlers encode failures as 4xx/5xx `HandlerResult`s rather than throwing domain errors across the wire.
+Failures return a 401 `HandlerResult` with a generic `{ error: 'invalid credentials' }` body — no email-existence disclosure. That includes an account with no `passwordHash` at all (SSO-only, magic-link-only, passkey-only, provider PAT): the password strategy **refuses** it, taking the same branch as an unknown email — same decoy scrypt, same status, same body, no cookie. An absent hash is never "nothing to compare, let them in", and the response does not reveal which accounts are password-less. The handlers encode failures as 4xx/5xx `HandlerResult`s rather than throwing domain errors across the wire.
 
 ## handleSignUp
 
@@ -1210,7 +1233,7 @@ interface UserStore {
 interface UserRecord {
   readonly id: string
   readonly email: string
-  readonly passwordHash: string
+  readonly passwordHash?: string | null   // absent = this account has no password
   readonly tenantId: string
   readonly createdAt: Date
   readonly mfaSecret?: string | null      // base32 TOTP secret; null = not enrolled
@@ -1218,6 +1241,10 @@ interface UserRecord {
 }
 ```
 
+`passwordHash` is **optional** — not every identity has a password. An SSO-only, magic-link-only, passkey-only or provider-PAT app simply omits it, and the `users` table column is nullable to match. Do not invent a placeholder: a fake hash is a real value sitting in the column a verifier compares against, which is strictly worse than storing nothing. `null`, `undefined` and `''` all mean "no password".
+
+`handleSignIn` refuses a password sign-in for such an account the same way it refuses an unknown email — it still burns a decoy scrypt and returns the identical 401 with no cookie — so the response reveals neither that the account exists nor that it is password-less. Assigning a hash later (password reset, set-password) promotes the account to a password user normally. `createdAt` stays required; every store can supply it, and `insert` takes `Omit<UserRecord, 'createdAt'>` so you never pass one yourself.
+
 There is no `updatePasswordHash` method and no `updatedAt` field. The interface is deliberately small. Add your own fields (display name, avatar URL, locale) on a sibling table joined by `userId` — keep the auth-critical fields in the auth table.
 
 ## memoryUserStore
@@ -1295,7 +1322,6 @@ const okta = (): UserStore => ({
       return {
         id:           `okta:${oktaUser.id}`,
         email:        oktaUser.profile.email,
-        passwordHash: '', // we never auth password locally — see below
         tenantId:     oktaUser.profile.tenantId,
         createdAt:    new Date(oktaUser.created),
       }
@@ -1975,16 +2001,88 @@ await ctx.store.query(tickets.descriptor)   // filtered
 await ctx.store.select('tickets').all()     // filtered
 ```
 
-## A failing `load` denies
+## When `load` fails
+
+`load` reads your store — for relational visibility it *must* — which makes it
+exactly the kind of call that blips. Two separate questions follow from a
+failure, and the answers are deliberately different.
+
+### First: is the failure even real? (`retry`)
+
+A transient failure must never reach the decision below, because once it gets
+there it is indistinguishable from an authorization answer. So `load` runs under
+a bounded retry before anything is concluded from it:
+
+```ts no-check
+import { Schedule } from 'effect'
+
+setRowFilter({
+  load,
+  predicate,
+  retry: Schedule.recurs(5),   // your own schedule
+  // retry: false,             // exactly one attempt
+})
+```
+
+The default is `DEFAULT_ROW_FILTER_RETRY` (exported from `@voltro/runtime`):
+**three attempts, backing off exponentially from 20ms** — about 60ms of added
+latency in the worst case. It is sized for a blip (a connection reaped from the
+pool, a failover flap), not for an outage. A `load` still failing after that is
+not having a bad moment, and stretching the schedule only turns a fast honest
+error into a slow one while holding the request open.
+
+### Then: what does a real failure mean? (`onLoadError`)
+
+Not "you may see nothing". **We cannot tell what you may see.** Those are
+different facts and only one of them is a fact — so the default raises a typed
+error:
+
+```ts no-check
+setRowFilter({
+  load,
+  predicate,
+  onLoadError: 'fail',   // default — raises RowFilterUnavailable
+  // onLoadError: 'deny', // degrade to zero rows instead
+})
+```
+
+- **`'fail'` (default)** — the request fails with the typed
+  `RowFilterUnavailable`. Handle it in your UI as an error state, the same as any
+  other failed request.
+- **`'deny'`** — refusal is expressed as a predicate matching nothing, so the
+  read returns an empty result. Choose this only if you have looked at the screen
+  and are content for it to render empty during an outage. Your `onError`
+  reporter still fires, so the failure stays findable in logs even though the
+  response is a 200.
+
+The default changed *to* `'fail'`, and the reasoning is worth stating plainly
+because the old default looked defensible: an empty result for an infrastructure
+failure is byte-identical to legitimate emptiness. The user reads "you have no
+tickets". The operator reads a healthy 200. The outage is invisible to both —
+the most misleading outcome on offer. Every constrained page **is** broken when
+this happens, and saying so is the only outcome either party can act on.
+
+### There is no fail-open option
+
+A frequent request, and a deliberate refusal: there is no policy that serves
+**unfiltered** rows when the filter is unavailable, falling back to whatever
+check the handler carries.
+
+Failing open on an authorization filter leaks data precisely when the system is
+under stress and nobody is reading dashboards. And it is only safe if every
+handler still carries its own row-level check — which is the entire thing a row
+filter exists to remove. A codebase where fail-open is safe is a codebase that
+did not need `setRowFilter`.
+
+Both policies above are fail-**closed**: neither can ever produce an unfiltered
+read.
 
-If `load` fails, every constrained read is **refused** rather than silently
-running unfiltered. A row filter that degrades to "no filter" under load failure
-is worse than no filter at all, because the system keeps serving and nothing
-looks wrong.
+### Subscriptions
 
-The refusal is expressed as a predicate that matches nothing, not as an error —
-so a failure surfaces as an **empty result** rather than a 500 on every page. The
-underlying cause is reported separately, so it cannot pass unnoticed.
+A resolution failure mid-stream **revokes** the subscription and emits a typed
+error frame, rather than delivering an empty snapshot — an empty snapshot on a
+live subscription reads to a client as "every row you could see was just
+deleted". Make sure your subscription error handling surfaces it.
 
 ## What does *not* bypass it
 
@@ -2022,7 +2120,7 @@ They answer different questions, and a complete policy usually wants both:
 | | Question | Failure |
 |---|---|---|
 | [`guards:`](/docs/authentication/authorization#enforce-it-declaratively-guards) | May you call this procedure? | typed `ScopeError`, before the executor runs |
-| `setRowFilter` | Which rows may you see? | the rows are simply absent |
+| `setRowFilter` | Which rows may you see? | the rows are simply absent — unless the filter itself could not load, which is a typed `RowFilterUnavailable` |
 
 A guard is the right tool for "may this caller edit *this* ticket". A row filter
 is the right tool for "which tickets appear in the list at all" — a question a

package/templates/agent-docs/cli.md

@@ -421,13 +421,43 @@ voltro dev apps/acme/api            # explicit path
 
 1. Reads `app.config.ts`. Bails if not `type: 'web'`.
 2. Walks `src/pages/` for queries + special files.
-3. Generates `.framework/main.tsx`, `.framework/app.tsx`, `index.html`.
+3. Generates `.framework/main.tsx`, `.framework/app.tsx`, `.framework/routeTable.ts`, `index.html`.
 4. Starts Vite with the framework's plugin chain (React, Tailwind v4, page discovery, inspect, dashboard registry).
 5. Binds to the configured port from `app.config.ts.port` (strict — fails on conflict).
 6. Watches `src/`. On save, Vite HMR fires:
-   - TSX changes → React Refresh updates the live component.
+   - A page / layout **component** change → React Fast Refresh patches the live
+     component in place; client state survives (see below).
+   - A page / layout **`loader`** (or other non-component export) change → a
+     full page reload, on purpose (see below).
    - CSS changes → swap stylesheets in place.
-   - New page file → regen `.framework/app.tsx` → reload the query tree.
+   - New page file → regen the entry files → reload the route tree.
+
+
+### Fast Refresh: what hot-updates and what reloads
+
+Editing a **page or layout component** applies as a hot update — the React tree
+stays mounted, so form input, scroll position, open dialogs and every `useState`
+survive. Editing a **`loader`** (or `meta` / `renderMode` / any other
+non-component export of a route module) triggers a full page reload instead.
+
+That split is deliberate, not a gap. A `loader` also runs on the server: the page
+in front of you was rendered from the OLD one, and the router caches loader
+results per route + params, so hot-swapping the function would leave stale data
+on screen with nothing to signal it. A reload re-runs SSR with the new loader.
+
+The mechanism, in case you hit an edge: React Fast Refresh only accepts a module
+whose exports are all components, and a page exporting `loader` beside its
+component fails that test. `voltro dev` registers each route module's
+non-component exports with the React plugin's ignore hook, and decides the
+reload itself by comparing those exports' VALUES across the update — a function
+by its source text, anything else by its JSON form — so a JSX-only edit (which
+recreates the `loader` object) is correctly read as "unchanged".
+
+One consequence worth knowing: a page that exports a non-component value which
+changes on the same save as its JSX — a `const COLUMNS = [...]` you edit
+together with the table that renders it — reloads rather than hot-updates. Move
+that value into a sibling module (`./columns.ts`) and the page hot-updates
+again; the sibling's own edits still propagate through the page's boundary.
 
 ### The in-page devtools overlay
 
@@ -585,6 +615,7 @@ If you must override per-process from the shell, set `PORT` inline on each one (
 
 - **Running `voltro dev` against a `voltro start` build directory.** The dev server expects source files; pointing it at `dist/` confuses it. Use `voltro start` for that.
 - **Ignoring `app.config.ts` changes.** They require a process restart (the discovery walker re-reads them at boot only). Save, watch the process die + come back up.
+- **Reading "the page reloaded" as "HMR is broken".** A page/layout component edit hot-updates and keeps client state; a `loader` edit reloads *by design* — it also runs server-side, and the rendered page came from the old one. If a pure component edit reloads, look for a non-component export on that route module that changed in the same save.
 - **Expecting a `.env` edit to hot-reload.** It can't — `process.env` is read once at boot. `voltro dev` hard-restarts the server on a `.env` change (you'll see `.env changed … — hard-restarting`); wait for the process to come back before testing, rather than assuming the new value is already live.
 - **Disabling the dashboard "to save resources".** It's a few MB of RAM + the inspect endpoints fail gracefully. Keep it on; it's the best debugging tool you have.
 
@@ -771,7 +802,7 @@ It covers both halves of the stack:
 | server | a `token` / `secret` / `password` column with no encryption | `.encrypted()` |
 | server | a notify / webhook helper called at a mutation's tail | `defineSubscriber` / `defineReaction` |
 | server | `hasMore` + `limit + 1` | `paginateById` |
-| server | `.getTime()` / `.toISOString()` mapping a row on the way out | `rowSchema(table)` as the descriptor's `output` |
+| server | `.getTime()` / `.toISOString()` mapping a row on the way out | `timestampMs` / `timestampMsOrNull` from `@voltro/database/wire` in the descriptor's `output` struct |
 | client | per-field `useState` + a submit flag | `useFormBinding` |
 | client | a table with local sort/filter state | `useDataTable` |
 | client | `FileReader` / `readAsDataURL` | `useUpload` |
@@ -1822,7 +1853,7 @@ _voltro update — bump the framework to the latest version and run the codemods
 `voltro update` upgrades an app to the latest framework release. It does three things in order:
 
 1. **Bump** every `@voltro/*` dependency in `package.json` to the target version.
-2. **Install** with your package manager (detected from the lockfile — pnpm / npm / yarn / bun).
+2. **Install** with your project's package manager — see [Which package manager](#which-package-manager) below.
 3. **Run the codemods** shipped with the target version — automatic source rewrites for any breaking API change, plus printed manual steps for anything that can't be automated.
 
 ```bash
@@ -1831,12 +1862,47 @@ 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 --exact         # pin exact versions (drop the ^ / ~ range prefix)
+voltro update --help          # every flag — always answered, even on a dirty tree
 
 # Recover the codemods after a MANUAL version bump (no bump, no install):
 voltro update --codemods-only --from 0.3.0            # re-run codemods 0.3.0 → installed
 voltro update --codemods-only --from 0.3.0 --to 0.4.0 # explicit delta
 ```
 
+## In a workspace, the whole workspace moves
+
+Run `voltro update` anywhere inside a workspace — a `pnpm-workspace.yaml`, or a
+`workspaces` field in an ancestor `package.json` — and **every member
+`package.json` that declares `@voltro/*` is bumped to the same version**, with
+the install running **once at the workspace root**.
+
+This is not a convenience. Your api and your web app share generated types (the
+rpcGroup) and a session cookie shape; if the api moves to 0.6.0 while
+`apps/web` and `packages/ui-*` stay on 0.5.0, the mismatch shows up as a runtime
+decode error in the browser, not as a build failure. Half-upgraded is the worst
+state to be in, so `voltro update` never leaves you there.
+
+The plan output — and `--dry-run` — lists every file it will touch:
+
+```text
+voltro update: 0.5.0 → 0.6.0
+  workspace: /repo (4 package.json with @voltro/* deps)
+  package.json
+    @voltro/cli: ^0.5.0 → ^0.6.0
+  apps/api/package.json
+    @voltro/cli: ^0.5.0 → ^0.6.0
+    @voltro/database: ^0.5.0 → ^0.6.0
+  apps/web/package.json
+    @voltro/client: ^0.5.0 → ^0.6.0
+  packages/ui-admin/package.json
+    @voltro/web: ~0.5.0 → ~0.6.0
+  package manager: pnpm
+  install runs in: /repo
+```
+
+A standalone (non-workspace) project is unaffected: its own `package.json`, its
+own install, in place.
+
 ## Already bumped by hand? Recover the codemods
 
 If you bump `@voltro/*` versions in `package.json` yourself and install first, a
@@ -1859,9 +1925,31 @@ source version.
 
 Codemods **rewrite your source**, so you need a clean diff to review afterwards. `voltro update` refuses to run on a dirty git working tree — commit or stash first. Use `--dry-run` to preview without touching anything, or `--force` to override the guard (you accept a mixed diff).
 
+`--help` / `-h` is answered *before* the guard, so `voltro update --help` prints the flag list even on a dirty tree. The same holds for `voltro doctor --help`.
+
+## If the install fails
+
+The bump is written before the install runs, so a failed install leaves your `package.json` on the target version — and **no codemods applied**. `voltro update` says so explicitly, because the codemods for a jump ship *inside* the target version: a failed install never put them on disk, so there is nothing that could have run them. Fix the install, run it, then apply the codemods you are missing with the command the failure message prints for you:
+
+```bash
+voltro update --codemods-only --from 0.5.0 --to 0.6.0
+```
+
 ## What gets bumped
 
-Every `@voltro/*` entry in `dependencies` and `devDependencies`, 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.
+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.
+
+## 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**:
+
+1. The **`packageManager` field** in a `package.json` (the corepack standard) — authoritative, wins over any lockfile.
+2. A **lockfile** at that level — `pnpm-lock.yaml`, `yarn.lock`, `bun.lock` / `bun.lockb`, `package-lock.json`.
+3. **npm**, only when nothing declares one.
+
+Walking up matters in a workspace: a scaffolded Voltro project keeps its lockfile at the monorepo root, so running `voltro update` from `apps/api` still finds `pnpm` rather than falling back to npm and running `npm install` against a pnpm workspace.
+
+The same resolved manager is used for the **registry lookup** of the latest version (`pnpm view`, `yarn npm info`, `bun pm view`), so a private or scoped registry configured in your `.npmrc` / `.yarnrc.yml` is honored. `npm view` is only a last-resort fallback.
 
 ## Codemods
 

package/templates/agent-docs/data.md

@@ -304,7 +304,7 @@ defineMutation({ name: 'notes.create', target: { table: 'notes', op: 'insert' },
 
 With that pairing, `useMutation('app', 'notes.create')` can stage an optimistic row in active `notes.list` caches without client-side cache plumbing.
 
-## `output` is the serializer — `rowSchema(table)`
+## `output` is the serializer — `timestampMs`
 
 A descriptor's `output` is not documentation of the shape. It **is** the
 serializer: it is handed to the rpc as the success schema, so a handler's result
@@ -325,32 +325,81 @@ output: Schema.Array(Schema.Struct({ createdAt: Schema.Number })),
 return rows.map((row) => ({ ...row, createdAt: row.createdAt.getTime() }))
 ```
 
-Declaring `Schema.DateFromNumber` instead makes the conversion automatic — but
-nobody wants to hand-map thirty columns to work that out per table.
-`rowSchema(table)` derives the whole struct from the table definition:
+Declaring `Schema.DateFromNumber` instead makes the conversion automatic.
+`@voltro/database/wire` ships that mapping under names you can drop straight
+into your own struct — including the nullable case, which is the one that goes
+wrong silently:
 
 ```ts
-// apps/api/queries/notes.list.query.ts
+// apps/api/queries/projects.list.query.ts
 import { defineQuery } from '@voltro/protocol'
-import { rowSchema } from '@voltro/database'
+import { timestampMs, timestampMsOrNull } from '@voltro/database/wire'
 import { Schema } from 'effect'
-import { notes } from '../database/schema'
 
-export const listNotes = defineQuery({
-  name:   'notes.list',
-  source: 'notes',
+export const listProjects = defineQuery({
+  name:   'projects.list',
+  source: 'projects',
   input:  Schema.Struct({}),
-  output: Schema.Array(rowSchema(notes)),
+  output: Schema.Array(
+    Schema.Struct({
+      id:             Schema.String,
+      name:           Schema.String,
+      jiraProjectKey: Schema.String,
+      addedAt:        timestampMs,        // Date in the handler, epoch ms on the wire
+      archivedAt:     timestampMsOrNull,  // for a nullable timestamp column
+      seenAt:         Schema.optional(timestampMs),
+    }),
+  ),
 })
 ```
 
-The executor returns rows straight from the store. No converters:
+The executor returns its rows and computes nothing at the tail:
 
 ```ts no-check
-// apps/api/queries/notes.list.query.server.ts
-export default () => database.notes.orderBy('createdAt', 'desc').limit(100)
+// apps/api/queries/projects.list.query.server.ts
+export default () => database.projects.orderBy('addedAt', 'desc').limit(100)
+```
+
+- `timestampMs` — `Date` in the handler, `number` (epoch ms) on the wire.
+- `timestampMsOrNull` — for a `.nullable()` timestamp. Use this rather than
+  converting a null by hand: `new Date(null)` is `1970-01-01`, so "never
+  archived" renders as a plausible date instead of as nothing.
+- An **optional** field is `Schema.optional(timestampMs)` — there is no third
+  export for it.
+
+This also matches the shape real handlers have. Most return a struct assembled
+by hand across several tables — `{ id, name, slug, addedAt, jiraProjectKey }` —
+where there is no single table to derive an output schema from anyway, and those
+are exactly the places the hand-written `Date → epoch` converters pile up.
+
+### Why the field schemas import from `@voltro/database/wire`
+
+`@voltro/database/wire` is a **browser-safe** entry: it contains plain
+`effect/Schema` values and imports `effect` and nothing else. That matters
+because a descriptor is loaded **value-level by the web client** — the rpc client
+needs every procedure's schema — so everything a `*.query.ts` transitively
+imports ends up in the browser bundle.
+
+The package root is not browser-safe, and neither is anything that reaches a
+**table value**. Importing `../database/schema` to get at `notes` imports
+`@voltro/database` itself, which pulls the store, the query builder and the SQL
+driver into the client graph. `voltro dev` refuses to boot in that case and
+prints the import chain:
+
+```
+browser-safety violation — the generated rpcGroup pulls a SERVER-ONLY module
+into the client bundle.
+  import chain:
+      → rpcGroup.generated.ts
+      → ./queries/notes.list.query
+      → ../database/schema
+      → @voltro/database
 ```
 
+So a descriptor's `output` is always written as your own `Schema.Struct` with
+field schemas — never derived from a table. Deriving from a table is a
+server-side operation; see below.
+
 ### The Encoded / Type split
 
 That split is the whole point — the handler works in domain types, the wire
@@ -369,35 +418,50 @@ carries something JSON can represent:
 number rounds silently past 2^53, and a value that is quietly wrong is worse than
 one that is rejected.
 
-`json()` / `vector()` / `raw()` map to `Schema.Unknown` rather than a guess.
-These are shapes the column declaration does not pin down, and a schema that
-guesses **wrong** rejects valid rows at the wire boundary — reporting the failure
-far from the column responsible. Loose beats wrong here; declare the precise
-shape yourself when you want one.
-
 A `.nullable()` column wraps its mapped type, so a null timestamp round-trips as
 `null` rather than becoming epoch 0 (which would render as a plausible
 `1970-01-01` instead of "never").
 
-### Keeping a column off the wire — `omit`
+### Row codecs for server-side code — `rowSchema`, `columnSchema`
 
-```ts
+`rowSchema(table)` builds the whole struct from a table definition, and
+`columnSchema(def)` maps one column. Both take the table as a **value**, so by
+the section above they can only be used in code that already runs on the server
+alone — a `*.query.server.ts` / `*.mutation.server.ts` executor, a `*.seed.ts`,
+a startup or job module, a maintenance script, a test. **Not** a descriptor's
+`output`.
+
+What they are for is encoding or decoding table rows outside the rpc path, where
+no `output` schema is doing it for you: writing rows to a file export or a queue
+payload, or validating seed / import data against the actual table shape before
+it is written.
+
+```ts no-check
+// apps/api/database/notes.seed.ts — server-only, so the table value is fine
 import { rowSchema } from '@voltro/database'
-import { users } from '../database/schema'
+import { Schema } from 'effect'
+import { notes } from './schema'
 
+const rows = Schema.decodeUnknownSync(Schema.Array(rowSchema(notes)))(
+  JSON.parse(await readFile('seed/notes.json', 'utf8')),
+)
+```
+
+`omit` drops columns from the schema — the way to keep an internal column out of
+an export:
+
+```ts no-check
 rowSchema(users, { omit: ['passwordHash'] })
 ```
 
-`omit` is a **convenience, not a security boundary**. The column is simply absent
-from *this* schema; a handler that returns the same row under a different schema
-still sends it. For a real boundary, see
+It is a **convenience, not a security boundary**. The column is simply absent
+from *this* schema; code that serializes the same row under a different schema
+still emits it. For a real boundary, see
 [`.encrypted()` and column sensitivity](/docs/database/sensitivity).
 
-### One column at a time — `columnSchema`
-
-`columnSchema` maps a single column, and it takes a column **definition** — what
-`table.fields` holds — not the builder that `text()` or `timestamp()` returns
-(a builder's definition is private, so it cannot be read from outside):
+`columnSchema` takes a column **definition** — what `table.fields` holds — not
+the builder that `text()` or `timestamp()` returns (a builder's definition is
+private, so it cannot be read from outside):
 
 ```ts no-check
 import { columnSchema } from '@voltro/database'
@@ -406,6 +470,10 @@ columnSchema(notes.fields.createdAt)   // ✅ a definition, from table.fields
 columnSchema(timestamp())              // ❌ a builder — not readable
 ```
 
+The mapping is single-sourced: `columnSchema` returns the very same
+`timestampMs` value for a `timestamp()` column, so a derived row schema and a
+hand-written descriptor struct can never disagree about the wire shape.
+
 ## What gets sent on the wire
 
 Queries are streaming RPCs whose elements are **subscription events**: an initial `snapshot` followed by `delta`s. See [Wire protocol](/docs/data/wire-protocol#subscription-events-snapshot-delta) for the envelope shape. For plain element streams, use [Streams](/docs/data/streams).

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

@@ -423,7 +423,7 @@ the framework ships richer types for specific use cases:
 - **`timestamp` without `tz`.** Use `timestamp()` which is `timestamptz`.
 - **Storing JSON blobs as `text`.** Use `json<T>()` for type-safety + JSONB performance.
 - **`references('table')`.** The constructor is `reference(() => table)` — singular, thunk-arg.
-- **Declaring a `timestamp()` column as `Schema.Number` in a descriptor's `output`.** That describes the *wire* type, not the domain type, so the schema has nothing left to convert and the handler ends up doing it by hand. Derive the row schema instead — [`rowSchema(table)`](/docs/data/queries#output-is-the-serializer-rowschema-table).
+- **Declaring a `timestamp()` column as `Schema.Number` in a descriptor's `output`.** That describes the *wire* type, not the domain type, so the schema has nothing left to convert and the handler ends up doing it by hand. Declare the field schema instead — [`timestampMs` / `timestampMsOrNull`](/docs/data/queries#output-is-the-serializer-timestampms) from `@voltro/database/wire`. Do **not** reach for `rowSchema(table)` here: a descriptor cannot import a table value without dragging `@voltro/database` into the browser bundle, and the boot aborts. `rowSchema` is a [server-side row codec](/docs/data/queries#row-codecs-for-server-side-code-rowschema-columnschema).