@voltro/cli 0.2.2 → 0.4.0

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.
+
+
 
 ---
 
@@ -389,6 +423,17 @@ The descriptor is the wire contract. The `.mutation.server.ts` file is the serve
 5. Commit the transaction.
 6. Drain the batched change events so matching query subscriptions receive new snapshots or deltas.
 
+## Partial updates: `ctx.store.applyDefined`
+
+A partial-update mutation should set only the fields the caller actually sent — not overwrite an omitted field with `undefined`. Instead of hand-writing `if (input.x !== undefined) patch.x = input.x` per field, use `ctx.store.applyDefined(input, keys)`:
+
+```ts
+const execute = async (input: UpdateNote, ctx: AppContext) =>
+  ctx.store.update('notes', input.id, ctx.store.applyDefined(input, ['title', 'body', 'dueAt']))
+```
+
+It returns a patch containing only the listed keys whose value is not `undefined` (a defined falsy value like `0` / `''` / `false` IS kept). Also importable standalone (`import { applyDefined } from '@voltro/runtime'`) for seeds/tests.
+
 ## Calling From React
 
 ```tsx
@@ -421,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:
@@ -465,6 +539,58 @@ const create = useMutation('app', 'notes.create').withOptimistic((cache, input)
 
 Use `.withoutOptimistic()` for effects that should not preview locally.
 
+### Nested / path-targeted optimistic
+
+By default a `target` patches the **flat top-level row array** a query returns, keyed by `id`. When a query returns a **nested array** — a JSON array column (`snapshot.projects`) or a computed/shaped value — add `path` (and, if the item key isn't `id`, `by`) to patch at **item** granularity, with no hand-written `.withOptimistic` reducer:
+
+```ts
+target: {
+  table: 'projectRoadmaps', op: 'update',
+  path: 'snapshot.projects',                 // dot-path to the nested array in the value
+  identify: (input) => input.projectId,      // which item to patch (default input.id)
+}
+```
+
+- `op: 'insert'` appends (or `order: 'prepend'`) a new item into the nested array — safe even on a computed query (a path insert targets a KNOWN document, not a blind top-level add).
+- `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
+target: {
+  table: 'projectRoadmaps', op: 'update', path: 'snapshot.projects',
+  identify: (i) => i.projectId,
+  match: (value, input) => value.id === input.roadmapId,   // only THIS roadmap's subscription
+}
+```
+
+`path`, `by`, `match`, and `shapeItem` are browser-safe descriptor data (a dot-path string + pure functions) — the same discipline as `identify`/`shape`.
+
 ## Typed Errors
 
 ```ts
@@ -485,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.
@@ -1077,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
@@ -1085,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
 
@@ -1252,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

@@ -219,6 +219,35 @@ text().unique()                                 // single-column, on the column
 
 Multi-column uniqueness is declared at the table level with `.unique(name, [cols])` — see [Composite UNIQUE constraints](#composite-unique-constraints) below.
 
+## Unique among ACTIVE rows — `.uniqueActive([...])`
+
+Enforce uniqueness only among the rows that aren't soft-deleted — "one active roadmap per (project, year)", where a soft-deleted roadmap frees the key for a new one:
+
+```ts
+table('project_roadmaps', {
+  id: id(), projectId: text(), year: integer(), deletedAt: timestamp(),
+})
+  .softDelete()
+  .uniqueActive(['projectId', 'year'])            // partial UNIQUE among deletedAt IS NULL
+```
+
+Emits a `CREATE UNIQUE INDEX … WHERE "deletedAt" IS NULL`, so a soft-deleted row leaves the active set and a NEW row with the same key inserts cleanly — no hand-written `generatedAs("CASE WHEN …")` column, and no [resurrection bug](/docs/database/migrations/troubleshooting) where a re-imported soft-deleted key collides. The predicate defaults to the `softDelete()` active set; override it for a custom one:
+
+```ts
+.uniqueActive('byActiveSlug', ['orgId', 'slug'], { where: `"status" = 'open'` })
+```
+
+Cross-dialect:
+
+| Dialect             | Support                                                        |
+|---------------------|----------------------------------------------------------------|
+| postgres / sqlite / mssql | native partial `CREATE UNIQUE INDEX … WHERE`             |
+| 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. |
+
+**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
 
 - Tables with <10k rows on a fast disk — the cost of maintaining the index outweighs the seq-scan cost.

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:

package/templates/agent-docs/deployment.md

@@ -411,7 +411,9 @@ voltro build ./apps/api    # produces .framework/dist-api/serveBundle/
 voltro serve ./apps/api    # boots from the bundle automatically
 ```
 
-There is nothing to configure and nothing to opt into: building an API app produces the bundle, and `voltro serve` prefers it whenever it is present. It is fully fallback-safe — a missing, stale, or unreadable bundle silently degrades to the standard boot path, so a bad build can never stop the app from serving. A container image that runs `voltro build` at build time and `voltro serve` at start gets the fast boot for free.
+Building an API app produces the bundle, and `voltro serve` boots from it. In **production** (`NODE_ENV=production`) the bundle is **required** — you run `voltro build` before `voltro serve`, and a bundle-build failure is fatal: production **never transpiles on demand**, so it fails loud rather than silently falling back to the slow tsx path. (`voltro dev` and a non-production local `voltro serve` still fall back to tsx as a convenience.) The generated Dockerfiles already do this: `voltro build` at build time, `voltro serve` at start.
+
+Because production never transpiles, the serve image needs none of the build toolchain. The framework declares `tsx`, `esbuild`, `vite`, and Tailwind as **optional** dependencies of `@voltro/cli`, and the production Dockerfiles isolate the app with `pnpm --prod --no-optional deploy` — which drops that whole tree (and its native binaries) from the image. A serve image ships only what it runs at runtime: your app, the framework, and the one SQL driver you declared.
 
 ## Tiers (Voltro Cloud — coming soon)
 

package/templates/agent-docs/internationalization.md

@@ -53,7 +53,7 @@ The resolved locale is **guaranteed** to be one of the codes in `locales`. Any u
 
 The client side mirrors #1 (cookie) and #3 (default) for hydration safety. `Accept-Language` is **server-only** because `navigator.languages` can diverge from what the server saw, which would cause a hydration mismatch.
 
-See [Catalogs](/docs/i18n/catalogs) for the type-safe catalog convention and the component hooks, and [URL strategies](/docs/i18n/url-strategies) for cookie-only vs URL-prefix routing.
+See [Catalogs](/docs/i18n/catalogs) for the type-safe catalog convention and the component hooks, [Plurals & formatting](/docs/i18n/formatting) for CLDR plural selection and the `Intl`-backed date / number / relative-time hooks, and [URL strategies](/docs/i18n/url-strategies) for cookie-only vs URL-prefix routing.
 
 
 
@@ -62,7 +62,7 @@ See [Catalogs](/docs/i18n/catalogs) for the type-safe catalog convention and the
 <!-- source: en/i18n/catalogs.md -->
 ## Catalogs & hooks
 
-_Type-safe message catalogs with defineCatalog + defineLocale (parity-enforced), reading translations with useT / <T> / useLocale, ICU placeholders, and the react-intl escape hatch._
+_Type-safe message catalogs with defineCatalog + defineLocale (parity-enforced), reading translations with useT / <T> / useLocale, ICU placeholders, code-splitting with defineCatalogs + LazyI18nProvider, and the react-intl escape hatch._
 
 A **catalog** is a flat `Record<string, string>` of message ID → ICU MessageFormat template. Voltro picks flat-string format (instead of react-intl's `{ defaultMessage, description }` objects) because translation tools (Crowdin / Lokalise / Phrase) import flat string maps natively, the format diffs cleanly in code review, and the base catalog *is* the source of truth — `defaultMessage` becomes redundant.
 
@@ -168,6 +168,62 @@ export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
 
 `pickCatalog(catalogs, locale, defaultLocale)` returns the concrete catalog type, so a known-key lookup is `string` (not `string | undefined`) — exactly what `PageMeta.title` needs. An unknown or `undefined` locale falls back to `defaultLocale`.
 
+## Code-splitting catalogs — `defineCatalogs`
+
+### Why `pickCatalog` cannot split
+
+`pickCatalog({ en, de, fr }, locale)` is a **static import map**. Every catalog is a value-level `import` of the module that builds the map, so the bundler has no choice but to put all of them in one chunk — a visitor who will only ever see German downloads English and French too. At real catalog sizes that becomes the single largest client chunk in the app, and it **grows linearly with every locale you add**.
+
+No provider-side change can fix this. The cost is paid at *import* time, before any React code runs — by the time a provider knows which locale is active, all of them are already in the bundle.
+
+The only thing a bundler treats as a chunk boundary is a **dynamic `import()`**. So the catalog map becomes a map of *loaders*:
+
+```ts
+// src/locales/index.ts
+import { defineCatalogs } from '@voltro/i18n'
+
+export const catalogs = defineCatalogs({
+  en: () => import('./en'),
+  de: () => import('./de'),
+}, 'en')
+```
+
+Each arrow is its own chunk; a session fetches exactly the locales it uses. Loaders accept either an `export default` catalog or a bare map, so the catalog files from the top of this page work unchanged.
+
+`defineCatalogs(loaders, defaultLocale)` returns:
+
+- **`locales`** — the declared locales, in declaration order.
+- **`defaultLocale`** — the base locale. Its type is constrained to the loader keys, so a `defaultLocale` you never declared a loader for is a **compile error**, not a runtime blank page.
+- **`load(locale)`** — resolves the catalog, importing its chunk on first use. Concurrent callers share one import: two components mounting in the same tick will not race two fetches.
+- **`peek(locale)`** — the catalog *if already loaded*, else `undefined`. Never triggers a fetch. This is what lets a provider render synchronously.
+- **`preload(locale)`** — fire-and-forget cache warming (server boot, hover intent, a route transition that is about to switch locale).
+
+An unknown locale resolves to `defaultLocale` rather than throwing — a stale cookie or a hand-typed URL prefix degrades to the base language instead of blanking the app. A **failed** load is not cached, so the next attempt retries: a 404'd chunk on a flaky network is recoverable.
+
+### `<LazyI18nProvider>`
+
+```tsx
+import { LazyI18nProvider } from '@voltro/i18n'
+import { catalogs } from './locales'
+
+<LazyI18nProvider catalogs={catalogs} locale={locale} fallback={<AppSkeleton />}>
+  <App />
+</LazyI18nProvider>
+```
+
+A resolved catalog is cached per loader map, so switching back to a locale is synchronous and re-renders never re-import.
+
+### The trade-off, stated honestly
+
+The active catalog is now **asynchronous**, and first paint needs it resolved. There are two ways to keep that from becoming a flash of untranslated UI, and you should pick one deliberately:
+
+- **`catalogs.preload(locale)` on the server, or before `hydrateRoot`.** The catalog is already in the cache, `peek()` hits, and the provider renders in the same tick as a static catalog would — no suspense boundary, no flash. This is the **right default**, and it costs no waterfall: the locale is known from the cookie or the URL prefix before React starts.
+- **`fallback`.** Rendered for the one tick it takes to load a catalog that genuinely isn't in memory. It defaults to `null` — deliberately blank rather than a screen of untranslated message IDs.
+
+So: **`fallback` is for a locale SWITCH, not for first paint.** On a switch the user already has a rendered page and a brief placeholder is fine. If your `fallback` is showing on first load, the preload is missing — fix the preload, don't dress up the fallback.
+
+`meta({ locale })` is synchronous and runs outside React, so it still needs the static `pickCatalog` form. Keep that map in a module the client bundle doesn't import, or the static graph pulls every locale back into the browser chunk and undoes the split.
+
 ## The react-intl escape hatch
 
 For features the wrap doesn't expose — custom formatters, `Intl` options, rich-text with React-element values — import from `react-intl` directly:
@@ -382,3 +438,182 @@ For theme the parallel cookie is **`voltro:theme`** (values `'system' | 'light'
 - **Don't mix strategies within one app.** Pick cookie-only *or* URL-prefix per app; mixing them produces ambiguous canonical URLs and broken language switching.
 - **Don't read `Accept-Language` on the client.** It's server-only — `navigator.languages` can diverge from what the server saw and cause a hydration mismatch.
 - **Don't invent your own cookie name.** The kit and the resolver only agree on `voltro:lang` / `voltro:theme`.
+
+
+
+---
+
+<!-- source: en/i18n/formatting.md -->
+## Plurals & formatting
+
+_Locale-aware plural selection (CLDR via Intl.PluralRules) and Intl-backed formatters — plural, usePlural, useFormatDate, useRelativeTime, useFormatNumber, useFormatCurrency, useFormatters._
+
+Two things go wrong in every app that ships `useLocale()` but no formatters.
+
+The first is pluralization by string surgery: `` `${count} epic(s)` ``. That literal `(s)` is a guess that only reads as acceptable in English — and it isn't even correct there ("1 epic(s)"). Outside English and German it is simply wrong: Polish needs three forms for what English does with two, and no amount of parentheses expresses that.
+
+The second is relative time. "3 minutes ago" looks trivial, so it gets written inline — and then again in another component, and again with a date library, until one app carries four divergent helpers, one of them hardcoded German. They disagree on rounding, on the sub-second case, and on the language.
+
+`@voltro/i18n` closes both with `Intl`-backed primitives that resolve the **active** locale from the provider. Nothing to pin, nothing to hand-roll, and no dependency — `Intl.PluralRules` / `DateTimeFormat` / `NumberFormat` / `RelativeTimeFormat` are in every runtime the framework targets.
+
+## `plural` — the pure core
+
+```ts
+import { plural } from '@voltro/i18n'
+
+plural('en', 1, { one: '{count} epic', other: '{count} epics' })   // "1 epic"
+plural('en', 3, { one: '{count} epic', other: '{count} epics' })   // "3 epics"
+plural('en', 0, { one: '{count} epic', other: '{count} epics' })   // "0 epics"
+```
+
+`plural(locale, count, forms, options?)` selects the form using the locale's **real CLDR rules** via `Intl.PluralRules`, then substitutes every `{count}` occurrence. It takes the locale as an argument and touches no React, so it works in `meta({ locale })`, in a server handler, or in a test — the hook below is a thin binding of it.
+
+`forms` accepts `zero`, `one`, `two`, `few`, `many` and `other`. **Only `other` is required**: it is the fallback for every category the caller didn't supply and for every category a locale doesn't distinguish.
+
+### One/other is not enough — the Polish proof
+
+```ts
+const files = {
+  one:   '{count} plik',
+  few:   '{count} pliki',
+  many:  '{count} plików',
+  other: '{count} pliku',
+}
+
+plural('pl', 1, files)   // "1 plik"
+plural('pl', 3, files)   // "3 pliki"    → few
+plural('pl', 7, files)   // "7 plików"   → many
+```
+
+Polish distinguishes `few` (2–4) from `many` (5+). This is the exact case a hardcoded `(s)` or a hand-written `count === 1 ? a : b` cannot express — and it is not an exotic edge case, it is a language with 40 million speakers. Supply the categories the locale needs; the ones you omit fall through to `other`:
+
+```ts
+plural('pl', 3, { one: '{count} epic', other: '{count} epics' })   // "3 epics" — no `few` given
+```
+
+### Explicit zero
+
+```ts
+plural('en', 0, { one: '{count} epic', other: '{count} epics', zero: 'no epics' })   // "no epics"
+plural('en', 1, { one: '{count} epic', other: '{count} epics', zero: 'no epics' })   // "1 epic"
+```
+
+`zero` is honoured for an **exact 0** even in locales whose CLDR category for 0 is `other` (English). Apps overwhelmingly want "no items" there rather than "0 items", and opting out is just omitting the key.
+
+### Ordinals
+
+Pass `Intl.PluralRules` options through as the fourth argument:
+
+```ts
+const ord = { one: '{count}st', two: '{count}nd', few: '{count}rd', other: '{count}th' }
+
+plural('en', 1, ord, { type: 'ordinal' })   // "1st"
+plural('en', 2, ord, { type: 'ordinal' })   // "2nd"
+plural('en', 3, ord, { type: 'ordinal' })   // "3rd"
+plural('en', 4, ord, { type: 'ordinal' })   // "4th"
+```
+
+An unknown locale tag falls back to `other` instead of throwing — a stale cookie renders English-ish output, not a crash.
+
+## The hooks
+
+Every hook below reads the active locale from the provider via `useLocale()` and returns a stable callback.
+
+### `usePlural`
+
+`plural` bound to the active locale — same `(count, forms, options?)` signature minus the leading locale:
+
+```tsx
+import { usePlural } from '@voltro/i18n'
+
+function EpicCount({ count }: { readonly count: number }) {
+  const plural = usePlural()
+  return <span>{plural(count, { one: '{count} epic', other: '{count} epics', zero: 'no epics' })}</span>
+}
+```
+
+### `useFormatDate`
+
+```tsx
+const formatDate = useFormatDate()
+
+formatDate(order.createdAt, { dateStyle: 'medium' })
+formatDate(order.createdAt, { dateStyle: 'medium', timeStyle: 'short', timeZone: 'Europe/Berlin' })
+```
+
+`(value, options?) => string`, where `value` is a `Date`, a timestamp number, or a date string, and `options` is `Intl.DateTimeFormatOptions`. **Omit `timeZone` and the viewer's own zone is used** — which is what a multi-timezone app wants. Pass one only when the value genuinely belongs to a fixed zone (a store's opening hours, a scheduled broadcast). Pinning a global zone across the whole app is the anti-pattern this replaces.
+
+### `useRelativeTime`
+
+```tsx
+const relativeTime = useRelativeTime()
+
+relativeTime(comment.postedAt)                        // "3 minutes ago" / "vor 3 Minuten"
+relativeTime(job.runsAt)                              // "in 2 days"
+relativeTime(comment.postedAt, { numeric: 'always' }) // "1 day ago" instead of "yesterday"
+relativeTime(comment.postedAt, { now: renderedAt })   // measure against a fixed base
+```
+
+`(value, options?) => string`. Options are `Intl.RelativeTimeFormatOptions` plus a `now` override (a `Date`, number, or string) for deterministic rendering and tests; the default base is `Date.now()`.
+
+It picks the **largest unit that fits**, so a 90-minute delta reads "1 hour ago", not "90 minutes ago". Anything under a second renders through the `second` unit at 0 — "now" — which avoids the "0 seconds ago" flicker hand-rolled versions produce. `numeric: 'auto'` is the default, so English gets "yesterday" rather than "1 day ago".
+
+### `useFormatNumber` and `useFormatCurrency`
+
+```tsx
+const formatNumber = useFormatNumber()
+
+formatNumber(1234.5)                                        // "1,234.5" / "1.234,5"
+formatNumber(0.42, { style: 'percent' })                    // "42%"
+formatNumber(1_200_000, { notation: 'compact' })            // "1.2M"
+
+const formatEur = useFormatCurrency('EUR')
+
+formatEur(19.9)                                             // "€19.90" / "19,90 €"
+formatEur(19.9, { maximumFractionDigits: 0 })               // options merge over the currency defaults
+```
+
+`useFormatNumber()` is `(value, options?) => string` over `Intl.NumberFormatOptions`. `useFormatCurrency(currency)` takes the ISO code up front and applies `{ style: 'currency', currency }`; any options you pass are merged on top, so you can still override fraction digits or notation.
+
+Note that the currency **code** is not the locale — `useFormatCurrency('EUR')` renders `€19.90` for an English viewer and `19,90 €` for a German one. The amount's currency and the viewer's language are independent, and this keeps them that way.
+
+### `useFormatters`
+
+For a component that needs several at once, without stacking five hook calls:
+
+```tsx
+import { useFormatters } from '@voltro/i18n'
+
+function ActivityRow({ entry }: { readonly entry: Entry }) {
+  const { locale, formatDate, relativeTime, formatNumber, plural } = useFormatters()
+
+  return (
+    <li lang={locale}>
+      <time dateTime={entry.at.toISOString()} title={formatDate(entry.at, { dateStyle: 'full' })}>
+        {relativeTime(entry.at)}
+      </time>
+      {plural(entry.changes, { one: '{count} change', other: '{count} changes' })}
+      <span>{formatNumber(entry.score)}</span>
+    </li>
+  )
+}
+```
+
+It returns the active `locale` plus `formatDate`, `relativeTime`, `formatNumber` and `plural` — memoized together. Currency is not in the bundle because it needs its ISO code up front; call `useFormatCurrency(code)` alongside it when you need one.
+
+## Formatters vs. ICU in the catalog
+
+Both can pluralize, and they are not competitors — pick by where the string lives:
+
+- **ICU in the catalog** (`'{count, plural, one {# item} other {# items}}'`) is right when the whole sentence is translator-owned. Translators see the plural structure in their tool and can add the categories their language needs without a code change. This is the default for user-facing prose.
+- **`plural` / `usePlural`** is right when the forms are decided in code — a pure helper outside React, a `meta({ locale })` title, a test asserting CLDR behaviour, or a count rendered next to non-string content.
+
+For dates, numbers and relative time the hooks are the blessed path; reach for `react-intl`'s `<FormattedDate>` / `<FormattedNumber>` only when you want the JSX form.
+
+## Anti-patterns
+
+- **Don't write `(s)`, `count === 1 ? 'x' : 'xs'`, or a `+ 's'` suffix.** It is wrong in most languages and cannot be fixed by a translator. Use `plural` / `usePlural` or ICU in the catalog.
+- **Don't hand-roll "X minutes ago".** `useRelativeTime` is one hook, is localized, and handles the sub-second and unit-selection cases that inline versions get wrong.
+- **Don't pin a global `timeZone` / locale for the whole app.** The formatters resolve the active locale from the provider; a pin makes every viewer read the app in one user's settings.
+- **Don't pass a locale-formatted string to a machine consumer.** Formatted output is presentation — send ISO strings and raw numbers to APIs, `dateTime` attributes and sort keys.
+- **Don't format inside a `.map()` by constructing `Intl` objects yourself.** The hooks memoize per locale; a fresh `new Intl.NumberFormat(...)` per row is the slow path.

package/templates/agent-docs/observability.md

@@ -205,6 +205,15 @@ The same trace continuity flows to a vendor APM when you install a deep-observab
 
 See [Observability › Routing traces to a vendor](/docs/observability/overview#routing-traces-to-a-vendor) for the contribution surface + the sampler caveat.
 
+### "Missing peer" warnings on install (benign)
+
+`pnpm install` may print missing-peer warnings for `@opentelemetry/sdk-logs` and `@opentelemetry/sdk-trace-web` — these are **optional peers of `@effect/opentelemetry`** (pulled in transitively), used only if you export logs/browser traces to OTLP. Boot and the in-memory trace ring work **without** them, so the warnings are safe to ignore. To silence them, either add the two packages to your app, or add a pnpm rule:
+
+```json
+// package.json
+"pnpm": { "peerDependencyRules": { "ignoreMissing": ["@opentelemetry/sdk-logs", "@opentelemetry/sdk-trace-web"] } }
+```
+
 
 
 ---

package/templates/agent-docs/plugins.md

@@ -63,7 +63,7 @@ Status legend: ✓ shipped · ◐ partial · — planned.
 | `@voltro/plugin-auth` | ✓ | Full auth suite via `authRoutesPlugin()`: password (rehash-on-verify), sessions (multi-key rotation + sliding-window), magic-link + password-reset, passkeys/WebAuthn (atomic clone detection, BYO multi-replica challenge store), CSRF, session enumeration + revocation, memberships + switch-tenant, TOTP/MFA (sign-in enforcement + recovery codes); `authTables` schemas |
 | `@voltro/plugin-multitenancy` | ✓ | `tenant()` schema mixin (read-scope + write-fill) + `assertOwnTenant` guard + typed `TenantMismatch` |
 | `@voltro/plugin-soft-delete` | ✓ | `softDelete()` schema mixin — `deletedAt` / `deletedBy`; `delete` → UPDATE, `hardDelete()` bypass |
-| `@voltro/plugin-rbac` | ✓ | Roles compile to scopes + the `permission()` handler guard + typed `Forbidden` |
+| `@voltro/plugin-rbac` | ✓ | Roles compile to scopes + the `permission()` handler guard + typed `ScopeError` |
 | `@voltro/plugin-ratelimit` | ✓ | Per-endpoint / per-subject / per-tenant limits; sliding-window / fixed-window / token-bucket; memory / postgres / redis stores |
 | `@voltro/plugin-billing` | ✓ | Subscriptions, plans, entitlements + usage metering over a pluggable provider (Stripe + mock); seat-based billing + mid-cycle proration + dunning (failed-payment retries); `requireEntitlement()` guard + `enforce` interceptor; `/billing/webhook` via plugin-webhooks; money as integer minor units |
 | `@voltro/plugin-mail` | ✓ | Transactional email — Resend / Postmark / SendGrid / SES / Mailgun / SMTP, *.email.tsx templates, per-tenant suppression, send-time scheduling, bulk/batch send, per-send idempotency, durable via workflows |
@@ -214,7 +214,7 @@ error to the rpc layer.
 // Pre-only: short-circuit before the executor runs.
 const guard: RpcInterceptor = (next, ctx) =>
   ctx.tag.startsWith('admin.') && ctx.subject.type !== 'user'
-    ? Effect.fail(new Forbidden({ tag: ctx.tag }))
+    ? Effect.fail(new ScopeError({ required: 'user', message: ` is admin-only` }))
     : next
 
 // Post-only: tap the success/failure channels.