@voltro/cli 0.3.0 → 0.4.0

package/dist/serveEntry.js

@@ -1,4 +1,4 @@
-import { At as e, nt as t } from "./dev-x_VqbV_8.js";
+import { jt as e, rt as t } from "./dev-CQxbrpDz.js";
 import { a as n } from "./startupRunner-DhlX9nqd.js";
-import { t as r } from "./serveCommand-Dttqe5Ms.js";
+import { t as r } from "./serveCommand-BZzUJIyo.js";
 export { e as loadDotEnv, n as registerAppModules, t as registerDriver, r as runServe };

package/package.json

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

package/templates/AGENTS.core.md

@@ -61,6 +61,53 @@ Ask in order; stop at the first "yes":
 Deep dive: **`data.md`** (queries/mutations/actions/streams/errors),
 **`workflows.md`**, **`scheduling.md`**.
 
+### Pick the CLIENT primitive (decision rubric)
+
+`useSubscription` / `useMutation` / `useAction` are the transport — they are NOT
+the whole client surface. The framework ships a **headless primitive for every
+common UI job**, each derived from the descriptor Schema you already wrote. Reach
+for one BEFORE hand-rolling; ask in order:
+
+1. **A form / any typed write UI?** → **`useFormBinding`** — fields + validation
+   derived from the mutation's input Schema, and a server
+   `ValidationError({ field })` routes itself to that field. Not per-field `useState`.
+2. **A table / list with sort, filter, pagination?** → **`useDataTable`** (columns
+   from the query's output Schema, live rows). **`useQueryFilters`** builds filter
+   controls from the query's INPUT Schema; **`useQueryField`** is the query-bound picker.
+3. **A file upload?** → **`useUpload`** (progress, cancel, provider-agnostic).
+   Not `FileReader` → base64 → action.
+4. **Gating UI on permission?** → **`useCan`** / **`useCanAny`** (scopes, from
+   `@voltro/client`, fed by `<PermissionProvider scopes>`) or
+   **`useResourceCan`** / **`useResourceCans`** (per-resource ReBAC, reactive).
+   These live in the client, not behind a plugin — scopes are a framework
+   concept, so gating a button never requires installing rbac.
+5. **A value derived from one or more subscriptions?** → **`useDerived`**
+   (dependency-tracked, referentially stable). Not a hand-maintained `useMemo` dep array.
+6. **A very large list?** → **`useWindowedSubscription`** (subscribe to the visible
+   window only, not a million rows).
+7. **Debounced input?** → **`useDebounced`**; **`useAsyncValidation`** for checks
+   that need the DB (uniqueness, cross-row) — live, over a query binding.
+8. **A loading placeholder?** → **`useFormSkeleton`** / **`useTableSkeleton`** —
+   shaped like the REAL data, from the same Schema.
+9. **Offline writes · undo · dry-run · "why is this value here?"** → **`useOutbox`**,
+   **`useUndoLog`**, **`usePreview`**, **`useProvenance`**.
+10. **Global rpc-error handling?** → **`useOnRpcError`** + **`reportClientError`**.
+
+| You're about to write | Reach for instead |
+|---|---|
+| per-field `useState` + `isSubmitting` + `resetForm()` | `useFormBinding` |
+| shadcn `<Table>` + per-table sort/filter state | `useDataTable` |
+| `FileReader` → base64 → action → `storage.put` | `useUpload` |
+| `useMemo` fanning in 3+ subscriptions | `useDerived` |
+| `setTimeout` debounce inside `useEffect` | `useDebounced` |
+| `data === undefined ? <Skeleton/> : …` | `useFormSkeleton` / `useTableSkeleton` |
+| a hand-kept page-scope check | `useCan` / `useResourceCan` |
+| a hand-rolled presence roster / notification inbox / feature flag | `@voltro/plugin-presence` / `-notifications` / `-flags` |
+
+Deep dive: **`schema-driven-ui.md`** (forms, tables, pickers, filters, skeletons),
+**`reference.md`** (the complete hook list). If you are hand-writing more than ~20
+lines of generic UI plumbing, stop and check those two first.
+
 ## Project layout
 
 One OR MORE **projects** live under `apps/`. A project (`project.json`) is the

package/templates/AGENTS.md

@@ -61,6 +61,53 @@ Ask in order; stop at the first "yes":
 Deep dive: **`data.md`** (queries/mutations/actions/streams/errors),
 **`workflows.md`**, **`scheduling.md`**.
 
+### Pick the CLIENT primitive (decision rubric)
+
+`useSubscription` / `useMutation` / `useAction` are the transport — they are NOT
+the whole client surface. The framework ships a **headless primitive for every
+common UI job**, each derived from the descriptor Schema you already wrote. Reach
+for one BEFORE hand-rolling; ask in order:
+
+1. **A form / any typed write UI?** → **`useFormBinding`** — fields + validation
+   derived from the mutation's input Schema, and a server
+   `ValidationError({ field })` routes itself to that field. Not per-field `useState`.
+2. **A table / list with sort, filter, pagination?** → **`useDataTable`** (columns
+   from the query's output Schema, live rows). **`useQueryFilters`** builds filter
+   controls from the query's INPUT Schema; **`useQueryField`** is the query-bound picker.
+3. **A file upload?** → **`useUpload`** (progress, cancel, provider-agnostic).
+   Not `FileReader` → base64 → action.
+4. **Gating UI on permission?** → **`useCan`** / **`useCanAny`** (scopes, from
+   `@voltro/client`, fed by `<PermissionProvider scopes>`) or
+   **`useResourceCan`** / **`useResourceCans`** (per-resource ReBAC, reactive).
+   These live in the client, not behind a plugin — scopes are a framework
+   concept, so gating a button never requires installing rbac.
+5. **A value derived from one or more subscriptions?** → **`useDerived`**
+   (dependency-tracked, referentially stable). Not a hand-maintained `useMemo` dep array.
+6. **A very large list?** → **`useWindowedSubscription`** (subscribe to the visible
+   window only, not a million rows).
+7. **Debounced input?** → **`useDebounced`**; **`useAsyncValidation`** for checks
+   that need the DB (uniqueness, cross-row) — live, over a query binding.
+8. **A loading placeholder?** → **`useFormSkeleton`** / **`useTableSkeleton`** —
+   shaped like the REAL data, from the same Schema.
+9. **Offline writes · undo · dry-run · "why is this value here?"** → **`useOutbox`**,
+   **`useUndoLog`**, **`usePreview`**, **`useProvenance`**.
+10. **Global rpc-error handling?** → **`useOnRpcError`** + **`reportClientError`**.
+
+| You're about to write | Reach for instead |
+|---|---|
+| per-field `useState` + `isSubmitting` + `resetForm()` | `useFormBinding` |
+| shadcn `<Table>` + per-table sort/filter state | `useDataTable` |
+| `FileReader` → base64 → action → `storage.put` | `useUpload` |
+| `useMemo` fanning in 3+ subscriptions | `useDerived` |
+| `setTimeout` debounce inside `useEffect` | `useDebounced` |
+| `data === undefined ? <Skeleton/> : …` | `useFormSkeleton` / `useTableSkeleton` |
+| a hand-kept page-scope check | `useCan` / `useResourceCan` |
+| a hand-rolled presence roster / notification inbox / feature flag | `@voltro/plugin-presence` / `-notifications` / `-flags` |
+
+Deep dive: **`schema-driven-ui.md`** (forms, tables, pickers, filters, skeletons),
+**`reference.md`** (the complete hook list). If you are hand-writing more than ~20
+lines of generic UI plumbing, stop and check those two first.
+
 ## Project layout
 
 One OR MORE **projects** live under `apps/`. A project (`project.json`) is the

package/templates/agent-docs/_manifest.json

@@ -170,7 +170,7 @@
       "group": null,
       "description": "Voltro's i18n layer (@voltro/i18n) — an opinionated wrap over react-intl, auto-wired from a single app.config.ts field, with cookie + Accept-Language locale resolution.",
       "path": "agent-docs/internationalization.md",
-      "files": 3
+      "files": 4
     },
     {
       "id": "introduction",
@@ -242,7 +242,7 @@
       "group": null,
       "description": "Project the typed descriptor graph into UI — forms, tables, pickers, and reactive components, all bound to a descriptor with near-zero glue.",
       "path": "agent-docs/schema-driven-ui.md",
-      "files": 13
+      "files": 23
     },
     {
       "id": "security",
@@ -305,7 +305,7 @@
       "group": null,
       "description": "Voltro's test story — the @voltro/testing package, the test pyramid (unit handlers/tools → workflow runner → e2e), and the voltro test / voltro e2e CLI commands.",
       "path": "agent-docs/testing.md",
-      "files": 4
+      "files": 5
     },
     {
       "id": "workflows",

package/templates/agent-docs/ai.md

@@ -1019,6 +1019,34 @@ It returns a `Stream<SeqEvent>` — each element is `{ seq, event }`. The descri
 
 On the client, `useResumableAgentStream('app', 'support.run')` does the rest: it unwraps each `SeqEvent` (so `.events` are the plain inner events), tracks the highest `seq`, and on a transport drop BEFORE the run's terminal event it auto-reconnects with `fromSeq` = the last seq it rendered (exponential backoff; the no-progress cap resets whenever a reconnect delivers a new event, so a long flaky stream survives any number of well-spaced drops). The server replays past the cursor, then continues — one seamless stream.
 
+The hook's own surface is small:
+
+```tsx
+import { useResumableAgentStream } from '@voltro/client'
+import type { AgentEvent } from '@voltro/ai/events'
+
+const run = useResumableAgentStream<AgentEvent>('app', 'support.run')
+
+// `input` MUST carry the resume key — `fromSeq` is injected by the hook.
+run.start({ streamId, message: prompt })
+run.cancel()
+```
+
+| Field | Meaning |
+|---|---|
+| `events` | The unwrapped inner events so far, in order and deduped by `seq`. |
+| `status` | `'idle'`, `'streaming'`, `'reconnecting'`, `'done'`, or `'error'`. |
+| `reconnects` | How many times the transport dropped and auto-reconnected this run. |
+| `error` | Set when `status === 'error'`. |
+| `start(input?)` | Begins a run, clearing previous events. |
+| `cancel()` | Stops the run and any pending reconnect. |
+
+A third options argument tunes the reconnect policy: `maxReconnects` (default
+`6`), `backoffMs` (`400`), `maxBackoffMs` (`8000`), and `isTerminal` — which
+defaults to treating an `AgentEvent`-shaped `{ _tag: 'done' | 'error' }` as the
+end of the run. Override `isTerminal` when your element type signals completion
+some other way, or the hook will keep trying to resume a finished stream.
+
 For multi-node deployments use `dataStoreResumableStreamStore(ctx.store)` — it persists to the framework's own database (`streamEventsTable` + `streamStateTable`, register them in your `database/index.ts`) and elects exactly ONE producer per `streamId` via an atomic claim, so only one node runs the model while every node's consumers tail the shared log. Sweep finished streams with `gcResumableStreams(store, { olderThan })`.
 
 For the fastest path, `redisResumableStreamStore(redis, { ttlSeconds })` backs the log with a Redis LIST (`RPUSH`/`LRANGE`) plus a `SET … NX` producer claim — TTL evicts finished/abandoned streams without a sweep. `@voltro/ai` takes no Redis dependency; you inject a tiny `ResumableRedis` client (five methods: `setNx` / `rpush` / `lrange` / `set` / `exists`) adapting ioredis / node-redis. All three backends satisfy the same `ResumableStreamStore` interface, so they swap without touching the producer/consumer code.

package/templates/agent-docs/authentication.md

@@ -403,7 +403,7 @@ if (!canTrigger) throw new Unauthorised({})
 ```ts
 import { permission } from '@voltro/plugin-rbac'
 
-yield* permission(ctx, 'admin:full')   // Effect<void, Forbidden>
+yield* permission(ctx, 'admin:full')   // Effect<void, ScopeError>
 ```
 
 See [the RBAC plugin](/docs/plugins/rbac) for the full model.
@@ -1778,9 +1778,12 @@ the headline that builds on it.)
 import { useResourceCan } from '@voltro/client'
 
 const canEdit = useResourceCan('app', 'todos.can', { action: 'edit', resourceType: 'todo', resourceId: id })
-// canEdit.allowed: boolean | undefined (undefined until resolved); reactive.
+// canEdit.allowed: boolean (false until the first verdict); canEdit.pending: boolean.
 ```
 
+Full API — including the batch `useResourceCans` for per-row gating — in
+[usePermissions](/docs/ui/client-utilities/use-permissions).
+
 ## Capability map
 
 `rebacPolicyGraph()` returns every resource type, its actions, the relations each

package/templates/agent-docs/cli.md

@@ -722,6 +722,23 @@ For WebSocket connections to land on the same backend (required for in-process s
 - Reverse proxy: `lb_policy ip_hash` (Caddy) / `ip_hash` (nginx).
 - Or use `@voltro/plugin-cluster` to share subscription state across instances → any-load-balancer-works.
 
+## `voltro doctor` — preflight a production serve
+
+Production `voltro serve` for an **API** app boots ONLY from the precompiled serve
+bundle and is **fatal if it's missing** — a hand-rolled Dockerfile that runs
+`voltro serve` without a prior `voltro build` breaks at deploy. `voltro doctor`
+(or `voltro serve --preflight`) catches that at BUILD time instead of cold-start:
+
+```bash
+voltro doctor .                 # check the serve bundle exists; print the fix if not
+voltro serve --preflight .      # same check, then exit — never boots
+```
+
+It exits **1** when the serve bundle is missing on an API app (so it fails a CI /
+Docker step) and prints the exact remedy: add a `voltro build .` step before
+`voltro serve .`. Drop it into your image build right after `voltro build` to
+guarantee the artefact is present before the image ships.
+
 ## Anti-patterns
 
 - **Running `voltro start` against a directory without `dist/`.** It exits 1 with a clear `no built dist found — run voltro build first` (checked against `.framework/dist/index.html` before any heavy work). Run `voltro build` first.
@@ -1672,8 +1689,30 @@ 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)
+
+# 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
 ```
 
+## Already bumped by hand? Recover the codemods
+
+If you bump `@voltro/*` versions in `package.json` yourself and install first, a
+plain `voltro update` sees the installed version already equals the target and
+reports **"already on X — nothing to do"** — skipping the codemods AND the
+printed manual steps for the delta you actually crossed. To re-apply them without
+touching `package.json` again:
+
+```bash
+voltro update --codemods-only --from <version-you-came-from>
+```
+
+`--codemods-only` (alias `--run-codemods`) runs the codemods + manual notes for
+`[from, to]` against the already-installed tree — no version bump, no install.
+`--to` defaults to the installed version; pass it to pin an explicit delta.
+`--from` also works on a normal `voltro update` to override the auto-detected
+source version.
+
 ## The clean-tree guard
 
 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).

package/templates/agent-docs/data.md

@@ -315,6 +315,40 @@ Queries are streaming RPCs whose elements are **subscription events**: an initia
 - **Using a stream for durable data.** Streams are transient. Persist rows and expose them through a query when the UI should survive reloads or sync across tabs.
 
 
+## Loading vs empty — don't conflate them
+
+`useSubscription` returns `loading` and `isEmpty` alongside `data`. They are
+**different** states, and branching on `data === undefined` alone is what causes
+a flash of empty-state before the first snapshot:
+
+| State | Meaning | Render |
+|---|---|---|
+| `loading` | no snapshot has arrived yet | skeleton |
+| `isEmpty` | snapshot arrived, zero rows (or a null value) | empty state |
+| neither | rows present | the list |
+
+```tsx
+const { data, loading, isEmpty } = useSubscription<Note[]>('app', 'notes.list', {})
+if (loading) return <TableSkeleton/>
+if (isEmpty) return <EmptyNotes/>
+return <NotesTable notes={data!}/>
+```
+
+`fallback` fills `data` while loading so a page can render its real (empty) shell
+immediately — it never lies about `loading`:
+
+```ts
+const { data, loading } = useSubscription('app', 'notes.list', {}, { fallback: [] })
+// data is [] before the first snapshot; loading is still true
+```
+
+**Errors.** `error` carries a **cold-start** stream failure (nothing ever
+arrived) — check it to avoid an infinite skeleton. A failure AFTER data arrived
+deliberately does NOT replace good data with an error banner (a transient
+websocket hiccup would blank a working screen); those reach the api's error bus
+instead — subscribe with `useOnRpcError` for connection-level UX.
+
+
 
 ---
 
@@ -432,6 +466,35 @@ export default function NewNote() {
 
 `useMutation` returns `mutate`, `pending`, `error`, `data`, plus the chainable optimistic helpers.
 
+### Handling the result — `onSuccess` / `onError` / `notify`
+
+Pass a result handler to `mutate` instead of wrapping every call in
+`try/catch/finally` + toasts. `pending` already replaces the `finally`:
+
+```ts
+const create = useMutation('app', 'teams.create')
+
+await create.mutate(input, {
+  onSuccess: (team) => setOpen(false),
+  notify: { success: t('teams.created'), error: (e) => messageFor(e) },
+})
+```
+
+**The load-bearing rule:** supplying an error handler (`onError` **or**
+`notify.error`) marks the failure **handled** — `mutate` then resolves with
+`undefined` instead of rejecting, which is what removes the `try/catch`. With no
+error handler it rejects exactly as before, so an unhandled failure stays loud.
+You opt in per call.
+
+`notify` routes to an app-wide sink you register once — the framework is not
+bound to any toast library:
+
+```ts
+import { setMutationNotifier } from '@voltro/client'
+setMutationNotifier({ success: (m) => toast.success(m), error: (m) => toast.error(m) })
+```
+
+
 ## Auto-Optimistic
 
 The default path is declarative:
@@ -492,6 +555,30 @@ target: {
 - `op: 'delete'` filters the item out by its key.
 - `by` overrides the item-key field (default `'id'`).
 
+**Shape the item with `shapeItem` (not `shape`).** For a nested target, build/patch the item with `shapeItem` — it is typed to the **item** of the nested array, not the mutation's output, so `current` needs no cast:
+
+```ts
+target: {
+  table: 'projectRoadmaps', op: 'update', path: 'snapshot.projects',
+  identify: (input) => input.projectId,
+  shapeItem: (input, current) => ({ ...current, startDate: input.startDate }),  // `current` IS the item
+}
+```
+
+(The flat `shape` stays bound to the output row — a single field can't be both, so the nested shaper is its own.)
+
+**Bulk (multi-item) patches.** `identify` may return an **array** of ids to patch or delete **many** items in one mutation — exactly the group-drag / batch-edit where per-item parallel writes used to race:
+
+```ts
+target: {
+  table: 'projectRoadmaps', op: 'update', path: 'snapshot.projects',
+  identify: (input) => input.projectIds,                    // ← ARRAY: patch them all
+  shapeItem: (input, current) => ({ ...current, shiftedBy: input.delta }),  // each keeps its own key
+}
+```
+
+(This works for flat top-level targets too — `identify` returning an array patches/deletes every matching row.)
+
 Add `match` to patch **only** the entries whose current value satisfies a predicate — the guard that stops a patch bleeding across sibling subscriptions sharing a source table:
 
 ```ts
@@ -502,7 +589,7 @@ target: {
 }
 ```
 
-`path`, `by`, and `match` are browser-safe descriptor data (a dot-path string + a pure predicate) — the same discipline as `identify`/`shape`.
+`path`, `by`, `match`, and `shapeItem` are browser-safe descriptor data (a dot-path string + pure functions) — the same discipline as `identify`/`shape`.
 
 ## Typed Errors
 
@@ -524,6 +611,42 @@ export const createNote = defineMutation({
 
 Throw a matching error from the server file; the client can narrow on `_tag`.
 
+### Matching typed errors on the client
+
+Tagged errors **round-trip structurally** over the wire — the caught value carries `_tag` plus every declared field as real properties (and `instanceof` works, same Schema class both ends). You do **not** need to parse the error message string.
+
+Inside Effect, use `Effect.catchTag('NoteQuotaExceeded', …)`. In a React `try/catch` (outside Effect, where `catchTag` isn't available and the decoded value may be a plain object, not a class instance), match with **`errorTag(err)`** — the dependency-free tag reader `@voltro/client` ships:
+
+```ts
+import { errorTag } from '@voltro/client'
+
+try {
+  await createNote(input)
+} catch (err) {
+  if (errorTag(err) === 'NoteQuotaExceeded') {
+    // err.limit is the declared field — read it directly, no regex
+  }
+}
+```
+
+**Trace id for debugging.** An error caught from `useMutation` / `useAction` carries a **non-enumerable `__voltroTraceId`** — the bridge to the server logs for that exact call:
+
+```ts
+const traceId = (err as { __voltroTraceId?: string }).__voltroTraceId
+// → `voltro logs --trace <traceId>` to see the server-side span
+```
+
+**Exhaustive matching with the generated `matchError`.** Codegen emits a per-app `matchError` (plus `AppError` / `AppErrorTag`) into `rpcGroup.generated.ts`, derived by reference from every descriptor's `error:` schema + your plugins' cross-cutting errors — so there's no hand-maintained tag list to drift out of date (a dead/renamed tag is a compile error):
+
+```ts
+import { matchError } from './rpcGroup.generated'
+
+const message = matchError(err, {
+  NoteQuotaExceeded: (e) => `Limit ${e.limit} reached`,   // e is typed
+  ScopeError: (e) => `Missing ${e.required}`,
+}, () => 'Something went wrong')
+```
+
 ## When Not To Use A Mutation
 
 - **External I/O.** Use an action or workflow.
@@ -1116,6 +1239,7 @@ The reading API is **explicit + namespace-only** — `useAggregate(def).read(...
 
 ```ts
 handle.read({
+  where:    { teamId: 't1' }, // filter the materialised rows (see below)
   limit:    10,            // pagination
   offset:   20,
   orderBy:  'rank',        // any column in the output schema
@@ -1124,7 +1248,34 @@ handle.read({
 })
 ```
 
-There's deliberately no `filter` / `where` / `join`. If you need a different cut of the data, define another aggregate.
+### Parameterised reads — `where`
+
+Without a filter an aggregate can only ever be "the one global roll-up". Every tenant-, team- or period-scoped roll-up — which is most of the real ones — then has to read the *whole* aggregate and filter client-side: every row crosses the wire so the caller can throw most of them away. `where` moves that cut to the read.
+
+```ts
+// one team's rows, for one year
+const rows = yield* handle.read({ where: { teamId: 'team_7', year: 2026 } })
+
+// an array is an IN set — status is 'open' OR 'blocked'
+const active = yield* handle.read({ where: { status: ['open', 'blocked'] } })
+
+// composes with the other read options
+const top = yield* handle.read({
+  where:   { teamId: 'team_7', status: ['open', 'blocked'] },
+  orderBy: 'rank',
+  limit:   10,
+})
+```
+
+The semantics, exactly:
+
+- **Entries are ANDed** — a row matches only when it satisfies *every* entry.
+- **A scalar value means strict equality** (`===`) against that field on the row.
+- **An array value means IN** — the row's value must be one of the array's entries.
+- An omitted `where`, or an empty `{}`, filters nothing.
+- Filtering happens **before** `orderBy` and `limit` / `offset`, so pagination paginates the filtered set.
+
+`where` is deliberately **data, not a predicate function**. It is applied over the rows the aggregate has already materialised — the refresh still computes the full roll-up, and `where` cuts the result before it crosses the wire. Keeping it a serializable record of field → value (rather than a callback) is what leaves the door open to pushing the same filter down to the store later. A cut you can't express as equality / IN belongs in another aggregate rather than in the read.
 
 ### Metadata
 
@@ -1291,11 +1442,11 @@ Mental model: `'replace'` is "snapshot at time T"; `'merge'` is "incremental del
 The defining property of an aggregate is **the query is fixed in advance**. Treating it as a query-buildable virtual table (`database.topPlayers.where(...)`) opens four footguns:
 
 1. **Hidden staleness.** `database.topPlayers.where(...)` looks like a live query. Readers can't tell it's stale data.
-2. **Computation drift.** Adding `WHERE region='EU'` shifts the filter from refresh-time to read-time — the materialisation point IS the query; don't re-query it.
+2. **Computation drift.** A full query builder shifts arbitrary computation from refresh-time to read-time — the materialisation point IS the query; don't re-query it. `read({ where })` is the bounded exception: an equality / IN cut of rows that are *already* materialised, not a new query.
 3. **Misleading expectations.** Users would reflexively try `database.topPlayers.insert(...)`. Framework would either silently do nothing or error with a cryptic message.
 4. **Cross-timeline joins.** Joining an aggregate with a live table mixes two timelines (refresh-time + now). Mostly a footgun.
 
-The explicit namespace (`useAggregate(def).read(...)`) makes the materialisation explicit. Friction in the wrong direction (filtering, joining) is a feature — it pushes you to either define another aggregate or do the work in app code with clear boundaries.
+The explicit namespace (`useAggregate(def).read(...)`) makes the materialisation explicit. `where` covers the one cut that genuinely belongs at read time — scoping a roll-up to a tenant, a team, a period. Everything past it (joins, aggregating over the aggregate, arbitrary predicates) keeps its friction on purpose: it pushes you to either define another aggregate or do the work in app code with clear boundaries.
 
 ## Decision: aggregate vs subscriber vs cron
 

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

@@ -242,9 +242,11 @@ Cross-dialect:
 | Dialect             | Support                                                        |
 |---------------------|----------------------------------------------------------------|
 | postgres / sqlite / mssql | native partial `CREATE UNIQUE INDEX … WHERE`             |
-| mysql / mariadb     | FAILS LOUDLY at migrate — no partial-index support; a full unique index would forbid re-creating a soft-deleted key. Use a generated STORED column + `.unique([...])` there. |
+| mysql / mariadb     | lowered automatically to a generated STORED column per key column (NULL when soft-deleted) + a UNIQUE over them — NULL-distinct gives the same resurrection-safe semantics. Nothing to hand-write. |
 
-The predicate is emitted verbatim (ANSI double-quoted identifiers, valid on the three supported dialects).
+**mysql / mariadb — how the emulation works.** Those engines have no partial index, so `.uniqueActive(['projectId', 'year'])` lowers to one `CASE WHEN <predicate> THEN CAST(<col> AS CHAR(255)) ELSE NULL END` STORED column per key column plus a `UNIQUE` over them. A soft-deleted row's generated columns are all NULL, and mysql/mariadb treat NULLs as DISTINCT in a unique index, so it never collides — re-creating the key just works, exactly like the partial index elsewhere. This round-trips through the declarative differ (the generated columns are part of the declared snapshot on those dialects, so `voltro dev` never re-plans them). You write the same `.uniqueActive([...])` on every dialect.
+
+The predicate is emitted verbatim (ANSI double-quoted identifiers; on mysql/mariadb they are re-quoted with backticks inside the generated column).
 
 ## When NOT to index
 

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

@@ -100,6 +100,8 @@ ctx.store.select('notes').where(not(eq('archived', true)))
 
 `and(...)` is rarely needed because chained `.where()` calls are already AND'd; useful inside `or(...)` to nest.
 
+`eq(col, val)` (and the other predicate helpers) is **callable without a row-type generic** — it defaults to a loose row shape — so in generic handler code you write `eq('teamId', id)` directly. There's no need for a `const ef = (c, v) => eq<Row, string>(c, v)` wrapper.
+
 ### JSON path filters
 
 For `json<T>()` columns: