@voltro/cli 0.21.0 → 0.22.1

package/dist/serveEntry.js

@@ -1,5 +1,5 @@
-import { X as e } from "./inspectMetrics-DMjWBQif.js";
+import { X as e } from "./inspectMetrics-9ZSuDeqD.js";
 import { c as t } from "./seedRunner-D6eu-u5U.js";
 import { r as n } from "./appModuleLoader-C9r9mxZt.js";
-import { t as r } from "./serveCommand-qHJCs0cX.js";
+import { t as r } from "./serveCommand-DXJOARkO.js";
 export { e as loadDotEnv, n as registerAppModules, t as registerDriver, r as runServe };

package/dist/{start-B1x6Z60h.js → start-CsIjcOi-.js}

@@ -1,5 +1,5 @@
-import { $ as e, C as t, E as n, G as r, H as i, J as a, P as o, Q as s, R as c, U as l, V as u, W as d, _ as f, a as p, at as m, b as ee, c as h, ct as g, dt as _, et as te, f as v, ft as y, g as ne, h as b, i as re, j as ie, m as x, nt as S, o as ae, p as C, pt as w, q as T, r as E, s as D, t as O, tt as k, ut as A, v as j, w as oe, y as M } from "./inspectMetrics-DMjWBQif.js";
-import { D as se, E as ce, T as le, a as N, p as ue, w as de } from "./inspect-Dwx0_tUj.js";
+import { $ as e, C as t, E as n, G as r, H as i, J as a, P as o, Q as s, R as c, U as l, V as u, W as d, _ as f, a as p, at as m, b as ee, c as h, ct as g, dt as _, et as te, f as v, ft as y, g as ne, h as b, i as re, j as ie, m as x, nt as S, o as ae, p as C, pt as w, q as T, r as E, s as D, t as O, tt as k, ut as A, v as j, w as oe, y as M } from "./inspectMetrics-9ZSuDeqD.js";
+import { D as se, E as ce, T as le, a as N, p as ue, w as de } from "./inspect-_ldwsAwH.js";
 import { t as fe } from "./bootTiming-BdyP9nYw.js";
 import { dirname as pe, extname as P, join as F, resolve as I } from "node:path";
 import { fileURLToPath as L, pathToFileURL as R } from "node:url";
@@ -940,7 +940,7 @@ CREATE INDEX IF NOT EXISTS ${e}_servable_until_idx ON ${e} (servable_until);
 				}), t.end(JSON.stringify({ error: "inspect disabled (VOLTRO_INSPECT=off)" }));
 				return;
 			}
-			let i = N(a);
+			let i = N(a, "GET");
 			if (!i.ok) {
 				t.writeHead(401, {
 					"content-type": "application/json",

package/dist/startEntry.js

@@ -1,3 +1,3 @@
-import { X as e } from "./inspectMetrics-DMjWBQif.js";
-import { t } from "./start-B1x6Z60h.js";
+import { X as e } from "./inspectMetrics-9ZSuDeqD.js";
+import { t } from "./start-CsIjcOi-.js";
 export { e as loadDotEnv, t as runStartCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.21.0",
+  "version": "0.22.1",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -62,22 +62,22 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.21.0",
-    "@voltro/cache": "0.21.0",
-    "@voltro/data-transfer": "0.21.0",
-    "@voltro/database": "0.21.0",
-    "@voltro/env": "0.21.0",
-    "@voltro/kv": "0.21.0",
-    "@voltro/logger": "0.21.0",
-    "@voltro/plugin-auth": "0.21.0",
-    "@voltro/plugin-broadcast": "0.21.0",
-    "@voltro/plugin-mail": "0.21.0",
-    "@voltro/plugin-storage": "0.21.0",
-    "@voltro/plugin-webhooks": "0.21.0",
-    "@voltro/protocol": "0.21.0",
-    "@voltro/runtime": "0.21.0",
-    "@voltro/serverless": "0.21.0",
-    "@voltro/workflow": "0.21.0",
+    "@voltro/ai": "0.22.1",
+    "@voltro/cache": "0.22.1",
+    "@voltro/data-transfer": "0.22.1",
+    "@voltro/database": "0.22.1",
+    "@voltro/env": "0.22.1",
+    "@voltro/kv": "0.22.1",
+    "@voltro/logger": "0.22.1",
+    "@voltro/plugin-auth": "0.22.1",
+    "@voltro/plugin-broadcast": "0.22.1",
+    "@voltro/plugin-mail": "0.22.1",
+    "@voltro/plugin-storage": "0.22.1",
+    "@voltro/plugin-webhooks": "0.22.1",
+    "@voltro/protocol": "0.22.1",
+    "@voltro/runtime": "0.22.1",
+    "@voltro/serverless": "0.22.1",
+    "@voltro/workflow": "0.22.1",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.md

@@ -595,7 +595,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.21.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.22.1** | `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.21.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.22.1** | `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/cli.md

@@ -495,10 +495,11 @@ Three checks run at boot and print one line each when they have something to say
 - **`apiKeys: true` with no `apikeys:issue:*` scope declared.** The capability is
   on and reachable by nobody; every issue request fails its guard.
 
-`voltro doctor` adds a fourth, over your source: an executor that writes
-`ctx.request.subject.id` while naming no guard, which is how an anonymous caller
-reaches a NOT NULL column and gets a raw statement failure instead of a typed
-refusal.
+`voltro doctor` adds a fourth, over your source: its **authz scan** asks of every
+executor — queries included — whether it references an access check at all, and
+lists the ones that reference none. It learns your own `require*` / `assert*`
+guard names, so it does not report the call sites of guards you already wrote.
+See [the authz scan](./build-and-start.md).
 
 ## `voltro dev <appDir>`
 
@@ -776,6 +777,32 @@ The restart is a full re-exec — there is no in-process hot-reload of a
 handler body; editing a query's executor respawns the child (debounced
 80ms, so a burst of saves collapses into one restart).
 
+### How the old process is stopped
+
+SIGTERM first. The child runs its teardown — plugin `onDeactivate`, the
+CDC detach, the scheduler and workflow runtime, the connection pool, and
+every `ctx.onShutdown(cb)` a `*.startup.ts` registered — and then exits.
+That is normally tens of milliseconds and you never see it.
+
+It gets **1.5 seconds**, then SIGKILL, and the escalation says so:
+
+```text
+child ignored SIGTERM — escalated to SIGKILL   pid=41207
+```
+
+Read that as "something in this app's shutdown does not complete" — a
+pool draining against a database that is already gone, a plugin
+`onDeactivate` waiting on a dead socket. The restart still happens; it
+just costs the full grace window every time, and whatever teardown had
+not finished was cut off. Worth fixing at the source rather than living
+with, because the same hang is a slow — then failed — shutdown in
+production.
+
+Neither timeout is optional: a stop that can wait forever is a dev
+server that stops restarting entirely, with the old process still
+holding the port and your browser's websocket still attached to code you
+edited minutes ago.
+
 ## When the dev server stops
 
 A restart replaces the child; the supervisor keeps watching. When the dev
@@ -1015,6 +1042,65 @@ Docker step) and prints the exact remedy: add a `voltro build .` step before
 `voltro serve .`. Drop it into your image build right after `voltro build` to
 guarantee the artefact is present before the image ships.
 
+### The authz scan
+
+`voltro doctor` answers one mechanical question over every executor: **does it
+reference an access check at all?**
+
+```
+authz scan · 586 executor(s)
+  ✗ no access check                          21
+  ⚠ inline ownership check, no named guard   24   (informational)
+  ✓ guards: on the descriptor                 0
+  ✓ calls a guard from the vocabulary       320
+  – accepted as recorded debt               221   (voltro-authz-allowlist.txt)
+
+  ✗ teams.deleteSubTeam  — deletes teams with nothing constraining WHICH row
+      api/teams/deleteSubTeam.mutation.server.ts
+```
+
+It scans **queries and streams too**, not only writes: an executor that takes an
+id and returns the row is the same hole as one that writes it. The exploitable
+shape is "acts on a row the client named, without comparing anything on that row
+to the caller", and a read has it.
+
+**It learns your guard names.** An exported `require*` / `assert*` from your own
+source counts as a guard, so `requireTeamAccess()` is recognised without any
+configuration. Without that the scan would report every call site of your own
+guards, which is the failure mode that makes a check ignorable.
+
+**An inline ownership check is informational.** `row.userId !== subject.id → new
+AccessDeniedError({})` is correct code — it is listed so you can see where the
+rule lives in a handler rather than on a descriptor, and it never fails the run.
+
+Findings are ordered by blast radius: a `delete` outranks an `insert`, and a
+target table that is `tenant()`-scoped or referenced by other tables outranks one
+that is neither.
+
+#### The ratchet — how to adopt this on an existing app
+
+A first run on a large app reports hundreds of handlers, and nobody triages
+hundreds of findings. So record them once and fail only on what comes after:
+
+```bash
+voltro doctor --write-authz-allowlist    # writes voltro-authz-allowlist.txt
+voltro doctor                            # exits 1 on anything NEW
+```
+
+The file is **debt, not approval** — every line is a handler nobody has confirmed
+is safe. It is keyed by rpc tag rather than path, so moving a file can neither
+re-open a hole nor hide one, and it is consulted **last**: an executor that gains
+a real guard is reported as guarded whether or not its line is still there. The
+list can only shrink unless someone adds to it deliberately.
+
+#### Before you hand-roll another check
+
+If your checks are imperative because a scope cannot express "may this subject
+act on THIS row", that is what `guards: [{ action, resourceType, resource }]` is
+for — and an app whose relationships live in its own tables (a `teamMembers` row,
+say) registers its own tuple source instead of copying data into a framework
+table. See [Authorization](../authentication/authorization.md).
+
 ### The predicate-column check
 
 `eq` / `isNull` / `inSet` are free functions, so the column name arrives as a bare
@@ -1552,7 +1638,34 @@ voltro check             --url https://api.example.com
 
 ## The inspect HTTP surface
 
-Every `voltro dev` / `voltro start` instance exposes a read-only introspection surface under `/_voltro/inspect/*`. The [Voltro Dashboard](/docs/observability/dashboard) consumes it to render the route sitemap, RPC list, subscription panel, workflow runs, and metrics. You can also hit the endpoints directly with `curl` (the `voltro inspect` subcommands above are the thin wrapper over exactly these).
+Every `voltro dev` / `voltro start` instance exposes an introspection surface
+under `/_voltro/inspect/*`.
+
+**It is not read-only.** The core endpoints are reads, but installed plugins
+mount their own — and some are POSTs that DO things: `plugin-governance` mounts
+`/erase` (an irreversible GDPR right-to-be-forgotten deletion) and `/export` (a
+full personal-data dump); `plugin-storage` mounts `/share` and `/revoke`.
+
+**So a mutating method needs a second credential.** `VOLTRO_INSPECT_WRITE_TOKEN`,
+sent as the `x-voltro-inspect-write` header ON TOP of the bearer — an additional
+factor, not an alternative: the read token still has to be correct. GET / HEAD /
+OPTIONS are unaffected. Unset, those endpoints are refused.
+
+```sh
+curl -H "authorization: Bearer $VOLTRO_INSPECT_TOKEN" \
+     -H "x-voltro-inspect-write: $VOLTRO_INSPECT_WRITE_TOKEN" \
+     -X POST http://localhost:4000/_voltro/inspect/plugins/governance/erase
+```
+
+`voltro dev` mints it per project like the read token, and the dashboard proxy
+injects it for loopback targets, so the dev loop is unchanged. **Nothing mints it
+for `serve` / `start`** — in production a destructive endpoint should take a
+deliberate act to enable. Use a DIFFERENT value from the read token; reusing it
+gives the split no meaning.
+
+A plugin mounting a non-GET inspect endpoint must also declare the
+`inspect:write` permission, and the boot audit refuses it otherwise. That governs
+what a PLUGIN may mount; the write credential governs who may call it. The [Voltro Dashboard](/docs/observability/dashboard) consumes it to render the route sitemap, RPC list, subscription panel, workflow runs, and metrics. You can also hit the endpoints directly with `curl` (the `voltro inspect` subcommands above are the thin wrapper over exactly these).
 
 ```bash
 PORT=4000   # from the app's app.config.ts

package/templates/agent-docs/data.md

@@ -328,6 +328,32 @@ defineMutation({ name: 'notes.create', target: { table: 'notes', op: 'insert' },
 
 With that pairing, `useMutation('app', 'notes.create')` can stage an optimistic row in active `notes.list` caches without client-side cache plumbing.
 
+### A guard that reads a second table belongs in `source`
+
+`source` is the reactive trigger set: the query re-runs when a listed table
+changes, and only then. So a guard that loads a row from ANOTHER table to decide
+access has made that table part of what the result depends on:
+
+```ts
+export const teamBoard = defineQuery({
+  name: 'boards.forTeam',
+  input: Schema.Struct({ teamId: Schema.String }),
+  output: BoardRows,
+  // `boards` alone is wrong here — `requireTeamAccess` reads `teamMembers`.
+  source: ['boards', 'teamMembers'],
+})
+```
+
+Leave `teamMembers` out and the subscription does not re-run when membership
+changes. **That is an authorization staleness, not a cosmetic one:** revoke
+someone's membership and their open subscription keeps serving rows they may no
+longer see, until something else happens to invalidate it.
+
+Nothing warns about this at runtime — a query that silently stops reacting looks
+exactly like one with nothing to report. Reported by a team whose own invariant
+caught it after five computed queries under-declared their `source`; the fix was
+array sources.
+
 ## `output` is the serializer — `timestampMs`
 
 A descriptor's `output` is not documentation of the shape. It **is** the
@@ -951,6 +977,38 @@ const message = matchError(err, {
 }, () => 'Something went wrong')
 ```
 
+## `internal: true` — off the wire entirely
+
+Every discovered `*.mutation.ts` / `*.query.ts` / `*.action.ts` / `*.stream.ts` is
+callable over the WebSocket by any authenticated browser session. `publicApi` and
+`exposeAsTool` opt IN to wider surfaces; `internal: true` opts OUT of the default
+one:
+
+```ts
+export const createFromAction = defineMutation({
+  name: 'auditLog.createFromAction',
+  input: Schema.Struct({ actorId: Schema.String, eventType: Schema.String }),
+  output: Schema.Void,
+  internal: true,
+})
+```
+
+It is not emitted into `rpcGroup.generated.ts`, and neither `voltro dev` nor
+`voltro serve` registers a route — the tag is unroutable over `/rpc` and the
+WebSocket. Server code calls it by importing its executor directly.
+
+**A naming convention is not a boundary.** One app had grown 18 procedures named
+`*Internal`, meaning "only other server code calls this"; all 18 were in the
+client group, and one of them accepted `actorId` / `actorEmail` / `actorType`
+from the caller and wrote an audit row. No guard, zero callers, reachable by
+anyone logged in. If the only thing keeping a procedure off the wire is that
+nobody wrote a client call for it, it is on the wire — the same reasoning as
+`.serverOnly()` on a column, one level up.
+
+**It is not a substitute for a guard.** An internal procedure still runs with
+whatever authority its caller has. This removes the wire surface, not the need to
+check who is asking; `voltro doctor`'s authz scan still covers it.
+
 ## When Not To Use A Mutation
 
 - **External I/O.** Use an action or workflow.

package/templates/agent-docs/database/migrations.md

@@ -90,6 +90,7 @@ voltro db apply                   # execute (dev only — refuses on NODE_ENV=pr
 voltro db apply --note '...'      # apply with a freeform note recorded in history
 voltro db plans [--limit 20]      # history from _voltro_migration_plans, newest first
 voltro db drift                   # live-vs-baseline check — exit 0 match, 3 no baseline, 4 drift
+voltro db drift --accept          # record the CURRENT live schema as the baseline (refuses unless db plan is empty)
 voltro db squash --before <date>  # consolidate history into one snapshot
 voltro db restore-snapshot <id>   # restore VOLTRO_SOFT_DROP=1 columns from a plan
 
@@ -119,6 +120,21 @@ there is no `--json` or `--sql`, and `voltro db apply` takes only
 deploy step ([prod pipeline](./prod-pipeline.md)), not a pre-serialised
 plan file.
 
+## Framework tables ride the same differ
+
+The `_voltro_*` tables the framework owns are planned, classified and applied by
+exactly the same code as yours — on every dialect. A framework release that adds
+a table, adds a column or reshapes one lands on the boot that follows your
+upgrade, wherever your own schema changes land. There is no separate command and
+no dialect-specific step.
+
+One asymmetry is deliberate and worth knowing if you ever read a plan: a
+framework-owned table that **nobody declares** — `cluster_*` from the workflow
+engine, a plugin's table after you removed the plugin — is never planned for a
+drop. "Nobody declared it, so do not drop it" and "we declare it, so keep it
+current" are different rules; collapsing them is what once made framework tables
+evolve on postgres and nowhere else.
+
 ## Where to go next
 
 | Topic | Page |
@@ -367,6 +383,92 @@ If the live DB doesn't have a column called `firstName`, the marker is a no-op:
 
 The marker isn't validated against the live DB at schema-build time — it would have to introspect during type-checking, which is expensive. The runtime check fires at plan time.
 
+## The indexes come with it
+
+Renaming a column is a metadata-only operation. Its **indexes** used to not be: index names are derived (`<table>_<column>_idx`), and no dialect renames an index when the column under it is renamed — so the planner saw `users_firstName_idx` on one side and `users_givenName_idx` on the other, and planned `DROP INDEX` + `CREATE INDEX`. On a large table that is a full B-tree rebuild: minutes of IO, and without `CONCURRENTLY` a write lock, behind a rename that was supposed to be instant.
+
+The planner now folds that into a `rename-index` operation, which is a catalog-only statement everywhere it is emitted:
+
+```
+✓ rename-column users.firstName → users.givenName   # catalog-only
+✓ rename-index  users_firstName_idx → users_givenName_idx   # catalog-only, no rebuild
+```
+
+You do not annotate anything for this — it follows from the column rename you already declared.
+
+Four cases deliberately still plan as drop + create, because pairing an old index with a new one has no evidence to stand on in them:
+
+- **sqlite** — it has no rename statement at all. The plan you read matches what runs.
+- **UNIQUE indexes** — they are constraint objects, and the syntax to rename one diverges by dialect.
+- **Expression / json-path indexes** — the database normalises their key text, so there is no shape to compare; only the name, which is the thing that changed.
+- **Two same-shaped indexes renamed at once** — nothing says which became which. Rebuilding both is slower; renaming the wrong one is worse.
+
+## Renaming a TABLE
+
+The same problem one level up, and with more at stake: a table rename and a
+drop+create look identical to the differ — old table gone, new table present —
+except that guessing wrong costs every row. So it needs a marker too, and it
+reads like its column counterpart:
+
+```ts
+// Before:
+export const notes = table('notes', { id: id({ prefix: 'note' }), body: text() })
+
+// After — without the marker:
+export const notes = table('archive_notes', { id: id({ prefix: 'note' }), body: text() })
+// → planner sees DROP TABLE notes + CREATE TABLE archive_notes
+// → the DROP is `lossy` and blocked; nothing happens until you acknowledge it
+
+// With the marker:
+export const notes = table('archive_notes', { id: id({ prefix: 'note' }), body: text() })
+  .renamedFrom('notes')
+// → one `rename-table` op, classified `safe`
+// → `ALTER TABLE notes RENAME TO archive_notes` — catalog-only, the rows stay put
+```
+
+Unlike an index rename, every dialect has this statement — sqlite included — so
+there is no dialect on which this falls back to a rebuild.
+
+**Its indexes come with it.** The same derivation that bites a column rename bites
+harder here: `notes_pkey` and `notes_<col>_idx` are named after the table, and no
+dialect renames them when the table is renamed. The planner emits a `rename-index`
+for each so the catalog catches up:
+
+```
+✓ rename-table  notes → archive_notes
+✓ rename-index  notes_pkey → archive_notes_pkey
+```
+
+Without that the plan would try to drop the primary-key index and re-add it as a
+plain UNIQUE, which postgres refuses outright.
+
+**Three cases where the planner will NOT fold the rename**, each because folding
+it could destroy data rather than move it — and none of them is silent:
+
+- **The old name is still declared by something.** If your schema still has a
+  `notes` table, it is yours and stays put; the new table is created empty. This
+  is a legitimate outcome (it is what lets a framework plugin reclaim a name
+  without taking yours), so the plan runs — and the `create-table` line says why
+  the marker was not applied.
+- **The new name already exists in the database.** → **refuses to plan.** Both
+  tables exist and only you know which holds the real rows. The fix tells you to
+  move them and drop one, or drop the empty one so the rename can run. Until
+  then the old table is untouched.
+- **Two tables both claim the same old name.** → **refuses to plan.** Nothing
+  says which should receive the rows; remove the marker from all but one.
+
+The last two refuse rather than degrade, because the quiet outcome — an empty
+plan reading "schema up to date" while the old table still holds every row — is
+the one that loses data by inaction.
+
+**Lifecycle.** Same as `.renamedFrom()` on a column: a marker whose old table is
+not in the database is a silent no-op, so it stays in your source across a staged
+rollout and comes out once every environment has applied it.
+
+**One constraint worth knowing:** a table whose name starts with `_` cannot derive
+a typeid prefix, so it needs an explicit `id({ prefix: '…' })`. You will hear about
+it at declaration, not at runtime.
+
 ## Lifecycle — when to remove the marker
 
 Keep the marker until the rename has been applied in EVERY env you care about (dev, staging, prod). The framework tracks applied ops in `_voltro_migration_plans`:
@@ -2067,9 +2169,24 @@ db drift: live schema DIVERGED from last applied state
 Something changed the live schema after the last apply. This command can see
 THAT it changed, not what or who — the fingerprints are hashes, not a diff.
 
-To reconcile, run `voltro db plan` to see what your code expects vs the live DB.
+Your DECLARED schema is already satisfied — `voltro db plan` reports 0 operations
+against this database. So the live schema is not wrong, only unrecorded: something
+applied a change without going through the planner (a hand-run ALTER, a DBA
+window, a restored dump), or it touched a table your code does not declare.
+
+If that was deliberate and the schema is right, record it:
+
+    voltro db drift --accept
+
+It updates the latest ledger row's baseline to the live schema and invents no
+history entry. Drift then measures from here.
 ```
 
+When `db plan` is NOT empty it says that instead, with the count — so the two
+cases are told apart by the command rather than left to you. It used to close by
+asserting that a zero-operation plan meant "a table your code does not declare",
+which is one of two possibilities and the less likely one.
+
 ### Out-of-band auto-applier
 
 Multiple tools applying to the same DB (the framework + a separate Flyway / Liquibase process / hand-written deploy script). The other tool's changes don't go through `_voltro_migration_plans`.
@@ -2084,31 +2201,36 @@ The drift detector ran against a read-replica that's lagging. Wait for the repli
 
 ## Reconciliation paths
 
-### Path 1 — adopt the live state by declaring it in TS
+### Path 1 — accept the live state
 
-When the live DB IS what you want (the manual DDL is correct, only
-bypassing the planner was sloppy), bring the declared schema up to the
-live shape: edit the `*.entity.ts` files so they describe exactly what
-the live DB now has. The next `voltro db plan` then diffs empty, and a
-`voltro db apply` records a fresh `_voltro_migration_plans` row at the
-new fingerprint — re-baselining history without any DDL.
+When the live DB IS what you want (the manual DDL is correct, only bypassing the
+planner was sloppy), first make sure your declaration says so: edit the
+`*.entity.ts` files until `voltro db plan` diffs empty. Then record the live
+schema as the baseline:
 
 ```sh
-voltro db plan    # confirm the diff is now empty (declared == live)
-voltro db apply --note 'accepting manual DDL from 2026-06-15 — see ticket #789'
+voltro db plan            # must report 0 operations — declared == live
+voltro db drift --accept
 ```
 
-`voltro db apply` with an empty plan writes no DDL; it just locks in
-the current fingerprint with your note. The history shows it:
+`--accept` writes the current live fingerprint onto the newest ledger row.
+Drift measures from there, and the next `voltro db drift` exits 0.
 
-```
-plan_mig_5k79  fp=a8f2c9d1  env=dev  src=auto-diff  0 op(s)  12ms  ...  by=alice
-  [note: accepting manual DDL from 2026-06-15 — see ticket #789]
-```
+**It refuses unless `db plan` is empty**, and that guard is the whole point.
+Accepting a schema with operations still outstanding would record "this is what
+we applied" over a state nobody applied, and every later drift check would
+measure against that fiction. If operations are pending, run `voltro db apply` —
+that applies them AND writes a real baseline of its own.
+
+It backfills the newest row rather than inserting one, because no migration ran
+and a history entry claiming otherwise would be worse than the gap it fills.
 
-There is no metadata-only `--reconcile` flag — re-baselining always
-goes through the declare-then-apply loop, so the TS schema stays the
-single source of truth.
+**An empty `voltro db apply` does NOT re-baseline an existing baseline.** It
+writes no DDL and no history row, so there is nothing for a `--note` to attach
+to — it will tell you the note was ignored rather than swallow it. (It does fill
+a baseline that is still NULL, which is a different case: a database that never
+had one.) `--accept` is the command whose job is to say "the live schema is
+right, the ledger just did not know".
 
 ### Path 2 — corrective plan against drift
 
@@ -2206,7 +2328,7 @@ The hardest part of drift response is figuring out **what** changed + **who** di
 ```
 Detect:    voltro db drift
 Fix code:  voltro db apply   (apply corrective plan from current diff)
-Adopt DB:  edit the *.entity.ts to match live, then voltro db apply (empty plan re-baselines)
+Adopt DB:  edit the *.entity.ts to match live until db plan is empty, then voltro db drift --accept
 Backup:    if data was lost, restore from your DB backup system — the framework can't help
 ```
 

package/templates/agent-docs/plugins.md

@@ -92,7 +92,7 @@ Status legend: ✓ shipped · ◐ partial · — planned.
 | `@voltro/plugin-openapi` | ✓ | OpenAPI 3.1 spec (`GET /openapi.json`) + Swagger-UI (`GET /docs`) generated from `defineRestRoute` descriptors AND (opt-in) rpc procedures (queries/mutations/actions/streams → `POST /rpc/<name>`) — input/output/error Schemas via `JSONSchema.make`. [→ details](/docs/plugins/openapi) |
 | `@voltro/plugin-versioning` | ✓ | Full row history + time-travel — value snapshot of every insert/update/delete on listed tables into `_voltro_row_history` (rides the ChangeEvent tap); `rowHistory` / `rowAsOf` queries + `restoreAsOf` / `diffVersions`; TTL + per-row cap retention. [→ details](/docs/plugins/versioning) |
 | `@voltro/plugin-presence` | ✓ | Ephemeral realtime presence — heartbeat roster per channel (`presence.heartbeat`/`list`/`leave` + `usePresence`), a `useTyping` typing indicator, swept `_voltro_presence` table, cross-instance. [→ details](/docs/plugins/presence) |
-| `@voltro/plugin-scim` | ✓ | SCIM 2.0 provisioning — Users + Groups REST at `/scim/v2` (bearer-gated) incl. group-membership PATCH/PUT + the RFC 7644 discovery trio (ServiceProviderConfig/Schemas/ResourceTypes), `userName`/`externalId`/`displayName eq` filters, pagination, unique `userName`, `active:false` deactivation; `scim_users`/`scim_groups`. [→ details](/docs/plugins/scim) |
+| `@voltro/plugin-scim` | ✓ | SCIM 2.0 provisioning — Users + Groups REST at `/scim/v2` (bearer-gated) incl. group-membership PATCH/PUT + the RFC 7644 discovery trio (ServiceProviderConfig/Schemas/ResourceTypes), `userName`/`externalId`/`displayName eq` filters, pagination, unique `userName`, `active:false` deactivation; `_voltro_scim_users`/`_voltro_scim_groups`. [→ details](/docs/plugins/scim) |
 | `@voltro/plugin-sso-saml` | ✓ | Enterprise SAML 2.0 SSO — SP-initiated login + Single Logout (both directions) + ACS + SP metadata under `/saml`; IdP-metadata-URL auto cert rotation, encrypted assertions, clock-skew, SP request signing. Signature verify via `@node-saml/node-saml` (optional+lazy), mints a framework session. [→ details](/docs/plugins/sso-saml) |
 
 API keys are **first-class** (not a plugin): `apiKeys: true` in `app.config.ts` → Bearer-key auth + admin-gated `/v1/api-keys` management, hash-only storage. [→ details](/docs/configuration/api-keys)

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

@@ -143,7 +143,7 @@ create-vs-update: they're *different mutations with different input schemas*, so
 they're naturally different forms — no "CRUD mode" switch.
 
 ```tsx
-import { AutoForm } from '@voltro/web'
+import { AutoForm } from '@voltro/ui'
 
 // fields from the mutation's input schema; client+server share the schema;
 // submits via the mutation with op-correct optimistic (insert prepends, etc.)
@@ -177,7 +177,7 @@ A combined create-or-edit screen is a three-line wrapper:
   object → a `custom` placeholder asking for a render-prop.
 - **Rung 1 — one custom widget** via a `<Field>` render-prop:
   ```tsx
-  import { AutoForm, Field, AsyncSelect } from '@voltro/web'
+  import { AutoForm, Field, AsyncSelect } from '@voltro/ui'
 
   <AutoForm api="app" mutation="todos.create">
     {() => (

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

@@ -2056,7 +2056,7 @@ curl -s -X POST http://localhost:4000/_voltro/inspect/invoke \
 # → { "ok": false, "error": { "_tag": "EntitlementExceeded", "entitlement": "projects", "limit": 3, "used": 3 } }
 ```
 
-Each successful create also logs `[notify:project] → …: Project created` (console channel) and persists a `notification_inbox` row.
+Each successful create also logs `[notify:project] → …: Project created` (console channel) and persists a `_voltro_notification_inbox` row.
 
 ## Enable durable analytics