@voltro/cli 0.29.0 → 0.30.1

package/dist/startEntry.js

@@ -1,3 +1,3 @@
-import { et as e } from "./inspectMetrics-DHYygE4s.js";
-import { t } from "./start-CsCIaW4-.js";
+import { et as e } from "./inspectMetrics-CkB2J0Zn.js";
+import { t } from "./start-egkbpugc.js";
 export { e as loadDotEnv, t as runStartCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.29.0",
+  "version": "0.30.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.29.0",
-    "@voltro/cache": "0.29.0",
-    "@voltro/data-transfer": "0.29.0",
-    "@voltro/database": "0.29.0",
-    "@voltro/env": "0.29.0",
-    "@voltro/kv": "0.29.0",
-    "@voltro/logger": "0.29.0",
-    "@voltro/plugin-auth": "0.29.0",
-    "@voltro/plugin-broadcast": "0.29.0",
-    "@voltro/plugin-mail": "0.29.0",
-    "@voltro/plugin-storage": "0.29.0",
-    "@voltro/plugin-webhooks": "0.29.0",
-    "@voltro/protocol": "0.29.0",
-    "@voltro/runtime": "0.29.0",
-    "@voltro/serverless": "0.29.0",
-    "@voltro/workflow": "0.29.0",
+    "@voltro/ai": "0.30.1",
+    "@voltro/cache": "0.30.1",
+    "@voltro/data-transfer": "0.30.1",
+    "@voltro/database": "0.30.1",
+    "@voltro/env": "0.30.1",
+    "@voltro/kv": "0.30.1",
+    "@voltro/logger": "0.30.1",
+    "@voltro/plugin-auth": "0.30.1",
+    "@voltro/plugin-broadcast": "0.30.1",
+    "@voltro/plugin-mail": "0.30.1",
+    "@voltro/plugin-storage": "0.30.1",
+    "@voltro/plugin-webhooks": "0.30.1",
+    "@voltro/protocol": "0.30.1",
+    "@voltro/runtime": "0.30.1",
+    "@voltro/serverless": "0.30.1",
+    "@voltro/workflow": "0.30.1",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.core.md

@@ -67,6 +67,56 @@ Ask in order; stop at the first "yes":
 Deep dive: **`data.md`** (queries/mutations/actions/streams/errors),
 **`workflows.md`**, **`scheduling.md`**.
 
+**Do NOT hand-roll debounce / one-at-a-time / rate limits around a workflow.**
+They are fields on `workflow({...})`, enforced BEFORE a run exists:
+
+```ts
+debounce:    { key: (p) => `tour:${p.rowId}`, period: '15 minutes' }
+singleton:   { key: (p) => p.tenantId, mode: 'skip' | 'cancel' }
+concurrency: { limit: 5, key: (p) => p.tenantId }
+throttle:    { limit: 100, period: '1 minute' }   // queues the excess
+rateLimit:   { limit: 100, period: '1 minute' }   // DROPS the excess
+batch:       { item: Item, key: (i) => i.tenantId, maxSize: 100, timeout: '30 seconds' }
+timeouts:    { start: '1 hour', finish: '10 minutes' }
+onFailure:   'notifierWorkflowName'
+cancelOn:    [{ event: 'jira.issue.deleted', schema: Deleted,
+                match: (e, p) => e.issueKey === p.issueKey }]
+```
+
+The hand-rolled version (an idempotency key carrying a timestamp + a re-check
+loop + a round cap) costs one durable cluster entity PER START to express "one
+job, latest deadline". `voltro workflows flow` shows what is queued and why.
+
+`cancelOn` reaches a run whose fiber is not executing anything — sleeping,
+suspended, or still queued — which a race inside the body cannot. `match` is
+REQUIRED (the omitted case would cancel every live run); a run that started AFTER
+the event is never cancelled; queued starts of the same workflow are discarded
+too, or the debounced duplicate fires seconds later against the deleted row.
+
+Stopping or re-driving MANY runs is `voltro workflows cancel-many` /
+`replay-many`. Both are a DRY RUN until `--commit`, `--limit` is required (the cap
+IS the blast radius; `truncated` says whether more matched), and a cancel needs a
+`--reason` that lands on every affected run.
+
+A model call inside a workflow: `aiStep` / `aiObjectStep` from
+`@voltro/ai/workflow`. Pass `store: ctx.store` and the spend is recorded per step;
+the prompt is journaled as a DIGEST unless you write `recordPrompt: 'full'`. Add
+`offload: true` and the run SUSPENDS instead of holding a worker while the model
+thinks — a dispatcher owns the call and resumes the run. Costs one suspend/resume
+round trip (~250ms), so offload the slow calls and leave a fast classification
+inline.
+
+**`idempotencyKey` is the execution's IDENTITY, permanently — not a dedupe
+window.** A second start with the same key replays the first run's result
+forever; after it completes the key is SPENT and a genuinely new invocation is a
+silent no-op. So it must vary per unit of work (`` `tour:${rowId}:${editedAt}` ``,
+not `` `tour:${rowId}` ``), while a flow-control `key` — the RESOURCE runs
+compete for — stays stable. Those are two different fields; conflating them is
+what makes "I need to re-arm a key" feel like a missing feature.
+
+A start can now come back `queued` / `dropped` / `skipped` with
+`executionId: null`, so narrow on `handle.status` before using the id.
+
 ### Pick the SERVER primitive (inside a handler)
 
 The four above answer "which FILE do I write". This answers "what do I write

package/templates/AGENTS.md

@@ -67,6 +67,56 @@ Ask in order; stop at the first "yes":
 Deep dive: **`data.md`** (queries/mutations/actions/streams/errors),
 **`workflows.md`**, **`scheduling.md`**.
 
+**Do NOT hand-roll debounce / one-at-a-time / rate limits around a workflow.**
+They are fields on `workflow({...})`, enforced BEFORE a run exists:
+
+```ts
+debounce:    { key: (p) => `tour:${p.rowId}`, period: '15 minutes' }
+singleton:   { key: (p) => p.tenantId, mode: 'skip' | 'cancel' }
+concurrency: { limit: 5, key: (p) => p.tenantId }
+throttle:    { limit: 100, period: '1 minute' }   // queues the excess
+rateLimit:   { limit: 100, period: '1 minute' }   // DROPS the excess
+batch:       { item: Item, key: (i) => i.tenantId, maxSize: 100, timeout: '30 seconds' }
+timeouts:    { start: '1 hour', finish: '10 minutes' }
+onFailure:   'notifierWorkflowName'
+cancelOn:    [{ event: 'jira.issue.deleted', schema: Deleted,
+                match: (e, p) => e.issueKey === p.issueKey }]
+```
+
+The hand-rolled version (an idempotency key carrying a timestamp + a re-check
+loop + a round cap) costs one durable cluster entity PER START to express "one
+job, latest deadline". `voltro workflows flow` shows what is queued and why.
+
+`cancelOn` reaches a run whose fiber is not executing anything — sleeping,
+suspended, or still queued — which a race inside the body cannot. `match` is
+REQUIRED (the omitted case would cancel every live run); a run that started AFTER
+the event is never cancelled; queued starts of the same workflow are discarded
+too, or the debounced duplicate fires seconds later against the deleted row.
+
+Stopping or re-driving MANY runs is `voltro workflows cancel-many` /
+`replay-many`. Both are a DRY RUN until `--commit`, `--limit` is required (the cap
+IS the blast radius; `truncated` says whether more matched), and a cancel needs a
+`--reason` that lands on every affected run.
+
+A model call inside a workflow: `aiStep` / `aiObjectStep` from
+`@voltro/ai/workflow`. Pass `store: ctx.store` and the spend is recorded per step;
+the prompt is journaled as a DIGEST unless you write `recordPrompt: 'full'`. Add
+`offload: true` and the run SUSPENDS instead of holding a worker while the model
+thinks — a dispatcher owns the call and resumes the run. Costs one suspend/resume
+round trip (~250ms), so offload the slow calls and leave a fast classification
+inline.
+
+**`idempotencyKey` is the execution's IDENTITY, permanently — not a dedupe
+window.** A second start with the same key replays the first run's result
+forever; after it completes the key is SPENT and a genuinely new invocation is a
+silent no-op. So it must vary per unit of work (`` `tour:${rowId}:${editedAt}` ``,
+not `` `tour:${rowId}` ``), while a flow-control `key` — the RESOURCE runs
+compete for — stays stable. Those are two different fields; conflating them is
+what makes "I need to re-arm a key" feel like a missing feature.
+
+A start can now come back `queued` / `dropped` / `skipped` with
+`executionId: null`, so narrow on `handle.status` before using the id.
+
 ### Pick the SERVER primitive (inside a handler)
 
 The four above answer "which FILE do I write". This answers "what do I write
@@ -602,7 +652,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.29.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.30.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. |
@@ -635,7 +685,8 @@ each plugin's own README.
 | templates.apiBackends | `node_modules/@voltro/cli/templates/agent-docs/templates/apibackends.md` | The minimal Voltro backend — app.config + schema + one streaming query + one tenant-guarded mutation. Tenant-aware out of the box. |
 | templates.appShells | `node_modules/@voltro/cli/templates/agent-docs/templates/appshells.md` | A marketing landing page — hero, features, CTA. Static-rendered with zero JS on the wire by default. |
 | templates.custom | `node_modules/@voltro/cli/templates/agent-docs/templates/custom.md` | Add a template the CLI can scaffold from — a directory under voltro-templates/apps/ with a manifest and the files to copy. |
-| Templates | `node_modules/@voltro/cli/templates/agent-docs/templates/overview.md` | Thirty-four dogfooded starter templates ship with the framework — twenty backend shapes, thirteen frontend shapes, and a serverless function library. Scaffold any of them with one CLI call. |
+| templates.mobile | `node_modules/@voltro/cli/templates/agent-docs/templates/mobile.md` | An Expo (React Native) app that is the third consumer of your api — the same typed hooks (useSubscription / useMutation), offline-first by default, typed deep links, and device registration for push. Expo owns Metro; voltro dev runs the sibling api. |
+| Templates | `node_modules/@voltro/cli/templates/agent-docs/templates/overview.md` | Thirty-eight dogfooded starter templates ship with the framework — twenty-two backend shapes, fourteen frontend shapes, a serverless function library, and an Expo mobile app. Scaffold any of them with one CLI call. |
 | templates.serverless | `node_modules/@voltro/cli/templates/agent-docs/templates/serverless.md` | A library of standalone *.serverless.ts functions — pure compute, request-header/geo, outbound HTTP, Web Crypto HMAC, an LLM call, status-controlled errors. Run with voltro serverless; ship to node / Cloudflare / Scaleway. No server, no port. |
 | Testing | `node_modules/@voltro/cli/templates/agent-docs/testing.md` | 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. |
 | Workflows | `node_modules/@voltro/cli/templates/agent-docs/workflows.md` | Durable Effect workflows in Voltro — what they are, when to use them, and the current runtime boundaries. |

package/templates/agent-docs/_index.md

@@ -9,7 +9,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.29.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.30.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. |
@@ -42,7 +42,8 @@ each plugin's own README.
 | templates.apiBackends | `node_modules/@voltro/cli/templates/agent-docs/templates/apibackends.md` | The minimal Voltro backend — app.config + schema + one streaming query + one tenant-guarded mutation. Tenant-aware out of the box. |
 | templates.appShells | `node_modules/@voltro/cli/templates/agent-docs/templates/appshells.md` | A marketing landing page — hero, features, CTA. Static-rendered with zero JS on the wire by default. |
 | templates.custom | `node_modules/@voltro/cli/templates/agent-docs/templates/custom.md` | Add a template the CLI can scaffold from — a directory under voltro-templates/apps/ with a manifest and the files to copy. |
-| Templates | `node_modules/@voltro/cli/templates/agent-docs/templates/overview.md` | Thirty-four dogfooded starter templates ship with the framework — twenty backend shapes, thirteen frontend shapes, and a serverless function library. Scaffold any of them with one CLI call. |
+| templates.mobile | `node_modules/@voltro/cli/templates/agent-docs/templates/mobile.md` | An Expo (React Native) app that is the third consumer of your api — the same typed hooks (useSubscription / useMutation), offline-first by default, typed deep links, and device registration for push. Expo owns Metro; voltro dev runs the sibling api. |
+| Templates | `node_modules/@voltro/cli/templates/agent-docs/templates/overview.md` | Thirty-eight dogfooded starter templates ship with the framework — twenty-two backend shapes, fourteen frontend shapes, a serverless function library, and an Expo mobile app. Scaffold any of them with one CLI call. |
 | templates.serverless | `node_modules/@voltro/cli/templates/agent-docs/templates/serverless.md` | A library of standalone *.serverless.ts functions — pure compute, request-header/geo, outbound HTTP, Web Crypto HMAC, an LLM call, status-controlled errors. Run with voltro serverless; ship to node / Cloudflare / Scaleway. No server, no port. |
 | Testing | `node_modules/@voltro/cli/templates/agent-docs/testing.md` | 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. |
 | Workflows | `node_modules/@voltro/cli/templates/agent-docs/workflows.md` | Durable Effect workflows in Voltro — what they are, when to use them, and the current runtime boundaries. |

package/templates/agent-docs/_manifest.json

@@ -269,7 +269,7 @@
       "group": "templates.apiBackends",
       "description": "The minimal Voltro backend — app.config + schema + one streaming query + one tenant-guarded mutation. Tenant-aware out of the box.",
       "path": "agent-docs/templates/apibackends.md",
-      "files": 21
+      "files": 22
     },
     {
       "id": "templates/appshells",
@@ -278,7 +278,7 @@
       "group": "templates.appShells",
       "description": "A marketing landing page — hero, features, CTA. Static-rendered with zero JS on the wire by default.",
       "path": "agent-docs/templates/appshells.md",
-      "files": 13
+      "files": 14
     },
     {
       "id": "templates/custom",
@@ -289,12 +289,21 @@
       "path": "agent-docs/templates/custom.md",
       "files": 1
     },
+    {
+      "id": "templates/mobile",
+      "title": "templates.mobile",
+      "section": "Templates",
+      "group": "templates.mobile",
+      "description": "An Expo (React Native) app that is the third consumer of your api — the same typed hooks (useSubscription / useMutation), offline-first by default, typed deep links, and device registration for push. Expo owns Metro; voltro dev runs the sibling api.",
+      "path": "agent-docs/templates/mobile.md",
+      "files": 1
+    },
     {
       "id": "templates/overview",
       "title": "Templates",
       "section": "Templates",
       "group": null,
-      "description": "Thirty-four dogfooded starter templates ship with the framework — twenty backend shapes, thirteen frontend shapes, and a serverless function library. Scaffold any of them with one CLI call.",
+      "description": "Thirty-eight dogfooded starter templates ship with the framework — twenty-two backend shapes, fourteen frontend shapes, a serverless function library, and an Expo mobile app. Scaffold any of them with one CLI call.",
       "path": "agent-docs/templates/overview.md",
       "files": 1
     },
@@ -323,7 +332,7 @@
       "group": null,
       "description": "Durable Effect workflows in Voltro — what they are, when to use them, and the current runtime boundaries.",
       "path": "agent-docs/workflows.md",
-      "files": 9
+      "files": 10
     }
   ],
   "plugins": [
@@ -631,6 +640,7 @@
     "api-backend-mariadb": "agent-docs/templates/apibackends.md",
     "api-backend-storage": "agent-docs/templates/apibackends.md",
     "api-backend": "agent-docs/templates/apibackends.md",
+    "api-collab": "agent-docs/templates/apibackends.md",
     "api-data-advanced": "agent-docs/templates/apibackends.md",
     "api-durable": "agent-docs/templates/apibackends.md",
     "api-feature-flags": "agent-docs/templates/apibackends.md",
@@ -648,6 +658,7 @@
     "app": "agent-docs/templates/appshells.md",
     "blank": "agent-docs/templates/appshells.md",
     "changelog": "agent-docs/templates/appshells.md",
+    "collab": "agent-docs/templates/appshells.md",
     "contact": "agent-docs/templates/appshells.md",
     "custom": "agent-docs/templates/custom.md",
     "dashboard": "agent-docs/templates/appshells.md",
@@ -655,6 +666,7 @@
     "edge-functions": "agent-docs/templates/serverless.md",
     "i18n": "agent-docs/templates/appshells.md",
     "landing": "agent-docs/templates/appshells.md",
+    "mobile-app": "agent-docs/templates/mobile.md",
     "overview": "agent-docs/templates/overview.md",
     "spa": "agent-docs/templates/appshells.md",
     "ssr-api": "agent-docs/templates/appshells.md",

package/templates/agent-docs/ai.md

@@ -1821,6 +1821,62 @@ const groundedAnswer = (prompt: string) =>
 - **A cache outage degrades to always-generate.** Both the lookup and the store are best-effort — a `CacheError` reads as a miss (or a swallowed put), never a failed call. The cache is an optimisation, not a dependency.
 - **The object variant stores the DECODED object.** With the memory backend it round-trips by reference; with a RESP backend it is JSON, so a schema whose decoded form is not JSON-safe (class instances, non-plain branded carriers) will not survive a cross-process hit — cache the text form or a JSON-safe projection for those.
 
+## A model call inside a workflow — `aiStep`
+
+`@voltro/ai/workflow` wraps a call as a durable step:
+
+```ts
+import { aiStep, aiObjectStep } from '@voltro/ai/workflow'
+
+const summary = yield* aiStep({
+  name: 'summarise-thread',
+  prompt: `Summarise:\n${thread}`,
+  store: ctx.store,
+  tenantId: payload.tenantId,
+})
+```
+
+Journaling is **not** what this adds — every `step()` is already journaled, so a replay of a plain wrapped `generateText` returns the recorded completion rather than re-calling the model. Three things are different:
+
+1. **It records what the run cost.** A model call inside a workflow was invisible to `_voltro_ai_usage` unless the app remembered to call `recordAiUsage` by hand — so the spend ledger was systematically missing exactly the calls that run unattended. Pass `store` and every call is recorded, attributed to the workflow and the step.
+2. **It does not copy the prompt into a second table.** `step({ input })` is written to `_voltro_workflow_run_steps` and rendered in the dashboard; for a prompt built from customer data that is a plaintext copy outside whatever boundary you established for the source. The default records a **digest** plus the length. `recordPrompt: 'full'` exists and has to be typed out.
+3. **Provider failures retry like provider failures.** The default policy handles a 429 with a `Retry-After` and a 5xx, rather than every app rediscovering that a bare call fails the whole durable run on a rate limit.
+
+`aiObjectStep` is the schema-constrained form; the schema is the step's success schema too, so the journaled value decodes on replay exactly as it did on the first run.
+
+Pass `offload: true` and the run stops occupying a worker while the model thinks — see the next section.
+
+## Offloading the call — `offload: true`
+
+An inline `aiStep` holds a runner fiber for the length of the model call. At six seconds a call and two hundred concurrent runs, that is two hundred parked workers waiting on a socket, and the cluster's concurrency is spent on latency rather than on work.
+
+```ts
+const summary = yield* aiStep({
+  name: 'summarise-thread',
+  prompt: `Summarise:\n${thread}`,
+  store: ctx.store,
+  offload: true,
+})
+```
+
+The run **suspends**: the worker is released, the wait lives as a row in `_voltro_ai_inferences`, and a dispatcher owns the socket. Two hundred waiting runs become two hundred rows and (by default) four in-flight requests.
+
+Nothing about this needs a third party to operate an inference tier. It needs something to own the socket while the run sleeps — and a server process is something. The two pieces it is built from already existed: durable suspend/resume (`awaitSignalSuspending`, built for human-in-the-loop waits) and a leased work queue with a coordinated drainer (the same shape the admission queue has).
+
+**The cost, so you can decide per call.** A suspend/resume round trip adds the dispatcher's poll interval (250 ms) plus one engine wake. On a six-second call that is under 5%; on a 200 ms classification call it doubles the latency. So it is a mode, not a default: offload the calls that are slow enough for a worker to be worth freeing — which is most of them — and leave the fast ones inline.
+
+**What the queue guarantees.**
+
+- The enqueue is idempotent. The row id is derived from the execution and the step name, so a replay cannot queue — and pay for — the same call twice.
+- The claim is a conditional update, not a read-then-write. Two dispatchers cannot both perform (and both bill) one call.
+- The order is **perform → resume the run → mark the row**. A crash between the resume and the mark leaves a row whose lease expires and is reclaimed, and the second resume of a resolved deferred is a no-op. The other order would leave a run waiting for a signal nobody will send again.
+- A give-up **resumes the run with the failure**. A queued call that was abandoned without telling its run is the one unrecoverable outcome here, and the ordering exists to rule it out.
+- Retries follow the same rules as the inline policy, `Retry-After` included, so the two modes do not back off differently.
+
+`aiObjectStep({ offload: true })` renders your schema to JSON Schema for the dispatcher — a JavaScript Schema cannot be journaled — and still **decodes on the awaiting side**, where the real schema exists.
+
+The Flow tab shows the queue: what is waiting and for how long, which calls have been waiting more than two minutes, which claims have a lease their dispatcher will never release, and the dispatcher's own last tick. A run parked on an offloaded call reads `suspended` in the run list with no step row yet, so this is the only view of the wait while it is happening.
+
 ## Deliberately your call
 
 The toolkit prices + records + gates; a few things stay explicit by design:

package/templates/agent-docs/cli.md

@@ -1181,6 +1181,33 @@ re-open a hole nor hide one, and it is consulted **last**: an executor that gain
 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.
 
+**Two kinds of line, because "debt" and "reviewed" are different claims.** A bare
+tag is debt. A tag with `reviewed=<why>` says a human read the executor and found
+it genuinely open — constrained by something the scanner cannot see:
+
+```txt
+teams.deleteSubTeam
+inquiries.publicFeed  reviewed=public by design; returns only published rows
+```
+
+The reason is required: `reviewed=` with no why is the claim without the
+evidence, and doctor refuses it. A bare tag is always available and is the honest
+alternative. The two are counted and printed apart, and
+`--write-authz-allowlist` **preserves** reviewed lines rather than flattening
+them back to debt.
+
+#### Reading the whole list
+
+The human view prints the 20 most severe unchecked executors. The complete scan
+— every finding, the counts, the inferred guard vocabulary, and the debt/reviewed
+split — is in `voltro doctor --json` under `authz`:
+
+```bash
+voltro doctor --json | jq '.authz.unchecked[] | {tag, why, path}'
+```
+
+Nothing is truncated there. If you are triaging, work from the JSON.
+
 #### Before you hand-roll another check
 
 If your checks are imperative because a scope cannot express "may this subject
@@ -1853,16 +1880,35 @@ voltro workflows resume <runId>
 voltro workflows signal <runId> --name approval        # inject a named signal
 voltro workflows update <runId> --name …
 voltro workflows children <parentExecutionId>
+voltro workflows flow                          # the admission queue + ledger
+voltro workflows pause|unpause <workflowName>  # stop/restart admission fleet-wide
+voltro workflows cancel-many --reason "…"      # DRY RUN until --commit
+voltro workflows replay-many --mode redrive    # DRY RUN until --commit
+voltro workflows inferences                    # offloaded model calls in flight
 ```
 
+`inferences` shows what nothing else can: a run parked on an offloaded model call reads `suspended` in the run list with no step row yet, so during a slow provider — the moment you would look — the run list has nothing to say.
+
 Underneath, workflow state lives in the `_voltro_workflow_runs` + `_voltro_workflow_run_steps` tables and is surfaced live by the dashboard's Workflows panel. The same data is reachable over HTTP:
 
 ```bash
 curl -s localhost:$PORT/_voltro/inspect/workflows/runs | jq            # recent runs
 curl -s "localhost:$PORT/_voltro/inspect/workflows/runs/<runId>/steps" | jq   # step-by-step
 curl -s "localhost:$PORT/_voltro/inspect/workflows/runs/<runId>/events" | jq  # the run's event log
+curl -s "localhost:$PORT/_voltro/inspect/workflows/stats?hours=24" | jq       # bucketed run activity (the dashboard chart)
 ```
 
+The runs endpoint filters **server-side**, so a triage query over a large run history costs one narrow page instead of the whole table:
+
+```bash
+# multi-status + tag search + source + id-prefix + time range — all composable
+curl -s "localhost:$PORT/_voltro/inspect/workflows/runs?statuses=failed,cancelled&q=orders&source=workflow-rpc&idPrefix=wfrun_&from=2026-08-01T00:00:00Z&to=2026-08-08T00:00:00Z" | jq
+```
+
+`statuses` is a comma list; `q` is a case-insensitive tag substring; `idPrefix` matches the run id **or** the execution id (you never have to know which kind your log line carried); `from`/`to` bound `startedAt`. The dashboard's filter bar sends exactly these params.
+
+`/workflows/stats` returns ~48 buckets over a trailing window (`hours`, default 24, max 168; optional `tag`), each with `started` / `succeeded` / `failed` / `cancelled` counts, plus per-workflow totals. When the window held more runs than the scan cap, the response says `truncated: true` — the chart renders that as a warning, because a silently-truncated chart shows throughput dropping at exactly the moment it spiked.
+
 Each run row carries ID, name, status (running / succeeded / failed / dead), step count, last completed step, and duration. The per-run action endpoint matches `…/workflows/runs/<runId>/<action>` for `cancel` / `retry` / `suspend` / `resume` / `signal` — the `voltro workflows` subcommands and the dashboard's run-detail buttons both POST to these:
 
 ```bash

package/templates/agent-docs/internationalization.md

@@ -45,7 +45,7 @@ The framework's generated `.framework/app.tsx` wraps the Router in `<I18nProvide
 
 Server-side, the active locale is determined by, in priority order:
 
-1. **`voltro:lang` cookie** — the user's explicit choice (written by `@voltro/ui-shadcn`'s ProfileMenu).
+1. **`voltro:locale` cookie** — the user's explicit choice (written by `@voltro/ui-shadcn`'s ProfileMenu).
 2. **`Accept-Language` header** — the browser/OS preference, q-weighted and sorted per RFC 4647.
 3. **`defaultLocale`** — last-resort fallback.
 
@@ -240,7 +240,7 @@ export const getCatalog = (locale?: string) => pickCatalog({ en, de }, locale, '
 ```
 
 ```tsx
-// any page — meta gets the active locale (from the URL prefix, or the voltro:lang cookie)
+// any page — meta gets the active locale (from the URL prefix, or the voltro:locale cookie)
 import { getCatalog } from '../locales'
 
 export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
@@ -330,14 +330,14 @@ The wrap deliberately doesn't re-export everything, to keep the framework's bles
 <!-- source: en/i18n/url-strategies.md -->
 ## URL strategies
 
-_Cookie-only vs URL-prefix routing (Strategy A / B), the URL-prefix integration sketch, resolveLocale on the /server subpath, the voltro:lang / voltro:theme cookie convention._
+_Cookie-only vs URL-prefix routing (Strategy A / B), the URL-prefix integration sketch, resolveLocale on the /server subpath, the voltro:locale / voltro:theme cookie convention._
 
 There are two ways an i18n app can encode the active locale. Pick **one**, based on what the app's URLs are *for*.
 
 ## Strategy A — cookie-only (default for product apps)
 
 - All locales are served from the **same** URL (`/dashboard`, `/settings`).
-- The `voltro:lang` cookie + `Accept-Language` determine which catalog renders.
+- The `voltro:locale` cookie + `Accept-Language` determine which catalog renders.
 - The ProfileMenu's language switch — or the standalone `<LocaleSwitcher>` from `@voltro/ui-shadcn` — writes the cookie and reloads.
 - Use when URLs are **functional** (`/dashboard/projects/42/deployments`) and don't need to encode the language. This is most apps.
 
@@ -511,15 +511,16 @@ The `/server` subpath is convention. Both that path and the main entry are pure
 
 ## Cookie convention
 
-The framework reads + writes **`voltro:lang`** for the active language choice (lowercase IETF tag: `en`, `de`, `fr-CA`). `@voltro/ui-shadcn`'s ProfileMenu and the framework's auto-wired resolver agree on this name — **don't pick a different one in app code.**
+The framework reads + writes **`voltro:locale`** for the active language choice (lowercase IETF tag: `en`, `de`, `fr-CA`). `@voltro/ui-shadcn`'s ProfileMenu and the framework's auto-wired resolver agree on this name — **don't pick a different one in app code.**
 
-For theme the parallel cookie is **`voltro:theme`** (values `'system' | 'light' | 'dark'`). Both are managed by the kit's ProfileMenu out of the box; the helpers live in `@voltro/ui-shadcn` (`THEME_COOKIE`, `LANG_COOKIE`, `getCookie`, `setCookie`, `deleteCookie`, `parsePreferenceCookies`, `applyTheme`).
+For theme the parallel cookie is **`voltro:theme`** (values `'system' | 'light' | 'dark'`). Both are managed by the kit's ProfileMenu out of the box; the helpers live in `@voltro/ui-shadcn` (`THEME_COOKIE`, `LOCALE_COOKIE`, `getCookie`, `setCookie`, `deleteCookie`, `parsePreferenceCookies`, `applyTheme`).
 
 ## Anti-patterns
 
 - **Don't mix strategies within one app.** Pick cookie-only *or* URL-prefix per app; mixing them produces ambiguous canonical URLs and broken language switching.
 - **Don't read `Accept-Language` on the client.** It's server-only — `navigator.languages` can diverge from what the server saw and cause a hydration mismatch.
-- **Don't invent your own cookie name.** The kit and the resolver only agree on `voltro:lang` / `voltro:theme`.
+- **Don't invent your own cookie name.** The kit and the resolver only agree on `voltro:locale` / `voltro:theme`.
+- **Don't hardcode the name either — import the constant.** `LOCALE_COOKIE` / `THEME_COOKIE` from `@voltro/ui-shadcn`. A cookie name the framework READS and your app WRITES is a public API, and it is the only kind where both sides can disagree with nothing failing: the resolver finds nothing, falls back to `Accept-Language`, and a user's language choice quietly stops working — but only for the users whose browser language differs from their choice, which is the least likely case anyone tests. With the constant, a rename in the framework is a compile error in your app. `voltro doctor` flags a written literal for exactly this reason.
 
 
 

package/templates/agent-docs/local-first-mobile.md

@@ -265,11 +265,23 @@ code already speaks:
 
 _"@voltro/react-native — the credential-free mobile plumbing: registerDevice + the _voltro_devices table, defineDeepLink + its matcher, useBackgroundSync, and offline-first client defaults + connection status."_
 
-The existing React-client bindings already run in React Native — the runtime has
-no DOM dependency. `@voltro/react-native` adds the mobile-specific plumbing **on
-top** of that, limited to the parts that need **no per-tenant credentials and no
-native runtime**: device registration, background-sync scheduling, offline-first
-defaults, a connection-status surface, and the deep-link declaration shape.
+The React-client bindings are **import-safe** in React Native — every DOM touch
+in `@voltro/client` is `typeof window`-guarded, so nothing crashes at import.
+What is **not done yet** is wiring the client's runtime for RN: building the
+`ApiHandle`s (runtime + subscription cache + rpc client) over a native
+WebSocket, plus an RN persistence adapter and a NetInfo connection signal. That
+is Phase **M0** of the mobile plan — until it lands, the reactive loop is
+unproven on a device. `@voltro/react-native` ships the mobile-specific plumbing
+that works **today**, limited to the parts that need **no per-tenant credentials
+and no native runtime**: device registration, background-sync scheduling,
+offline-first defaults, a connection-status surface, and the deep-link
+declaration shape.
+
+> **Scaffold a mobile app.** `voltro create-project acme --api=api-backend
+> --mobile` (or `voltro add-app mobile --template mobile-app`) scaffolds an Expo
+> app that consumes your api with the same typed hooks. Expo owns Metro
+> (`expo start` / `expo run:ios`), not `voltro dev`. See
+> [the `mobile-app` template](/docs/templates/mobile-app).
 
 The package **root is RN-safe** — no `node:*`, no `@voltro/database`, and React
 is reached only through the hooks (an optional peer). The `_voltro_devices` table
@@ -409,6 +421,6 @@ not built here:
 |---|---|
 | **APNs / FCM sender adapters** | Need per-tenant Apple Developer / Firebase credentials — genuinely external, managed via provider provisioning. Registration stores the token; sending to it is the seam. |
 | **Native module bindings** (camera, biometrics, secure token storage) | Need a native runtime this TS package cannot provide. |
-| **Swift / Kotlin SDK generators** | An open product decision — not built until demand justifies the maintenance. |
+| **Swift / Kotlin SDK generators** | **Built + golden-tested** — `voltro build api --target swift\|kotlin` emits a native SDK package. What is deferred is *compiling* the emitted package (`swiftc` / Gradle): that is a mobile-CI step, no cross-language toolchain lives in the framework repo. |
 | **Universal-links / App-Links file automation** (`apple-app-site-association`, `assetlinks.json`) | A deployment-layer concern, not a client primitive. |
 | **`*.deepLink.ts` codegen discovery** | One additive file after the release settles; the descriptor shape is final, so register links via `matchFirstDeepLink()` today. |

package/templates/agent-docs/routing.md

@@ -556,6 +556,20 @@ Use SSR for:
 - **Personalised content** — recommendations, "your" anything.
 - **Search result pages** — the query string changes per request.
 
+### What the server render sees
+
+An SSR render is given the request, not a guess at it: the matched `pathname`
+and `params`, the request's cookies and headers (`useServerRequest()`), and the
+**query string**. `useSearchParams()` is the supported reader and works on both
+sides — on the server it reads the request URL, on the client
+`window.location.search` — so a page keyed off `?tab=…` renders the same markup
+in both places.
+
+That last part is worth stating because it is the thing a mismatch is made of.
+Anything the server renders from a value the client computes differently
+hydrates with a warning, even when the DOM happens to agree; reach for the hook
+rather than reading the router context directly.
+
 Cost: every request triggers a fresh render. For very high-traffic pages, prefer ISR.
 
 ### Streaming SSR
@@ -1197,7 +1211,7 @@ export const meta = ({ loaderData }: { loaderData: { note?: { title: string; bod
 })
 ```
 
-The third context field — `locale: string` — is the active i18n locale for this render. For `[locale]/…` routes it carries the URL-prefix locale (`'de'` on `/de/notes/42`). For bare-path routes it carries the active locale from the framework's `voltro:lang` cookie when set — so **cookie-based i18n works too** (an authed dashboard with no `[locale]` URL still gets a translated `<title>` that tracks the language switch) — otherwise the app's `defaultLocale`. Use it to localise title / description / canonical / OG per locale at SSG time so search engines see translated head tags on every variant, and to give cookie-i18n pages a translated tab title:
+The third context field — `locale: string` — is the active i18n locale for this render. For `[locale]/…` routes it carries the URL-prefix locale (`'de'` on `/de/notes/42`). For bare-path routes it carries the active locale from the framework's `voltro:locale` cookie when set — so **cookie-based i18n works too** (an authed dashboard with no `[locale]` URL still gets a translated `<title>` that tracks the language switch) — otherwise the app's `defaultLocale`. Use it to localise title / description / canonical / OG per locale at SSG time so search engines see translated head tags on every variant, and to give cookie-i18n pages a translated tab title:
 
 ```tsx
 import { getCatalog } from '../lib/locale'

package/templates/agent-docs/security.md

@@ -88,6 +88,23 @@ DNS is not resolved. A public hostname that *resolves* to a private address (DNS
 rebinding) still passes. That vector needs network-layer egress control; it is
 stated here rather than silently implied.
 
+## Auditing what your log tables actually hold
+
+```bash
+voltro db scan-credentials
+voltro db scan-credentials --table my_events:actor
+```
+
+Counts rows whose Subject carries a credential-shaped key — `token`, `secret`, `password`, `apikey`, `credential`, `privatekey` — in `_voltro_audit_log` and `_voltro_row_history`, plus any table you name with `--table <name>[:<column>]` (the column defaults to `subject`). Exit code `1` on a hit, so CI can gate on it.
+
+**It is a command and not a documented query on purpose.** The same check once shipped as SQL you were asked to run yourself, in its postgres spelling (`subject::text ILIKE '%token%'`). On MySQL/MariaDB the natural translation is a bare `LIKE` — and against the `utf8mb4_bin` collation the migrator emits for a `json()` column, `LIKE` is case-**sensitive**. So `'%token%'` does not match `jiraToken`, and almost every JSON key that carries a credential is camelCase. A team ran the translated query over 141 rows, got `0`, and nearly reported themselves clean; 117 of those rows held a working credential. Every dialect now casts to its own text type before lowering, in code you do not have to translate.
+
+**A `0` here never means two things.** Each line prints the number of rows *scanned* beside the number of hits. An empty table says so in words rather than reading as clean, a missing table reports as missing rather than as zero, and a run that examined nothing exits `2`.
+
+Run it on every environment. A development database is not a sample of production.
+
+If it finds something: purge the rows **and** rotate the credentials — assume anything written to a log table has been read — then move the credential off the Subject entirely with `connectionCredentials(...)`, which keeps it in the framework vault.
+
 ## Supply-chain assurance
 
 Every release passes automated supply-chain gates in CI before a single package is published: