@voltro/cli 0.58.0 → 0.59.0

package/dist/{commands-DowWkYtd.js → commands-cu34ENUT.js}

@@ -121,7 +121,7 @@ var u = () => {
 		name: "check",
 		summary: "Verify the app graph (blast-radius checks) against a running api; LLM-shaped --json diagnostics. Flags: --json, --process <p>, --diff removeTable:<name>.",
 		status: "wired",
-		run: (e) => import("./checkCommand-C1EbNmwl.js").then((t) => t.runCheckCommand(e)),
+		run: (e) => import("./checkCommand-C1CQc8lD.js").then((t) => t.runCheckCommand(e)),
 		help: {
 			usage: "[--json] [--offline] [--process <name>] [--diff removeTable:<name>]",
 			flags: [
@@ -171,7 +171,7 @@ var u = () => {
 		name: "evolve",
 		summary: "Schema-evolution copilot: propose an observed-graph-driven codemod + a branch-verified backfill for a schema change (rename/retype/split/drop a column, rename a table). Dry-run by default; --write applies. Usage: voltro evolve rename-column <table>.<col> --to <newName> [--write] [--json].",
 		status: "wired",
-		run: (e) => import("./evolveCommand-DTawtTxf.js").then((t) => t.runEvolveCommand(e)),
+		run: (e) => import("./evolveCommand-8CuFBlbQ.js").then((t) => t.runEvolveCommand(e)),
 		help: {
 			usage: "<rename-column|rename-table|retype-column|split-column|drop-column> <target> [--to <new>] [--write]",
 			flags: [
@@ -281,7 +281,7 @@ var u = () => {
 		name: "info",
 		summary: "Report versions (CLI, node, every installed @voltro/* — flags lockstep skew), package manager, and dialect. --json for CI. Exits 1 on version skew.",
 		status: "wired",
-		run: (e) => import("./infoCommand-BFksHunl.js").then((t) => t.runInfoCommand(e)),
+		run: (e) => import("./infoCommand-D02A4WI2.js").then((t) => t.runInfoCommand(e)),
 		help: {
 			usage: "[--json]",
 			flags: [["--json", "machine-readable report"]],
@@ -331,12 +331,12 @@ var u = () => {
 		run: async (e) => {
 			let t = e.find((e) => !e.startsWith("-")) ?? process.cwd();
 			if (e.includes("--preflight")) {
-				let { runServePreflight: e } = await import("./doctorCommand-B8H2MYCE.js");
+				let { runServePreflight: e } = await import("./doctorCommand-DXnNpKQT.js");
 				return e(s(t), !0);
 			}
 			let { tryRunWebServe: n } = await import("./webDev-Bzb8ZFus.js"), r = await n(s(t));
 			if (!r.ran) {
-				let { runServeDispatch: t } = await import("./serveCommand-BUXUtSF5.js");
+				let { runServeDispatch: t } = await import("./serveCommand-1R52mo6F.js");
 				return t(e);
 			}
 			return r.exitCode;
@@ -364,13 +364,13 @@ var u = () => {
 		handlesHelp: !0,
 		summary: "Preflight an app for production: the precompiled serve bundle, hand-rolled primitives (naming the shipped one), @voltro/* version skew, executors with no access check, `.serverOnly()` leaks, and junction-FK gaps.",
 		status: "wired",
-		run: (e) => import("./doctorCommand-B8H2MYCE.js").then((t) => t.runDoctorCommand(e))
+		run: (e) => import("./doctorCommand-DXnNpKQT.js").then((t) => t.runDoctorCommand(e))
 	},
 	{
 		name: "build",
 		summary: "Production build for a web app (vite build + per-page SSG pre-render).",
 		status: "wired",
-		run: (e) => import("./build-51qBWfYY.js").then((t) => t.runBuildCommand(e)),
+		run: (e) => import("./build-uRMZrT8z.js").then((t) => t.runBuildCommand(e)),
 		help: {
 			usage: "[app] [--target <t>]",
 			flags: [["--target <t>", "build target"], ["--report", "print what a visitor downloads: first load, chunks, server artefacts"]],
@@ -386,7 +386,7 @@ var u = () => {
 		name: "prune-runtime",
 		summary: "Trim a deployed web tree’s node_modules to the reachable runtime set (standalone image slimming).",
 		status: "wired",
-		run: (e) => import("./runtimeTrace-BUk5zMXY.js").then((t) => t.runPruneRuntimeCommand(e)),
+		run: (e) => import("./runtimeTrace-DDuKJgVi.js").then((t) => t.runPruneRuntimeCommand(e)),
 		hidden: !0
 	},
 	{
@@ -555,14 +555,14 @@ var u = () => {
 		handlesHelp: !0,
 		summary: "Upgrade the app to the latest framework: bump every @voltro/* dependency (across ALL workspace members, install once at the workspace root), then run the codemods shipped with the target version. Flags: --to <version>, --from <version>, --codemods-only, --dry-run, --force, --exact, --help. After: run `voltro db apply`.",
 		status: "wired",
-		run: (e) => import("./updateCommand-eVKVHj3N.js").then((t) => t.runUpdateCommand(e))
+		run: (e) => import("./updateCommand-inInBIAh.js").then((t) => t.runUpdateCommand(e))
 	},
 	{
 		name: "_apply-codemods",
 		summary: "Internal: apply shipped codemods for a framework version jump (re-exec target of `voltro update`).",
 		status: "wired",
 		hidden: !0,
-		run: (e) => import("./updateCommand-eVKVHj3N.js").then((t) => t.runApplyCodemods(e))
+		run: (e) => import("./updateCommand-inInBIAh.js").then((t) => t.runApplyCodemods(e))
 	},
 	{
 		name: "embeddings",

package/dist/{doctorCommand-5ULMpL10.js → doctorCommand-CGjefPmk.js}

@@ -1,6 +1,6 @@
 import { Xt as e, Yt as t, Zt as n } from "./dev-Ce2gEziv.js";
 import { Bt as r, Ht as i, T as a, Ut as o, V as s, Vt as c, t as l, u } from "./webDev-CBN9KkyQ.js";
-import { r as d, u as f } from "./apiBuild-CkpsCqIu.js";
+import { r as d, u as f } from "./apiBuild-BU5cd-Fn.js";
 import { S as p } from "./frameworkTableAssembly-vfkzuzEo.js";
 import { n as m } from "./pageConvention-CMpfDN6r.js";
 import { n as h, r as g, t as ee } from "./cliOutput-D1tSBoRM.js";
@@ -2162,7 +2162,7 @@ var le = {
 		findings: []
 	});
 	try {
-		let { offlineManifest: n, toInput: r } = await import("./checkCommand-C1EbNmwl.js"), { buildAppGraph: i, checkAppGraph: a } = await import("./appGraph-CFmFKHb2.js"), o = await n(e), s = r(o.manifest, o.tables), c = await zn(e), l = [.../* @__PURE__ */ new Set([...s.scopes ?? [], ...c])];
+		let { offlineManifest: n, toInput: r } = await import("./checkCommand-C1CQc8lD.js"), { buildAppGraph: i, checkAppGraph: a } = await import("./appGraph-CFmFKHb2.js"), o = await n(e), s = r(o.manifest, o.tables), c = await zn(e), l = [.../* @__PURE__ */ new Set([...s.scopes ?? [], ...c])];
 		if (l.length === 0) {
 			try {
 				let { loadAppSchemaInputs: t } = await import("./frameworkTableAssembly-B96WCNJA.js");

package/dist/doctorCommand-DXnNpKQT.js

@@ -0,0 +1,2 @@
+import { b as e, y as t } from "./doctorCommand-CGjefPmk.js";
+export { t as runDoctorCommand, e as runServePreflight };

package/dist/{evolveCommand-DTawtTxf.js → evolveCommand-8CuFBlbQ.js}

@@ -1,6 +1,6 @@
 import { n as e } from "./cliOutput-D1tSBoRM.js";
-import { i as t } from "./checkCommand-C30J2F18.js";
-import { i as n, n as r } from "./codemodRunner-BKjCwGiN.js";
+import { i as t } from "./checkCommand-DC7k1_hP.js";
+import { i as n, n as r } from "./codemodRunner-kNnh1I7_.js";
 import { basename as i, join as a, resolve as o } from "node:path";
 import { branchNamespaceName as s, planBranchProvision as c } from "@voltro/database";
 import { readFile as l } from "node:fs/promises";

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as e, i as t, n, o as r, r as i, t as a } from "./commands-DowWkYtd.js";
+import { a as e, i as t, n, o as r, r as i, t as a } from "./commands-cu34ENUT.js";
 import { r as o } from "./templates-BTWZkJJT.js";
 //#region src/index.ts
 var s = "framework";

package/dist/{infoCommand-BFksHunl.js → infoCommand-D02A4WI2.js}

@@ -1,5 +1,5 @@
 import { n as e, r as t, t as n } from "./cliOutput-D1tSBoRM.js";
-import { o as r } from "./updateCommand-CtuD5r1t.js";
+import { o as r } from "./updateCommand-Bw3mCUDT.js";
 import { join as i, resolve as a } from "node:path";
 import { readFileSync as o, readdirSync as s, statSync as c } from "node:fs";
 //#region src/infoCommand.ts

package/dist/{runtimeTrace-BUk5zMXY.js → runtimeTrace-DDuKJgVi.js}

@@ -1,4 +1,4 @@
-import { n as e } from "./apiBuild-CkpsCqIu.js";
+import { n as e } from "./apiBuild-BU5cd-Fn.js";
 import { join as t, resolve as n, sep as r } from "node:path";
 import { existsSync as i, promises as a } from "node:fs";
 import { createLogger as o } from "@voltro/logger";

package/dist/{sdkgen-CAhmmbjx.js → sdkgen-vq1fF9D_.js}

@@ -422,7 +422,7 @@ let package = Package(
 		await l.mkdir(o(e), { recursive: !0 }), await l.writeFile(e, n.content, "utf8");
 	}
 }, X = async (e) => {
-	let { offlineManifest: t } = await import("./checkCommand-C1EbNmwl.js"), { manifest: n } = await t(e);
+	let { offlineManifest: t } = await import("./checkCommand-C1CQc8lD.js"), { manifest: n } = await t(e);
 	return n;
 }, Z = async (e) => {
 	let t = J(await (e.manifestProvider ?? X)(e.root), {

package/dist/serveCommand-1R52mo6F.js

@@ -0,0 +1,2 @@
+import { n as e } from "./serveCommand-Dr4KXmTS.js";
+export { e as runServeDispatch };

package/dist/{serveCommand-DhtC7WBq.js → serveCommand-Dr4KXmTS.js}

@@ -9,7 +9,7 @@ import { Yt as sn, en as cn, ft as ln, ht as un, lt as dn, mt as fn, pt as pn, q
 import { g as hn, s as gn } from "./inspect-PcC5J-Dl.js";
 import { n as _n } from "./cliArgs-D4p8n7EE.js";
 import { r as vn } from "./appPort-B_HpJ_ck.js";
-import { r as yn, u as bn } from "./apiBuild-CkpsCqIu.js";
+import { r as yn, u as bn } from "./apiBuild-BU5cd-Fn.js";
 import { r as xn } from "./dialectDriver-czCHYpeH.js";
 import { i as Sn, n as Cn } from "./connectionConfig-Bk9IC7D0.js";
 import { c as wn, n as Tn, o as En } from "./seedRunner-DISBKow-.js";

package/dist/serveEntry.js

@@ -1,4 +1,4 @@
-import { t as e } from "./serveCommand-DhtC7WBq.js";
+import { t as e } from "./serveCommand-Dr4KXmTS.js";
 import { t } from "./loadEnv-D9nEOClM.js";
 import { r as n } from "./appModuleLoader-C9r9mxZt.js";
 import { i as r } from "./dialectDriver-czCHYpeH.js";

package/dist/{updateCommand-CtuD5r1t.js → updateCommand-Bw3mCUDT.js}

@@ -1,4 +1,4 @@
-import { n as e, r as t, t as n } from "./codemodRunner-BKjCwGiN.js";
+import { n as e, r as t, t as n } from "./codemodRunner-kNnh1I7_.js";
 import { basename as r, dirname as i, join as a, relative as o, resolve as s } from "node:path";
 import { existsSync as c, readFileSync as l, readdirSync as u, statSync as d, writeFileSync as f } from "node:fs";
 import { totalmem as p } from "node:os";

package/dist/updateCommand-inInBIAh.js

@@ -0,0 +1,2 @@
+import { m as e, p as t } from "./updateCommand-Bw3mCUDT.js";
+export { t as runApplyCodemods, e as runUpdateCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.58.0",
+  "version": "0.59.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -844,6 +844,18 @@
         "title": "rerank reaches the gateway through a ProviderConfig",
         "kind": "manual"
       },
+      {
+        "version": "0.59.0",
+        "id": "0.59.0/01_sourcemaps_moved_to_the_top_level",
+        "title": "`web.sourcemaps` moved to the top level of app.config.ts",
+        "kind": "transform"
+      },
+      {
+        "version": "0.59.0",
+        "id": "0.59.0/02_costsource_gained_unpriced",
+        "title": "`costSource` gained `unpriced`, and AI usage is counted in a unit",
+        "kind": "manual"
+      },
       {
         "version": "0.6.0",
         "id": "0.6.0/01_no-dev-session-secret",
@@ -926,24 +938,24 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.58.0",
-    "@voltro/cache": "0.58.0",
-    "@voltro/client": "0.58.0",
-    "@voltro/content": "0.58.0",
-    "@voltro/data-transfer": "0.58.0",
-    "@voltro/database": "0.58.0",
-    "@voltro/env": "0.58.0",
-    "@voltro/kv": "0.58.0",
-    "@voltro/logger": "0.58.0",
-    "@voltro/plugin-auth": "0.58.0",
-    "@voltro/plugin-broadcast": "0.58.0",
-    "@voltro/plugin-mail": "0.58.0",
-    "@voltro/plugin-storage": "0.58.0",
-    "@voltro/plugin-webhooks": "0.58.0",
-    "@voltro/protocol": "0.58.0",
-    "@voltro/runtime": "0.58.0",
-    "@voltro/serverless": "0.58.0",
-    "@voltro/workflow": "0.58.0",
+    "@voltro/ai": "0.59.0",
+    "@voltro/cache": "0.59.0",
+    "@voltro/client": "0.59.0",
+    "@voltro/content": "0.59.0",
+    "@voltro/data-transfer": "0.59.0",
+    "@voltro/database": "0.59.0",
+    "@voltro/env": "0.59.0",
+    "@voltro/kv": "0.59.0",
+    "@voltro/logger": "0.59.0",
+    "@voltro/plugin-auth": "0.59.0",
+    "@voltro/plugin-broadcast": "0.59.0",
+    "@voltro/plugin-mail": "0.59.0",
+    "@voltro/plugin-storage": "0.59.0",
+    "@voltro/plugin-webhooks": "0.59.0",
+    "@voltro/protocol": "0.59.0",
+    "@voltro/runtime": "0.59.0",
+    "@voltro/serverless": "0.59.0",
+    "@voltro/workflow": "0.59.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.md

@@ -749,7 +749,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.58.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.59.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.58.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.59.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/ai.md

@@ -185,6 +185,20 @@ const usable = models.filter(canExecute).filter((m) => m.capabilities?.vision)
 
 Each entry adds `capabilities`, `modalities`, `contextWindow`, `maxOutputTokens`, `releasedAt`, `knowledgeCutoff` and `dataPolicy`.
 
+Plus **`raw`** — the entry exactly as it came over the wire.
+
+The normalised fields are the shared answer to the questions every app on the gateway asks. `raw` is for the ones only one app asks: a chips row built from the vendor's own `tags`, a pricing display that shows a structure we have not normalised, `zdr` and `no_training` kept apart instead of folded into `dataPolicy`.
+
+```ts
+const models = await readGatewayCatalog({ modality: 'language' })
+const chips = models[0]?.raw?.tags            // vendor's own vocabulary
+const audioRate = (models[0]?.raw?.pricing as { audio_per_second?: string })?.audio_per_second
+```
+
+Without it, an app with its own display fetches `/v1/models` a second time and keeps a second parser of the same response — and then has to decide again, at every field the gateway adds, whether to wait for a framework release. That is the decision `raw` removes, which is why it is one field rather than three more normalised ones.
+
+It is absent on the injected-provider path (the seam a test uses), for the same reason `capabilities` is: that path never saw a response, and an empty object would turn "no wire data" into the claim "the wire carried nothing".
+
 `capabilities` is **unioned from three fields that each half-say it** — `tags`, `supported_parameters` and `modalities` — because they overlap and regularly disagree: a model tagged `reasoning` does not always carry the parameter, and the other way round. Taking either alone produces a false negative, and a false "cannot" removes a model from a picker with no way for anyone to find out why. That union is framework knowledge; without it every app writes the same forty lines, differently.
 
 `dataPolicy` carries `zeroRetention` and `noTraining` (`'all' | 'some' | 'none'`). They decide whether a model may see customer text, and an unreadable value reads as `'none'` — the question is "may this", and an unparseable answer is not a yes.
@@ -2589,7 +2603,42 @@ yield* generateSpeech({ text, provider: { name: 'elevenlabs', model: 'eleven_tur
 
 This ships **no** adapters, on purpose: bundling an ElevenLabs client would put the framework in the business of tracking somebody else's REST API, and the app already has the adapter. What the app deletes is its dispatch, not its adapters.
 
-A registered provider receives every option the primitive already had — `voice`, `outputFormat`, `speed`, `language`, `instructions`, `providerOptions` — or the seam would be a narrower primitive wearing the same name. Built-in names (`mock`, `openai`, `gateway`, `anthropic`) cannot be shadowed: silently overriding one would make the same config mean different things depending on which module loaded first.
+A registered provider receives every option the primitive already had — `voice`, `outputFormat`, `speed`, `language`, `instructions`, `providerOptions` — or the seam would be a narrower primitive wearing the same name.
+
+#### Taking over a built-in name
+
+`mock`, `openai`, `gateway` and `anthropic` resolve without a registration, and shadowing one by accident would make the same config mean different things depending on which module loaded first. So it takes a flag:
+
+```ts
+registerSpeechProvider('openai', myOpenAiTts, { replaceBuiltin: true })
+```
+
+The flag exists because a provider name is not always an alias you choose. `openai` is the value the gateway puts in its model ids, so it is what a stored catalog's rows carry and what a picker submits — an app told to pick another name cannot, without rewriting persisted rows and live sessions. Refusing outright did not protect that app; it made it keep its own dispatch for every provider, not just the colliding one.
+
+What the refusal was protecting is kept: the intent is now in the call, so an override is a decision someone wrote down rather than an accident of load order. Registered providers are resolved **before** built-ins — otherwise the flag would let you register a name and never reach it.
+
+### Cost — speech is not billed in tokens
+
+`generateSpeech` never records a ledger row itself; it returns `usage` and you pass it to `recordAiUsage`, the same as `generateText`. The difference is the unit. Every speech vendor meters characters of input or seconds of audio, so a `usage` shape that only knew tokens could not hold the call at all — speech spend was not un-priced, it was **absent**.
+
+A registered provider returns a `MeteredUsage`:
+
+```ts
+synthesize: (request) => Effect.succeed({
+  audio,
+  usage: { unit: 'characters', input: request.text.length },
+})
+```
+
+```ts
+yield* recordAiUsage(store, {
+  provider: 'elevenlabs', model: 'eleven_turbo_v3', operation: 'generateSpeech',
+  usage: { unit: 'characters', input: 4200 },
+  price: { inputPer1M: 30, outputPer1M: 0 },   // your rate, in your unit
+})
+```
+
+The ledger row carries `unit` beside the two counts. **A non-token unit is never priced by the token table**: without a `price` or an `actualCostUsd` the row is written `costSource: 'unpriced'` with the real count and a zero cost, because a per-1M-token rate applied to a character count produces a number indistinguishable from a real one. Sum the count columns grouped by `unit`, never across it.
 
 ## As a durable step — `transcribeStep`
 

package/templates/agent-docs/cli.md

@@ -1455,13 +1455,14 @@ web: {
   // `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',
 },
+
+// Top level, NOT under `web:` — it covers every bundle the build minifies
+// (browser, SSR, start, and an api app's serve bundle). Emits `.map` files with
+// no `//# sourceMappingURL` comment, so nothing shipped points at them.
+// `plugin-sentry` can upload and sweep them for you; `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

package/templates/agent-docs/plugins/sentry.md

@@ -161,17 +161,15 @@ The two halves are independent: the api plugin alone gives you server traces + e
 
 **Traces default to on, at `tracesSampleRate: 1.0`.** That is the coherent default rather than a generous one: the browser half already sampled every page load, navigation and rpc call at 1.0, so with the api half off each of those spans was emitted, paid for, and belonged to a trace with no server side — a browser hop hanging off nothing. The rate is named on the boot line (`sentry active traces=true tracesSampleRate=1`) so a first boot shows what it is about to send; lower it with `tracesSampleRate`, or set `traces: false` to keep errors and breadcrumbs only.
 
-## Source maps (browser stack traces)
+## Source maps (every bundle, browser and server)
 
-The web bundle is minified, so browser errors arrive in Sentry with **minified** stack traces unless the maps are uploaded. `voltro build` does it:
+Every bundle `voltro build` emits is minified, so an error arrives in Sentry with a **minified** stack trace unless the maps are uploaded. `voltro build` does it:
 
 ```ts
-// app.config.ts
-web: {
-  sourcemaps: {
-    mode: 'hidden',
-    upload: { org: 'acme', project: 'web' },
-  },
+// app.config.ts — top level, for a web app AND an api app
+sourcemaps: {
+  mode: 'hidden',
+  upload: { org: 'acme', project: 'web' },
 }
 ```
 
@@ -191,11 +189,9 @@ That emits the maps, uploads them through `@sentry/cli`, and then **removes them
 `app.config.ts` is TypeScript, so the ordinary branch is the answer:
 
 ```ts
-web: {
-  sourcemaps: process.env.CI
-    ? { mode: 'hidden', upload: { org: 'acme', project: 'web' } }
-    : 'hidden',
-}
+sourcemaps: process.env.CI
+  ? { mode: 'hidden', upload: { org: 'acme', project: 'web' } }
+  : 'hidden',
 ```
 
 `'hidden'` alone emits the maps and **keeps** them — right for reading a stack trace locally, and a leak in an image. Omit the field entirely and nothing is emitted, which is the default.
@@ -206,9 +202,52 @@ web: {
 
 It is read from `SENTRY_AUTH_TOKEN` and there is deliberately no `authToken` option: `app.config.ts` is a committed file, and a token with `project:releases` scope can write to every project in the org. Give it to the **build** (a CI secret, a Docker build secret) — not to the deployment, since the upload happens while the bundle is being built.
 
-**Install `@sentry/cli` yourself: `pnpm add -D @sentry/cli` in the web app.** The framework depends on it nowhere, and that is a licence decision rather than a packaging one — it is FSL-1.1-MIT, which restricts competing commercial use, so it must not sit in the dependency graph of a package we publish. A build with an upload configured and the package missing **refuses and names the command**, rather than skipping the upload and leaving you to find out months later that no frame resolves.
+**Install `@sentry/cli` yourself: `pnpm add -D @sentry/cli` in the app being built.** The framework depends on it nowhere, and that is a licence decision rather than a packaging one — it is FSL-1.1-MIT, which restricts competing commercial use, so it must not sit in the dependency graph of a package we publish. A build with an upload configured and the package missing **refuses and names the command**, rather than skipping the upload and leaving you to find out months later that no frame resolves.
+
+### It covers the server too — and that is what it was missing
+
+An earlier version of this page said server traces were un-minified already and
+that source maps were a browser-only concern. That was wrong about the built
+artefact, and the correction is the reason the option moved to the top level.
+
+`voltro build` minifies **four** bundles, not one: the browser bundle, the SSR
+bundle, the `voltro start` bundle, and — for an api app — the precompiled entry
+plus the serve bundle that `voltro serve` actually runs. `keepNames` rescues the
+handful of identifiers that are read as strings (Effect tags, error `name`s) and
+nothing else, so a frame out of the serve bundle reads:
+
+```
+at l  (file:///…/serveBundle/serveEntry.js:79:51)
+at Qo (file:///…/serveBundle/serveEntry.js:236:76405)
+```
 
-Server stack traces are un-minified already (the api ships readable JS), so this is a browser-only concern.
+The server half is also where it hurts most. A schedule, a workflow step, a
+subscriber or a REST route has no browser caller whose frame could stand in for
+it — a workflow that dies at 03:30 in a cron is only what its stack trace says.
+
+So `sourcemaps` is one field at the top level of `app.config.ts` and it covers
+everything the build minifies. **It replaces `web.sourcemaps`**, which reached
+only the browser bundle; the build refuses the old spelling rather than ignoring
+it, and `voltro update` moves it for you.
+
+Two details worth knowing before the first upload:
+
+- **Each output directory is uploaded under the prefix that matches how its
+  files are named.** `dist/assets` is fetched by a browser under `~/assets`; the
+  SSR, start and serve bundles are files a node process loaded and go up under
+  `~/`. Set `upload.urlPrefix` only if you know your project needs one value for
+  both.
+- **`node:*-slim` images have no CA certificates.** `/etc/ssl/certs` is empty and
+  the `ca-certificates` package is not installed. Node carries its own roots, so
+  nothing in JS notices — but `sentry-cli` is a Rust binary that uses the system
+  store, and it fails with `SSL peer certificate … unable to get local issuer
+  certificate`. Add `ca-certificates` to the build stage.
+
+**What we have not measured:** how a given Sentry project resolves the uploaded
+artifacts end to end. `sentry-cli sourcemaps upload` matches on debug IDs it
+injects into the emitted JS, and the URL prefix is the older release-artifact
+fallback — which is why the prefix is set correctly per directory rather than
+left to one default, and why this paragraph is here instead of a claim.
 
 ## Catching errors — what's automatic, what's manual