npm - @voltro/cli - Versions diffs - 0.29.0 → 0.30.0 - Mend

@voltro/cli 0.29.0 → 0.30.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (169) hide show

package/dist/serveEntry.js CHANGED Viewed

@@ -1,5 +1,5 @@
-import { et as e } from "./inspectMetrics-DHYygE4s.js";
+import { et as e } from "./inspectMetrics-BeJdP_3b.js";
 import { c as t } from "./seedRunner-Bqxgp7HZ.js";
 import { r as n } from "./appModuleLoader-C9r9mxZt.js";
-import { t as r } from "./serveCommand-BXl8mhZD.js";
+import { t as r } from "./serveCommand-Ciq_wIY8.js";
 export { e as loadDotEnv, n as registerAppModules, t as registerDriver, r as runServe };

package/dist/{start-CsCIaW4-.js → start-ocqB1seX.js} RENAMED Viewed

@@ -1,5 +1,5 @@
-import { B as e, E as t, G as n, I as r, K as i, N as a, O as o, Q as s, S as c, T as l, U as u, W as ee, Z as d, _ as te, _t as f, a as p, at as m, b as h, c as g, f as _, ft as v, g as y, gt as b, h as x, ht as ne, i as re, it as ie, lt as ae, m as S, mt as C, nt as oe, o as se, ot as w, p as T, q as E, r as D, rt as O, s as k, t as A, v as j, x as ce, y as M } from "./inspectMetrics-DHYygE4s.js";
-import { D as le, E as ue, O as N, a as de, p as P, w as F } from "./inspect-BMvQpwqy.js";
+import { B as e, E as t, G as n, I as r, K as i, N as a, O as o, Q as s, S as c, T as l, U as u, W as ee, Z as d, _ as te, _t as f, a as p, at as m, b as h, c as g, f as _, ft as v, g as y, gt as b, h as x, ht as ne, i as re, it as ie, lt as ae, m as S, mt as C, nt as oe, o as se, ot as w, p as T, q as E, r as D, rt as O, s as k, t as A, v as j, x as ce, y as M } from "./inspectMetrics-BeJdP_3b.js";
+import { A as le, E as N, O as P, a as ue, k as F, m as de } from "./inspect-BUUjt773.js";
 import { t as fe } from "./bootTiming-BdyP9nYw.js";
 import { dirname as I, extname as pe, join as L, resolve as R } from "node:path";
 import { fileURLToPath as z, pathToFileURL as B } from "node:url";
@@ -283,7 +283,7 @@ CREATE INDEX IF NOT EXISTS ${e}_servable_until_idx ON ${e} (servable_until);
 					locale: E.locale
 				} : {}
 			}
-		}), t = E?.locale ?? T.cookies["voltro:lang"] ?? "en", r = (t) => ce({
+		}), t = E?.locale ?? T.cookies["voltro:locale"] ?? "en", r = (t) => ce({
 			helpers: C,
 			prepared: e,
 			meta: t,
@@ -349,7 +349,7 @@ CREATE INDEX IF NOT EXISTS ${e}_servable_until_idx ON ${e} (servable_until);
 		C.renderRouterStateScript(O.stateInput)
 	].filter((e) => e.length > 0).join("\n    ");
 	if (g === "ssr" && D === "full" && e.buffered !== !0) {
-		let e = E?.locale ?? T.cookies["voltro:lang"] ?? "en", t = x({ shell: s });
+		let e = E?.locale ?? T.cookies["voltro:locale"] ?? "en", t = x({ shell: s });
 		return {
 			renderMode: "ssr",
 			stream: (n) => y({
@@ -371,13 +371,13 @@ CREATE INDEX IF NOT EXISTS ${e}_servable_until_idx ON ${e} (servable_until);
 			})
 		};
 	}
-	let { html: le, meta: ue } = C.renderPageToHtml(k), N = A(ue), de = E?.locale ?? T.cookies["voltro:lang"] ?? "en", P = s.replace("<div id=\"root\"></div>", `<div id="root">${le}</div>`).replace("</head>", `    ${N}\n  </head>`).replace(/<html(\s+lang="[^"]*")?/i, `<html lang="${de}"`);
-	D === "none" && (P = Se(P));
-	let F = g === "isr" ? w(m.revalidate) : null;
+	let { html: le, meta: N } = C.renderPageToHtml(k), P = A(N), ue = E?.locale ?? T.cookies["voltro:locale"] ?? "en", F = s.replace("<div id=\"root\"></div>", `<div id="root">${le}</div>`).replace("</head>", `    ${P}\n  </head>`).replace(/<html(\s+lang="[^"]*")?/i, `<html lang="${ue}"`);
+	D === "none" && (F = Se(F));
+	let de = g === "isr" ? w(m.revalidate) : null;
 	return {
-		html: P,
+		html: F,
 		renderMode: g,
-		revalidateMs: F
+		revalidateMs: de
 	};
 }, $ = (e) => e === "" ? "/" : e, De = async (e) => {
 	let t = await import(B(e).href);
@@ -651,13 +651,13 @@ CREATE INDEX IF NOT EXISTS ${e}_servable_until_idx ON ${e} (servable_until);
 				status: r.status,
 				headers: {
 					"content-type": r.contentType,
-					...F(n.origin)
+					...N(n.origin)
 				},
 				body: r.body
 			};
 		}
 		if (i !== "/_voltro/inspect/stream") {
-			let e = P(t, Ne, n);
+			let e = de(t, Ne, n);
 			if (e !== null) return {
 				status: e.status,
 				headers: {
@@ -859,7 +859,7 @@ CREATE INDEX IF NOT EXISTS ${e}_servable_until_idx ON ${e} (servable_until);
 			return;
 		}
 		if (s === "OPTIONS" && o.startsWith("/_voltro/inspect")) {
-			let e = F(a.origin);
+			let e = N(a.origin);
 			t.writeHead(204, e), t.end();
 			return;
 		}
@@ -869,13 +869,13 @@ CREATE INDEX IF NOT EXISTS ${e}_servable_until_idx ON ${e} (servable_until);
 				t.writeHead(400, { "content-type": "text/plain" }), t.end("missing ?target=");
 				return;
 			}
-			if (!ue(n)) {
+			if (!P(n)) {
 				t.writeHead(400, { "content-type": "text/plain" }), t.end("target not allowed: must be loopback or an origin configured in VOLTRO_DASHBOARD_APPS");
 				return;
 			}
 			try {
 				let r = { accept: a.accept ?? "application/json" }, i = a.authorization;
-				i ? r.authorization = Array.isArray(i) ? i[0] : i : N(n) && process.env.VOLTRO_INSPECT_TOKEN && (r.authorization = `Bearer ${process.env.VOLTRO_INSPECT_TOKEN}`);
+				i ? r.authorization = Array.isArray(i) ? i[0] : i : le(n) && process.env.VOLTRO_INSPECT_TOKEN && (r.authorization = `Bearer ${process.env.VOLTRO_INSPECT_TOKEN}`);
 				let o;
 				if (s && s !== "GET" && s !== "HEAD") {
 					let t = [];
@@ -905,14 +905,14 @@ CREATE INDEX IF NOT EXISTS ${e}_servable_until_idx ON ${e} (servable_until);
 				t.writeHead(400, { "content-type": "text/plain" }), t.end("missing ?target=");
 				return;
 			}
-			if (!ue(n)) {
+			if (!P(n)) {
 				t.writeHead(400, { "content-type": "text/plain" }), t.end("target not allowed: must be loopback or an origin configured in VOLTRO_DASHBOARD_APPS");
 				return;
 			}
 			let i = new AbortController();
 			e.on("close", () => i.abort()), t.on("close", () => i.abort());
 			try {
-				let e = a.authorization ?? (N(n) && process.env.VOLTRO_INSPECT_TOKEN ? `Bearer ${process.env.VOLTRO_INSPECT_TOKEN}` : void 0), r = await fetch(n, {
+				let e = a.authorization ?? (le(n) && process.env.VOLTRO_INSPECT_TOKEN ? `Bearer ${process.env.VOLTRO_INSPECT_TOKEN}` : void 0), r = await fetch(n, {
 					redirect: "manual",
 					method: "GET",
 					headers: {
@@ -947,15 +947,15 @@ CREATE INDEX IF NOT EXISTS ${e}_servable_until_idx ON ${e} (servable_until);
 			return;
 		}
 		if (o === "/_voltro/inspect/stream") {
-			let r = F(a.origin);
-			if (le()) {
+			let r = N(a.origin);
+			if (F()) {
 				t.writeHead(503, {
 					"content-type": "application/json",
 					...r
 				}), t.end(JSON.stringify({ error: "inspect disabled (VOLTRO_INSPECT=off)" }));
 				return;
 			}
-			let i = de(a, "GET");
+			let i = ue(a, "GET");
 			if (!i.ok) {
 				t.writeHead(401, {
 					"content-type": "application/json",

package/dist/startEntry.js CHANGED Viewed

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

package/package.json CHANGED Viewed

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

package/templates/AGENTS.core.md CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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.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. |
@@ -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 CHANGED Viewed

@@ -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.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. |
@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -1853,16 +1853,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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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. |