@voltro/cli 0.2.2 → 0.4.0

package/dist/serveEntry.js

@@ -1,4 +1,4 @@
-import { At as e, nt as t } from "./dev--jHe1vcu.js";
+import { jt as e, rt as t } from "./dev-CQxbrpDz.js";
 import { a as n } from "./startupRunner-DhlX9nqd.js";
-import { t as r } from "./serveCommand-93rRdEp0.js";
+import { t as r } from "./serveCommand-BZzUJIyo.js";
 export { e as loadDotEnv, n as registerAppModules, t as registerDriver, r as runServe };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -52,27 +52,30 @@
     "@effect/platform-node": "^0.107.0",
     "@effect/sql": "^0.51.1",
     "@effect/workflow": "^0.18.2",
+    "@voltro/ai": "0.4.0",
+    "@voltro/cache": "0.4.0",
+    "@voltro/data-transfer": "0.4.0",
+    "@voltro/database": "0.4.0",
+    "@voltro/env": "0.4.0",
+    "@voltro/kv": "0.4.0",
+    "@voltro/logger": "0.4.0",
+    "@voltro/plugin-auth": "0.4.0",
+    "@voltro/plugin-broadcast": "0.4.0",
+    "@voltro/plugin-mail": "0.4.0",
+    "@voltro/plugin-storage": "0.4.0",
+    "@voltro/plugin-webhooks": "0.4.0",
+    "@voltro/protocol": "0.4.0",
+    "@voltro/runtime": "0.4.0",
+    "@voltro/serverless": "0.4.0",
+    "@voltro/workflow": "0.4.0",
+    "chokidar": "^5.0.0",
+    "ioredis": "^5.11.1",
+    "ts-morph": "^28.0.0"
+  },
+  "optionalDependencies": {
     "@tailwindcss/vite": "^4.3.2",
     "@vitejs/plugin-react": "^6.0.3",
-    "@voltro/ai": "0.2.2",
-    "@voltro/cache": "0.2.2",
-    "@voltro/data-transfer": "0.2.2",
-    "@voltro/database": "0.2.2",
-    "@voltro/env": "0.2.2",
-    "@voltro/kv": "0.2.2",
-    "@voltro/logger": "0.2.2",
-    "@voltro/plugin-auth": "0.2.2",
-    "@voltro/plugin-broadcast": "0.2.2",
-    "@voltro/plugin-mail": "0.2.2",
-    "@voltro/plugin-storage": "0.2.2",
-    "@voltro/plugin-webhooks": "0.2.2",
-    "@voltro/protocol": "0.2.2",
-    "@voltro/runtime": "0.2.2",
-    "@voltro/serverless": "0.2.2",
-    "@voltro/workflow": "0.2.2",
-    "chokidar": "^5.0.0",
     "esbuild": "^0.28.0",
-    "ioredis": "^5.11.1",
     "tsx": "^4.23.0",
     "vite": "^8.1.4"
   },

package/templates/AGENTS.core.md

@@ -61,6 +61,53 @@ Ask in order; stop at the first "yes":
 Deep dive: **`data.md`** (queries/mutations/actions/streams/errors),
 **`workflows.md`**, **`scheduling.md`**.
 
+### Pick the CLIENT primitive (decision rubric)
+
+`useSubscription` / `useMutation` / `useAction` are the transport — they are NOT
+the whole client surface. The framework ships a **headless primitive for every
+common UI job**, each derived from the descriptor Schema you already wrote. Reach
+for one BEFORE hand-rolling; ask in order:
+
+1. **A form / any typed write UI?** → **`useFormBinding`** — fields + validation
+   derived from the mutation's input Schema, and a server
+   `ValidationError({ field })` routes itself to that field. Not per-field `useState`.
+2. **A table / list with sort, filter, pagination?** → **`useDataTable`** (columns
+   from the query's output Schema, live rows). **`useQueryFilters`** builds filter
+   controls from the query's INPUT Schema; **`useQueryField`** is the query-bound picker.
+3. **A file upload?** → **`useUpload`** (progress, cancel, provider-agnostic).
+   Not `FileReader` → base64 → action.
+4. **Gating UI on permission?** → **`useCan`** / **`useCanAny`** (scopes, from
+   `@voltro/client`, fed by `<PermissionProvider scopes>`) or
+   **`useResourceCan`** / **`useResourceCans`** (per-resource ReBAC, reactive).
+   These live in the client, not behind a plugin — scopes are a framework
+   concept, so gating a button never requires installing rbac.
+5. **A value derived from one or more subscriptions?** → **`useDerived`**
+   (dependency-tracked, referentially stable). Not a hand-maintained `useMemo` dep array.
+6. **A very large list?** → **`useWindowedSubscription`** (subscribe to the visible
+   window only, not a million rows).
+7. **Debounced input?** → **`useDebounced`**; **`useAsyncValidation`** for checks
+   that need the DB (uniqueness, cross-row) — live, over a query binding.
+8. **A loading placeholder?** → **`useFormSkeleton`** / **`useTableSkeleton`** —
+   shaped like the REAL data, from the same Schema.
+9. **Offline writes · undo · dry-run · "why is this value here?"** → **`useOutbox`**,
+   **`useUndoLog`**, **`usePreview`**, **`useProvenance`**.
+10. **Global rpc-error handling?** → **`useOnRpcError`** + **`reportClientError`**.
+
+| You're about to write | Reach for instead |
+|---|---|
+| per-field `useState` + `isSubmitting` + `resetForm()` | `useFormBinding` |
+| shadcn `<Table>` + per-table sort/filter state | `useDataTable` |
+| `FileReader` → base64 → action → `storage.put` | `useUpload` |
+| `useMemo` fanning in 3+ subscriptions | `useDerived` |
+| `setTimeout` debounce inside `useEffect` | `useDebounced` |
+| `data === undefined ? <Skeleton/> : …` | `useFormSkeleton` / `useTableSkeleton` |
+| a hand-kept page-scope check | `useCan` / `useResourceCan` |
+| a hand-rolled presence roster / notification inbox / feature flag | `@voltro/plugin-presence` / `-notifications` / `-flags` |
+
+Deep dive: **`schema-driven-ui.md`** (forms, tables, pickers, filters, skeletons),
+**`reference.md`** (the complete hook list). If you are hand-writing more than ~20
+lines of generic UI plumbing, stop and check those two first.
+
 ## Project layout
 
 One OR MORE **projects** live under `apps/`. A project (`project.json`) is the
@@ -220,8 +267,22 @@ primitive → just save; the supervised dev loop respawns and regenerates.
   But DO call `assertOwnTenant(input.tenantId, ctx.request.subject)` (from
   `@voltro/plugin-multitenancy/guard`) in custom mutations that write raw rows,
   and declare `error: TenantMismatch` — subscriptions are auto-scoped, writes are not.
+- **Gate authorization declaratively with `guards:`.** Add
+  `guards: [{ scope: 'notes:write' }]` to `defineMutation`/`defineQuery`/`defineAction`
+  — the framework enforces it BEFORE the executor (before the txn opens), fails
+  with a typed `ScopeError` (auto-merged into the wire error union), and checks the
+  caller's EFFECTIVE scopes (raw ∪ rbac roles). Guards are browser-safe DATA (scope
+  strings + a pure `resource: (input) => id` extractor — never a server fn). Use the
+  in-handler `ctx.access.has(scope)` / `yield* ctx.access.require(scope)` (or rbac's
+  `permission()`) only for checks that need LOADED data (row ownership).
 - **Don't store secrets in the schema or in `Subject`.** Declare env via
   `defineEnv` (`configuration.md`); carry only ids in `Subject`.
+- **In production, `voltro build` BEFORE `voltro serve`.** A production
+  (`NODE_ENV=production`) serve REQUIRES the precompiled serve bundle and fails
+  loud if it's missing — production never transpiles on demand. The generated
+  Dockerfiles already do `voltro build` then `voltro serve`; if you write your
+  own prod start, build first. (`voltro dev` + a non-prod local `serve` still use
+  tsx.) Depth: the deployment topic.
 - **Don't copy prod data down unmasked.** `voltro data export` (and
   `--target api`) reads REAL rows — PII included. Copying prod → dev/stage MUST
   go through a masking profile (`--profile`; classify columns `.sensitive()` /

package/templates/AGENTS.md

@@ -61,6 +61,53 @@ Ask in order; stop at the first "yes":
 Deep dive: **`data.md`** (queries/mutations/actions/streams/errors),
 **`workflows.md`**, **`scheduling.md`**.
 
+### Pick the CLIENT primitive (decision rubric)
+
+`useSubscription` / `useMutation` / `useAction` are the transport — they are NOT
+the whole client surface. The framework ships a **headless primitive for every
+common UI job**, each derived from the descriptor Schema you already wrote. Reach
+for one BEFORE hand-rolling; ask in order:
+
+1. **A form / any typed write UI?** → **`useFormBinding`** — fields + validation
+   derived from the mutation's input Schema, and a server
+   `ValidationError({ field })` routes itself to that field. Not per-field `useState`.
+2. **A table / list with sort, filter, pagination?** → **`useDataTable`** (columns
+   from the query's output Schema, live rows). **`useQueryFilters`** builds filter
+   controls from the query's INPUT Schema; **`useQueryField`** is the query-bound picker.
+3. **A file upload?** → **`useUpload`** (progress, cancel, provider-agnostic).
+   Not `FileReader` → base64 → action.
+4. **Gating UI on permission?** → **`useCan`** / **`useCanAny`** (scopes, from
+   `@voltro/client`, fed by `<PermissionProvider scopes>`) or
+   **`useResourceCan`** / **`useResourceCans`** (per-resource ReBAC, reactive).
+   These live in the client, not behind a plugin — scopes are a framework
+   concept, so gating a button never requires installing rbac.
+5. **A value derived from one or more subscriptions?** → **`useDerived`**
+   (dependency-tracked, referentially stable). Not a hand-maintained `useMemo` dep array.
+6. **A very large list?** → **`useWindowedSubscription`** (subscribe to the visible
+   window only, not a million rows).
+7. **Debounced input?** → **`useDebounced`**; **`useAsyncValidation`** for checks
+   that need the DB (uniqueness, cross-row) — live, over a query binding.
+8. **A loading placeholder?** → **`useFormSkeleton`** / **`useTableSkeleton`** —
+   shaped like the REAL data, from the same Schema.
+9. **Offline writes · undo · dry-run · "why is this value here?"** → **`useOutbox`**,
+   **`useUndoLog`**, **`usePreview`**, **`useProvenance`**.
+10. **Global rpc-error handling?** → **`useOnRpcError`** + **`reportClientError`**.
+
+| You're about to write | Reach for instead |
+|---|---|
+| per-field `useState` + `isSubmitting` + `resetForm()` | `useFormBinding` |
+| shadcn `<Table>` + per-table sort/filter state | `useDataTable` |
+| `FileReader` → base64 → action → `storage.put` | `useUpload` |
+| `useMemo` fanning in 3+ subscriptions | `useDerived` |
+| `setTimeout` debounce inside `useEffect` | `useDebounced` |
+| `data === undefined ? <Skeleton/> : …` | `useFormSkeleton` / `useTableSkeleton` |
+| a hand-kept page-scope check | `useCan` / `useResourceCan` |
+| a hand-rolled presence roster / notification inbox / feature flag | `@voltro/plugin-presence` / `-notifications` / `-flags` |
+
+Deep dive: **`schema-driven-ui.md`** (forms, tables, pickers, filters, skeletons),
+**`reference.md`** (the complete hook list). If you are hand-writing more than ~20
+lines of generic UI plumbing, stop and check those two first.
+
 ## Project layout
 
 One OR MORE **projects** live under `apps/`. A project (`project.json`) is the
@@ -220,8 +267,22 @@ primitive → just save; the supervised dev loop respawns and regenerates.
   But DO call `assertOwnTenant(input.tenantId, ctx.request.subject)` (from
   `@voltro/plugin-multitenancy/guard`) in custom mutations that write raw rows,
   and declare `error: TenantMismatch` — subscriptions are auto-scoped, writes are not.
+- **Gate authorization declaratively with `guards:`.** Add
+  `guards: [{ scope: 'notes:write' }]` to `defineMutation`/`defineQuery`/`defineAction`
+  — the framework enforces it BEFORE the executor (before the txn opens), fails
+  with a typed `ScopeError` (auto-merged into the wire error union), and checks the
+  caller's EFFECTIVE scopes (raw ∪ rbac roles). Guards are browser-safe DATA (scope
+  strings + a pure `resource: (input) => id` extractor — never a server fn). Use the
+  in-handler `ctx.access.has(scope)` / `yield* ctx.access.require(scope)` (or rbac's
+  `permission()`) only for checks that need LOADED data (row ownership).
 - **Don't store secrets in the schema or in `Subject`.** Declare env via
   `defineEnv` (`configuration.md`); carry only ids in `Subject`.
+- **In production, `voltro build` BEFORE `voltro serve`.** A production
+  (`NODE_ENV=production`) serve REQUIRES the precompiled serve bundle and fails
+  loud if it's missing — production never transpiles on demand. The generated
+  Dockerfiles already do `voltro build` then `voltro serve`; if you write your
+  own prod start, build first. (`voltro dev` + a non-prod local `serve` still use
+  tsx.) Depth: the deployment topic.
 - **Don't copy prod data down unmasked.** `voltro data export` (and
   `--target api`) reads REAL rows — PII included. Copying prod → dev/stage MUST
   go through a masking profile (`--profile`; classify columns `.sensitive()` /

package/templates/agent-docs/_manifest.json

@@ -35,7 +35,7 @@
       "group": null,
       "description": "The voltro CLI — every command, grouped by purpose, with the flags that actually matter.",
       "path": "agent-docs/cli.md",
-      "files": 8
+      "files": 9
     },
     {
       "id": "configuration",
@@ -170,7 +170,7 @@
       "group": null,
       "description": "Voltro's i18n layer (@voltro/i18n) — an opinionated wrap over react-intl, auto-wired from a single app.config.ts field, with cookie + Accept-Language locale resolution.",
       "path": "agent-docs/internationalization.md",
-      "files": 3
+      "files": 4
     },
     {
       "id": "introduction",
@@ -242,7 +242,7 @@
       "group": null,
       "description": "Project the typed descriptor graph into UI — forms, tables, pickers, and reactive components, all bound to a descriptor with near-zero glue.",
       "path": "agent-docs/schema-driven-ui.md",
-      "files": 13
+      "files": 23
     },
     {
       "id": "security",
@@ -305,7 +305,7 @@
       "group": null,
       "description": "Voltro's test story — the @voltro/testing package, the test pyramid (unit handlers/tools → workflow runner → e2e), and the voltro test / voltro e2e CLI commands.",
       "path": "agent-docs/testing.md",
-      "files": 4
+      "files": 5
     },
     {
       "id": "workflows",

package/templates/agent-docs/ai.md

@@ -1019,6 +1019,34 @@ It returns a `Stream<SeqEvent>` — each element is `{ seq, event }`. The descri
 
 On the client, `useResumableAgentStream('app', 'support.run')` does the rest: it unwraps each `SeqEvent` (so `.events` are the plain inner events), tracks the highest `seq`, and on a transport drop BEFORE the run's terminal event it auto-reconnects with `fromSeq` = the last seq it rendered (exponential backoff; the no-progress cap resets whenever a reconnect delivers a new event, so a long flaky stream survives any number of well-spaced drops). The server replays past the cursor, then continues — one seamless stream.
 
+The hook's own surface is small:
+
+```tsx
+import { useResumableAgentStream } from '@voltro/client'
+import type { AgentEvent } from '@voltro/ai/events'
+
+const run = useResumableAgentStream<AgentEvent>('app', 'support.run')
+
+// `input` MUST carry the resume key — `fromSeq` is injected by the hook.
+run.start({ streamId, message: prompt })
+run.cancel()
+```
+
+| Field | Meaning |
+|---|---|
+| `events` | The unwrapped inner events so far, in order and deduped by `seq`. |
+| `status` | `'idle'`, `'streaming'`, `'reconnecting'`, `'done'`, or `'error'`. |
+| `reconnects` | How many times the transport dropped and auto-reconnected this run. |
+| `error` | Set when `status === 'error'`. |
+| `start(input?)` | Begins a run, clearing previous events. |
+| `cancel()` | Stops the run and any pending reconnect. |
+
+A third options argument tunes the reconnect policy: `maxReconnects` (default
+`6`), `backoffMs` (`400`), `maxBackoffMs` (`8000`), and `isTerminal` — which
+defaults to treating an `AgentEvent`-shaped `{ _tag: 'done' | 'error' }` as the
+end of the run. Override `isTerminal` when your element type signals completion
+some other way, or the hook will keep trying to resume a finished stream.
+
 For multi-node deployments use `dataStoreResumableStreamStore(ctx.store)` — it persists to the framework's own database (`streamEventsTable` + `streamStateTable`, register them in your `database/index.ts`) and elects exactly ONE producer per `streamId` via an atomic claim, so only one node runs the model while every node's consumers tail the shared log. Sweep finished streams with `gcResumableStreams(store, { olderThan })`.
 
 For the fastest path, `redisResumableStreamStore(redis, { ttlSeconds })` backs the log with a Redis LIST (`RPUSH`/`LRANGE`) plus a `SET … NX` producer claim — TTL evicts finished/abandoned streams without a sweep. `@voltro/ai` takes no Redis dependency; you inject a tiny `ResumableRedis` client (five methods: `setNx` / `rpush` / `lrange` / `set` / `exists`) adapting ioredis / node-redis. All three backends satisfy the same `ResumableStreamStore` interface, so they swap without touching the producer/consumer code.

package/templates/agent-docs/authentication.md

@@ -403,7 +403,7 @@ if (!canTrigger) throw new Unauthorised({})
 ```ts
 import { permission } from '@voltro/plugin-rbac'
 
-yield* permission(ctx, 'admin:full')   // Effect<void, Forbidden>
+yield* permission(ctx, 'admin:full')   // Effect<void, ScopeError>
 ```
 
 See [the RBAC plugin](/docs/plugins/rbac) for the full model.
@@ -1778,9 +1778,12 @@ the headline that builds on it.)
 import { useResourceCan } from '@voltro/client'
 
 const canEdit = useResourceCan('app', 'todos.can', { action: 'edit', resourceType: 'todo', resourceId: id })
-// canEdit.allowed: boolean | undefined (undefined until resolved); reactive.
+// canEdit.allowed: boolean (false until the first verdict); canEdit.pending: boolean.
 ```
 
+Full API — including the batch `useResourceCans` for per-row gating — in
+[usePermissions](/docs/ui/client-utilities/use-permissions).
+
 ## Capability map
 
 `rebacPolicyGraph()` returns every resource type, its actions, the relations each

package/templates/agent-docs/cli.md

@@ -25,6 +25,7 @@ The dispatcher routes `voltro <command> [args]` to the matching subcommand and p
 | [Build & run](/docs/cli/build-and-start) | `build`, `start`, `serve` |
 | Deploy | `deploy` (`plan` — auto-detect the target tier per app + function), [`serverless`](/docs/deployment/serverless-functions) (`list` / `dev` / `serve` / `build` / `deploy`), [`static`](/docs/deployment/static-sites) (`hosts` / `deploy`) |
 | [Database](/docs/cli/migrate) | `migrate`, `db` (`plan` / `apply` / `plans` / `drift` / `squash` / `restore-snapshot` / `migrate` / `rollback` / `status` / `seed`) |
+| [Update](/docs/cli/update) | `update` (`--to` / `--dry-run` / `--force` / `--exact`) — bump every `@voltro/*`, install, run the codemods that adapt your source to the new version |
 | [Data transfer](/docs/cli/data) | `data` (`export` / `import` / `unpack` / `inspect` / `backup` / `restore`) — directory + single-file `.vbundle` bundles, streaming assets, masking, at-rest encryption |
 | Ops / infra | `cache` (`status` / `flush` / `invalidate`), `add` (`redis`), `baseline` (`list` / `status` / `set`), `schedule-manifest`, [`storage`](/docs/plugins/storage) (`doctor` / `cors`) |
 | AI / data | `embeddings backfill <table> --text <field> --vector <field>` — (re)embed rows the `vectorEmbedding()` mixin missed (pre-existing rows / a model change); `--dry-run` to preview |
@@ -149,6 +150,7 @@ The HTTP surface is reachable directly too — e.g. `curl -s localhost:4000/_vol
 - [Dev](/docs/cli/dev) — what happens during `voltro dev`
 - [Build & start](/docs/cli/build-and-start) — production paths
 - [Migrate](/docs/cli/migrate) — schema changes end-to-end
+- [Update](/docs/cli/update) — upgrade the framework + run codemods
 - [Inspect & test](/docs/cli/inspect) — debugging + harness
 
 
@@ -720,6 +722,23 @@ For WebSocket connections to land on the same backend (required for in-process s
 - Reverse proxy: `lb_policy ip_hash` (Caddy) / `ip_hash` (nginx).
 - Or use `@voltro/plugin-cluster` to share subscription state across instances → any-load-balancer-works.
 
+## `voltro doctor` — preflight a production serve
+
+Production `voltro serve` for an **API** app boots ONLY from the precompiled serve
+bundle and is **fatal if it's missing** — a hand-rolled Dockerfile that runs
+`voltro serve` without a prior `voltro build` breaks at deploy. `voltro doctor`
+(or `voltro serve --preflight`) catches that at BUILD time instead of cold-start:
+
+```bash
+voltro doctor .                 # check the serve bundle exists; print the fix if not
+voltro serve --preflight .      # same check, then exit — never boots
+```
+
+It exits **1** when the serve bundle is missing on an API app (so it fails a CI /
+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.
+
 ## Anti-patterns
 
 - **Running `voltro start` against a directory without `dist/`.** It exits 1 with a clear `no built dist found — run voltro build first` (checked against `.framework/dist/index.html` before any heavy work). Run `voltro build` first.
@@ -1648,3 +1667,82 @@ The manifest is read through a TTL-cached source (~10 seconds): a procedure you
 ## Protocol scope
 
 MCP over JSON-RPC 2.0. `initialize` negotiates the protocol revision (`2025-06-18`, `2025-03-26`, `2024-11-05`) and advertises the `tools`, `resources`, and `prompts` capabilities; methods are `ping`, `tools/list`, `tools/call`, `resources/list`, `resources/read`, `prompts/list`, `prompts/get`. The stdio bin frames this as newline-delimited JSON-RPC; the HTTP bin serves it over Streamable HTTP. Both transports route to the same pure protocol core (`handleMcpRequest`, `callTool`, `listResources`/`readResource`, `listPrompts`/`getPrompt`, `routeHttp`), all exported from `@voltro/mcp`.
+
+
+
+---
+
+<!-- source: en/cli/update.md -->
+## Update
+
+_voltro update — bump the framework to the latest version and run the codemods that adapt your source to any changed APIs._
+
+`voltro update` upgrades an app to the latest framework release. It does three things in order:
+
+1. **Bump** every `@voltro/*` dependency in `package.json` to the target version.
+2. **Install** with your package manager (detected from the lockfile — pnpm / npm / yarn / bun).
+3. **Run the codemods** shipped with the target version — automatic source rewrites for any breaking API change, plus printed manual steps for anything that can't be automated.
+
+```bash
+voltro update                 # bump to the latest published version, install, run codemods
+voltro update --to 0.4.0      # pin an explicit target version
+voltro update --dry-run       # preview the bump + which codemods would run — writes nothing
+voltro update --force         # allow a dirty working tree (not recommended)
+voltro update --exact         # pin exact versions (drop the ^ / ~ range prefix)
+
+# Recover the codemods after a MANUAL version bump (no bump, no install):
+voltro update --codemods-only --from 0.3.0            # re-run codemods 0.3.0 → installed
+voltro update --codemods-only --from 0.3.0 --to 0.4.0 # explicit delta
+```
+
+## Already bumped by hand? Recover the codemods
+
+If you bump `@voltro/*` versions in `package.json` yourself and install first, a
+plain `voltro update` sees the installed version already equals the target and
+reports **"already on X — nothing to do"** — skipping the codemods AND the
+printed manual steps for the delta you actually crossed. To re-apply them without
+touching `package.json` again:
+
+```bash
+voltro update --codemods-only --from <version-you-came-from>
+```
+
+`--codemods-only` (alias `--run-codemods`) runs the codemods + manual notes for
+`[from, to]` against the already-installed tree — no version bump, no install.
+`--to` defaults to the installed version; pass it to pin an explicit delta.
+`--from` also works on a normal `voltro update` to override the auto-detected
+source version.
+
+## The clean-tree guard
+
+Codemods **rewrite your source**, so you need a clean diff to review afterwards. `voltro update` refuses to run on a dirty git working tree — commit or stash first. Use `--dry-run` to preview without touching anything, or `--force` to override the guard (you accept a mixed diff).
+
+## What gets bumped
+
+Every `@voltro/*` entry in `dependencies` and `devDependencies`, with the range style preserved (`^0.3.0` stays caret, `~0.3.0` stays tilde) unless you pass `--exact`. Non-registry specs (`workspace:*`, `catalog:`, `link:`, …) are left untouched — they're already resolved by your monorepo or catalog.
+
+## Codemods
+
+Each breaking public-API change in a release ships a **codemod**. When you update across that release, `voltro update` applies it:
+
+- A **transform codemod** rewrites your source automatically — renamed imports, moved modules, changed component props, restructured call signatures. The rewrite is scoped to files that actually import the affected symbol.
+- A **manual codemod** prints written steps during the update, only when your app is affected — for changes that can't be mechanically transformed (a behavior change, a descriptor/executor restructure). Where the affected sites can be found but the fix needs your judgment, a codemod inserts `// TODO(voltro-migration): …` markers so you can locate every spot.
+
+Codemods that span multiple versions run in order (e.g. upgrading `0.2.0 → 0.4.0` runs the `0.3.0` and `0.4.0` codemods in sequence). Review the resulting diff before committing.
+
+## The database is separate
+
+`voltro update` does **not** touch your database. Framework-owned `_voltro_*` tables (workflow runs, schedules, …) are reconciled by the declarative differ, not by codemods: when a release changes one of those tables, your next `voltro db apply` (or `voltro dev` boot, which auto-applies) picks up the change. After an update:
+
+```bash
+voltro update
+voltro db apply        # reconcile any changed framework tables — NOT voltro db migrate
+# then run your typecheck to confirm your code compiles against the new API
+```
+
+Use `voltro db apply` (the declarative diff), not `voltro db migrate` (the imperative file-runner) — only the former reconciles framework tables.
+
+## Where to read next
+
+- [Migrate](/docs/cli/migrate) — schema changes end-to-end
+- [Build & start](/docs/cli/build-and-start) — production paths