@voltro/cli 0.37.0 → 0.39.0

package/dist/webDev-id3I5PvG.js

@@ -0,0 +1,2 @@
+import { _ as e } from "./webDev-CTpSY-e_.js";
+export { e as tryRunWebServe };

package/dist/{webhookDiscovery-D7VaeMlz.js → webhookDiscovery-CphsQe59.js}

@@ -23,12 +23,10 @@ var r = /\.webhook\.tsx?$/, i = async (t, r) => {
 					descriptor: s
 				});
 				break;
-			case "webhookProvider":
-				o.push({
-					file: i,
-					descriptor: s
-				});
-				break;
+			case "webhookProvider": o.push({
+				file: i,
+				descriptor: s
+			});
 		}
 	}
 	return {

package/dist/{webhookDiscovery-CrGAfhIG.js → webhookDiscovery-il9ti-HE.js}

@@ -1,2 +1,2 @@
-import { i as e, r as t, t as n } from "./webhookDiscovery-D7VaeMlz.js";
+import { i as e, r as t, t as n } from "./webhookDiscovery-CphsQe59.js";
 export { n as WEBHOOK_PATTERN, t as loadWebhookFiles, e as outgoingFromEvents };

package/dist/{webhooksCommand-CHWSPk5z.js → webhooksCommand-BVvOtZ1B.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-BV6XNYKf.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-CrGAfhIG.js");
+	let { walk: t, loadDiscovered: n } = await import("./dev-alhkKoEX.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.37.0",
+  "version": "0.39.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -580,6 +580,24 @@
         "title": "a procedure input rejects a field it does not declare (it used to drop it)",
         "kind": "manual"
       },
+      {
+        "version": "0.38.0",
+        "id": "0.38.0/01_impersonation-key-in-protocol",
+        "title": "`IMPERSONATION_METADATA_KEY` is imported from @voltro/protocol",
+        "kind": "transform"
+      },
+      {
+        "version": "0.38.0",
+        "id": "0.38.0/02_startup-failure-refuses-boot",
+        "title": "a `*.startup.ts` that fails refuses the boot (it used to warn and continue)",
+        "kind": "manual"
+      },
+      {
+        "version": "0.39.0",
+        "id": "0.39.0/01_empty-input-schema-rejects-every-field",
+        "title": "a procedure declaring `Schema.Struct({})` used to accept every field and now accepts none",
+        "kind": "manual"
+      },
       {
         "version": "0.4.0",
         "id": "0.4.0/01_rbac-forbidden-to-scopeerror",
@@ -679,22 +697,22 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.37.0",
-    "@voltro/cache": "0.37.0",
-    "@voltro/data-transfer": "0.37.0",
-    "@voltro/database": "0.37.0",
-    "@voltro/env": "0.37.0",
-    "@voltro/kv": "0.37.0",
-    "@voltro/logger": "0.37.0",
-    "@voltro/plugin-auth": "0.37.0",
-    "@voltro/plugin-broadcast": "0.37.0",
-    "@voltro/plugin-mail": "0.37.0",
-    "@voltro/plugin-storage": "0.37.0",
-    "@voltro/plugin-webhooks": "0.37.0",
-    "@voltro/protocol": "0.37.0",
-    "@voltro/runtime": "0.37.0",
-    "@voltro/serverless": "0.37.0",
-    "@voltro/workflow": "0.37.0",
+    "@voltro/ai": "0.39.0",
+    "@voltro/cache": "0.39.0",
+    "@voltro/data-transfer": "0.39.0",
+    "@voltro/database": "0.39.0",
+    "@voltro/env": "0.39.0",
+    "@voltro/kv": "0.39.0",
+    "@voltro/logger": "0.39.0",
+    "@voltro/plugin-auth": "0.39.0",
+    "@voltro/plugin-broadcast": "0.39.0",
+    "@voltro/plugin-mail": "0.39.0",
+    "@voltro/plugin-storage": "0.39.0",
+    "@voltro/plugin-webhooks": "0.39.0",
+    "@voltro/protocol": "0.39.0",
+    "@voltro/runtime": "0.39.0",
+    "@voltro/serverless": "0.39.0",
+    "@voltro/workflow": "0.39.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",
@@ -703,10 +721,10 @@
   "optionalDependencies": {
     "@tailwindcss/vite": "^4.3.3",
     "@vercel/nft": "^1.10.2",
-    "@vitejs/plugin-react": "^6.0.4",
-    "esbuild": "^0.28.0",
-    "tsx": "^4.23.1",
-    "vite": "^8.1.5"
+    "@vitejs/plugin-react": "^6.0.5",
+    "esbuild": "^0.28.2",
+    "tsx": "^4.23.12",
+    "vite": "^8.2.1"
   },
   "peerDependencies": {
     "@effect/platform": "^0.97.0",

package/templates/AGENTS.md

@@ -707,7 +707,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.37.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.39.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. |
@@ -733,7 +733,7 @@ each plugin's own README.
 | Observability | `node_modules/@voltro/cli/templates/agent-docs/observability.md` | OpenTelemetry tracing in Voltro — the auto-emitted spans for every primitive, span attributes and nesting, the three enabling modes (console / OTLP / buffer), and adding your own spans with Effect.withSpan. |
 | Plugins | `node_modules/@voltro/cli/templates/agent-docs/plugins.md` | How Voltro plugins compose into the runtime, what they can intercept, the catalogue, and writing your own. |
 | Reference | `node_modules/@voltro/cli/templates/agent-docs/reference.md` | The client-side hook surface, grouped by purpose. |
-| Releases | `node_modules/@voltro/cli/templates/agent-docs/releases.md` | The largest release in the framework's history — what breaks your boot, what changes at runtime, and why none of it is rewritten for you. |
+| Releases | `node_modules/@voltro/cli/templates/agent-docs/releases.md` | 0.35 through 0.38 in one pass — the boot-breaking access declarations, the stricter input handling, and the runtime behaviour that moved underneath you. |
 | Routing | `node_modules/@voltro/cli/templates/agent-docs/routing.md` | Voltro's file-based router — pages, layouts, render modes, loaders, navigation, islands. The web side of the framework. |
 | Scheduling | `node_modules/@voltro/cli/templates/agent-docs/scheduling.md` | Deployment-agnostic scheduled jobs in Voltro — one *.cron.tsx definition that runs unchanged on a single box, a multi-instance fleet, or an external scheduler. |
 | Schema-driven UI | `node_modules/@voltro/cli/templates/agent-docs/schema-driven-ui.md` | Project the typed descriptor graph into UI — forms, tables, pickers, and reactive components, all bound to a descriptor with near-zero glue. |

package/templates/agent-docs/_index.md

@@ -9,7 +9,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.37.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.39.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. |
@@ -35,7 +35,7 @@ each plugin's own README.
 | Observability | `node_modules/@voltro/cli/templates/agent-docs/observability.md` | OpenTelemetry tracing in Voltro — the auto-emitted spans for every primitive, span attributes and nesting, the three enabling modes (console / OTLP / buffer), and adding your own spans with Effect.withSpan. |
 | Plugins | `node_modules/@voltro/cli/templates/agent-docs/plugins.md` | How Voltro plugins compose into the runtime, what they can intercept, the catalogue, and writing your own. |
 | Reference | `node_modules/@voltro/cli/templates/agent-docs/reference.md` | The client-side hook surface, grouped by purpose. |
-| Releases | `node_modules/@voltro/cli/templates/agent-docs/releases.md` | The largest release in the framework's history — what breaks your boot, what changes at runtime, and why none of it is rewritten for you. |
+| Releases | `node_modules/@voltro/cli/templates/agent-docs/releases.md` | 0.35 through 0.38 in one pass — the boot-breaking access declarations, the stricter input handling, and the runtime behaviour that moved underneath you. |
 | Routing | `node_modules/@voltro/cli/templates/agent-docs/routing.md` | Voltro's file-based router — pages, layouts, render modes, loaders, navigation, islands. The web side of the framework. |
 | Scheduling | `node_modules/@voltro/cli/templates/agent-docs/scheduling.md` | Deployment-agnostic scheduled jobs in Voltro — one *.cron.tsx definition that runs unchanged on a single box, a multi-instance fleet, or an external scheduler. |
 | Schema-driven UI | `node_modules/@voltro/cli/templates/agent-docs/schema-driven-ui.md` | Project the typed descriptor graph into UI — forms, tables, pickers, and reactive components, all bound to a descriptor with near-zero glue. |

package/templates/agent-docs/_manifest.json

@@ -231,9 +231,9 @@
       "title": "Releases",
       "section": "Releases",
       "group": null,
-      "description": "The largest release in the framework's history — what breaks your boot, what changes at runtime, and why none of it is rewritten for you.",
+      "description": "0.35 through 0.38 in one pass — the boot-breaking access declarations, the stricter input handling, and the runtime behaviour that moved underneath you.",
       "path": "agent-docs/releases.md",
-      "files": 1
+      "files": 2
     },
     {
       "id": "routing",

package/templates/agent-docs/authentication.md

@@ -2154,6 +2154,36 @@ that throws — each is a denial, not a pass. An authorization question nobody c
 answer is a refusal; treating it as a pass is how a policy layer ends up
 enforcing nothing while looking like it does.
 
+**A guard naming an unregistered `resourceType` refuses the BOOT.** Denying is
+correct per call and useless as a deployment outcome: the app comes up green and
+every guarded procedure is down, with a log line per refused call as the only
+sign. A consumer put a number on it — 39 procedures, team settings through role
+administration. So the two facts are compared once, after the startups have run,
+and a missing registration names the type and the procedures that demanded it.
+The commonest cause is a typo: the `resourceType` in a guard and the one in
+`defineResourcePolicy` are two strings, and nothing but that check compares them.
+
+### The source sees the whole subject
+
+`req.subject` is the caller, not just `req.subjectId`. That matters whenever a
+CREDENTIAL is narrower than the person holding it — an API key above all:
+
+```ts
+setTupleSource(async (req) => {
+  // A key minted for one team must not act on another. `req.subjectId` is the
+  // OWNING USER, so a source reading only memberships passes an owner who
+  // belongs to both teams.
+  const boundTeam = req.subject.metadata?.teamId
+  if (boundTeam !== undefined && boundTeam !== req.resourceId) return []
+  return loadResourceTuples(store, req.subjectId, req.resourceType, req.resourceId)
+})
+```
+
+Narrow it yourself: `Subject` is a union whose system and anonymous members carry
+no `metadata`. Without this a declared guard could not express the binding, so an
+app had to keep a hand-written check in the executor beside it — and a guard that
+must always run paired with a hand-written check is not a declaration.
+
 ### Guards are re-checked on every subscription delivery
 
 A subscription is a long-lived grant. Its guards — scope and relationship alike

package/templates/agent-docs/cli.md

@@ -33,7 +33,7 @@ The dispatcher routes `voltro <command> [args]` to the matching subcommand and p
 | [Inspect & debug](/docs/cli/inspect) | `inspect`, `logs`, `traces`, `workflows`, `cluster`, `check` |
 | [Health & surface](/docs/cli/build-and-start) | [`doctor`](/docs/cli/build-and-start) — serve preflight + the hand-roll detector (names the shipped primitive at the spot you're rebuilding it); [`capabilities`](/docs/cli/build-and-start) (`--json`) — the export surface read from your installed `@voltro/*`, so it can be verified instead of recalled; `info` (`--json`) — CLI / node / package-manager / dialect + every installed `@voltro/*` version, flagging lockstep skew (exits 1 on skew) |
 | Harness | `test`, `e2e` |
-| Cloud | `cloud` (`login` / `whoami` / `projects` / `env` / `import`) |
+| Cloud | `cloud` (`login` / `whoami` / `projects` / `env` / `import`); `login` is a top-level alias of `cloud login` |
 | Secrets | `secret` (`generate [purpose]` — the right var+format per secret; `generate` alone → a generic secret; `list`) |
 | Meta | `agents-md`, `telemetry` (reports that Voltro collects none — no phone-home, nothing to opt out of), `version`, `help` |
 
@@ -44,7 +44,7 @@ to the reachable runtime set — the standalone Dockerfiles run it for you) and
 version's codemods). Both are dispatchable; neither is something you invoke
 directly.
 
-Each command takes an optional path argument (the app directory) — defaults to `.` when run from inside an app. `voltro init` initialises the current directory as a workspace root — `pnpm-workspace.yaml`, a root `package.json` with `dev`/`build`/`test`/`typecheck`, a `.gitignore` and `git init`, idempotently and without scaffolding any apps (`voltro create-project <name>` does that, and bootstraps the same root when there isn't one). `voltro secret generate [purpose]` prints a cryptographically strong secret — with a purpose (`data-transfer`, `session`, `bundle-key`, `field-encryption`, `storage`, `inspect`) it emits the correct env var + length/format as a paste-ready `NAME=value` (`voltro secret list` shows them all); with no purpose, a generic base64url secret. `voltro telemetry` reports that Voltro collects none. `voltro deploy` shows the deploy paths — self-host via a [baseline](/docs/deployment/baselines) + CI, managed via the control-plane client `voltro cloud` (managed cloud deploy is coming soon — see [Voltro Cloud](/docs/deployment/voltro-cloud)), individual [serverless functions](/docs/deployment/serverless-functions) (`voltro serverless` → self-hosted Node, or Cloudflare / Scaleway), or a [static site](/docs/deployment/static-sites) (`voltro static` → Cloudflare Pages / S3 / Netlify).
+Each command takes an optional path argument (the app directory) — defaults to `.` when run from inside an app. `voltro init` initialises the current directory as a workspace root — `pnpm-workspace.yaml`, a root `package.json` with `dev`/`build`/`test`/`typecheck`, a `.gitignore` and `git init`, idempotently and without scaffolding any apps (`voltro create-project <name>` does that, and bootstraps the same root when there isn't one). `voltro secret generate [purpose]` prints a cryptographically strong secret — with a purpose (`data-transfer`, `session`, `bundle-key`, `field-encryption`, `storage`, `inspect`) it emits the correct env var + length/format as a paste-ready `NAME=value` (`voltro secret list` shows them all); with no purpose, a generic base64url secret. `voltro telemetry` reports that Voltro collects none. `voltro deploy` shows the deploy paths — self-host via a [baseline](/docs/deployment/self-hosting) + CI, managed via the control-plane client `voltro cloud` (managed cloud deploy is coming soon — see [Voltro Cloud](/docs/deployment/voltro-cloud)), individual [serverless functions](/docs/deployment/serverless-functions) (`voltro serverless` → self-hosted Node, or Cloudflare / Scaleway), or a [static site](/docs/deployment/static-sites) (`voltro static` → Cloudflare Pages / S3 / Netlify).
 
 ## Help + version
 
@@ -620,7 +620,7 @@ is added with `voltro add-app`. Now `voltro list-templates` shows it; `voltro
 create-project --web my-template` (or `--api`) uses it, and any kind is added
 with `voltro add-app <name> --template my-template`.
 
-For private templates (in your own repo), set `VOLTRO_TEMPLATES_PATH=/path/to/my/templates` and the CLI walks there instead of the default location.
+For private templates (in your own repo), set `VOLTRO_TEMPLATES_DIR=/path/to/my/templates` and the CLI resolves templates from there instead of the default location. Point it at the templates **root** — the CLI appends `apps/`, so your templates live at `/path/to/my/templates/apps/<template-id>/`. When the variable is set it is authoritative: the CLI does not fall back to the bundled templates.
 
 ## Idempotency
 
@@ -1851,17 +1851,21 @@ voltro capabilities --json       # the full machine-readable surface
 ```
 
 ```text
-voltro capabilities — 2517 exported symbols across 36 packages
-  @voltro/runtime@0.4.0 — 9 primitives, 41 values, 118 types
-    defineAggregate, defineReaction, defineSubscriber, defineResourcePolicy, …
-  @voltro/client@0.4.0 — 47 hooks, 12 components, 60 types
-    useSubscription, useMutation, useFormBinding, useDataTable, useUpload, …
-
-  * 8 primitive(s)/hook(s) appear nowhere in this project's agent guide:
-      @voltro/plugin-mail: defineEmail
+voltro capabilities — 3856 exported symbols across 36 packages
+  @voltro/runtime@0.38.0 — 12 primitives, 5 hooks, 100 components, 360 values, 388 types
+    defineAggregate, defineConnection, defineCostBudget, defineEventTrigger, defineExecutor, …
+  @voltro/database@0.38.0 — 3 primitives, 33 components, 333 values, 223 types
+    defineMigration *, defineMixin, defineSeed *
+
+  * 9 primitive(s)/hook(s) appear nowhere in this project's agent guide:
+      @voltro/database: defineMigration
+      @voltro/plugin-flags: defineFlag
       …
 ```
 
+The count is the packages **installed in that project**, not everything the
+framework publishes — a leaner app reports fewer.
+
 Every symbol reported was read out of an installed package a moment ago, so an
 agent can **verify** the surface instead of recalling it. The `--json` form is
 stable and locale-independent — the same tree produces byte-identical output on
@@ -2195,7 +2199,7 @@ 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).
+what a PLUGIN may mount; the write credential governs who may call it. The [Voltro Dashboard](/docs/observability/overview) 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
@@ -3785,4 +3789,4 @@ Emits the `globalEnv` / `globalPassThroughEnv` entries for `turbo.json`, so Turb
 ## Related
 
 - [Secrets](/docs/cli/overview#common-env-vars) — generating secret values with `voltro secret`.
-- [Configuration](/docs/configuration) — declaring env vars with `envVar(...)`.
+- [Configuration](/docs/configuration/environment) — declaring env vars with `envVar(...)`.

package/templates/agent-docs/data.md

@@ -970,7 +970,24 @@ const create = useMutation('app', 'notes.create')
 await create.mutate({ title, body })
 ```
 
-The client stages an optimistic patch, calls the server, then removes the patch when the server result or failure arrives. Server-pushed deltas are still the source of truth.
+The client stages an optimistic patch, calls the server, then retires the patch. Server-pushed deltas are still the source of truth.
+
+**Retiring the patch has exactly two shapes, and they are not interchangeable:**
+
+- **Rollback — only when the write FAILED.** The server did not write, so the
+  preview must go, immediately. Nothing else ever rolls a patch back: not a
+  timer, not an elapsed window, not a heuristic.
+- **Hand-off — when the server's own state arrives and reflects the write.** A
+  delta always supersedes (it *is* the echo of committed writes); a fresh
+  snapshot supersedes only when it actually moved the base. Base gains the real
+  row and the placeholder goes in the same update, so there is no flash and no
+  optimistic+real duplicate.
+
+If a confirmed write never gets its echo — reactivity is broken for that query's
+source table — the client **re-issues the subscription and keeps the preview**,
+and reports it on the error bus (visible in `voltro logs`). It does not fall back
+to a base it knows does not reflect the write: a user watching their saved change
+disappear will either redo it or plan on a state they believe was not stored.
 
 For special shapes, override the patch:
 
@@ -1809,6 +1826,32 @@ first-paint optimization, never a correctness dependency. A failed preload is
 likewise non-fatal — the live subscription still delivers the value on the
 client, the only loss is the first-paint seed.
 
+### `preloadFailed` — "no data" vs "could not get data"
+
+A preload that FAILED server-side and one that was never declared arrive the same
+way: as the absence of a seed. That makes an empty first paint ambiguous, and the
+ambiguity is not academic — a session cookie that has outlived the IdP's token
+lifetime makes EVERY preload on the page fail at once, so the page renders its
+empty state while the server log holds the only explanation.
+
+`preloadFailed` separates the two:
+
+```tsx
+const projects = usePreloadedSubscription<Project[]>('app', 'projects.list')
+
+if (projects.loading) return <Skeleton/>
+if (projects.preloadFailed) return <Spinner label="Loading…"/>  // not empty — unasked
+return <ProjectTable rows={projects.data}/>
+```
+
+It is a boolean and says nothing about WHY. The server's failure text is a
+refused call's error message; it belongs in the server log, which is the one
+place a browser cannot read. It also says nothing about the LIVE subscription,
+which usually recovers on its own — the browser reconnects with a credential the
+SSR request did not have. Read it as "the first paint has no server data, and
+that was not for lack of asking", which is exactly enough to pick a spinner over
+an empty state.
+
 ### Seeding by hand
 
 `export const preload` is sugar over an explicit seed. When a loader ALREADY has

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

@@ -1835,7 +1835,7 @@ The token is the same one the remote app boots with:
 VOLTRO_INSPECT_TOKEN=<secret> voltro start
 ```
 
-See [Introspection](/docs/observability/inspect) for the full auth
+See [Introspection](/docs/cli/inspect) for the full auth
 configuration.
 
 ## URL shape
@@ -1861,7 +1861,7 @@ appends it. The trailing-slash variant works too.
 
 - [Migration overview](/docs/database/migrations) — the
   plan/apply lifecycle this slots into
-- [Introspection](/docs/observability/inspect) — the
+- [Introspection](/docs/cli/inspect) — the
   `/_voltro/inspect/*` surface this command consumes
 - [Drift detection](/docs/database/migrations/drift) — fingerprint-based
   drift surfacing the same inspect endpoint emits

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

@@ -1043,7 +1043,7 @@ MariaDB's GTID format differs from MySQL's: `0-1-100` (domain-server-sequence) v
 - **`mariadb` schema package is wire-compatible with `mysql`**. If you migrate from MySQL → MariaDB, the framework re-emits DDL cleanly via `applySchema(..., 'mariadb')`. Production data round-trips through `mysqldump` without translation.
 - **`sql_mode=NO_BACKSLASH_ESCAPES`** is sometimes set on MariaDB deploys. The framework's identifier escaping handles it, but user-written `unsafe()` strings that hand-escape backslashes may produce wrong output. Leave that mode off if you can.
 - **Sequence-based ID columns**. MariaDB has true CREATE SEQUENCE; the framework doesn't use it (TypeID / ULID / Snowflake are client-side). If you reach for sequences for legacy reasons, they're outside the framework's auto-injection path.
-- **Hand-rolled `AUTO_INCREMENT` primary keys** work the same as on mysql: an `insert` / `insertMany` with no client-side `id` recovers the DB-generated id via `LAST_INSERT_ID()` (connection-pinned; `insertMany` recovers the whole consecutive range). See the [mysql page](/docs/en/database/dialects/mysql#auto_increment-ids--last_insert_id-recovery) for the worked example — the recovery path is identical on both engines.
+- **Hand-rolled `AUTO_INCREMENT` primary keys** work the same as on mysql: an `insert` / `insertMany` with no client-side `id` recovers the DB-generated id via `LAST_INSERT_ID()` (connection-pinned; `insertMany` recovers the whole consecutive range). See the [mysql page](/docs/database/dialects/mysql#auto_increment-ids--last_insert_id-recovery) for the worked example — the recovery path is identical on both engines.
 
 ## Where it lives
 
@@ -1080,7 +1080,7 @@ SQL Server 2016 / 2017 work for the basic workflow path; some performance charac
 ```sh
 DB_DIALECT=mssql
 DB_URL=mssql://sa:<password>@localhost:11433/voltro_test
-# or discrete fields: DB_DIALECT + DB_HOST / DB_PORT / DB_USER / DB_PASSWORD / DB_NAME
+# or discrete fields: DB_DIALECT + DB_HOST / DB_PORT / DB_USER / DB_PASSWORD / DB_DATABASE
 
 # Local Docker dev fixture defaults:
 #   container: mcr.microsoft.com/mssql/server:2022-latest

package/templates/agent-docs/deployment.md

@@ -1248,21 +1248,35 @@ those do not come out of the pool budget, they come out of the DATABASE's.
 
 Set `REPLICA_COUNT` from your deployment (Helm: `{{ .Values.replicaCount }}`) and
 the line does the multiplication for you; without it the line still names the
-formula. `voltro dev` deliberately does not print it — one process, no replicas.
+formula.
+
+**`voltro dev` prints it too, when the environment says it is not a laptop.**
+A bare `voltro dev` stays silent — one process, no replicas, nothing to
+multiply. But `voltro dev` is a supported way to RUN an app, and a deployment
+that uses it needs this line as much as any other. So it prints whenever
+`REPLICA_COUNT`, `DB_MAX_CONNECTIONS` / `PG_MAX_CONNECTIONS`, or
+`DB_REPLICA_URLS` is set — each of which means somebody has already decided
+something about the number.
 
 **Some connections are not in the pool, and the count is per process.** A
-connection running `LISTEN` cannot be returned to a pool, so the driver opens a
-standalone one. There are three such places and a full deployment can hold all
-three:
+connection that speaks a long-lived protocol cannot be returned to a pool, so
+the driver opens a standalone one. There are four such places and a full
+deployment can hold several at once:
 
 | Process | Connection | When |
 |---|---|---|
-| api `voltro serve` | CDC `LISTEN` consumer | `changeStrategy: 'cdc'` (the default on postgres) |
+| api `voltro serve` / `dev` | CDC `LISTEN` consumer | postgres, `changeStrategy: 'cdc'` (the default) |
+| api `voltro serve` / `dev` | binlog CDC reader | mysql / mariadb, `changeStrategy: 'cdc'` |
 | web `voltro start` | ISR invalidator `LISTEN` | any page declares `cacheInvalidatesOn` |
 | web `voltro start` | postgres ISR cache client | `SSR_CACHE=postgres` |
 
-The third is not a `LISTEN` at all, which is why counting `LISTEN` rows in
-`pg_stat_activity` undercounts. Each process prints its own number in the boot
+SQL Server is the one CDC dialect that costs nothing here: Change Tracking is
+read with ordinary queries through the pool, so its out-of-pool count is a
+verified zero rather than an omission.
+
+Two of the four are not a `LISTEN` at all — the binlog reader speaks the
+replication protocol, and the ISR cache client is an ordinary client — which is
+why counting `LISTEN` rows in `pg_stat_activity` undercounts. Each process prints its own number in the boot
 line above — including `No connections outside the pool in this process` when
 there are none, so "counted, zero" is distinguishable from "not counted".
 

package/templates/agent-docs/internationalization.md

@@ -838,9 +838,16 @@ program.pipe(withTimezone('Europe/Berlin'))
 ```
 
 `currentTimezone` never fails — an absent context is the documented `UTC`
-default, so call sites don't handle a missing-service error. The runtime provides
-the tag per request (via `resolvedTimezoneLayer`); the web layer's `useTimezone()`
-hook is a thin projection over it.
+default, so call sites don't handle a missing-service error.
+
+> **What ships today is the SEAM, not the wiring.** `@voltro/datetime/context`
+> exports `currentTimezone`, `withTimezone` and `resolvedTimezoneLayer`, and you
+> provide the layer yourself. The framework does **not** yet install it per
+> request, and there is **no `useTimezone()` hook** in the web layer — both are
+> planned to land in `@voltro/runtime` + `@voltro/web`. Until then: resolve the
+> zone yourself (`resolveTimezone`) and provide `resolvedTimezoneLayer` around
+> the work that needs it, or pass an explicit `timeZone` argument. Without a
+> provided layer every call reads the `UTC` default.
 
 ## Arithmetic — the DST split is in the names