@voltro/cli 0.55.0 → 0.57.0

package/templates/agent-docs/observability.md

@@ -416,3 +416,230 @@ curl "http://localhost:4000/_voltro/inspect/timeline/replay?table=todos&seq=42"
 - The inspect surface is a `voltro dev` / DevTools concern; out-of-band DB writes
   (not in the app's ChangeEvent stream) aren't recorded, and production should
   use OTLP for forensics.
+
+
+
+---
+
+<!-- source: en/observability/inspect-scope.md -->
+## What an inspect answer is about
+
+_Every /_voltro/inspect/* answer is an Observation — it says which scope it describes, which replica answered, and how complete it is. Reading the envelope, the four scopes, fleetSize, and ?scope=fleet._
+
+Every 2xx `/_voltro/inspect/*` answer is an **Observation**: the payload plus
+what a reader needs in order to act on it.
+
+```json
+{
+  "data": { "…": "the payload" },
+  "scope": { "kind": "process" },
+  "origin": {
+    "replicaId": "api-7d9f-x2k",
+    "instanceId": "api-7d9f-x2k@1787893389882.k3f9aa",
+    "startedAt": 1787893389882,
+    "version": "0.56.0",
+    "bootPath": "serve"
+  },
+  "completeness": { "complete": false, "fleetSize": 3, "reason": "process-scoped: this is 1 of 3 replicas" },
+  "capturedAt": 1787893390411
+}
+```
+
+## Why the payload alone was not enough
+
+`/subscriptions` answers with the subscriptions of the **one process that
+received the request**. `/schedules` answers with the whole fleet's, read from
+the shared database. Both used to be plain JSON, so on a multi-replica
+deployment the first is an unlabelled sample and reads exactly like the second.
+
+On **one** replica the difference is invisible — and one replica is every
+development environment, every e2e run and every template. So the environment
+in which the two look identical is the one everybody builds and tests in, and
+the difference only appears in production, where nobody can go and read the
+source to settle it.
+
+## The four scopes
+
+| `scope.kind` | What it means | Examples |
+|---|---|---|
+| `process` | True of `origin` and of nothing else. Another replica answers differently. | `/subscriptions`, `/metrics`, `/logs`, `/cache`, `/events`, `/traces`, `/cluster` |
+| `shared-store` | Read from storage every replica shares — any of them would answer the same. | `/schedules`, `/workflows/*`, `/migrations`, `/database`, `/data/*` |
+| `fleet` | Assembled from more than one process. `completeness` says who answered. | `/members`, `/subscriptions?scope=fleet` |
+| `declaration` | From the source tree. Identical on every replica **of one version** — and different across a rolling deploy. | `/app`, `/routes`, `/manifest`, `/env`, `/rpc` |
+
+`declaration` is its own kind rather than "fleet" on purpose: during a rolling
+deploy your fleet genuinely runs two versions, and `origin.version` is how you
+see which one answered.
+
+## `fleetSize` — the label that needs no aggregation
+
+A `process`-scoped answer carries how many replicas exist:
+
+```json
+"completeness": { "complete": false, "fleetSize": 3, "reason": "process-scoped: this is 1 of 3 replicas" }
+```
+
+So a plain `curl` states that it is a fraction, and of what. Query a few times
+and union by `origin.instanceId` — which you can now do, because the answer
+says which process produced it.
+
+**When the field is missing, it means "could not tell", not "one".** If the app
+runs no membership registry, `fleetSize` is **absent** and `complete` is
+`false` with a reason. Reporting `1` there would tell you that you are seeing
+the whole fleet.
+
+## `?scope=fleet`
+
+```sh
+curl -s -H "authorization: Bearer $VOLTRO_INSPECT_TOKEN" \
+  'localhost:4000/_voltro/inspect/subscriptions?scope=fleet' | jq .
+```
+
+Each replica publishes its counters into `_voltro_replica_observations` on a
+timer, so **any** replica can answer by reading rather than by asking the
+others. The answer is `fleet`-scoped and says what it is missing:
+
+```json
+{
+  "data": { "resume": [
+    { "replicaId": "api-a", "version": "0.56.0", "ageMs": 4021, "payload": { "…": "counters" } },
+    { "replicaId": "api-b", "version": "0.56.0", "ageMs": 9114, "payload": { "…": "counters" } }
+  ] },
+  "scope": { "kind": "fleet", "assembledBy": "api-a", "assembledAt": 1787893390411 },
+  "completeness": {
+    "complete": false, "responded": 2, "expected": 3, "missing": ["api-c"],
+    "reason": "1 replica(s) have written nothing readable"
+  }
+}
+```
+
+Three properties are deliberate:
+
+- **A replica that has written nothing is `missing`, not absent.** Dropping it
+  would make a partial answer look complete — the same unlabelled sample, one
+  level up and more expensive, because now you believe you asked everybody.
+- **A stale row is reported with its `ageMs`, not filtered out.** Removing it
+  hides that the answer is partial; keeping it unmarked presents fiction as
+  current.
+- **Mixed versions are named** in `completeness.versions` when the responders
+  disagree. A rolling deploy spans two shapes, and averaging them silently is
+  wrong in a way nothing downstream can detect.
+
+**If there is no shared store, the request is refused with `501`** and a reason
+— never answered with this replica's own numbers. Handing back a sample to
+someone who asked for the fleet in writing is exactly the failure the envelope
+exists to prevent.
+
+## `?replica=<id>` — asking one named replica
+
+```sh
+# this replica's own answer (the default)
+curl -s … /_voltro/inspect/subscriptions
+
+# every replica's counters, assembled from the shared store
+curl -s … '/_voltro/inspect/subscriptions?scope=fleet'
+
+# ONE named replica, asked through the one you can reach
+curl -s … '/_voltro/inspect/subscriptions?replica=api-7d9f-x2k'
+```
+
+The answer comes back with **that** replica's `origin`, process-scoped: the
+proxy does not launder whose answer it is.
+
+The address is looked up in `_voltro_replica_observations` — **the caller names
+an ID, never a URL**, and an id we do not know produces a `404` with no request
+leaving the process. That is what keeps this from being an SSRF primitive.
+"unknown replica" and "that replica published no reachable address" give the
+same message on purpose: telling them apart would tell a caller which ids
+exist.
+
+A replica publishes an address only when it is genuinely reachable by a peer.
+An unset `POD_IP` falls back to `127.0.0.1`, which is a shrug rather than a
+statement, so it is recorded as **not** reachable and no peer will try it. Set
+`VOLTRO_INSPECT_ADVERTISE_HOST` to declare one — including `127.0.0.1`, when
+the peers really are on this machine.
+
+A proxied request carries a hop header and is always answered locally, so
+`?replica=` cannot cycle. A peer that does not answer inside a short deadline
+becomes a `504` naming it, because a diagnostic that hangs is worse than one
+that says no.
+
+## Writes are never fleet-addressable
+
+`?scope=fleet` and `?replica=` exist only for reads. A mutating endpoint
+(`/invoke`, `/seeds/run`, `/data/import`, `/migrations/rollback`,
+`/agent/call`) rejects them: fanning a destructive operation out across a fleet
+is not something an accidental query parameter should be able to ask for.
+
+## Reading it from your own tooling
+
+```sh
+# the payload
+curl -s … /_voltro/inspect/subscriptions | jq .data.resume
+
+# is this the whole picture?
+curl -s … /_voltro/inspect/subscriptions | jq '.completeness | {complete, fleetSize}'
+
+# which pod answered?
+curl -s … /_voltro/inspect/subscriptions | jq -r .origin.replicaId
+```
+
+`capturedAt` is the **origin's** clock. Do not compare it with another
+replica's — replica clocks disagree, which is why the fleet view reports an
+`ageMs` computed against one reader's instant rather than a timestamp you are
+invited to subtract.
+
+## The live stream
+
+`/_voltro/inspect/stream` (SSE) carries `origin` on **every event**, not on a
+handshake. A consumer that connects late — a reconnect, a second tab, a `curl`
+piped into `jq` — never sees a handshake, and this is a live stream from
+whichever replica the connection landed on. Without the per-event stamp, a tail
+on a three-replica fleet shows a third of it continuously, with nothing on the
+wire to say so.
+
+`ts` is that replica's clock. Do not order two origins by it.
+
+**It is mounted on both boot paths.** `voltro serve` used to answer `404` here
+— the stream was wired for `voltro dev` and nowhere else — so every live view in
+the dashboard worked in development and was dead in production. Both paths now
+mount it through one builder.
+
+**Authenticating it needs no special step from you, and one from the
+dashboard.** `EventSource` accepts no headers, so a browser cannot attach a
+bearer to an SSE request the way it does to every other inspect call. The
+dashboard passes the app's token through a same-origin cookie scoped to its own
+proxy path, cleared the moment the stream opens; the proxy moves it into an
+`Authorization` header. Nothing about the token ever appears in a URL, and the
+app receives a header like any other caller.
+
+## In the dashboards
+
+Both dashboards unwrap `.data` in their fetch layer and keep the envelope. A
+page whose data is process-local renders a notice saying which replica it is
+showing and how many exist; a page whose answer is complete renders nothing,
+because a banner over a complete answer teaches people to ignore banners.
+
+### The Fleet panel
+
+Both dashboards ship a **Fleet** page — the self-hosted DevTools under
+`/apps/<id>/fleet`, the hosted console under the app's *Fleet* tab. One page,
+one shared component, two transports.
+
+It renders **three** populations, and the two after the first are the point:
+
+- the replicas that **answered**, each with its version, how long ago it
+  published, and whether a peer can reach it;
+- the replicas that are **silent** — membership knows them and they have
+  published nothing readable. Shown as their own section rather than omitted,
+  because "not shown" and "not there" look identical and mean opposite things;
+- the replicas whose answer is **stale**, with the age. Filtering them would
+  make a partial answer look complete; leaving them unmarked would present old
+  numbers as current.
+
+A **mixed-version** note appears when the responders disagree — a rolling
+deploy is in flight and the numbers span two shapes.
+
+The completeness banner is phrased as a ratio (*"3 of 5 replicas answered"*)
+rather than a count, because a count invites the reader to believe that is the
+fleet.

package/templates/agent-docs/plugins/audit.md

@@ -356,7 +356,7 @@ What it discloses, and what it never does:
 
 | | |
 | --- | --- |
-| a string | its LENGTH — `string(113)`. Never a prefix, never a hash |
+| a string | its LENGTH — `string(113)`. Never a prefix, never a hash. Below a floor, a bucket: `string(<16)` |
 | a number, a boolean, a date | its TYPE only. A number can BE the secret |
 | a declared field name | survives — `jiraToken` |
 | a key that is not an identifier | described, not reproduced — `<key:string(36)>` |
@@ -369,10 +369,26 @@ Two of those are worth a sentence each.
 it looks like a declared field: a plain short identifier. A legitimate key that
 is not one (`content-type`) loses its name and keeps its shape.
 
-**A string's length is a real disclosure, and a small one.** For a fixed-format
-credential it carries nothing — every token of a given kind is the same length.
-For a human-chosen password it is a weak hint. If that matters in your threat
-model, `'all'` is the default and stays available.
+**A string's length is a real disclosure, and a small one — above a floor.** For
+a fixed-format credential it carries nothing — every token of a given kind is the
+same length. For a human-chosen password it is a weak hint.
+
+Below a floor it stops being small: a six-digit TOTP reported as `string(6)`, or
+a four-digit PIN as `string(4)`, tells a reader with log access exactly what
+shape to try. Nothing this mode is FOR lives under 16 characters — the case that
+motivated it is 113 against an expected 44 — so a string shorter than that
+reports `string(<16)`: shorter than the floor, not how much shorter.
+
+```ts
+auditPlugin({ redactOutcome: 'shape', redactionLengthFloor: 0 })
+```
+
+`0` turns the floor off, for a deployment whose audited payloads are ids and
+tokens and every character of length is worth having; raise it for one holding
+short human-entered secrets. An EMPTY string stays exact (`string(0)`) — "the
+field arrived empty" is a real diagnosis and an empty string is not a secret. The
+floor applies to described keys too, for the reason above them: a key that is not
+a declared field is a key carrying data.
 
 `redactSubject` spells its variant `'metadata-shape'`, because its default
 (`'metadata'`) already names the field it acts on.

package/templates/agent-docs/plugins/billing.md

@@ -40,6 +40,8 @@ export default {
 
 `plans` is the single source of tier→limit truth — it lives in code, not the DB, so limits change by redeploy, not migration. Entitlement values are `number | 'unlimited'`. With no provider configured (and no `STRIPE_SECRET_KEY`), the plugin uses an in-memory **mock provider** — zero-config for dev and tests.
 
+> **Under `NODE_ENV=production`, a mock chosen by ABSENCE warns.** `STRIPE_SECRET_KEY` is a deployment variable, and one that silently stops being set — a rotated secret, a typo in a values file, a CI variable nobody created — is routine. Without the line, an app that had been charging customers keeps answering every billing call successfully, reaches nobody, and leaves nothing to find afterwards. Set the key, or write `provider: 'mock'` so the mock is a decision on the page rather than an absence. An explicitly declared mock stays silent.
+
 What it provides:
 
 - The `_voltro_billing_*` tables (customers, subscriptions, invoices, usage, flush_claims, dunning_notices) via `extendSchema.tables`.
@@ -239,6 +241,21 @@ All three route through the existing `BillingService.reportUsage` (a local per-p
 
 **Idempotency + multi-instance.** The self-scheduled flush is per-period idempotent (`markReported` makes a re-flush a no-op) AND **cluster-coordinated by default**: each replica self-schedules, but an INSERT-wins claim on the flush window (`_voltro_billing_flush_claims`) means exactly one replica flushes a given window — so two replicas never double-push it, with no extra wiring. Set `flushIntervalMs: 0` to disable the timer entirely and drive `billing.flushUsage()` from your own `*.cron.tsx` instead.
 
+**A `cdc` meter accrues once fleet-wide, not once per replica.** The change tap it
+rides is delivered to EVERY replica — that is what makes a `changeScope: 'fleet'`
+store (postgres LISTEN/NOTIFY, mysql binlog) cross-instance in the first place —
+and accrual is an increment on a shared counter, so a tenant on two pods used to
+be invoiced twice. Each change is now claimed in `_voltro_change_claims` before it
+accrues, through the same INSERT-wins arbiter behind
+[`defineSubscriber({ once })`](/docs/data/subscribers) and a reaction's
+`dedupeKey`. Nothing to configure; the boot log warns loudly if a deployment ever
+runs the tap ungated, because an over-counted meter is indistinguishable from a
+correct one by looking at the number.
+
+The claim key names the CHANGE, not the row: two genuine edits to one row share an
+id, so an id-keyed meter on `op: 'update'` would count the first and drop every one
+after it.
+
 **Boundaries (v1).** Metering captures writes the framework observes through `ctx.store` — the bulk helpers (`updateMany` / `deleteMany`) emit per-row ChangeEvents that ARE counted, but a single bulk SQL escape-hatch write isn't. The meter is best-effort post-commit telemetry, not a financial ledger of record.
 
 ## Plans, seats & the billed amount

package/templates/agent-docs/plugins/broadcast.md

@@ -51,7 +51,8 @@ The bus is **additive** to the inline emit path:
 
 - It publishes `{ origin, event }` on the `<namespace>:changes` channel.
 - It injects remote events into every other replica's store, skipping its own origin so there's no double-emit.
-- A broker outage degrades cross-replica fan-out only — local reactivity keeps working.
+- A broker outage degrades cross-replica fan-out only — local reactivity keeps working, **including a broker that is down at boot**. The replica starts, serves, and joins the bus when the broker returns; the time it spent unsubscribed is then reported as a gap and every live query re-runs. A crash loop across the fleet is the wrong answer to a broker restart, which is exactly the moment every replica is dialling at once.
+- A restarted peer is recognised as a **new process**, not the same one continuing. Each publish carries a per-process epoch, because a replica id survives a restart (`POD_NAME` on a StatefulSet, `VOLTRO_REPLICA_ID` by definition) and a serial does not.
 
 The plugin declares the `network:outbound:*` permission. The boot banner names the resolved tier (cross-instance via redis/nats, or off for the dialect when no broker is configured).
 

package/templates/agent-docs/plugins/ratelimit.md

@@ -215,7 +215,12 @@ updates under concurrency), so it can't reuse a plain get/set cache. Three
 stores ship, all fail OPEN on backend errors (degrade to no-limit, never to 500s):
 
 - **Memory** *(default)* — single-process, zero-config. Perfect for dev and
-  single-instance deploys; not shared across replicas.
+  single-instance deploys; not shared across replicas. **Which means every limit
+  is multiplied by the replica count**: `100/min` on five pods is 500/min, and a
+  limiter is usually the thing standing between an endpoint and abuse. The plugin
+  warns at boot when the environment says several replicas (`POD_NAME`,
+  `FLY_ALLOC_ID`, `K_REVISION`, … — or `REPLICA_COUNT`, which is a declaration in
+  both directions) and the store is still the process-local one.
 - **Postgres** — multi-node correct. Runs on the framework's **already-open
   `SqlClient`** — the same connection pool the app itself uses — so it reads no
   `DB_*`/`PG_*` env of its own and never opens a second pool. The plugin binds

package/templates/agent-docs/plugins/row-history.md

@@ -138,6 +138,17 @@ Version numbers are 1-based in **both** timings, so switching `timing` does not
 
 **The refusal takes the row with it.** When the trail's insert fails, the write it covers is rolled back — including a write made OUTSIDE any transaction of your own. That has not always been true: the row's statement committed on its own and the trail ran as a second statement afterwards, so a failing trail left a committed row behind a write that reported failure. Anything that retried that write then met its own row and reported a duplicate key for a row nobody wrote twice. A table with recorders is written inside a transaction now, on every SQL dialect, so "the mutation fails with it" means what it says.
 
+**Post-commit records once fleet-wide, not once per replica.** The change tap it
+rides is delivered to EVERY replica — that is what makes a `changeScope: 'fleet'`
+store (postgres LISTEN/NOTIFY, mysql binlog) cross-instance in the first place —
+and it used to record on each of them. It did not surface as a conflict either:
+versions are numbered `MAX(version) + 1`, so two replicas both computed version 1,
+one won the primary key, and the loser's retry re-read MAX, got 2, and appended a
+second entry. Three replicas produced versions `1, 2, 3` for one change — not
+merely doubled, *mis-ordered*, and `selectAsOf` reads `version`. Each change is now
+claimed fleet-wide before it is recorded, keyed on the change rather than the row.
+Nothing to configure; `'in-transaction'` never had this.
+
 **Why the default is still `'post-commit'`.** In-transaction makes `_voltro_row_history` a hard dependency of every write path it covers: its availability becomes your write path's availability, and every covered write holds its locks longer. Post-commit loses at worst *one entry*; in-transaction can, at worst, stop writes to the covered tables entirely. For a compliance trail the second trade is the right one — for the undo / time-travel use this plugin also serves, it is not.
 
 ### Under CDC, and inside a transaction

package/templates/agent-docs/plugins.md

@@ -1130,6 +1130,25 @@ framework's ALREADY-OPEN handles so it never rebuilds them:
   the SAME pool the app's store uses. Run raw SQL through it instead of
   standing up your OWN `ManagedRuntime` + pool from env. `undefined` on
   the in-memory store (no SQL engine) — guard with `if (ctx.sql)`.
+- **`ctx.claimChange(scope, key)`** — claim ONE change fleet-wide; `true` means
+  this replica may run the effect. The counterpart of `scheduleCoordinated` for
+  the OTHER thing that fires on every replica: a change tap. `onChangeEvent` is
+  delivered to every replica — that is what makes a `changeScope: 'fleet'` store
+  cross-instance — so a tap that COUNTS or SENDS multiplies by the replica count.
+  `@voltro/plugin-billing` accrued a usage unit per metered row change and a
+  tenant on two pods was invoiced twice.
+
+  `scope` namespaces the key (use your plugin's name); `key` must name the
+  CHANGE. Derive it with `changeDigest` + `OccurrenceCounter` from
+  `@voltro/database` rather than inventing one — a fleet change carries no LSN,
+  no commit id and no `traceId`, so content plus its position among
+  content-identical repeats is the only thing two replicas provably agree on. A
+  row id is not enough: two genuine updates to one row share it.
+
+  AT MOST once — the claim is taken before the effect, so a replica that wins and
+  dies takes the change with it, and a claim that cannot be written is taken by
+  nobody. Fail-closed, like the rate slot and the budget guard.
+
 - **`ctx.scheduleCoordinated(name, intervalMs, effect)`** — run a periodic
   task on ONLY ONE replica per tick, cluster-coordinated via the same
   claim-table exactly-once gate the cron scheduler uses. Replaces the

package/templates/agent-docs/reference.md

@@ -89,6 +89,7 @@ these before hand-rolling a form, a table, or a picker** — full guide in
 | [`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. |
+| [`useSubscriptionHealth`](/docs/ui/client-utilities/use-subscription-health) | Which of an api's calls are currently REFUSED — a refused subscription never retries and reads as `loading`. |
 | [`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). |

package/templates/agent-docs/scheduling.md

@@ -539,6 +539,29 @@ defineSchedule({
 
 > The watchdog stops *waiting* and records the timeout; it cannot truly abort a Promise's in-flight side effects (JavaScript has no thread-kill). Make long handlers cooperative — check a deadline, or do the heavy lifting in a [workflow](/docs/workflows/overview) with its own step-level durability.
 
+## Across replicas — the heartbeat
+
+`onOverlap: 'skip'` is a **cluster-wide** rule, not a per-process one: a firing is suppressed when an occurrence of the same schedule is running on *any* replica. That check reads `_voltro_schedule_runs`, so it needs a way to tell a run that is still working from one whose process died mid-run and left its row on `running` forever.
+
+That is `heartbeatAt`: a run in flight bumps it every **30 seconds**, and a row silent for three beats is read as dead rather than as a live occurrence. Without it the only evidence a row carried was `firedAt`, and a window generous enough never to cut off a long run is also long enough to suppress a half-hourly cron for hours after one restart.
+
+```ts
+// app.config.ts
+export default defineAppConfig({
+  scheduling: {
+    scheduleHeartbeatMs: 30_000,   // default; VOLTRO_SCHEDULE_HEARTBEAT_MS overrides it
+  },
+})
+```
+
+Raise it in a deployment with many long-running schedules where the writes matter more than the detection latency; a run shorter than one interval writes no beat at all and costs nothing either way. It is **not a lease** — a stale beat only stops a corpse from holding the schedule shut; nothing takes ownership of the run.
+
+The skip is logged with what it measured, so the two cases are legible from the log alone:
+
+```
+schedule: overlap skip  name=reindex scope=cluster heldBy=pod-7f4c lastSeenMs=1840
+```
+
 ## Backfill — `backfill`
 
 When the process was down across one or more firing instants, what should happen on boot? Computed from the last `_voltro_schedule_runs` row for the schedule.

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

@@ -370,6 +370,36 @@ widget })` rides an annotation, `description` becomes help text, and
 underneath is an implementation detail — no engine type appears in the public
 API, and production builds stub its devtools channel automatically.
 
+### When the FORM decides which mutation it is
+
+Some forms only learn their target from what the user does: a calendar entry
+becomes a recurring **series** the moment "repeats" is ticked, and the series
+mutation takes eleven more fields than the single one.
+
+Pass a function of the current values instead of a tag:
+
+```tsx
+const form = useFormBinding<CalendarInput>(
+  'app',
+  (v) => (v.repeats ? 'calendarRecurringEvent.create' : 'calendarEntries.create'),
+  { defaults: { title: '', repeats: false } },
+)
+```
+
+The schema in force follows the tag, so `form.fields` grows and shrinks with it
+and validation always matches what will actually be submitted. **The values do
+not reset** — the engine is constructed once and never rebuilt, so everything
+typed before the switch survives it. That is the whole reason this exists:
+deriving the tag outside the binding is not available (the values belong to the
+binding and do not exist before it), and re-mounting with a different tag throws
+the user's input away.
+
+Two details worth knowing. On the first render there are no values yet, so the
+function is called with your `defaults`. And the accessibility ids are pinned to
+the first tag and stay there — they are DOM ids, and letting them move on the
+keystroke that flips the branch would remount every field, taking the focus and
+the caret with it.
+
 ### Reference fields, uploads, and testing the form
 
 **Reference fields.** Mark a schema field as a table reference and it renders
@@ -1597,6 +1627,57 @@ identity* changed underneath them.
 
 
 
+---
+
+<!-- source: en/ui/client-utilities/use-subscription-health.md -->
+## useSubscriptionHealth
+
+_Which of an api's calls are currently refused — the state a screen cannot derive from its own hook._
+
+A refused subscription is **terminal for its transport**. It does not retry, so
+there is no second error event to react to — and `SubscriptionFailed` presents
+`data: undefined`, which is the value most reading layers derive `loading` from.
+A component that branches on `data === undefined` therefore shows a spinner from
+then on, indefinitely. The state union models this correctly (`failed: true`,
+`loading: false`); what loses it is the wrapper hook in between, and a wrapper
+that passes `{ data, loading }` through is the natural shape to write.
+
+`useSubscriptionHealth` answers the question no single hook can: **is anything on
+this api currently refused, and what.**
+
+```tsx
+import { useSubscriptionHealth } from '@voltro/client'
+
+const SessionBar = () => {
+  const { healthy, failed } = useSubscriptionHealth('app')
+  if (healthy) return null
+  return <Banner>Not loading: {failed.map((f) => f.tag).join(', ')}</Banner>
+}
+```
+
+A tag enters `failed` when a call for it fails and leaves when a call for the
+**same tag** succeeds. It is keyed by tag rather than counted, because the
+question a screen asks is "is this working now" and two failures of one call are
+one broken thing. `healthy` is the positive form of the same fact, so a component
+reads `if (!healthy)` instead of `if (failed.length > 0)`.
+
+Each entry is `{ tag, source, error, at }` — `at` is the timestamp of the
+failure, so a bar can say *since 12:04* rather than only *broken*.
+
+## What it does not do
+
+It is not a retry mechanism and not an error boundary. Recovery is the
+transport's job: an `Unauthenticated` failure makes the framework re-resolve the
+credential and rebuild the connection, and a rebuilt client re-subscribes on its
+own — a failed entry is never carried across the swap, so it is re-attempted
+rather than restored as broken. Nothing in your app wires that.
+
+The register is scoped to one api's runtime and is reset when that runtime is
+rebuilt, deliberately: carrying a failure across a transport swap would report a
+call as broken that has not been tried since.
+
+
+
 ---
 
 <!-- source: en/ui/client-utilities/use-tracking.md -->

package/templates/agent-docs/templates/appshells.md

@@ -81,7 +81,7 @@ A contact form, a newsletter signup, a theme toggle — anything that needs JS
 
 ```tsx
 // src/components/SignupForm.island.tsx
-import { island } from '@voltro/web'
+import { island } from '@voltro/web/islands'
 const SignupForm = () => { /* … */ }
 export default island(SignupForm, { name: 'SignupForm', hydrate: 'visible' })
 ```
@@ -971,7 +971,7 @@ The post list ships zero JavaScript, but the post page wants a thin reading-prog
 // src/components/ReadingProgress.island.tsx
 import type { ReactNode } from 'react'
 import { useEffect, useState } from 'react'
-import { island } from '@voltro/web'
+import { island } from '@voltro/web/islands'
 
 function ReadingProgress(): ReactNode {
   const [pct, setPct] = useState(0)
@@ -1180,7 +1180,7 @@ The form is an island with `hydrate: 'visible'` — it's below the fold, so hydr
 // src/components/ContactForm.island.tsx
 import type { FormEvent, ReactNode } from 'react'
 import { useState } from 'react'
-import { island } from '@voltro/web'
+import { island } from '@voltro/web/islands'
 import { CONTACT_ENDPOINT } from '../config'
 
 type Status =