@voltro/cli 0.54.0 → 0.56.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/billing.md

@@ -239,6 +239,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

@@ -583,16 +583,45 @@ notificationsPlugin({ name: 'ops' })                        // notifications#ops
 notificationsPlugin({ alias: 'alerts', name: 'ops' })       // alerts#ops.inbox
 ```
 
-`alias` exists to escape a tag collision, which is fatal at codegen. Two costs
-are worth knowing before you reach for it:
+`alias` exists to escape a tag collision, which is fatal at codegen. One cost is
+worth knowing before you reach for it:
 
-- the local and cloud dashboards fetch a plugin's inspect panel at its DEFAULT
-  slug, so an aliased plugin keeps serving its inspect endpoints while its
-  dashboard panel stops resolving;
 - the plugin-migration ledger key is `<plugin-alias>__<migration.id>`, so
   aliasing a plugin that ships `extendSchema.migrations` makes its already-applied
   migrations look unapplied. Choose the alias before first boot, not after.
 
+The dashboard panel is NOT one of those costs. The dashboards fetch a plugin's
+inspect panel at its DEFAULT slug with the path compiled in — they live in other
+repositories and cannot follow an alias — so a plugin's inspect endpoints keep a
+mount under its canonical name alongside the aliased one. Aliasing does not take
+the panel away.
+
+The exception is `name`, not `alias`: two installs of one plugin are two panels
+with one canonical name, so they get no shared mount. Showing either one under
+it would hand a dashboard the other install's rows under a name that looks
+right. Each install is reachable at its own slug, which `/_voltro/inspect/plugins`
+reports for every plugin as `inspectSlug` (alongside `baseName`, the canonical
+package name before any alias).
+
+The plugin's own hooks are not one of those costs either — they follow the alias.
+`useInbox()`, `useUpload()`, `useComments()` and the rest resolve their wire tag
+at call time from the namespace your app installed the plugin under, so
+`notificationsPlugin({ alias: 'alerts' })` makes `useInbox()` subscribe to
+`alerts.inbox` with no change at the call site. Two pieces make that work and
+both are automatic:
+
+- `voltro dev` writes a `registerPluginAliases({ … })` declaration into
+  `rpcGroup.generated.ts` — the module the web client already loads — mapping
+  each installed plugin's canonical package name to the namespace it answers to;
+- each plugin's hooks call `pluginTag(baseName, route)` from `@voltro/protocol`
+  instead of spelling the namespace.
+
+If you install the SAME plugin twice with `name` (two instances) and no install
+is the un-suffixed primary, `pluginTag` refuses rather than guessing which one a
+hook means — call the route by its full tag
+(`useSubscription(api, 'notifications#ops.inbox')`) to say which install you
+want.
+
 ### `tables: false` — keeping your own tables
 
 Plugins whose tables carry no authorization or safety decision accept
@@ -610,12 +639,21 @@ writes to those tables BY NAME, so you take over declaring each one with the
 shape the package exports, and a missing or mis-shaped table fails at the first
 write rather than at boot.
 
-It is deliberately NOT offered on plugins whose tables carry a guarantee — the
+It is deliberately NOT offered on plugins whose tables carry a guarantee. The
 SAML assertion replay cache, SCIM provisioning state, billing's usage counters,
-cdc-out's delivery outbox, the governance consent ledger, search's tenant-scoped
-index rows. A `tables: false` there would disable a security or correctness
+cdc-out's delivery outbox, the governance consent ledger and search's
+tenant-scoped index rows are examples, **not the whole list** — read "the plugin
+does not offer `tables`" as the answer, never "so every plugin not named here
+would let me". A `tables: false` there would disable a security or correctness
 decision with no signal to the app that it now owns it.
 
+`@voltro/plugin-storage` is the case people expect to find in that list.
+`_voltro_storage_grants` decides who may read and write an object, so it belongs
+there — but the option would not reach it in any case: storage's four tables are
+contributed as framework tables, not through `extendSchema`, so there is nothing
+for a `tables: false` to switch off. Owning the grant table would need a
+grant-store seam, which does not exist yet.
+
 Boot fails with a clear error on tag collisions (between two plugins, or
 with a user-authored tag).
 
@@ -1092,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

@@ -61,6 +61,8 @@ these before hand-rolling a form, a table, or a picker** — full guide in
 | 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. |
+| [`useFormField`](/docs/ui/forms-and-tables) | One field of the enclosing binding — value, blur, the display-gated error, a11y props. Re-renders that field alone. |
+| [`useFormBindingContext`](/docs/ui/forms-and-tables) | The binding a `<FormBindingProvider>` (or `<AutoForm>`) mounted above — for a widget kit that needs the form itself, not one 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. |
@@ -229,9 +231,9 @@ type TeamsState = SubscriptionState<ReadonlyArray<Team>> & { readonly canEdit: b
 ```
 
 `loading` means **no data has arrived yet**, not "the subscription is still
-warming up". A cold-start failure leaves `loading` true and sets `error`, so a
-component branching on `loading` alone renders a skeleton forever — check
-`error`.
+warming up". A cold-start failure is its own state — `loading: false`,
+`failed: true`, `error` non-optional — so branching on `loading` alone is safe;
+render the failure off `failed`.
 
 Use `{ skip }` to defer until inputs are ready:
 

package/templates/agent-docs/routing.md

@@ -207,6 +207,24 @@ src/pages/users/new/page.tsx        # /users/new → wins (static beats dynamic)
 src/pages/[...rest]/page.tsx        # everything else
 ```
 
+## Development mounts in React `StrictMode`
+
+The client entry wraps the tree in `StrictMode`, so **in development every
+effect runs twice, with a real unmount in between**. That is the point — it
+surfaces effects that are not safe to re-run — but it has one consequence
+worth stating outright, because it is expensive to rediscover:
+
+**An effect that keys off "have I mounted before?" fires on the second mount.**
+A deployment measured this as a picker that cleared its own just-loaded value:
+a "when the dependency changes, clear the selection" effect built on a
+mount-counting ref saw the second mount as a change, and an edit form opened
+with an empty required field and a red message while the record had the value.
+Visible only in development, which is exactly where it reads as a data bug.
+
+The rule that survives the double mount: **compare VALUES, not runs.** A reset
+that fires because "this is not the first run" is a reset waiting for the next
+remount; one that fires because the dependency actually differs is not.
+
 ## Query strings
 
 Query params are orthogonal to the URL pattern — they never appear in the file path. A page declares its query contract as a **`searchParams` schema export**, the same page-export convention as `meta`, `loader`, and `renderMode`:

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

@@ -257,6 +257,30 @@ const Input = Schema.Struct({
 )
 ```
 
+**The ids, and the shapes worth knowing.** `required`, `minLength {min}`,
+`maxLength {max}`, `betweenLength {min,max}`, `exactLength {amount}`,
+`pattern`, `invalidEmail` / `invalidUrl` / `invalidUuid`, `minValue {min}`,
+`maxValue {max}`, `minDate {min}` / `maxDate {max}`, `minItems` / `maxItems`,
+`integer`, `invalid`, `checking`, `invalidFileType` / `fileTooLarge`.
+
+Three of those exist because the generic answer is worse at the point of use:
+
+- **Two length bounds on one field are ONE statement.** `minLength(2)` +
+  `maxLength(50)` produce `betweenLength {min,max}` — not "at least 2" for a
+  field whose rule is "between 2 and 50" — and `length(4)` produces
+  `exactLength {amount}`.
+- **A declared `format` names the rule.** A regex never does: "Invalid format"
+  beside an email box tells nobody anything. Annotate the format and the id
+  gets specific — `Schema.String.pipe(Schema.pattern(EMAIL))
+  .annotations({ jsonSchema: { format: 'email' } })` → `validation.invalidEmail`.
+- **A date bound is not a number bound.** `minDate` / `maxDate` rather than
+  `minValue` reading "must be at least 2026-01-01".
+
+**Counting rules pass `count`.** `minItems` / `maxItems` carry `{ count }`
+(alongside `min`/`max`) because that is the parameter an i18n layer selects a
+plural form on — i18next keys pluralisation on a parameter named exactly
+`count`, so a message carrying only `{min}` cannot be pluralised at all.
+
 **Server-side rules route to their field too.** An executor raises a typed
 field error through the always-present `ctx.validation` — no declaration
 needed, `ValidationError` is auto-merged into every mutation's and action's
@@ -383,6 +407,61 @@ const form = useFormBinding('app', 'tasks.create', {
 holds SPA navigations (Back button included) and arms the native
 `beforeunload` prompt — see the routing docs.
 
+### Rich text — and who sanitizes it
+
+A rich-text field is `RichTextDocument`. Use it in the mutation input and the
+form renders an editor with no further annotation:
+
+```ts
+import { RichTextDocument } from '@voltro/web'
+
+const ArticleUpdateInput = Schema.Struct({
+  id: Schema.String,
+  body: RichTextDocument,
+})
+```
+
+Display it with `<RichTextView doc={article.body} />`.
+
+**The contract, because "who sanitizes" is the whole question.** The value is
+**not an HTML string** — it is a closed document tree with a fixed set of node
+types. There is no `html` node, no raw-markup escape hatch, no attribute bag,
+so there is nothing to sanitize: anything that is not one of the declared nodes
+simply fails to decode.
+
+That makes the **`Schema` decode the boundary** — the server's existing,
+non-bypassable input check, the same one every mutation input already passes
+through. The guarantee is therefore not "somebody remembered to sanitize this
+one"; it is that a document which reached your database is one of these shapes.
+
+The rest follows from that:
+
+- **A link's `href` is the one field pointing outward, and it is allowlisted**:
+  `http(s)`, `mailto:`, a `#fragment`, a `/path`. Nothing else — `javascript:`
+  and `data:` are refused by the decode, and control characters/whitespace are
+  stripped before the check, because `java\tscript:` navigates exactly like
+  `javascript:`.
+- **Client-side sanitizing is not a security boundary and is not treated as
+  one.** The widget's parser runs in the browser for the editing experience;
+  the browser is where an attacker sits, so every property it maintains is
+  re-established by the decode on the server.
+- **Rendering never uses `dangerouslySetInnerHTML`.** `<RichTextView>` maps
+  nodes to React elements and text to React children, so markup someone typed
+  into the box is markup the reader SEES. It also drops an href that would not
+  survive a decode — for the value that never went through one.
+
+**The built-in editor** is a `<textarea>` over a small, closed markdown subset:
+headings, `**bold**`, `*italic*`, `` `code` ``, `[text](href)`, `-` lists,
+`>` quotes and fenced code. Everything it does not recognise stays literal text.
+That is also what makes the field work with JavaScript off — the textarea posts
+source, `/form/*` parses it, the same decode validates it. Register your own
+`rich-text` widget (rung 2) for a WYSIWYG; the stored value shape is unchanged.
+
+**Not the collaborative case.** Concurrent, multi-writer editing is
+`crdtDoc()` + `useCrdtEditor` (`@voltro/local-first`) — a CRDT bytes column, a
+sync lane, Tiptap. This is the single-editor field: one column, one writer,
+ordinary JSON your server can validate, index and diff.
+
 **Testing.** `renderFormBinding` (from `@voltro/testing/client`) drives the
 REAL binding against a fake api — fill, blur, submit, read the visible
 errors; a mutation handler that throws `ValidationError({ field })`
@@ -399,6 +478,52 @@ expect(form.errors()['email']).toBe('validation.emailTaken')
 
 Runs under jsdom (`// @vitest-environment jsdom`).
 
+### What submit does with a failure, and what never reaches the wire
+
+**`submit()` does not reject.** A form calls it from an `onSubmit` handler that
+cannot await it, so a rejection has nowhere to go but the console — the form
+sits there looking saved while the failure is invisible. It resolves
+`undefined` instead, and the failure is state: field-routable errors land on
+their field, everything else in `state.submitError`, with an optional
+`onError` for a toast. That covers a composed `onSubmit` too — a follow-up
+write failing on its OWN mutation handle is a failure the binding never saw
+before, and it is the common shape (create the row, then its first child).
+
+**Only declared keys are sent.** A form almost always carries more than the
+mutation declares — a display toggle, a repeat control, a file held before
+upload — and the server has refused undeclared input fields since 0.37. The
+binding restricts the payload to the keys the input schema declares, which is
+the rule the no-JS path already followed (`unknown keys are dropped`), so the
+two submit paths agree. In development it warns once, naming what it dropped,
+because a genuinely misplaced field should still be visible. `toInput` remains
+the place to say what the write actually takes.
+
+**`setValue` with an unchanged value is a no-op.** Every React state source is
+expected to behave that way, and this one did not: each call produced a fresh
+`values` object, so an effect depending on `values` that re-set a field to the
+value it already held never settled.
+
+A widget kit that needs the whole form rather than one field reads it with
+`useFormBindingContext()` — the same provider, one level up.
+
+**Server and browser derive the same form.** A page rendered on the server
+resolves the mutation's input schema exactly as the browser will, so field
+lists, labels and required marks match and hydration holds. (`voltro dev` and
+`voltro start` both hand the descriptors over before rendering.)
+
+```tsx
+const form = useFormBinding('app', 'employees.update', {
+  toInput: (values) => ({ id, ...employeePatch(values) }),
+  onError: (error) => toast.error(String(error)),   // optional; state.submitError always carries it
+})
+
+// A field component anywhere below — no binding threaded through as a prop
+const City = () => {
+  const f = useFormField('address.city')
+  return <input value={String(f.value ?? '')} onChange={(e) => f.setValue(e.target.value)} onBlur={f.onBlur} />
+}
+```
+
 ### Forms without JavaScript
 
 On a server-rendered page, `<AutoForm>` works with JavaScript disabled — or not

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 =