npm - @voltro/cli - Versions diffs - 0.2.2 → 0.4.0 - Mend

@voltro/cli 0.2.2 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (77) hide show

package/CHANGELOG.md +49 -0
package/THIRD-PARTY-NOTICES.md +234 -1
package/bin/voltro.mjs +71 -1
package/dist/apiBuild-CvtQeBMs.js +190 -0
package/dist/apiBuild-DQBNqNZ8.js +2 -0
package/dist/bin.js +2 -2
package/dist/{commands-DQy4812j.js → commands-DhyBIs1O.js} +2381 -1768
package/dist/{dev--jHe1vcu.js → dev-CQxbrpDz.js} +1677 -1626
package/dist/dev-DYjGqPGD.js +2 -0
package/dist/index.d.ts +2 -0
package/dist/index.js +1 -1
package/dist/serveCommand-BZzUJIyo.js +1077 -0
package/dist/serveEntry.js +2 -2
package/package.json +22 -19
package/templates/AGENTS.core.md +61 -0
package/templates/AGENTS.md +61 -0
package/templates/agent-docs/_manifest.json +4 -4
package/templates/agent-docs/ai.md +28 -0
package/templates/agent-docs/authentication.md +5 -2
package/templates/agent-docs/cli.md +98 -0
package/templates/agent-docs/data.md +193 -3
package/templates/agent-docs/database/advancedqueries.md +29 -0
package/templates/agent-docs/database/querying.md +2 -0
package/templates/agent-docs/deployment.md +3 -1
package/templates/agent-docs/internationalization.md +237 -2
package/templates/agent-docs/observability.md +9 -0
package/templates/agent-docs/plugins.md +2 -2
package/templates/agent-docs/reference.md +76 -0
package/templates/agent-docs/schema-driven-ui.md +551 -2
package/templates/agent-docs/templates/apibackends.md +10 -8
package/templates/agent-docs/templates/overview.md +1 -1
package/templates/agent-docs/testing.md +177 -3
package/templates/apps/api-ai/package.json +7 -7
package/templates/apps/api-auth/package.json +8 -8
package/templates/apps/api-backend/package.json +7 -7
package/templates/apps/api-backend-deactivation/package.json +7 -7
package/templates/apps/api-backend-mail/package.json +8 -8
package/templates/apps/api-backend-mariadb/package.json +9 -9
package/templates/apps/api-backend-storage/package.json +8 -8
package/templates/apps/api-data-advanced/package.json +8 -8
package/templates/apps/api-durable/package.json +8 -8
package/templates/apps/api-feature-flags/package.json +9 -9
package/templates/apps/api-governance/package.json +8 -8
package/templates/apps/api-kv/package.json +8 -8
package/templates/apps/api-moderation/package.json +8 -8
package/templates/apps/api-observability/package.json +8 -8
package/templates/apps/api-ratelimit/package.json +8 -8
package/templates/apps/api-rbac/README.md +9 -4
package/templates/apps/api-rbac/mutations/notes.create.mutation.server.ts +1 -1
package/templates/apps/api-rbac/mutations/notes.create.mutation.ts +6 -6
package/templates/apps/api-rbac/package.json +8 -8
package/templates/apps/api-rbac/tests/notes.create.test.ts +8 -8
package/templates/apps/api-rest/package.json +7 -7
package/templates/apps/api-saas/package.json +11 -11
package/templates/apps/api-search/package.json +8 -8
package/templates/apps/api-versioning/package.json +8 -8
package/templates/apps/api-webhooks/package.json +8 -8
package/templates/apps/changelog/package.json +6 -6
package/templates/apps/edge-functions/package.json +2 -2
package/templates/apps/frontend-admin/package.json +8 -8
package/templates/apps/frontend-app/package.json +8 -8
package/templates/apps/frontend-blank/package.json +7 -7
package/templates/apps/frontend-contact/package.json +7 -7
package/templates/apps/frontend-dashboard/package.json +7 -7
package/templates/apps/frontend-docs/package.json +7 -7
package/templates/apps/frontend-i18n/package.json +6 -6
package/templates/apps/frontend-landing/package.json +7 -7
package/templates/apps/frontend-spa/package.json +7 -7
package/templates/apps/frontend-ssr/package.json +7 -7
package/templates/apps/frontend-ssr-api/package.json +8 -8
package/templates/apps/frontend-static-blog/package.json +6 -6
package/templates/baselines/compose/docker/api.Dockerfile +10 -5
package/templates/baselines/compose-mariadb/docker/api.Dockerfile +10 -5
package/dist/apiBuild-OpZROja5.js +0 -2
package/dist/apiBuild-o70rjpVJ.js +0 -184
package/dist/dev-BKkZglQV.js +0 -2
package/dist/serveCommand-93rRdEp0.js +0 -1077

package/templates/agent-docs/schema-driven-ui.md CHANGED Viewed

@@ -378,6 +378,37 @@ permissions). Don't hand-wire `useResumableAgentStream` + a bubble list for a
 standard chat — `<AgentChat>` is the supported path; reach for the resumable
 hook directly only for a TRANSIENT (non-persisted) run over a `*.stream.ts`.
+### `useAgentChat(apiName, agent, { threadId })`
+The headless core `<AgentChat>` renders over. It opens no transport of its own —
+it composes the agent's SYNTHESIZED pair: a `useSubscription` on
+`<agent>.messages` (the persisted thread, including the live `streaming: true`
+row) plus a `useAction` on `<agent>.send`. Because the feed is a reactive query,
+reconnect- and reload-survival come for free.
+```tsx
+const chat = useAgentChat('app', 'support', { threadId })
+await chat.send('Where is my order?')
+await chat.send('Retry', { locale: 'en' })   // extra fields merge into the send input
+chat.regenerate()                            // re-run the last user prompt
+```
+| Field | Meaning |
+|---|---|
+| `messages` | The thread, sorted by `order` then `stepOrder`. Each message has `id`, `role`, `content`, `streaming`, and the persisted `parts`. |
+| `streaming` | `true` while any message row is still being written. |
+| `loading` | `true` until the first snapshot arrives. |
+| `error` | The subscription error, or the last send failure. |
+| `send(prompt, extra?)` | Appends the user turn and drives the assistant turn. |
+| `regenerate()` | Re-sends the last user prompt as a fresh turn; `undefined` if there is none. |
+| `sending` | `true` while a `send` is in flight. |
+`threadId` is required — mint one per chat (a `useRef`'d uuid) and keep it stable
+across renders, since it is the subscription key for the whole thread. Render
+from `message.parts` (text / reasoning / tool / source / file) rather than
+`content` so a reloaded thread and a live one look identical.
 ---
@@ -392,7 +423,7 @@ source of truth, no separate frontend permission list. Feed the subject's scopes
 (from your session query) to `<PermissionProvider>`; `useCan` reads them.
 ```tsx
-import { PermissionProvider, useCan } from '@voltro/web'
+import { PermissionProvider, useCan } from '@voltro/client'
 <PermissionProvider scopes={session.scopes}>…</PermissionProvider>
 const canDelete = useCan('todos:delete')   // ADMIN bypasses; deny-by-default
@@ -401,6 +432,10 @@ const canDelete = useCan('todos:delete')   // ADMIN bypasses; deny-by-default
 UX only — the server still enforces. Pairs with `<AutoForm>` / `<DataTable>` to
 auto-hide actions the subject can't perform.
+The scope set itself, the `canCall` matcher, the OR variant (`useCanAny` /
+`canCallAny`), and the per-RESOURCE gates (`useResourceCan` / `useResourceCans`)
+are in [usePermissions](/docs/ui/client-utilities/use-permissions).
 ---
@@ -469,7 +504,7 @@ _Live read-only detail view for one record plus its eager-loaded relations._
 The read counterpart to `<AutoForm>`: a live detail view for one record + its
 eager-loaded relations (scalars → a definition list; arrays → nested tables).
-`useRecord('app', 'users.get', { id })` is the headless core.
+[`useRecord`](/docs/ui/client-utilities/use-record) is the headless core.
 ```tsx
 import { RecordView } from '@voltro/web'
@@ -605,3 +640,517 @@ const w = useWindowedSubscription('app', 'rows.list', { rowHeight: 32, viewportH
   <div style={{ height: w.bottomSpacer }} />
 </div>
 ```
+---
+<!-- source: en/ui/client-utilities/use-theme.md -->
+## useTheme
+_Read and set the app theme through the same cookie and class the pre-paint script owns._
+With `theme: 'system'` the framework already emits a `<head>` script that reads
+the `voltro:theme` cookie (falling back to `prefers-color-scheme`) and toggles
+`.dark` on `<html>` before first paint. What was missing was the in-app
+switcher — so apps layered a second theme system on top, and then two writers
+raced on one `class` attribute: a flash on navigation, and a stored preference
+that disagreed with the rendered class. `useTheme` is that switcher, reading and
+writing exactly the cookie and class the pre-paint script already uses.
+```tsx
+import { useTheme } from '@voltro/web'
+const { theme, resolvedTheme, setTheme } = useTheme()
+<button onClick={() => setTheme(resolvedTheme === 'dark' ? 'light' : 'dark')}>
+```
+`theme` is the stored preference — `'light' | 'dark' | 'system'`, where
+`'system'` means no explicit choice. `resolvedTheme` is what is actually applied
+right now (`'light' | 'dark'`), resolving `'system'` against `matchMedia`, and
+it stays live when the OS flips. `setTheme` persists the cookie and applies the
+class immediately; `setTheme('system')` clears the cookie and falls back to the
+OS.
+Requires `theme: 'system'` in the web `app.config.ts` — that is what emits the
+pre-paint script. Do not also install a third-party theme provider.
+---
+<!-- source: en/ui/client-utilities/use-connection-status.md -->
+## useConnectionStatus
+_One honest signal for whether the server is reachable — derived, never polled._
+Connection health from the two signals the client genuinely has, so apps stop
+hand-rolling a degraded-connection state machine in an auth provider.
+```tsx
+import { useConnectionStatus } from '@voltro/client'
+const { status, reportSuccess } = useConnectionStatus('app')
+{status !== 'connected' && <OfflineBanner status={status} />}
+```
+`status` is `'connected' | 'degraded' | 'offline'`. `offline` is browser-reported
+(`navigator.onLine` plus its `online` / `offline` events) — reliable for "the
+network is gone", and it wins over `degraded`. `degraded` means an rpc on that
+api failed and nothing has succeeded since; it is real evidence, not a guess.
+Coming back online clears the failure count, since failures counted during an
+offline window *are* that window. `reportSuccess()` clears it eagerly from a
+place that knows a call went through.
+Also returned: `online`, `failureCount`, `lastFailureAt`. There is deliberately
+no polling ping — the framework does not call the server just to colour an
+indicator, so `connected` means "nothing has failed", not "just verified".
+---
+<!-- source: en/ui/client-utilities/use-debounced.md -->
+## useDebounced
+_Delay a value until typing stops — the one debounce the framework's own bindings use._
+Every app that has a search box eventually writes the same six lines: a
+`useState`, a `useEffect`, a `setTimeout`, and a cleanup that clears it. Get the
+cleanup wrong and stale timers fire after unmount; get the dependency array
+wrong and the timer never restarts. `useDebounced` is that snippet, written
+once. `useAsyncValidation` and `useQueryField` are built on it, so a debounced
+subscription in your code behaves exactly like the framework's own.
+```tsx
+import { useDebounced } from '@voltro/client'
+const [term, setTerm] = useState('')
+const debouncedTerm = useDebounced(term, 300)
+const results = useSubscription('app', 'todos.search', { term: debouncedTerm })
+```
+The whole API is `useDebounced(value, ms = 300)`. There is no options object —
+no leading edge, no `maxWait`, no `flush()` or `cancel()`. It is a trailing-edge
+debounce and nothing else. If you need one of those, you need a different
+primitive, not a flag on this one.
+It is generic over the value, not limited to strings: `useDebounced(filters)`
+over an object works the same way.
+## Two behaviours worth knowing before you use it
+**The first value is not delayed.** The internal state is seeded with `value` on
+the very first render, so the initial value is returned synchronously — including
+during SSR, where no timer ever fires. Only *changes* wait for the quiet window.
+That is what you want (no empty first paint), but it means you cannot use the
+"debounced value hasn't caught up yet" trick to detect the initial render.
+Comparing the two is how you detect *pending* input, which is exactly what
+`useAsyncValidation` does internally to show its `checking` state:
+```tsx
+const settling = term !== debouncedTerm
+```
+**The value is compared by identity.** `value` and `ms` are the effect's
+dependencies, so a value that is a fresh object or array on every render
+restarts the timer on every render. Pass primitives, or memoize:
+```tsx
+const filters = useMemo(() => ({ status, assignee }), [status, assignee])
+const debouncedFilters = useDebounced(filters, 300)
+```
+Changing `ms` restarts the quiet window too, for the same reason — so derive the
+delay from something stable rather than recomputing it inline.
+---
+<!-- source: en/ui/client-utilities/use-skeletons.md -->
+## useFormSkeleton & useTableSkeleton
+_Loading placeholders shaped like the real data — field and column descriptors from the same Schema the real UI uses._
+A generic spinner tells the user nothing and reserves no space, so the layout
+jumps the moment data arrives. The usual fix is to hand-write a placeholder with
+"about four grey bars" — which then silently drifts from the form it is standing
+in for. These two hooks remove that guesswork: the descriptor's Schema already
+knows exactly how many fields the form will render and which columns the table
+will have, *before* any data is fetched. Same source as `<AutoForm>` and
+`<DataTable>`, so the placeholder and the real UI cannot disagree.
+```tsx
+import { useFormSkeleton, useTableSkeleton } from '@voltro/client'
+const fields = useFormSkeleton('app', 'todos.create')   // mutation INPUT Schema
+const columns = useTableSkeleton('app', 'todos.list')   // query OUTPUT Schema
+```
+Both take `(apiName, tag)` and return a `ReadonlyArray<FieldDescriptor>`. That
+is the whole signature — there are no options.
+## Reach for the component first
+Most of the time you do not need these hooks at all — `@voltro/ui` ships
+`<FormSkeleton>` and `<TableSkeleton>`, which call them for you:
+```tsx
+import { FormSkeleton, TableSkeleton } from '@voltro/ui'
+{loading ? <FormSkeleton api="app" mutation="todos.create" /> : <AutoForm api="app" mutation="todos.create" />}
+{loading ? <TableSkeleton api="app" query="todos.list" rows={5} /> : <DataTable api="app" query="todos.list" />}
+```
+Both accept a fallback count for the moment the descriptor is not resolvable yet
+(`fallbackFields`, default 3; `fallbackColumns`, default 4), and both mark
+themselves `aria-busy` + `aria-hidden` so a screen reader never announces the
+placeholder bars.
+The hooks are the headless layer underneath. Reach for them when the shipped
+markup does not fit your design system and you want to render the placeholder
+yourself:
+```tsx
+{loading
+  ? fields.map((f) => <div key={f.name} className="h-10 animate-pulse rounded bg-muted" />)
+  : <AutoForm api="app" mutation="todos.create" />}
+```
+Each `FieldDescriptor` carries `name`, `label` (the humanised property name),
+`widget` (`'text' | 'textarea' | 'number' | 'checkbox' | 'switch' | 'select' |
+'radio' | 'async-select' | 'multi-select' | 'date' | 'datetime' | 'daterange' |
+…`), `required`, `nullable`, an optional `options` array for closed value sets,
+and the resolved `jsonSchema` node. `widget` is what makes the placeholder
+faithful — a `textarea` deserves a taller bar than a `checkbox`.
+## Three things that will surprise you
+**They know nothing about loading.** Neither hook subscribes to anything or
+tracks a request; they read a Schema. The `loading` flag in the example above is
+yours — from the `useSubscription` / `useMutation` whose data you are waiting
+on. They are cheap and synchronous, and they work during SSR, which is why the
+shape is correct on the very first paint.
+**An unknown tag returns `[]`, silently.** A typo in the api name or the tag
+produces an empty array, not an error — so a skeleton that renders nothing is
+almost always a misspelled tag, not a Schema the hooks failed to read.
+**Neither hook checks the descriptor's kind.** `useFormSkeleton` reads the
+descriptor's `input`; `useTableSkeleton` reads its `output`. Pass a query tag to
+`useFormSkeleton` and you get that query's input fields — useful for a filter
+panel's skeleton, but it means nothing stops you from pairing the wrong hook
+with the wrong tag. `useTableSkeleton` additionally returns `[]` unless the
+output Schema is an array of objects.
+The labels are humanised property names, not the Schema `title` annotation —
+built-in refinements carry a type-name title (`nonEmptyString`) that would leak
+into the UI. That matches what `<AutoForm>` renders, so the placeholder's label
+widths line up with the real ones.
+---
+<!-- source: en/ui/client-utilities/use-capability-manifest.md -->
+## useCapabilityManifest
+_Read the api's capability manifest (procedures + tables + schemas) from the browser, without codegen._
+What does this api actually expose? `useCapabilityManifest` answers that at
+runtime: a **one-shot fetch** of `/_voltro/inspect/manifest` — the same inspect
+surface [`useProvenance`](/docs/ui/client-utilities/use-provenance) rides. It is
+a structural lookup, not a live subscription, so it does not re-fetch on data
+changes.
+```tsx
+import { useCapabilityManifest } from '@voltro/client'
+const { manifest, loading, error } = useCapabilityManifest('app')
+```
+The manifest carries:
+| Field | Contents |
+|---|---|
+| `procedures` | Every procedure's `tag`, `kind`, `input`/`output` Schema, plus the `source` table a query reads and the `targets` (`{ table, op }`) a mutation writes. |
+| `tables` | The user tables — `name`, `columns` (`type`, `nullable`, `refersTo`, `enum`), and whether the table is `reactive`. Framework `_voltro_*` tables are flagged `framework`. |
+| `workflows` | The discovered workflow names. |
+| `widgets` | The registered widget ids. |
+| `version` | The manifest format version. |
+## Deriving an admin surface
+`deriveEntityAdmins(manifest)` is the pure projection the [admin
+template](/docs/templates/admin) is built on. It joins each user table to the
+procedures that read and write it, so a generated back-office binds to tags that
+**actually exist** instead of guessing them from a naming convention:
+```tsx
+import { useCapabilityManifest, deriveEntityAdmins } from '@voltro/client'
+const { manifest } = useCapabilityManifest('app')
+const entities = manifest ? deriveEntityAdmins(manifest) : []
+// each: { table, columns, reactive, listTag?, createTag?, updateTag?, deleteTag?,
+//         createScope, writeScope, deleteScope }
+```
+A tag is `undefined` when the app exposes no procedure for that operation — render
+that affordance read-only rather than binding to a tag that does not resolve. The
+`*Scope` strings are the conventional names the UI gates writes on via
+[`useCan`](/docs/ui/client-utilities/use-can); map them to your app's real RBAC
+scopes.
+The inspect surface is open in dev. When a deploy sets an inspect token the
+manifest GET is bearer-gated, so an admin UI pointed at a locked-down api has to
+supply that token — a deployment concern, not something this hook handles.
+---
+<!-- source: en/ui/client-utilities/use-permissions.md -->
+## usePermissions
+_The scope set useCan reads, plus the reactive per-resource gates scopes cannot express._
+[`useCan`](/docs/ui/client-utilities/use-can) is only a matcher — it needs a
+scope set to match against. `<PermissionProvider>` supplies it and
+`usePermissions` reads it, so the whole app gates on one reactive source instead
+of each component fetching the session again.
+## PermissionProvider / usePermissions
+```tsx
+import { PermissionProvider, usePermissions, canCall, ADMIN_SCOPE } from '@voltro/client'
+<PermissionProvider scopes={session.scopes}>…</PermissionProvider>
+const { scopes } = usePermissions()   // ReadonlyArray<string>
+```
+`<PermissionProvider>` takes exactly `scopes` and `children`. Mount it once high
+in the tree, fed by your session subscription — scopes are ordinary reactive
+data, so a role change re-renders every gate.
+With no provider above it, `usePermissions()` returns `{ scopes: [] }`, which
+makes `useCan` deny. That is the deliberate default: a missing provider hides
+affordances rather than revealing them.
+`canCall(subjectScopes, required)` is the same matcher as a plain function, for
+loaders and route guards that are not components. `required` as an array means
+ALL of them (AND); `ADMIN_SCOPE` (`'admin:full'`) satisfies anything; an empty
+requirement always passes.
+## useCanAny / canCallAny
+`useCan` with an array demands ALL of the scopes. `useCanAny` is the OR variant —
+true when the subject holds AT LEAST ONE. Use it for "this section is visible to
+editors OR reviewers" affordances.
+```tsx
+import { useCanAny, canCallAny } from '@voltro/client'
+const canReview = useCanAny(['notes:edit', 'notes:review'])
+```
+`canCallAny(subjectScopes, required)` is the same OR check as a plain function,
+matching `canCall`. `ADMIN_SCOPE` satisfies it, and an empty requirement passes —
+nothing is being demanded.
+`@voltro/client` is the one place these live. Scopes are a framework concept —
+`@voltro/protocol` owns `ScopeError`, `guards: [{ scope }]` and `ctx.access` —
+and [rbac](/docs/plugins/rbac) is only ONE way to produce them; an app can
+register its own `setResourceScopeResolver` over its own tables instead. These
+hooks CONSUME scopes, so they must not drag in a plugin that PRODUCES them.
+## useResourceCan / useResourceCans
+Scopes answer "may this subject delete todos". They cannot answer "may this
+subject delete **todo 42**" — that depends on relation tuples only the server
+holds. These two hooks ask the server, reactively.
+```tsx
+import { useResourceCan, useResourceCans } from '@voltro/client'
+const { allowed, pending } = useResourceCan('app', 'docs.can', {
+  action: 'write', resourceType: 'doc', resourceId: id,
+})
+const { allowedIds } = useResourceCans('app', 'docs.canMany', {
+  action: 'delete', resourceType: 'doc', resourceIds,
+})
+<DataTable … rowActions={(r) => allowedIds.has(r.id) ? <DeleteBtn id={r.id} /> : null} />
+```
+Both take `(apiName, rpcTag, input, options?)`, where `options` is the ordinary
+[`SubscriptionOptions`](/docs/reference/hooks-data) (`skip`, `fallback`) — they are thin
+projections over `useSubscription`. You bind them to a server query whose source
+is the ReBAC tuple table, returning `{ allowed }` or `{ allowedIds }`; because
+that source is reactive, a revoke re-runs `can()` server-side and the button
+disables with no refetch.
+`useResourceCan` returns `{ allowed: boolean, pending: boolean }` —
+`allowed` is a real boolean that starts `false` and stays `false` while
+`pending`, never `undefined`. `useResourceCans` returns
+`{ allowedIds: ReadonlySet<string>, pending: boolean }`; an id absent from the
+set is denied. Both fail closed.
+All of this hides affordances. The server still enforces every call through the
+same `can()` engine — see
+[Authorization](/docs/authentication/authorization).
+---
+<!-- source: en/ui/client-utilities/use-on-rpc-error.md -->
+## useOnRpcError
+_One place to react to rpc failures that are nobody's local problem — auth loss, telemetry, toasts._
+Some failures do not belong to the component that triggered them. An
+`Unauthenticated` error means the session is gone, whatever screen you happen to
+be on. Rather than repeat that check in every `useMutation` call site, each api's
+runtime carries an error bus; this hook subscribes to it with React lifecycle.
+```tsx
+import { useOnRpcError, errorTag } from '@voltro/client'
+useOnRpcError('app', useCallback((e) => {
+  if (errorTag(e.error) === 'Unauthenticated') redirectToSignIn()
+}, []))
+```
+The event is `{ source, tag, error, traceId? }`. `source` is
+`'mutation' | 'action' | 'subscription'`, so both unary calls and stream
+failures arrive here. `error` is the raw value — a `Schema.TaggedError`, a plain
+`Error`, or anything else that was thrown; `errorTag(err)` reads `_tag` off
+tagged errors and returns `undefined` otherwise. `traceId` is the same id the
+server logged, so a handler can point at `voltro logs --trace <id>`.
+Two things to know. The hook re-subscribes whenever the listener **reference**
+changes, so define it with `useCallback` or at module scope unless you want that.
+And the bus is per api runtime — an app talking to several apis subscribes once
+per api name.
+This is the read side of failures that already happened on the wire. To push a
+client-side error the server never saw, call `reportClientError(error, context)`
+instead. Note also that a subscription failure *after* data arrived reaches only
+this bus, never the hook's `error` field — see
+[Queries](/docs/data/queries).
+---
+<!-- source: en/ui/client-utilities/use-refresh-subscriptions.md -->
+## useRefreshSubscriptions
+_Re-issue every live subscription after the connection's subject changes — no reload, no reconnect._
+When a user signs in, the server rebinds the subject on the *existing*
+connection. Every open subscription is now snapshotting against the wrong
+subject's tenant scope. Reloading the page would fix it and lose everything else;
+this hook is the surgical version.
+```tsx
+import { useRefreshSubscriptions } from '@voltro/client'
+const refresh = useRefreshSubscriptions('app')
+await signIn(...)
+refresh()
+```
+It returns a stable zero-argument function. Calling it interrupts each active
+subscription's fiber and re-forks it over the **same** WebSocket — no reconnect.
+Server-side each one is a fresh subscription, so it flows through the auth
+middleware again and resolves the new subject.
+Optimistic patches survive the refresh: they are tied to mutation lifecycles, not
+subscription lifecycles, and the new snapshots land underneath them.
+This is not a cache-invalidation tool. Subscriptions are already live, so a
+normal write needs no refresh — reach for this only when the *connection's
+identity* changed underneath them.
+---
+<!-- source: en/ui/client-utilities/use-tracking.md -->
+## useTracking
+_A declarative event map next to a component instead of track() calls sprinkled through handlers._
+Imperative `track()` calls rot: they live inside handlers, get forgotten on the
+new code path, and vanish in a refactor. `useTracking` moves the instrumentation
+into one declarative map beside the component, so what a component reports is
+readable in a single place.
+```tsx
+import { defineTracking, useTracking } from '@voltro/client'
+const spec = defineTracking('CheckoutButton', {
+  onMount: 'checkout.viewed',
+  onClick: (props) => ({ event: 'checkout.started', plan: props.plan }),
+})
+const CheckoutButton = (props) => {
+  const tracked = useTracking(spec, props, sink)
+  return <button {...tracked}>Checkout</button>
+}
+```
+`useTracking(spec, props, sink)` returns a **copy of your props** with every
+callback the map names wrapped, so invoking `onClick` fires its event and then
+calls your original handler. Spread the returned props; nothing is mutated.
+In the map, `onMount` and `onUnmount` are lifecycle — they fire from an effect,
+once per mount, and are never wrapped as props. Every other key is the name of a
+callback prop to wrap. An entry is either a bare event name or a function of the
+props returning `{ event, ...payload }`.
+The `sink` is yours to provide: `(event: TrackingEvent) => void`. The kernel is
+transport-agnostic — it does not know where events go, which is also what makes
+it testable with a recorder.
+`resolveTrackingEvent(entry, props)` and `wrapTrackedCallbacks(spec, props, sink)`
+are exported as pure functions if you need the behaviour outside a component.
+For a typed, validated event taxonomy on top of the same sink, see the
+[Analytics catalog](/docs/ui/client-utilities/analytics-catalog).
+---
+<!-- source: en/ui/client-utilities/use-record.md -->
+## useRecord
+_One live record from a "get" query, normalized — the headless core of RecordView._
+A detail view wants *one* record, but a "get" query may return a row array or a
+single object depending on how it was written. `useRecord` subscribes and
+normalizes that away, so the component never branches on the shape.
+```tsx
+import { useRecord } from '@voltro/client'
+const { record, loading, error } = useRecord('app', 'users.get', { id })
+```
+An array result yields its **first** row; an object result is the record itself;
+anything else is `undefined`. `loading` is true exactly while no snapshot has
+arrived, and `error` is the underlying subscription's cold-start error.
+It is a thin projection over `useSubscription` — same live semantics, so the
+detail view updates on any write with no refetch — with the single difference
+that it takes no options argument, only `(apiName, queryTag, input?)`. Eager
+loaded relations arrive as nested arrays on the record.
+Reach for it when you want the data but not the markup.
+[`<RecordView>`](/docs/ui/client-utilities/record-view) is this hook plus a
+rendered definition list and sub-tables.

package/templates/agent-docs/templates/apibackends.md CHANGED Viewed

@@ -2604,9 +2604,9 @@ done
 <!-- source: en/templates/api-rbac.md -->
 ## API · RBAC
-_Role-based access control with @voltro/plugin-rbac — a role→scope map, an interceptor that resolves the caller's roles to scopes, and an in-handler permission(ctx, 'notes:write') guard that fails typed Forbidden. admin:full bypasses. Config-only, zero infra; useCan() for web UI._
+_Role-based access control with @voltro/plugin-rbac — a role→scope map, an interceptor that resolves the caller's roles to scopes, and an in-handler permission(ctx, 'notes:write') guard that fails typed ScopeError. admin:full bypasses. Config-only, zero infra; useCan() for web UI._
-Roles → scopes → guards. `@voltro/plugin-rbac` compiles a role map and an rpc interceptor resolves each caller's **roles** to **scopes**, stamped on the subject. Guard handlers with `permission(ctx, 'notes:write')`, the Effect-native guard that fails typed `Forbidden`. The `admin:full` scope is a blanket bypass. Config-only, zero infra. Template id: **`api-rbac`**.
+Roles → scopes → guards. `@voltro/plugin-rbac` compiles a role map and an rpc interceptor resolves each caller's **roles** to **scopes**, stamped on the subject. Guard handlers with `permission(ctx, 'notes:write')`, the Effect-native guard that fails typed `ScopeError`. The `admin:full` scope is a blanket bypass. Config-only, zero infra. Template id: **`api-rbac`**.
 ## Scaffold
@@ -2643,13 +2643,13 @@ rbacPlugin({
 import { permission } from '@voltro/plugin-rbac'
 export default (input, ctx) => Effect.gen(function* () {
-  yield* permission(ctx, 'notes:write')       // fails typed Forbidden for viewer
+  yield* permission(ctx, 'notes:write')       // fails typed ScopeError for viewer
   const store = yield* EffectStore
   return yield* store.insert('notes', { title: input.title, body: input.body })
 })
 ```
-Declare `error: Forbidden` (from the browser-safe `@voltro/plugin-rbac/errors`). Companions: `anyPermission(ctx, [...])` (OR), `assertPermission` (sync throw), `can(ctx, scope)` (boolean).
+Declare `error: ScopeError` (from `@voltro/protocol`). Companions: `anyPermission(ctx, [...])` (OR), `assertPermission` (sync throw), `can(ctx, scope)` (boolean).
 ## Try it
@@ -2659,21 +2659,23 @@ curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json
   -d '{"tag":"notes.create","input":{"title":"hi","body":"x"}}'
 # → { ok:true, … }
-# readers tenant → viewer → notes:write missing → typed Forbidden:
+# readers tenant → viewer → notes:write missing → typed ScopeError:
 curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' -H 'x-tenant: readers' \
   -d '{"tag":"notes.create","input":{"title":"hi","body":"x"}}'
-# → { ok:false, error:{ _tag:"Forbidden", required:"notes:write" } }
+# → { ok:false, error:{ _tag:"ScopeError", required:"notes:write" } }
 ```
 ## On the web side
 ```tsx
-import { useCan } from '@voltro/plugin-rbac/web'
+import { PermissionProvider, useCan } from '@voltro/client'
+<PermissionProvider scopes={session.scopes}>…</PermissionProvider>
 const canWrite = useCan('notes:write')
 {canWrite && <NewNoteButton />}      // hide affordances the user can't use
 ```
-`useCan` is a UI affordance only — the server `permission()` guard is the enforcement.
+The UI gate ships in [`@voltro/client`](/docs/ui/client-utilities/use-can), not in the plugin: scopes are a framework concept, so gating a button must not require an rbac dependency. `useCan` is a UI affordance only — the server `permission()` guard is the enforcement.
 ## Persisted roles

package/templates/agent-docs/templates/overview.md CHANGED Viewed

@@ -47,7 +47,7 @@ The four `api-backend*` shapes share the same minimal `notes` domain and differ
 | [`api-search`](/docs/templates/api-search) | **Full-text search in sync** — `@voltro/plugin-search` mirrors every table write into an index via the post-commit change tap; the synthesized `search.query` rpc returns tenant-scoped hits. Memory backend (zero infra); one line to Typesense/Meilisearch/Algolia. |
 | [`api-feature-flags`](/docs/templates/api-feature-flags) | **Feature flags as code** — `@voltro/plugin-flags`: kill-switch / %-rollout / targeting, a declarative `gatedBy` map + an in-handler `requireFlag` guard (both fail typed `FlagDisabled`), `useFlag()` on the web. Memory store. |
 | [`api-ratelimit`](/docs/templates/api-ratelimit) | **Per-endpoint rate limiting** — `@voltro/plugin-ratelimit` intercepts rpc: a default + rules (sliding-window / token-bucket, by subject/tenant/…), typed `RateLimited` auto-merged into the error union. Memory store. |
-| [`api-rbac`](/docs/templates/api-rbac) | **Role → scope access control** — `@voltro/plugin-rbac`: a role map, an interceptor resolving roles to scopes, and an in-handler `permission(ctx, 'notes:write')` guard (typed `Forbidden`). `admin:full` bypasses. Config-only. |
+| [`api-rbac`](/docs/templates/api-rbac) | **Role → scope access control** — `@voltro/plugin-rbac`: a role map, an interceptor resolving roles to scopes, and an in-handler `permission(ctx, 'notes:write')` guard (typed `ScopeError`). `admin:full` bypasses. Config-only. |
 | [`api-moderation`](/docs/templates/api-moderation) | **Pre-commit content moderation** — `@voltro/plugin-moderation` checks fields before the handler: a `block` rule rejects with typed `ContentRejected`, a `flag` rule queues for review. keywordProvider / aiProvider. |
 | [`api-versioning`](/docs/templates/api-versioning) | **Row history + time-travel** — `@voltro/plugin-versioning` snapshots every write via the change tap; `rowHistory()` (every version) + `rowAsOf()` (value at a past instant), read through handlers. Memory store. |
 | [`api-backend-deactivation`](/docs/templates/api-backend-deactivation) | **The `deactivation()` mixin** — lock a user out (`deactivatedAt`) while the row stays VISIBLE/queryable — the deliberate opposite of `softDelete()`'s hide+anonymise. Pure schema. |