@voltro/cli 0.54.0 → 0.55.0

package/dist/{webhooksCommand-BvzXNHji.js → webhooksCommand-B1LVcyO3.js}

@@ -222,7 +222,7 @@ createVerifier({ secret: [process.env.WEBHOOK_SECRET, process.env.WEBHOOK_SECRET
 		...t === void 0 ? {} : { payload: t }
 	};
 }, S = u({ scope: "voltro:webhooks" }), C = ["--out", "--name"], w = async (e) => {
-	let { walk: t, loadDiscovered: n } = await import("./dev-cKUiZZsB.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
+	let { walk: t, loadDiscovered: n } = await import("./dev-DfVZaoys.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
 	return r((await n(await t(e))).events.map((e) => ({
 		file: e.file,
 		descriptor: e.descriptor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.54.0",
+  "version": "0.55.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -754,6 +754,18 @@
         "title": "WidgetKind gained 'array' and 'reference' — total widget registries need two new entries",
         "kind": "manual"
       },
+      {
+        "version": "0.55.0",
+        "id": "0.55.0/01_target-relations-declare-columns",
+        "title": "A target's `relations:` names the junction's two columns now, not just the table",
+        "kind": "manual"
+      },
+      {
+        "version": "0.55.0",
+        "id": "0.55.0/02_widget-kind-gained-rich-text",
+        "title": "WidgetKind gained 'rich-text' — total widget registries need one new entry",
+        "kind": "manual"
+      },
       {
         "version": "0.6.0",
         "id": "0.6.0/01_no-dev-session-secret",
@@ -836,24 +848,24 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.54.0",
-    "@voltro/cache": "0.54.0",
-    "@voltro/client": "0.54.0",
-    "@voltro/content": "0.54.0",
-    "@voltro/data-transfer": "0.54.0",
-    "@voltro/database": "0.54.0",
-    "@voltro/env": "0.54.0",
-    "@voltro/kv": "0.54.0",
-    "@voltro/logger": "0.54.0",
-    "@voltro/plugin-auth": "0.54.0",
-    "@voltro/plugin-broadcast": "0.54.0",
-    "@voltro/plugin-mail": "0.54.0",
-    "@voltro/plugin-storage": "0.54.0",
-    "@voltro/plugin-webhooks": "0.54.0",
-    "@voltro/protocol": "0.54.0",
-    "@voltro/runtime": "0.54.0",
-    "@voltro/serverless": "0.54.0",
-    "@voltro/workflow": "0.54.0",
+    "@voltro/ai": "0.55.0",
+    "@voltro/cache": "0.55.0",
+    "@voltro/client": "0.55.0",
+    "@voltro/content": "0.55.0",
+    "@voltro/data-transfer": "0.55.0",
+    "@voltro/database": "0.55.0",
+    "@voltro/env": "0.55.0",
+    "@voltro/kv": "0.55.0",
+    "@voltro/logger": "0.55.0",
+    "@voltro/plugin-auth": "0.55.0",
+    "@voltro/plugin-broadcast": "0.55.0",
+    "@voltro/plugin-mail": "0.55.0",
+    "@voltro/plugin-storage": "0.55.0",
+    "@voltro/plugin-webhooks": "0.55.0",
+    "@voltro/protocol": "0.55.0",
+    "@voltro/runtime": "0.55.0",
+    "@voltro/serverless": "0.55.0",
+    "@voltro/workflow": "0.55.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.md

@@ -730,7 +730,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.54.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.55.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |

package/templates/agent-docs/_index.md

@@ -9,7 +9,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.54.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.55.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |

package/templates/agent-docs/authentication.md

@@ -2617,10 +2617,14 @@ Optional, one line, and it buys back a feature the filter otherwise switches
 off for the whole app:
 
 ```ts
+const OWNED = new Set(['documents', 'comments'])
+
 setRowFilter({
   load,
-  predicate,
-  tables: ['bookmarks', 'recentSearches', 'todoSchedules', 'todoTags'],
+  predicate: (ctx, table) => (OWNED.has(table) ? eq('ownerId', ctx.userId) : undefined),
+  // Derived from the same set the predicate reads. Two hand-kept lists is the
+  // shape in which a table lands in exactly one of them.
+  tables: [...OWNED],
 })
 ```
 
@@ -2629,10 +2633,49 @@ is excluded for a subscription whose row set is re-resolved per delivery —
 replaying deltas could serve rows the subject has since lost. Without a
 declaration the framework cannot tell which tables your predicate may reach, so
 it excludes them all: one registration disables cheap reconnects for every
-subscription in the process. A deployment measured a filter over 4 tables
-costing it on all 173 of their query descriptors, 55 of whose source tables the
-filter never touches. With the declaration, only subscriptions on the listed
-tables are excluded.
+subscription in the process, including every one reading a table your predicate
+never returns anything for. With the declaration, only subscriptions on the
+listed tables are excluded.
+
+**What it does not buy, and this bounds the whole feature.** A subscription only
+has a delta chain when its executor returns a **descriptor**. One that returns a
+mapped value or a page envelope —
+
+```ts
+export default async ({ database }) => {
+  const rows = await database.notifications.where(...)
+  return { notifications: rows.map(toDto), hasMore: rows.length === 20 }
+}
+```
+
+— re-runs an opaque handler and emits snapshots, with or without a filter. So
+the count `tables:` gives back is the count of descriptor-returning
+subscriptions, not the number of queries in your app. Declare it anyway (it
+costs nothing, and it applies the moment such a query returns the builder), but
+measure before expecting a change.
+
+**How to see which of yours are which.** The two shapes are indistinguishable
+from the outside — a subscription that resumed and one that was never eligible
+both reconnect with rows on the screen. So the runtime records its own verdict
+at the moment it decides, per query label:
+
+```sh
+curl -s localhost:4000/_voltro/inspect/subscriptions | jq .resume
+```
+
+```json
+[
+  { "label": "documents.list", "resumable": 12, "excluded": {} },
+  { "label": "notifications.list", "resumable": 0, "excluded": { "computed": 8 } },
+  { "label": "comments.list", "resumable": 0, "excluded": { "row-filter": 3 } }
+]
+```
+
+A label appears once something has subscribed to it, so click through the app
+first. `computed` means no declaration can ever help that query; `row-filter`
+means the filter narrows its source and the exclusion is the point;
+`eager-load` means dropping the `.with(...)` would flip it. `voltro dev` also
+logs each verdict once per label under the `voltro:resume` scope.
 
 **Why a declaration and not a probe.** Resolving the scope at subscribe time
 and treating "returns `undefined` for this table" as safe is cheaper and

package/templates/agent-docs/cli.md

@@ -2969,17 +2969,67 @@ the swap could not run: 2 row(s) in the bundle reference a row the bundle does n
   The target is UNCHANGED — the swap runs in one transaction and none of it committed.
 ```
 
-Staging tables from a run that died mid-load are collected by the next
-`replace` over the same tables. One over a DIFFERENT set leaves them, and
-nothing else removes them:
+### Staging tables a dead run left behind
+
+A staged run RECORDS the scratch tables it creates, in the same
+`_voltro_replace_in_progress` table an interrupted destructive `replace` writes
+to — with one difference that matters: **a staging record never refuses a boot.**
+Nothing was destroyed, so there is nothing to refuse over. The boot reports
+instead:
+
+```
+staged data-import leftovers:
+  - 3 staging table(s) from a `replace` over api, last active 74 minute(s) ago — DROPPED: the run
+    is not resumable and has been silent long enough that nothing is loading into them.
+  The target of a staged `replace` is untouched until one short swap at the end, so none of this is
+  a reason to refuse the boot — it is a reason to know the disk is holding a copy of a bundle.
+```
+
+The run refreshes a heartbeat on that record every couple of seconds while rows
+land, which is what lets a boot tell the three cases apart:
+
+| what the record says | what the boot does |
+|---|---|
+| silent past the threshold, started without `--no-atomic` | **drops** the tables it names |
+| still beating | leaves them — an import is loading into them right now, here or on another replica |
+| started `--no-atomic` | leaves them — its staging IS the resume point |
+
+The threshold is `30` minutes by default. It is deliberately generous: the cost
+of collecting too early is that an in-flight import's swap fails with a missing
+table and you re-run it — the target is untouched either way — but the cost is
+still a re-run.
+
+Declare a different one for a deployment whose imports routinely pause longer
+than that, waiting on an upstream export or a maintenance window:
+
+```ts
+// app.config.ts
+export default {
+  dataTransfer: {
+    stagingStaleMinutes: 90,
+  },
+}
+```
+
+`VOLTRO_STAGING_STALE_MINUTES` overrides the declaration in turn — an operator
+acting on a running deployment outranks what the project declared. Note that the
+threshold decides only what a boot DROPS: leftover staging tables are named in
+the boot log either way.
+
+What the boot does NOT collect, you can:
 
 ```bash
 voltro data clear-staging --yes
 ```
 
-Deliberately a command and not a boot sweep: a booting process cannot tell a
-leftover from a staging table another replica is loading into right now, and
-deleting the second would destroy an import in flight.
+It now labels each table with what its own run says, so a resume point is
+distinguishable from a leftover before you drop it:
+
+```
+2 staging table(s) from an earlier `--mode replace`:
+    _voltro_staging_tasks — RESUMABLE: a `--no-atomic` re-run continues from it, last active 4 min ago
+    _voltro_staging_notes — no run claims it (an orphan, or from before the marker)
+```
 
 A **cycle** in the bundle's foreign keys is detected before the load, not after
 it. The swap inserts parents first, so two tables referencing each other cannot
@@ -3562,7 +3612,14 @@ A native run reports **blobs**, not rows: the vendor tool reports no row count w
 
 ### The provenance stamp — a restore that refuses the wrong DB
 
-A native dump is opaque: it doesn't say which dialect made it, which schema shape it carries, or when. `backup` writes a sidecar `voltro-backup-stamp.json` next to the artifact recording exactly that — `dialect`, the live schema `fingerprint`, the `@voltro/cli` version, and the timestamp.
+A native dump is opaque: it doesn't say which dialect made it, which schema shape it carries, or when. `backup` writes a sidecar `voltro-backup-stamp.json` next to the artifact recording exactly that — `dialect`, the `@voltro/cli` version, the timestamp, and **two** schema fingerprints.
+
+Two, because they are different facts and only one of them is a claim about the artifact:
+
+- **`schemaFingerprint`** — the source database's whole live schema at backup time. This is what the skew warning below compares against a target.
+- **`dumpFingerprint`** — the schema the **artifact carries**: that same snapshot minus the tables the dump excludes. On postgres and the mysql family those are `_voltro_replace_in_progress` and `_voltro_data_transfers` (see above); on sqlite, turso and mssql nothing is excluded and the two values are equal.
+
+The distinction is not bookkeeping. `voltro data backup` opens its own run row in `_voltro_data_transfers` *before* it dumps, so on any database the framework has run against, the artifact is two tables short of the live schema it was taken from. Anything comparing a restored schema against a stamped one has to compare against `dumpFingerprint` — the drill did not, and failed every healthy backup with *"the artifact is inconsistent."*
 
 `restore` reads the stamp **before touching the DB** and acts on two failures that are otherwise silent until they corrupt:
 
@@ -3578,13 +3635,39 @@ voltro data restore ./backups/2026-07-01 --drill --drill-url postgres://…/scra
 # or set DRILL_DB_URL and just: voltro data restore ./backups/2026-07-01 --drill
 ```
 
-`--drill` restores the artifact into a **throwaway** database (from `--drill-url` / `DRILL_DB_URL`) and verifies it — **without ever touching the live DB**. It refuses a drill target that resolves to your live connection (a drill that `--clean`s production is the disaster it exists to rehearse against). After the restore it introspects the throwaway DB and compares its schema fingerprint to the backup's stamp:
+`--drill` restores the artifact into a **throwaway** database (from `--drill-url` / `DRILL_DB_URL`) and verifies it — **without ever touching the live DB**. It refuses a drill target that resolves to your live connection (a drill that `--clean`s production is the disaster it exists to rehearse against). After the restore it introspects the throwaway DB and probes its migration ledger:
 
 - **zero tables restored** → FAIL (the dump is empty or unreadable — this backup would not recover you),
-- **fingerprint disagrees with the stamp** → FAIL (the restore didn't reproduce what was backed up),
-- **tables + matching fingerprint** → PASS.
+- **schema fingerprint disagrees with the stamp's `dumpFingerprint`** → FAIL (the restore didn't reproduce what was backed up),
+- **`_voltro_migration_plans` restored EMPTY** → FAIL (see below),
+- **tables + matching fingerprint + a populated or absent ledger** → PASS.
+
+A stamp too old to carry a `dumpFingerprint` gives a **PASS (partial)** that says the shape could not be cross-checked. It does not fall back to `schemaFingerprint`: that is the comparison that fails a healthy backup, and a check that is red on every real input gets switched off — taking its genuine failures with it.
+
+It exits non-zero on any FAIL, so a scheduled CI job turns a silently-broken backup into a red build. Run it against your latest artifact on a cron — a backup you've never restored is a hypothesis, and this is how you keep it a fact.
+
+#### The ledger check — the one thing a schema comparison cannot see
+
+A fingerprint answers *"is the shape right?"*. A drill's real question is *"would my app come up against this?"*, and the gap between them is **content** — a framework table that restored with the right columns and the wrong rows.
+
+`voltro serve`'s boot gate reads the newest row of `_voltro_migration_plans` and refuses with `prod-mismatch` when there is none. So a ledger table that restores with exactly the right columns and **zero rows** is a database no source tree can boot, and its schema fingerprint is identical to a healthy one's. The drill fails that, and names it:
+
+```
+FAIL — restored 30 table(s) with the right shape, but `_voltro_migration_plans`
+       came back EMPTY.
+       `voltro serve` reads the newest row of that table as its boot gate and
+       refuses with `prod-mismatch` when there is none.
+```
+
+A restored database with **no ledger table at all** is not a voltro-managed schema (a hand-made dump, someone else's database) — the drill says so and claims nothing about booting it, rather than failing it.
+
+What the drill deliberately does **not** judge is a ledger whose fingerprint differs from what your code declares. It has no way to know which commit you will deploy next to this database, and `voltro db apply` clears that state anyway; failing a backup for it would make the drill red for a reason that is not about the backup.
+
+#### Why there is no full app boot
+
+Booting a real app against the restored database sounds like the stronger check, and it would be a weaker one. There is no app in the drill's path — it would have to boot a **fixture**, and a fixture booting says nothing about whether *your* app boots. It moves the drill from *"proves your backup"* to *"proves our fixture"* while reading as the bigger claim.
 
-It exits non-zero on any FAIL, so a scheduled CI job turns a silently-broken backup into a red build. Run it against your latest artifact on a cron — a backup you've never restored is a hypothesis, and this is how you keep it a fact. (The verify is schema-level; a full app boot against the restored DB is a heavier check you can layer on top.)
+The part worth having does not need a process: the boot gate is a comparison, not a startup sequence, so the one boot-fatal condition that holds regardless of which code you deploy is reachable with a `SELECT`. That is the ledger check above.
 
 ### Point-in-time recovery (PITR) is your database's job, not the framework's
 

package/templates/agent-docs/data.md

@@ -431,6 +431,15 @@ between acting on it and learning to skim it:
   recorder resolves it through the relation registry instead, target and (for a
   many-to-many) junction alike. A write to the junction changes membership,
   which is exactly the change a user makes.
+- **A `crud.*` executor is watched exactly like a hand-written one** — and it is
+  the case that needs it most. `crud.list('tasks', { include: { subTasks: true } })`
+  reads a table your own file never names, so there is nothing in front of you to
+  check `source:` against. The descriptor stays yours either way: `crud.*` supplies
+  only the executor, you write the `source:` beside it. `crud.count` counts as a
+  read too — it returns a number rather than rows, but an insert changes that
+  number, so the counted table belongs in `source:` or "page 3 of 12" stops moving.
+  `crud.create` / `update` / `remove` issue no read at all and never produce a
+  finding.
 - **A table read only to NARROW a result is not counted** — a parent reached
   through `inSubquery(...)`, or a read the framework made to resolve your row
   filter. Those decide which rows come back rather than contributing rows, and
@@ -733,9 +742,12 @@ is always present (the fallback stands in until the first snapshot) and `loading
 is a plain boolean reporting the true state. There is nothing to narrow.
 
 **Errors.** `loading` means **no data has arrived yet** — it is not a claim that
-the subscription is healthy. A **cold-start** failure (nothing ever arrived)
-leaves `loading` true *and* sets `error`, so a component that branches on
-`loading` alone renders a skeleton forever; check `error` to break out of it. A
+the subscription is healthy. A **cold-start** failure (nothing ever arrived) is
+its own state: `loading` is `false`, `failed` is `true`, and `error` is
+non-optional there, so branching on `loading` alone can no longer render a
+skeleton forever. (It used to leave `loading` true, and the type's own comment
+predicted the consequence — the fix was to stop making `loading` mean two
+things rather than to keep warning about it.) A
 failure AFTER data arrived deliberately does NOT replace good data with an error
 banner (a transient websocket hiccup would blank a working screen); those reach
 the api's error bus instead — subscribe with `useOnRpcError` for
@@ -1119,7 +1131,13 @@ export const employeesUpdate = defineMutation({
   target: {
     table: 'employees',
     op: 'update',
-    relations: { assignedStores: 'employee_assigned_stores' },
+    relations: {
+      assignedStores: {
+        junction: 'employee_assigned_stores',
+        anchorColumn: 'employeeId',   // the junction reference() pointing at `employees`
+        targetColumn: 'storeId',      // the junction's other reference()
+      },
+    },
   },
 })
 ```
@@ -1127,9 +1145,7 @@ export const employeesUpdate = defineMutation({
 After the executor succeeds, `input.assignedStores` is reconciled against the
 junction via the diff-based link writer (`store.relationLinks`): missing rows
 inserted, surplus rows deleted, unchanged rows untouched — so reactive
-subscriptions on the junction see one change per changed row. The anchor
-column is derived from the junction's `reference()` targets; a self-junction
-(both columns referencing one table) is refused by name, never guessed.
+subscriptions on the junction see one change per changed row.
 
 The semantics worth knowing: an ABSENT input field leaves the links
 untouched — absent is not empty; an empty array is the explicit "clear them
@@ -1137,6 +1153,34 @@ all". The row id comes from the executor's `output.id`, falling back to
 `input.id`. The link writes go through `ctx.store`, so undo capture and
 cross-table rules see them like any other write.
 
+### The same declaration drives the optimistic update
+
+A junction change used to reach the browser only with the server delta — so on
+one submit the renamed title flipped immediately and the assigned stores sat on
+their old value until the roundtrip landed. It does not any more: `useMutation`
+reconciles the junction rows of every subscription sourced on `junction` the
+moment the mutation is sent, against the same `input[field]` the server will
+write.
+
+It is a diff, not a redraw: a surviving link keeps its own row (and its real
+id), a surplus link disappears, and only a genuinely new link is a staged
+optimistic row. The patches ride the ordinary optimistic lane — reverted if the
+mutation fails, kept after it succeeds until the server data actually moves.
+Nothing is on a timer.
+
+Client-side the anchor id is `input.id`; for an `insert` it is the same
+optimistic id the new row was stamped with, since the server's `output.id` is
+not knowable before the response arrives.
+
+**Why you state the two columns.** The optimistic patch runs in the BROWSER, and
+the browser cannot import your `db/` schema — `@voltro/database` is server-only
+by construction — so the junction's two `reference()` columns cannot be derived
+there. `anchorColumn` is the one pointing at the target's own table;
+`targetColumn` is the other. They are not taken on trust: before it writes, the
+server compares your declaration against the junction's real reference columns
+and refuses, naming the correct pair, if they disagree. A self-junction (both
+columns referencing one table) is still refused by name, never guessed.
+
 ## Typed Errors
 
 ```ts
@@ -2065,7 +2109,8 @@ the resume window (`reactive.resume.windowMs`, default 60 s) the server replays
 **only the deltas the client missed** — the re-subscribe presents the last
 materialised revision and the stream continues on the same revision line, so a
 short offline gap costs a handful of patches instead of every row. Outside the
-window, for computed queries, for row-filtered apps, or whenever anything is in
+window, for computed queries, for a subscription whose source table a
+registered row filter may narrow, or whenever anything is in
 doubt, the query answers with a fresh snapshot — the delta-resume wire contract
 lives in [the wire protocol](/docs/data/wire-protocol#reconnect-delta-resume).
 
@@ -5022,11 +5067,17 @@ A resume is declined — always with a fresh snapshot — when:
   keeps delta-resume on every subscription whose source is not in that set —
   the common case, since most filters narrow a handful of tables. Without the
   declaration the framework cannot know which tables the predicate may reach
-  and excludes them all, which is what a deployment measured as one filter over
-  4 tables costing the feature on all 173 of their queries. Eager loads are
-  excluded wholesale because a relation resolves below the seam that narrows.
-  They reconnect with a fresh
-  snapshot, exactly as before.
+  and excludes them all. Eager loads are excluded wholesale because a relation
+  resolves below the seam that narrows. They reconnect with a fresh snapshot,
+  exactly as before.
+
+**Which of your queries actually got a ring** is recorded per label, since the
+excluded and the never-eligible look identical on the wire:
+`/_voltro/inspect/subscriptions` returns a `resume` array of
+`{ label, resumable, excluded }`, and `voltro dev` logs each verdict once under
+the `voltro:resume` scope. A `computed` verdict is the one worth reading first:
+it means the executor returns a value rather than a descriptor, so no row-filter
+declaration can ever change it.
 
 **Author a live-subscribed getter to return, not throw.** A subscription is a
 long-lived stream, so a getter that throws on every re-evaluation is a broken

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).
 

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`: