@voltro/cli 0.3.0 → 0.5.0

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.

package/templates/agent-docs/reference.md

@@ -21,10 +21,15 @@ The web side of a Voltro app talks to API apps through React hooks. Data hooks a
 | [`useMutation`](/docs/reference/hooks-data) | Run an atomic write (`*.mutation.ts`). |
 | [`useAction`](/docs/reference/hooks-data) | Run a unary non-transactional action (`*.action.ts`). |
 | [`useWorkflow`](/docs/reference/hooks-data) | Start, cancel, resume, or signal a durable workflow (`*.workflow.tsx`). |
+| [`useWorkflowSignal`](/docs/reference/hooks-data) | Focused signal sender, for approval buttons that don't also start workflows. |
+| [`useWorkflowUpdate`](/docs/reference/hooks-data) | Focused tracked update — waits for the workflow handler's result. |
 | [`useWorkflowRun`](/docs/reference/hooks-data) | Subscribe to one workflow run's reactive status row. |
 | [`useWorkflowRuns`](/docs/reference/hooks-data) | Subscribe to a bounded/filterable workflow run list. |
 | [`useWorkflowRunSteps`](/docs/reference/hooks-data) | Subscribe to one run's checkpointed step timeline. |
 | [`useWorkflowRunEvents`](/docs/reference/hooks-data) | Subscribe to one run's lifecycle/timer/signal event timeline. |
+| [`useWorkflowDomainEvents`](/docs/reference/hooks-data) | Subscribe to the domain events a workflow emitted (the business-event timeline). |
+| [`useWorkflowEventDeliveries`](/docs/reference/hooks-data) | Subscribe to delivery attempts/outcomes for those emitted events. |
+| [`useWorkflowRunState`](/docs/ui/reactive-components) | Aggregates run + steps + events into one `{ status, currentStep, waitingFor, … }` plus cancel/resume/signal/update. |
 | [`useAgentStream`](/docs/reference/hooks-data) | Consume a one-shot element stream (`*.stream.ts`). |
 | [`useAgent`](/docs/reference/hooks-data) | Convenience wrapper for transient AI streams. |
 
@@ -44,6 +49,51 @@ The web side of a Voltro app talks to API apps through React hooks. Data hooks a
 |---|---|
 | [`useServerRequest`](/docs/reference/hooks-server) | Request snapshot during SSR and hydration-sensitive client code. |
 
+## Schema-driven UI Hooks
+
+The headless primitives that derive UI from a descriptor's Schema. **Reach for
+these before hand-rolling a form, a table, or a picker** — full guide in
+[Schema-driven UI](/docs/ui/overview).
+
+| Hook | Purpose |
+|---|---|
+| [`useFormBinding`](/docs/ui/forms-and-tables) | Bind a form to a MUTATION — fields + validation from its input Schema; a server `ValidationError({ field })` routes to that field. |
+| [`useDataTable`](/docs/ui/forms-and-tables) | Bind a table to a QUERY — live rows, columns derived from the output Schema, sort/filter/pagination. |
+| [`useQueryFilters`](/docs/ui/forms-and-tables) | Filter controls derived from a query's INPUT Schema (the read-side mirror of a form). |
+| [`useQueryField`](/docs/ui/forms-and-tables) | Query-bound picker — a debounced search term drives a live subscription. |
+| [`useFormSkeleton`](/docs/ui/client-utilities/use-skeletons) / [`useTableSkeleton`](/docs/ui/client-utilities/use-skeletons) | Placeholders shaped like the REAL data, from the same Schema. |
+| [`useAsyncValidation`](/docs/ui/client-utilities/use-async-validation) | Live server-side validation (uniqueness, cross-row) over a query binding. |
+| [`useDebounced`](/docs/ui/client-utilities/use-debounced) | Debounce a value (search, filter, validation input). |
+| [`useRecord`](/docs/ui/client-utilities/use-record) | One live record from a "get" query, normalized (array → first row). |
+
+## Files, Permissions, and Client Utilities
+
+| Hook | Purpose |
+|---|---|
+| [`useUpload`](/docs/plugins/storage) | File upload with progress + cancel, on every storage provider. Not base64 → action. |
+| [`useCan`](/docs/ui/client-utilities/use-can) | Scope/RBAC UI gate, over `<PermissionProvider>`. Lives in `@voltro/client` — scopes are a framework concept, so gating a button needs no rbac dependency. |
+| [`useCanAny`](/docs/ui/client-utilities/use-permissions) | OR variant of `useCan` — true when the subject holds AT LEAST ONE of the required scopes. |
+| [`usePermissions`](/docs/ui/client-utilities/use-permissions) / `<PermissionProvider>` | The current subject's scope set, fed once from your session query — the source `useCan` reads. Gates UI on the SAME scope strings the server checks. |
+| [`useResourceCan`](/docs/ui/client-utilities/use-permissions) / `useResourceCans` | Per-RESOURCE (ReBAC) gate, reactive — one resource or many in a single subscription. |
+| [`useDerived`](/docs/ui/client-utilities/use-derived) | Dependency-tracked derived value from reactive sources. Replaces hand-maintained `useMemo` dep arrays. |
+| [`useWindowedSubscription`](/docs/ui/client-utilities/use-windowed-subscription) | Subscribe to the VISIBLE window of a huge list, not the whole table. |
+| [`useOutbox`](/docs/ui/client-utilities/use-outbox) | Queue mutations offline, replay in order on reconnect. |
+| [`useUndoLog`](/docs/ui/client-utilities/use-undo) / `useUndo` | Client controller for the server-persisted undo stack. |
+| [`usePreview`](/docs/ui/client-utilities/use-preview) | Mutation dry-run — run the real handler in a rolled-back transaction. |
+| [`useProvenance`](/docs/ui/client-utilities/use-provenance) | "Why is this value here?" — lineage lookup for a field. |
+| [`useOnRpcError`](/docs/ui/client-utilities/use-on-rpc-error) / `reportClientError` | Subscribe to the rpc error bus; report a client error to the server. |
+| [`useTracking`](/docs/ui/client-utilities/use-tracking) | Fire mount/unmount + interaction tracking events. |
+| [`useCapabilityManifest`](/docs/ui/client-utilities/use-capability-manifest) | The api's capability manifest (procedures + tables + schemas), fetched once. |
+| [`useRefreshSubscriptions`](/docs/ui/client-utilities/use-refresh-subscriptions) | Force-refresh live subscriptions (e.g. after an out-of-band change). |
+
+## AI Hooks
+
+| Hook | Purpose |
+|---|---|
+| [`useAgentChat`](/docs/ui/reactive-components) | Full chat surface over an `*.agent.tsx` (messages + send + streaming). |
+| [`useResumableAgentStream`](/docs/ai/streaming) | Agent stream that survives reload/reconnect. |
+| [`useDataCopilot`](/docs/ai/data-copilot) | Bind a data-copilot action by api name + tag. |
+
 ## Where To Read Next
 
 - [Data hooks](/docs/reference/hooks-data)
@@ -255,6 +305,32 @@ Events include lifecycle changes, timers, signals, and updates recorded by the w
 
 `useWorkflowEvents(apiName, runId)` is a shorter alias for the same hook.
 
+## `useWorkflowDomainEvents(apiName, filters?, options?)`
+
+Subscribes to the **domain events** an app emitted through `ctx.events.emit(...)` — the business-event log behind [event triggers](/docs/workflows/event-triggers), not one run's internal timeline.
+
+```tsx
+const { events } = useWorkflowDomainEvents('app', { name: 'order.paid', limit: 50 })
+```
+
+Both filters are optional: `name` narrows to one event name, `limit` defaults to `100` and is clamped to `500` by the server. Rows arrive newest-first (by `occurredAt`), and each carries `id`, `name`, `payload`, `source`, `subject`, `traceId`, and `occurredAt`. The third argument is the standard `SubscriptionOptions` (e.g. `{ skip }`).
+
+Alongside `events`, the hook returns the normal subscription fields (`data`, `error`, `revision`, …).
+
+## `useWorkflowEventDeliveries(apiName, eventId)`
+
+Subscribes to the **fan-out** of one emitted domain event: one row per trigger the event was routed to, so you can see which workflows a single `emit(...)` actually started.
+
+```tsx
+const { deliveries } = useWorkflowEventDeliveries('app', selectedEvent?.id)
+
+deliveries.map((d) => `${d.workflowName}: ${d.status}`)
+```
+
+The subscription is skipped while `eventId` is `undefined`, so it pairs directly with a row selected out of `useWorkflowDomainEvents`. Rows are ordered oldest-first and carry `eventId`, `eventName`, `triggerId`, `workflowName`, `executionId`, `idempotencyKey`, `skipped`, `errorMessage`, `createdAt`, `completedAt`, and a `status` of `'starting'`, `'started'`, `'skipped'`, or `'failed'`.
+
+A `skipped` delivery is the normal outcome when a trigger's `filter` returned false or its `idempotencyKey` had already been seen — it is not a failure. `errorMessage` is set only on `'failed'`.
+
 ## `useAgentStream(apiName, rpcTag)`
 
 Consumes a `defineStream` RPC. Despite the name, this hook is not limited to AI agents; it handles any one-shot element stream.
@@ -735,8 +811,42 @@ await ctx.store.delete('notes', noteId)
 const rows = await ctx.store.query(database.notes.descriptor)
 ```
 
+`ctx.store.query` returns the row type the builder already knew — `database.notes`
+resolves to that table's row, so `rows[0].title` is a `string` with no cast. A
+hand-built descriptor still resolves to the untyped `Row`.
+
 Mutations receive a transactional store view. Actions and streams receive a normal store view; writes from them are not automatically rolled back as one unit.
 
+## `ctx.load` / `ctx.loadMany` — request-scoped batching
+
+`relations()` + `.with()` is the right answer whenever the shape of the related
+data is known statically: it compiles to ONE query. Reach for it first.
+
+This is for the case it cannot express — assembly whose shape depends on the
+DATA. A breadth-first walk over a tree is the canonical example: each level's
+ids come from the level above, so no declarative relation spec covers it, and
+the natural code is one query per node.
+
+```ts
+let level = [await ctx.load('nodes', rootId)]
+while (level.length > 0) {
+  const childIds = level.flatMap((n) => n?.childIds ?? [])
+  if (childIds.length === 0) break
+  level = [...await ctx.loadMany('nodes', childIds)]
+}
+```
+
+Every `load` issued in the same tick for the same table is coalesced into one
+`WHERE id IN (...)`, so that walk costs one query per LEVEL, not per node.
+Repeated ids — a diamond where two parents share a child — are fetched once.
+A missing row is `null` rather than a throw, because a dangling edge in a graph
+walk is usually data; use `.one()` when absence is an error.
+
+The cache lives exactly as long as the request. That is a correctness
+requirement, not a tuning choice: a longer-lived cache would serve one
+subject's rows to another (a data-isolation bug on a tenant-scoped store) and
+would go stale across a mutation in the same request.
+
 ## `ctx.cache`
 
 Async cache facade for request handlers: