@voltro/cli 0.55.0 → 0.57.0

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

@@ -222,8 +222,8 @@ 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-DfVZaoys.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
-	return r((await n(await t(e))).events.map((e) => ({
+	let { walk: t, loadDiscovered: n } = await import("./dev-Bl9HqtV7.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
+	return r((await n(await t(e), { root: e })).events.map((e) => ({
 		file: e.file,
 		descriptor: e.descriptor
 	}))).map((e) => x(e.descriptor));

package/dist/{workflowsCmd-BGF-mRZ5.js → workflowsCmd-g-DNpaUc.js}

@@ -1,5 +1,5 @@
 import { n as e } from "./cliOutput-D1tSBoRM.js";
-import { n as t, o as n, r, t as i } from "./inspectFetch-EMuhTG_9.js";
+import { n as t, o as n, r, t as i } from "./inspectFetch-BU1NyzxV.js";
 import { ansi as a } from "@voltro/logger";
 //#region src/workflowsCmd.ts
 var o = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.55.0",
+  "version": "0.57.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -766,6 +766,42 @@
         "title": "WidgetKind gained 'rich-text' — total widget registries need one new entry",
         "kind": "manual"
       },
+      {
+        "version": "0.56.0",
+        "id": "0.56.0/01_inspect_answers_are_observations",
+        "title": "inspect answers are `Observation`s — the payload is `.data`",
+        "kind": "manual"
+      },
+      {
+        "version": "0.56.0",
+        "id": "0.56.0/02_broadcast_gap_is_one_object",
+        "title": "attachBroadcastBus's onGap now receives a single BroadcastGap object",
+        "kind": "manual"
+      },
+      {
+        "version": "0.56.0",
+        "id": "0.56.0/03_outbox_drain_needs_an_identity",
+        "title": "drainOutbox now requires claimedBy — the fleet-wide exactly-once gate",
+        "kind": "manual"
+      },
+      {
+        "version": "0.56.0",
+        "id": "0.56.0/04_reaction_dedupe_is_one_claim",
+        "title": "runReaction's dedupe is a single atomic claim",
+        "kind": "manual"
+      },
+      {
+        "version": "0.56.0",
+        "id": "0.56.0/05_plugin_bind_context_claims_a_change",
+        "title": "PluginBindContext requires claimChange; change identity moved to @voltro/database",
+        "kind": "manual"
+      },
+      {
+        "version": "0.56.0",
+        "id": "0.56.0/06_serve_is_api_only",
+        "title": "`voltro serve` on a WEB app now refuses — use `voltro start`",
+        "kind": "manual"
+      },
       {
         "version": "0.6.0",
         "id": "0.6.0/01_no-dev-session-secret",
@@ -848,24 +884,24 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.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",
+    "@voltro/ai": "0.57.0",
+    "@voltro/cache": "0.57.0",
+    "@voltro/client": "0.57.0",
+    "@voltro/content": "0.57.0",
+    "@voltro/data-transfer": "0.57.0",
+    "@voltro/database": "0.57.0",
+    "@voltro/env": "0.57.0",
+    "@voltro/kv": "0.57.0",
+    "@voltro/logger": "0.57.0",
+    "@voltro/plugin-auth": "0.57.0",
+    "@voltro/plugin-broadcast": "0.57.0",
+    "@voltro/plugin-mail": "0.57.0",
+    "@voltro/plugin-storage": "0.57.0",
+    "@voltro/plugin-webhooks": "0.57.0",
+    "@voltro/protocol": "0.57.0",
+    "@voltro/runtime": "0.57.0",
+    "@voltro/serverless": "0.57.0",
+    "@voltro/workflow": "0.57.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.core.md

@@ -142,6 +142,24 @@ line below replaces something real apps write by hand hundreds of times.
    notify-helper at the tail of the mutation body instead makes the reactivity
    invisible — you can only find it by reading every executor. Both are
    best-effort, so genuinely critical delivery still belongs in a workflow.
+   **A subscriber runs on EVERY replica.** That is right for a handler that
+   refreshes an index or drops a process-local cache, and wrong for one whose
+   effect IS a write someone receives — two pods send two mails. When the
+   handler is an effect, add `once:` (a deterministic key per change) and
+   exactly one replica runs it:
+   ```ts
+   defineSubscriber({
+     table: 'absence_requests', on: ['insert'],
+     once: true,
+     handler: notifyApprovers,
+   })
+   ```
+   `once: true` derives the key from the change (content + its position among
+   content-identical repeats) — prefer it. A function is for when you want to be
+   COARSER than one-per-change; a key you write must tell two genuine changes
+   apart, and a row id does not for `update`. `once` is AT MOST once — a replica
+   that wins and dies takes the event with it. `defineReaction`'s `dedupeKey`
+   gives its act the same fleet-wide gate.
 4. **A roll-up / counter recomputed on every read?** → **`defineAggregate`**
    (`*.aggregate.ts`). Add `incremental:` for `count|sum|avg|min|max` group-bys
    and it is MAINTAINED on write rather than recomputed. `read({ where })`
@@ -217,6 +235,7 @@ line below replaces something real apps write by hand hundreds of times.
 | `const rows = …; if (!rows[0]) throw new NotFound()` | `.one()` |
 | 3+ sequential `store.query` to assemble related data | `relations()` + `.with()` |
 | a notify/webhook helper called at the end of a mutation | `defineSubscriber` / `defineReaction` |
+| a subscriber that sends a mail / notification / webhook | the same, plus **`once:`** — without it, one per replica |
 | `WHERE ownerId = me` in every list handler | `setRowFilter` (covers the SUBSCRIPTION too) |
 | a counter recomputed by scanning rows on every read | `defineAggregate` (+ `incremental:`) |
 | `requireScope(...)` as the first line of every executor | `guards:` on the descriptor |
@@ -358,7 +377,7 @@ public REST routes, declared via `restRoutes` in `app.config.ts`).
 | `*.workflow.tsx` + `*.workflow.server.tsx` | durable multi-step work |
 | `*.trigger.tsx` | domain event → workflow |
 | `*.cron.tsx` | scheduled job (single file) |
-| `*.subscribe.ts` | best-effort post-commit reaction to a table |
+| `*.subscribe.ts` | best-effort post-commit reaction to a table (every replica; `once:` for one) |
 | `*.reaction.tsx` | standing reactive agent |
 | `*.aggregate.ts` | scheduled materialised query |
 | `*.startup.tsx` | run-once boot hook holding a resource |

package/templates/AGENTS.md

@@ -142,6 +142,24 @@ line below replaces something real apps write by hand hundreds of times.
    notify-helper at the tail of the mutation body instead makes the reactivity
    invisible — you can only find it by reading every executor. Both are
    best-effort, so genuinely critical delivery still belongs in a workflow.
+   **A subscriber runs on EVERY replica.** That is right for a handler that
+   refreshes an index or drops a process-local cache, and wrong for one whose
+   effect IS a write someone receives — two pods send two mails. When the
+   handler is an effect, add `once:` (a deterministic key per change) and
+   exactly one replica runs it:
+   ```ts
+   defineSubscriber({
+     table: 'absence_requests', on: ['insert'],
+     once: true,
+     handler: notifyApprovers,
+   })
+   ```
+   `once: true` derives the key from the change (content + its position among
+   content-identical repeats) — prefer it. A function is for when you want to be
+   COARSER than one-per-change; a key you write must tell two genuine changes
+   apart, and a row id does not for `update`. `once` is AT MOST once — a replica
+   that wins and dies takes the event with it. `defineReaction`'s `dedupeKey`
+   gives its act the same fleet-wide gate.
 4. **A roll-up / counter recomputed on every read?** → **`defineAggregate`**
    (`*.aggregate.ts`). Add `incremental:` for `count|sum|avg|min|max` group-bys
    and it is MAINTAINED on write rather than recomputed. `read({ where })`
@@ -217,6 +235,7 @@ line below replaces something real apps write by hand hundreds of times.
 | `const rows = …; if (!rows[0]) throw new NotFound()` | `.one()` |
 | 3+ sequential `store.query` to assemble related data | `relations()` + `.with()` |
 | a notify/webhook helper called at the end of a mutation | `defineSubscriber` / `defineReaction` |
+| a subscriber that sends a mail / notification / webhook | the same, plus **`once:`** — without it, one per replica |
 | `WHERE ownerId = me` in every list handler | `setRowFilter` (covers the SUBSCRIPTION too) |
 | a counter recomputed by scanning rows on every read | `defineAggregate` (+ `incremental:`) |
 | `requireScope(...)` as the first line of every executor | `guards:` on the descriptor |
@@ -358,7 +377,7 @@ public REST routes, declared via `restRoutes` in `app.config.ts`).
 | `*.workflow.tsx` + `*.workflow.server.tsx` | durable multi-step work |
 | `*.trigger.tsx` | domain event → workflow |
 | `*.cron.tsx` | scheduled job (single file) |
-| `*.subscribe.ts` | best-effort post-commit reaction to a table |
+| `*.subscribe.ts` | best-effort post-commit reaction to a table (every replica; `once:` for one) |
 | `*.reaction.tsx` | standing reactive agent |
 | `*.aggregate.ts` | scheduled materialised query |
 | `*.startup.tsx` | run-once boot hook holding a resource |
@@ -730,7 +749,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **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. |
+| **What's new in 0.57.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.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. |
+| **What's new in 0.57.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/_manifest.json

@@ -206,7 +206,7 @@
       "group": null,
       "description": "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.",
       "path": "agent-docs/observability.md",
-      "files": 4
+      "files": 5
     },
     {
       "id": "plugins",
@@ -260,7 +260,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": 23
+      "files": 24
     },
     {
       "id": "security",

package/templates/agent-docs/ai.md

@@ -1326,7 +1326,7 @@ 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 multi-node deployments use `dataStoreResumableStreamStore(ctx.store)` — it persists to the framework's own database (`_voltro_stream_events` + `_voltro_stream_state`, created for you: the table assembly adds both for any app that depends on `@voltro/ai`, so `voltro dev` / `voltro db apply` / `voltro migrate` all plan them) 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

@@ -2691,31 +2691,46 @@ comment, and this one is load-bearing: the resume grant is issued on its
 strength. Omit `tables:` entirely and nothing is verified and nothing resumes —
 the conservative default.
 
-## Eager loads are refused, not silently unfiltered
+## Eager loads are narrowed too
 
 A relation pulled in with `.with(...)` is resolved **below** the seam that
-applies the filter: the stores expand the eager tree themselves (the memory
-store recurses through its own raw read; the SQL stores fold the relation into
-one join). So a filtered table reached through a relation would come back
-unfiltered.
+AND-merges the filter onto a read's base table: the stores expand the eager tree
+themselves (the memory store recurses through its own raw read; the SQL stores
+fold the relation into one join or JSON aggregate). So for a while a filtered
+table reached through a relation came back unfiltered, and then — once that was
+found — the read refused rather than serve those rows.
 
-Rather than serve those rows, the read **refuses**, naming the table and both
-ways out:
+Neither is the case now. The middleware writes your filter's predicate into each
+narrowed branch's `where`, which is where a caller could have put it themselves,
+so every resolver on every dialect applies it without knowing a row filter
+exists:
 
+```ts
+// what you wrote
+notes.with({ readers: true })
+
+// what the store resolves, when your filter narrows `readers`
+notes.with({ readers: { where: /* your filter's predicate for `readers` */ } })
 ```
-row filter: 'readers' is reached through an eager load on 'notes', and an eager
-relation is resolved BELOW the row filter — its rows would come back
-unfiltered. Refusing the read rather than serving it.
-  → read 'readers' as its own query (it is filtered there), or
-  → drop 'readers' from this .with(...) if the relation does not need
-    row-level narrowing.
-```
 
-Only relations reaching a table your filter actually narrows are affected —
-every other eager load is untouched. Applying the filter inside eager
-compilation is the real fix and it is a per-dialect change; until then this is
-a refusal rather than a leak, for the same reason the module refuses to
-fail open.
+Your own `where` is kept and the filter goes **under** it, so a branch you
+narrowed stays narrower and nothing a caller writes can widen the filter.
+Nested `.with(...)` is narrowed at every level. A relation reaching a table your
+filter does not narrow is untouched.
+
+**One case still refuses: a filtered `manyToMany` JUNCTION.** A branch `where`
+is a predicate on the relation's TARGET, and a filter narrowing the junction has
+nowhere to be expressed — so that read raises rather than joining junction rows
+the filter would have removed:
+
+```
+row filter: the junction table 'noteTags' behind relation 'tags' on 'notes' is
+row-filtered, and a many-to-many junction is read below the seam that could
+narrow it — its rows would be joined unfiltered. Refusing the read rather than
+serving it.
+  → read 'noteTags' as its own query (it is filtered there), or
+  → drop 'tags' from this .with(...).
+```
 
 ## Row filters vs. guards
 

package/templates/agent-docs/cli.md

@@ -1441,6 +1441,86 @@ Type mapping is faithful: `string → String`, `integer → Int`, `number → Do
 
 **Scope — this is the SDK code generator, not a native runtime.** Deliberately out of scope (they need a native runtime or managed infra, not generated client code): native module bindings (camera, biometrics), the APNs/FCM push **sender** (per-tenant Apple/Firebase credentials, provisioned server-side), and the managed OTA / EAS build pipeline. The generated source is verified at the generator level (golden-string tests over the emitted Swift + Kotlin). Compiling it with `swiftc` / Gradle is the remaining step in your own mobile CI — the framework harness has no Swift/Kotlin toolchain.
 
+## Serving: asset prefix, pre-compression, sourcemaps, keep-alive
+
+Four knobs that decide what leaves the container. All are `voltro start`
+concerns; none change what your code does.
+
+```ts
+// apps/web/app.config.ts
+web: {
+  // Serve `assets/` from a CDN. Becomes vite's `base`, so every emitted URL —
+  // entry, modulepreloads, CSS, images, fonts — is written with the prefix at
+  // BUILD time. Pre-rendered HTML still comes from the app; upload
+  // `dist/assets/` to the prefix on deploy. Filenames are content-hashed, so a
+  // previous deploy's assets stay valid for a visitor mid-navigation.
+  assetPrefix: 'https://cdn.example.com/_assets',
+
+  // Emit `.map` files WITHOUT a `//# sourceMappingURL` comment, so nothing in
+  // the shipped JS points at them. For `plugin-sentry`: upload them in your
+  // deploy step and DELETE them before the image is built. `voltro start`
+  // refuses to serve a `.map` regardless, so a forgotten delete is not a leak.
+  sourcemaps: 'hidden',
+},
+http: {
+  // Node hangs up an idle keep-alive connection after 5s; every proxy in front
+  // holds one longer, and the request that lands in that window comes back as
+  // a 502. Default 72000 clears nginx-60/ALB-60; raise it above YOUR proxy's
+  // idle timeout. `headersTimeoutMs` must exceed it and is derived if omitted.
+  keepAliveTimeoutMs: 72_000,
+},
+```
+
+**Pre-compression is automatic.** `voltro build` writes `.br` (quality 11) and
+`.gz` beside every content-hashed asset over 1 KB, and `voltro start` serves the
+variant when the client accepts it. Measured on one 321 KB chunk, three requests:
+
+| | time | bytes |
+|---|---:|---:|
+| compressed per request (before) | 5.6 / 5.0 / 4.6 ms | 100 665 |
+| pre-compressed (now) | 1.6 / 1.7 ms | **86 083** |
+
+Faster *and* smaller: a build can afford brotli q11 where a per-request path
+cannot. Both encodings of one asset carry the same `ETag` — it is computed over
+the uncompressed file, so a shared cache sees one representation.
+
+**A cross-origin api gets a `preconnect`.** When an api's `wsUrl` is on another
+host, the shell carries `<link rel="preconnect" href="…" crossorigin>` so DNS +
+TCP + TLS overlap the bundle download instead of following it. Same-origin apis
+are skipped — the browser already has that connection.
+
+## `voltro serve <appDir>` — API apps only
+
+`voltro serve` is the production server for an **API** app. On a **web** app it
+refuses and points you at `voltro start`:
+
+```text
+`voltro serve` is the production server for an API app — this is a WEB app.
+
+  production   voltro start .
+  development  voltro dev .
+```
+
+That is a refusal, not a missing feature. `serve` used to build a web app a
+second time and hand it to `vite preview`, and both halves were wrong:
+
+- **In production it never ran.** The launcher's serve fast path requires
+  `.framework/dist-api/serveBundle/serveEntry.js` — an artefact a web build does
+  not produce — so a web app exited 1 pointing at a path that cannot exist,
+  directly after a `voltro build` that had just succeeded.
+- **Below production it destroyed the build.** That second build had no
+  `@tailwindcss/vite`, no image pipeline and no per-page islands entries. With
+  Tailwind it aborted; without it, it succeeded — and since both builds write
+  `.framework/dist`, which Vite empties, it deleted `dist/server`, the island
+  shells and every pre-rendered page. `voltro start` could then not boot at all.
+
+So the table is:
+
+| app | development | production |
+|---|---|---|
+| web | `voltro dev` | `voltro start` |
+| api | `voltro dev` | `voltro serve` |
+
 ## `voltro doctor` — preflight a production serve
 
 Production `voltro serve` for an **API** app boots ONLY from the precompiled serve
@@ -1775,6 +1855,9 @@ It covers both halves of the stack:
 | server | `requireScope(...)` at the top of an executor | `guards:` on the descriptor |
 | server | a `token` / `secret` / `password` column with no encryption | `.encrypted()` |
 | server | a notify / webhook helper called at a mutation's tail | `defineSubscriber` / `defineReaction` |
+| server | a `*.subscribe.ts` handler that writes or publishes, with no `once:` | `once: true` on `defineSubscriber` |
+| server | an executor builds a field its descriptor's `output` does not declare | add it to `output` — the struct IS the serializer |
+| server | a mutation writes a NULLABLE column through an input field that cannot be `null` | `Schema.optional(Schema.NullOr(...))` |
 | server | `hasMore` + `limit + 1` | `paginateById` |
 | server | `.getTime()` / `.toISOString()` mapping a row on the way out | `timestampMs` / `timestampMsOrNull` from `@voltro/database/wire` in the descriptor's `output` struct |
 | client | per-field `useState` + a submit flag | `useFormBinding` |
@@ -1801,6 +1884,47 @@ already uses `.one()`, stays silent.
 
 Two of them are worth spelling out, because their advice is not one-line:
 
+**The subscriber rule is the second half of the mutation-tail rule.** That one
+moves an effect OUT of a mutation and into a subscriber, which is right — and
+lands it on a channel every replica listens to. `store.onChange` is a broadcast:
+correct for a READER (a cache drop, an index refresh, a live query must run
+everywhere) and a multiplier for an EFFECT, because there is nothing to make
+idempotent — the effect IS the write, so each run produces another one. One
+`INSERT` behind two replicas therefore writes two notification rows, and four
+with a broadcast bus in front.
+
+So the rule fires when a handler WRITES (`ctx.store.insert` / `update` /
+`upsert` / …), publishes (`ctx.publish`), or calls a `notify` / `sendWebhook` /
+`sendMail`-shaped helper, and the subscriber declares no `once:`. Any `once:`
+silences it — `true` or a key function — because the question is whether the
+decision was made, not which way. It reads the handler through the AST, so
+`handler: notifyApprovers` naming a function in the same file is judged exactly
+like an inline arrow; a handler IMPORTED from another module is not judged at
+all, since its body is not in the file being read.
+
+**Two rules read a DECLARATION against a DECLARATION, and are therefore exact.**
+`executor-builds-an-undeclared-field` compares the object literal an executor
+returns with its descriptor's `output` struct: since the struct IS the
+serializer, a key it does not declare is stripped on the way out, so every
+reader downstream gets `undefined` and renders a blank with nothing logged
+anywhere. `nullable-column-a-mutation-cannot-clear` compares a mutation's target
+table's nullable columns with its input schema — a nullable column written
+through a field that cannot be `null` can be set once and never emptied.
+
+Both REFUSE rather than guess, and the refusals are the interesting part. A
+spread on either side of the output comparison (`{ ...row, extra }`, or a
+`...Base` inside the declared struct) means the key set is not knowable from the
+source; reporting the visible half would name the field the author can already
+see and miss the ones they cannot. An output that is a named schema rather than
+a literal struct is unjudgeable, not empty — the second reading would make every
+field a finding. And a table declaration the scan cannot find produces no
+finding at all, because "this table has no nullable columns" and "I could not
+look" lead to opposite conclusions.
+
+It stays quiet on a reader on purpose. `once:` on a cache-warming subscriber
+would silence it on every replica but one, which is worse than the repetition it
+removes — only the handler's author knows which of the two they wrote.
+
 **The credential-column rule skips names that aren't credentials.** A name ending
 in `Id` / `_id`, a name ending in `Hash` / `_hash`, and a name beginning with
 `vault` are all left alone:
@@ -2265,6 +2389,33 @@ voltro check             --url https://api.example.com
 
 `--token` (or `VOLTRO_INSPECT_TOKEN`) supplies the bearer; `VOLTRO_INSPECT_URL` sets a default target so you can drop the flag. Works for `inspect`, `logs`, `traces`, `workflows`, `cluster` and `check`.
 
+### `logs` and `traces` need a ring on the target — off by default
+
+A deployed app runs `voltro serve`, and `voltro serve` keeps **no** in-process log ring or span buffer unless you ask for one. Without it both commands answer:
+
+```
+voltro logs: NOTHING WAS SEARCHED — the target could not be read: HTTP 404
+endpoint not enabled on this instance — This instance keeps no in-process logs ring…
+```
+
+That headline is the point: *"no records matched the given filters"* would have sent you off widening `--tail` forever. Turn a ring on per app:
+
+```ts
+// app.config.ts
+export default defineAppConfig({
+  inspect: {
+    logs:   true,              // default size
+    traces: { size: 2_000 },   // or name it
+  },
+})
+```
+
+or per deployment, without a rebuild: `VOLTRO_INSPECT_LOGS=2000`, `VOLTRO_INSPECT_TRACES=on`, `=off` to override a config that declared one.
+
+**Why off by default.** A ring is memory on every replica, forever, for data most deployments already collect from stdout through their platform's pipeline. That pipeline stays the main road; the ring answers the different question — *what has THIS instance been doing in the last few minutes* — and it answers it for a hosted app, where reading a pod's stdout is not an option.
+
+**What a ring does not do.** It holds a bounded number of records on ONE replica. Against a fleet you are reading 1/N, and it is not retention: a restart empties it. `voltro dev` keeps both rings unconditionally — this switch is about what production does.
+
 ## `voltro probe access` — is a declared guard actually enforced?
 
 `voltro check` reads an app's manifest and reports a procedure with **no access
@@ -4548,6 +4699,25 @@ prints only because your tree matched it.
 
 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).
 
+### When nothing changed, read WHICH nothing
+
+Two states end an update with no diff, and they mean opposite things: the jump
+ships no codemods, or it ships some and every one of them decided your project
+is not affected. The summary names which:
+
+```text
+codemods: 2 ship for this jump; none matched your project.
+  · 0.55.0/01_target-relations-declare-columns — its own check found nothing to change
+  · 0.55.0/02_widget-kind-gained-rich-text — its own check found nothing to change
+```
+
+`none ship for this jump` is the first. The second lists the ids, because a
+codemod's own check is a predicate that can be wrong — and a gate that reads
+the wrong files answers "does not apply" for a project that is fully affected.
+If you recognise a subject in that list as something your app *does* use, that
+is a bug in the check rather than a fact about your code; the CHANGELOG entry
+for the version says what each one looks for.
+
 ## 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.

package/templates/agent-docs/configuration.md

@@ -202,10 +202,35 @@ is accepted but only reachable from server-side render code, and the boot
 ## Plugins declare their env
 
 A plugin that reads environment variables declares them via `declaredEnv` on its
-`VoltroPlugin` (metadata only — the plugin still reads its own values). This
-makes a plugin's env needs visible in the manifest, `.env.example`, and the
-dashboard. The first-party plugins already declare theirs, so the manifest is
-complete out of the box.
+`VoltroPlugin`. The plugin still reads its own values; declaring them makes its
+env needs visible in the manifest, `.env.example`, and the dashboard. The
+first-party plugins already declare theirs, so the manifest is complete out of
+the box.
+
+**`required: true` is a boot CONTRACT, not documentation.** Every required entry
+is resolved before any plugin activates, and one that does not resolve **aborts
+the boot** with the plugin named:
+
+```
+plugin environment validation failed (1 variable):
+  • STRIPE_SECRET_KEY — required by @voltro/plugin-billing, and nothing set it
+      Stripe API secret key.
+  → set the variable, or pass the value as a plugin option if the plugin takes one, or
+    declare it yourself in app.config.ts's `env` (an app declaration overrides a plugin's).
+```
+
+That is the point of failing at the boot: a deployment variable which silently
+stops being set — a rotated secret, a typo in a values file, a CI variable nobody
+created — is routine, and the alternative is finding out from the first customer.
+
+A `secret: true` variable resolves through the configured **secrets backend**,
+not just `process.env`. A backend that cannot answer fails the boot too, reported
+as *unreadable* rather than as an absent variable — those are different facts and
+need different next steps.
+
+Your own `defineEnv` declaration of the same variable **overrides the plugin's**:
+declare it there to give it a default, or to mark it optional because you pass
+the value as a plugin option instead.
 
 ## Anti-pattern