@voltro/cli 0.11.4 → 0.12.0

package/dist/startEntry.js

@@ -1,3 +1,3 @@
-import { xt as e } from "./inspectMetrics-D4EJ8LTi.js";
-import { t } from "./start-DyJE6w1R.js";
+import { X as e } from "./inspectMetrics-uEfIS1vp.js";
+import { t } from "./start-DKcQd52a.js";
 export { e as loadDotEnv, t as runStartCommand };

package/dist/startup.js

@@ -1,2 +1,2 @@
-import { n as e, t } from "./startupRunner-DhlX9nqd.js";
+import { n as e, t } from "./startupRunner-DPGFchOa.js";
 export { t as loadStartupFiles, e as runStartups };

package/dist/{startupRunner-DhlX9nqd.js → startupRunner-DPGFchOa.js}

@@ -1,44 +1,30 @@
-import { basename as e } from "node:path";
-import { pathToFileURL as t } from "node:url";
+import { n as e } from "./appModuleLoader-C9r9mxZt.js";
+import { basename as t } from "node:path";
 import { publishServerError as n } from "@voltro/protocol";
-//#region src/appModuleLoader.ts
-var r = /* @__PURE__ */ new Map(), i = /* @__PURE__ */ new Map(), a = (e) => {
-	for (let [t, n] of Object.entries(e)) r.set(t, n);
-}, o = () => r.size > 0, s = async (e) => {
-	let n = i.get(e);
-	if (n) return n;
-	let a = r.get(e);
-	if (a !== void 0) {
-		if (typeof a == "function") {
-			let t = await a();
-			return i.set(e, t), t;
-		}
-		return a;
-	}
-	return await import(t(e).href);
-}, c = (e) => e.replace(/\.startup\.tsx?$/, ""), l = async (t, n) => {
-	let r = [];
-	for (let i of t) {
-		let t;
+//#region src/startupRunner.ts
+var r = (e) => e.replace(/\.startup\.tsx?$/, ""), i = async (n, i) => {
+	let a = [];
+	for (let o of n) {
+		let n;
 		try {
-			t = await s(i);
+			n = await e(o);
 		} catch (e) {
-			n.warn("startup: failed to import", { file: i }, e);
+			i.warn("startup: failed to import", { file: o }, e);
 			continue;
 		}
-		let a = t.default;
-		if (typeof a != "function") {
-			n.warn("startup: no default-export function", { file: i });
+		let s = n.default;
+		if (typeof s != "function") {
+			i.warn("startup: no default-export function", { file: o });
 			continue;
 		}
-		r.push({
-			file: i,
-			id: c(e(i)),
-			fn: a
+		a.push({
+			file: o,
+			id: r(t(o)),
+			fn: s
 		});
 	}
-	return r;
-}, u = async (e, t, r) => {
+	return a;
+}, a = async (e, t, r) => {
 	let i = [];
 	for (let a of e) {
 		let e = r.child(`startup:${a.id}`), o = {
@@ -82,4 +68,4 @@ var r = /* @__PURE__ */ new Map(), i = /* @__PURE__ */ new Map(), a = (e) => {
 	} };
 };
 //#endregion
-export { a, s as i, u as n, o as r, l as t };
+export { a as n, i as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.11.4",
+  "version": "0.12.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.107.0",
     "@effect/sql": "^0.51.1",
     "@effect/workflow": "^0.18.2",
-    "@voltro/ai": "0.11.4",
-    "@voltro/cache": "0.11.4",
-    "@voltro/data-transfer": "0.11.4",
-    "@voltro/database": "0.11.4",
-    "@voltro/env": "0.11.4",
-    "@voltro/kv": "0.11.4",
-    "@voltro/logger": "0.11.4",
-    "@voltro/plugin-auth": "0.11.4",
-    "@voltro/plugin-broadcast": "0.11.4",
-    "@voltro/plugin-mail": "0.11.4",
-    "@voltro/plugin-storage": "0.11.4",
-    "@voltro/plugin-webhooks": "0.11.4",
-    "@voltro/protocol": "0.11.4",
-    "@voltro/runtime": "0.11.4",
-    "@voltro/serverless": "0.11.4",
-    "@voltro/workflow": "0.11.4",
+    "@voltro/ai": "0.12.0",
+    "@voltro/cache": "0.12.0",
+    "@voltro/data-transfer": "0.12.0",
+    "@voltro/database": "0.12.0",
+    "@voltro/env": "0.12.0",
+    "@voltro/kv": "0.12.0",
+    "@voltro/logger": "0.12.0",
+    "@voltro/plugin-auth": "0.12.0",
+    "@voltro/plugin-broadcast": "0.12.0",
+    "@voltro/plugin-mail": "0.12.0",
+    "@voltro/plugin-storage": "0.12.0",
+    "@voltro/plugin-webhooks": "0.12.0",
+    "@voltro/protocol": "0.12.0",
+    "@voltro/runtime": "0.12.0",
+    "@voltro/serverless": "0.12.0",
+    "@voltro/workflow": "0.12.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.md

@@ -452,6 +452,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
+| **What's new in 0.11.4** | `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,6 +9,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
+| **What's new in 0.11.4** | `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/cli.md

@@ -105,8 +105,7 @@ pnpm dev       # turbo adds the new app to its parallel boot
 voltro db plan                 # diff declared schema vs live, color-coded
 # review the plan
 voltro db apply                # execute it (dev)
-# or, for the flagless idempotent apply (CI / ops):
-voltro migrate
+# `voltro migrate` is an alias of `db apply` — same differ, shorter name (CI / ops)
 ```
 
 ### "I want a clean rebuild"
@@ -130,19 +129,69 @@ voltro workflows list          # recent workflow runs
 
 ### "Did my edit break a binding?"
 
-`voltro check` runs blast-radius checks against the **running** api's live
-capability manifest — dangling `source` / `target` tables, unknown RBAC scopes,
-broken route bindings, orphan tables — at edit time instead of at runtime
-(needs `voltro dev` up). `--json` emits LLM-shaped diagnostics so a coding
-agent can fix-and-repeat; `--diff` previews the blast radius of a removal
-BEFORE you apply it.
+`voltro check` runs blast-radius checks over your app's typed graph — dangling
+`source` / `target` tables, scopes no role grants, unguarded mutations, broken
+route bindings, orphan tables — at edit time instead of at runtime. `--json`
+emits LLM-shaped diagnostics so a coding agent can fix-and-repeat; `--diff`
+previews the blast radius of a removal BEFORE you apply it.
+
+It prefers a running api (its manifest is ground truth, including live table
+introspection). **With none reachable it assembles the same graph from source**,
+so it works as a pre-commit hook or a CI gate without a second terminal —
+`--offline` forces that path.
 
 ```bash
-voltro check                          # blast-radius checks vs the live manifest
+voltro check                          # running api if there is one, else from source
+voltro check --offline                # never contact a server — the CI form
+voltro check --url https://api.example.com   # a DEPLOYED app
 voltro check --json                   # { ok, diagnostics: [{ rule, node, breaks, fix }] }
 voltro check --diff removeTable:todos # what a proposed removal would break, before applying
 ```
 
+`rbac/unknown-scope` needs a declared scope vocabulary to compare against —
+`rbacPlugin({ roles })` publishes one automatically. It catches a guard
+requiring a scope no role grants, which makes that procedure permanently and
+silently uncallable. (With a custom `resolvePermissions` the vocabulary isn't
+exhaustive, so the rule stays quiet rather than flagging correct code.)
+
+#### Declared vs OBSERVED — reconciled against reality
+
+A query's `source` and a mutation's `targets` are not documentation: the
+framework routes optimistic patches and decides which subscriptions a write
+invalidates from them. A wrong declaration is a live, user-visible bug that
+nothing type-checks — the mutation succeeds, the write lands, and the wrong list
+fails to update.
+
+`voltro dev` records what each procedure ACTUALLY touched, into
+`app.graph.observed.json` (gitignored automatically). When that file is present,
+`check` diffs it against the declarations:
+
+```
+observed: 12/34 procedures exercised (35%)
+  mutation(orders.place) (api/orders/place.mutation.ts)
+    writes 'inventory' (update) but declares no target for it
+    subscriptions on that table are not invalidated by this mutation
+    fix: add { table: 'inventory', op: 'update' } to this procedure's targets
+  22 unexercised — no recording, so nothing is claimed about them
+```
+
+Three things about that output are deliberate:
+
+- **Coverage comes first.** Three findings at 8% coverage and three at 95% are
+  different claims. Hiding the denominator is how a check starts overstating
+  what it knows.
+- **`unexercised` is a third state, not a finding.** A procedure no test and no
+  dev session ever ran has *no observation* — which is not the same as "touches
+  nothing". It is counted and never reported as a problem.
+- **Observed diagnostics never fail the build.** An observation is evidence
+  about the runs that happened, not a proof about the ones that didn't, and
+  `check`'s exit code gates CI. They are always warnings.
+
+No file → the section is skipped silently. This is not derived by parsing your
+handlers: a static pass over code that reaches the store through shared helpers,
+behind conditionals, has a long tail of both false positives and false negatives
+— and a check that is *sometimes* wrong is one people stop reading.
+
 The HTTP surface is reachable directly too — e.g. `curl -s localhost:4000/_voltro/inspect/rpc | jq` (there is no `/_voltro/inspect/queries` endpoint; it's `rpc` for procedures, `routes` for the web page tree, `subscriptions` for active subscribers).
 
 ## Where to read next
@@ -798,6 +847,78 @@ Docker step) and prints the exact remedy: add a `voltro build .` step before
 `voltro serve .`. Drop it into your image build right after `voltro build` to
 guarantee the artefact is present before the image ships.
 
+### The predicate-column check
+
+`eq` / `isNull` / `inSet` are free functions, so the column name arrives as a bare
+`string` and the builder cannot relate it to the table the predicate is attached
+to:
+
+```ts
+database.teamAppointments.where(isNull('deletedAt'))
+//                               ^ teamAppointments has no softDelete() mixin,
+//                                 so no `deletedAt` column exists. tsc: OK.
+```
+
+That type-checks — review and CI pass — and then fails at runtime as a bare SQL
+error. `voltro doctor` checks every literal predicate column against the table's
+declared columns and names both:
+
+```
+✗  predicate columns: 1 filter on a column that does not exist (214 checked)
+  api/appointments/rollforward.query.server.ts:31  'teamAppointments' has no column 'deletedAt'
+    columns: id, teamId, startsAt, createdAt, updatedAt
+  This type-checks today and fails at runtime as a bare SQL error.
+```
+
+Matching is on the AST, never on text, so a column name in a comment or an
+unrelated string cannot trip it. A call site whose table cannot be resolved is
+skipped silently — an unresolvable receiver is usually not a table at all.
+
+The type-level fix (binding the predicate to the row, `where(c => isNull(c.x))`)
+is the right end state and is planned separately. This check is the half that
+works **retroactively**: it finds the bug in code that already exists, which a
+type change never will.
+
+The detector also flags **raw `fetch()` in server files**. The SSRF guard the
+framework ships lives in the `HttpClient` handlers `yield*` — so it protects
+exactly the apps that already adopted it, and misses the ones that never did.
+Those are usually the same apps that secured least elsewhere, which is why the
+absence is worth naming out loud rather than assuming the default did its job.
+
+Server files only (`*.server.ts`, `*.cron.ts`, `*.subscribe.ts`, …): `fetch` is
+unremarkable in a browser component, and flagging it there would make the rule
+noise that gets scrolled past — taking the real findings with it.
+
+### The `workflows.start` audit
+
+`voltro doctor` also diffs every `workflows.start(name, payload)` call site
+against the workflows the app actually registers:
+
+```
+✗  workflow starts: 13/14 call sites checked
+  api/crons/weekly.cron.ts:22  'sprint.report' payload is missing: teamId
+  api/crons/weekly.cron.ts:22  'sprint.report' payload has unknown field(s): scheduledAt
+    accepted: sinceIso, teamId
+  1 UNCHECKED (not verified — not a pass):
+    api/crons/digest.cron.ts:8 — payload spreads a value
+```
+
+**Why this exists even though `workflows.start` validates at runtime.** Runtime
+validation fires on the next firing — which for a daily cron is hours, for a
+weekly one is a week, and for a quarterly one is a quarter. And
+`voltro inspect schedules --failing` cannot see a job that has *never fired*,
+because its roll-up is built from recorded runs. A weekly workflow broken by a
+refactor is invisible to both until it next runs.
+
+**`UNCHECKED` is never folded into a pass.** A payload built with a spread or a
+computed key can contribute any name, so its key set is unknowable here. Those
+call sites are counted and listed rather than passed silently — `0 issues` must
+not be readable as "all verified". The workflow **name** is checked regardless,
+since a rename or a deletion is decidable whatever the payload looks like.
+
+The required keys come from the live `payloadSchema`, the same source the runtime
+validation reads, so the two cannot disagree about what a payload needs.
+
 ### The hand-roll detector
 
 `voltro doctor` also scans your source for shapes the framework already has a
@@ -1007,16 +1128,18 @@ package's README.
 <!-- source: en/cli/migrate.md -->
 ## Migrate
 
-_voltro migrate — the idempotent schema apply; voltro db plan/apply for the declarative diff workflow._
+_voltro migrate — apply the declared schema through the declarative differ (an alias of voltro db apply)._
 
-`voltro migrate` applies your declared schema (`*.entity.ts` / `*.schema.ts` / `schema.ts`) to the configured database. It's a **flagless, idempotent apply**: it walks the project for table descriptors, emits `CREATE TABLE IF NOT EXISTS` + `CREATE INDEX IF NOT EXISTS`, and runs the DDL in one transaction. Re-running is a no-op.
+`voltro migrate` applies your declared schema (`*.entity.ts` / `*.schema.ts` / `schema.ts`) to the configured database. It is an **alias of [`voltro db apply`](#the-declarative-workflow)**: it diffs the declared schema against the live database and emits the ALTERs, so a changed column or a new index actually lands.
+
+> Before 0.11.4 this command was a create-only apply (`CREATE TABLE IF NOT EXISTS`, no diffing), which meant a column or type change reported success having applied **nothing**. If you need that bootstrap-only behaviour for a brand-new database, it is now `voltro migrate --create-only`.
 
 ```bash
 voltro migrate            # apply the discovered schema to the configured store
 voltro migrate apps/api   # explicit app directory (defaults to cwd)
 ```
 
-There are no `--plan` / `--dry` / `--reset` / `--advisory-lock` flags on `voltro migrate` — the only argument it reads is an optional path. The diff / plan / apply / drift / squash workflow lives under `voltro db` (see below).
+`voltro migrate` forwards its arguments to `voltro db apply`, so the same flags apply; `--create-only` selects the bootstrap-only emitter instead. The diff / plan / apply / drift / squash workflow lives under `voltro db` (see below).
 
 For the deep dive on the schema DSL + day-to-day patterns, see [Database / Migrations](/docs/database/migrations).
 
@@ -1163,6 +1286,23 @@ has never run is not "failing".
 Pair it with `voltro logs --level error`: a failing handler now logs at **error**
 level, so the two surfaces agree.
 
+## Targeting a deployed app
+
+Every command in this family resolves its target from the local runtime registry — the apps running on *this* machine. Pass `--url` to point one at a **deployed** app instead:
+
+```bash
+voltro inspect app     --url https://api.example.com --token "$TOKEN"
+voltro logs   --tail 100 --url https://api.example.com
+voltro traces --errors   --url https://api.example.com
+voltro check             --url https://api.example.com
+```
+
+`--token` (or `VOLTRO_INSPECT_TOKEN`) supplies the bearer; `VOLTRO_INSPECT_URL` sets a default target so you can drop the flag. Works for `inspect`, `logs`, `traces`, `workflows`, `cluster` and `check`.
+
+## Securing the local surface
+
+`voltro dev` mints a per-project `VOLTRO_INSPECT_TOKEN` into `.env.local`, so the inspect surface is authenticated from the first boot — the dev server listens on every interface, and without a token anyone on the same network could read your rows, schema and logs. You don't have to wire it anywhere: the CLI picks the token up from the runtime registry (so the commands work from any directory), and the dashboard's server-side proxy supplies it for same-machine targets. Setting `VOLTRO_INSPECT_TOKEN` yourself always wins.
+
 ## The inspect HTTP surface
 
 Every `voltro dev` / `voltro start` instance exposes a read-only introspection surface under `/_voltro/inspect/*`. The [Voltro Dashboard](/docs/observability/dashboard) consumes it to render the route sitemap, RPC list, subscription panel, workflow runs, and metrics. You can also hit the endpoints directly with `curl` (the `voltro inspect` subcommands above are the thin wrapper over exactly these).
@@ -1293,6 +1433,30 @@ Runs Vitest with the framework's preset:
 - `STORE=memory` by default for fast isolation.
 - Plays well with `@voltro/testing` helpers (mock stores).
 
+### Every vitest flag is forwarded
+
+Anything the command does not interpret itself goes straight to vitest — parsed
+by **vitest's own CLI parser**, not a list this wrapper maintains:
+
+```bash
+voltro test --coverage
+voltro test --reporter=junit --outputFile=reports/junit.xml
+voltro test --coverage --reporter=junit --outputFile=reports/junit.xml
+```
+
+That covers coverage numbers and a JUnit report for a merge-request widget, which
+is what most pipelines want beyond the exit code.
+
+The framework keeps three decisions for itself and they win over a forwarded
+flag: the **root** (a positional that is an existing directory, which vitest
+would otherwise read as a filter), `--watch`, and `passWithNoTests` — an explicit
+filter that matches no file is an *error*, which vitest cannot decide because it
+does not know which positional was treated as a root.
+
+An unrecognised flag is ignored rather than fatal, and a flag vitest cannot parse
+at all degrades to "run without the extra flags" with a warning instead of taking
+the run down.
+
 The actual test runner is Vitest; this command is a thin wrapper that injects the framework's config. You can run vitest directly if you prefer:
 
 ```bash
@@ -1332,7 +1496,9 @@ The framework's `voltro e2e` handles the lifecycle for you: it boots the api + w
 
 ## Securing the inspect surface
 
-The inspect endpoints expose framework internals (queries, subscription state, workflow runs). In production, lock them down with a bearer token:
+The surface is **fail-closed**: with no `VOLTRO_INSPECT_TOKEN` configured, every endpoint answers `401`. The absence of a secret is not consent — a check you were configured not to perform is a refusal, not a pass.
+
+That is why `voltro dev` mints one for you (above) and why nothing mints outside dev: in production a missing secret must stay a boot-time decision rather than an invented value. So a production `voltro start` serves nothing here until you set the token yourself:
 
 ```bash
 VOLTRO_INSPECT_TOKEN=$(openssl rand -hex 32)
@@ -1350,7 +1516,7 @@ Or disable the surface entirely: `VOLTRO_INSPECT=off`. The dashboard then can't
 
 ## Anti-patterns
 
-- **Inspect surface open in production.** Either disable (`VOLTRO_INSPECT=off`) or lock behind `VOLTRO_INSPECT_TOKEN`. Anyone hitting `/_voltro/inspect/*` can read rpc shapes + live subscription data.
+- **Assuming the surface is open because you didn't configure it.** It is the reverse: no token means `401`, not "everyone". If a production dashboard suddenly stops introspecting, the missing `VOLTRO_INSPECT_TOKEN` is the first thing to check — not a network problem.
 - **`voltro test` against `STORE=postgres` by default.** Slower + flaky (test isolation harder). Use postgres only for integration tests that NEED it.
 - **Skipping `voltro e2e` because "it's slow".** It catches integration bugs that unit tests miss. Run it in CI on every PR; locally for changes that touch queries.
 

package/templates/agent-docs/data.md

@@ -691,6 +691,14 @@ column — and required otherwise. `upsertRow`'s `conflictColumns` are constrain
 to the table's own columns, so a typo is a compile error too. The string-keyed
 `ctx.store.insert` / `upsert` still work unchanged; the typed seam is opt-in.
 
+> **If you adopt it, check your tooling for the old spelling.** `insertRow`
+> replaces `store.insert('<tableName>', …)`, so anything that matches on that
+> string stops matching — a lint rule, a codemod, an architecture test. One team
+> had a test asserting every mutation writes an audit log; it matched
+> `store.insert('auditLogs'`, and migrating to `insertRow` silently blinded it.
+> Green suite, gap reintroduced. Grep for the old spelling before you migrate,
+> not after.
+
 ## Partial updates: `ctx.store.applyDefined`
 
 A partial-update mutation should set only the fields the caller actually sent — not overwrite an omitted field with `undefined`. Instead of hand-writing `if (input.x !== undefined) patch.x = input.x` per field, use `ctx.store.applyDefined(input, keys)`:
@@ -2099,6 +2107,37 @@ export default crud.list('articles', { columns: ['id', 'title', 'createdAt'] })
 
 **Trap:** an eager `include` branch joins on a foreign key, so a projection that omits that FK breaks the relation. Keep the FK in `columns` when you also pass `include`.
 
+### `scope` — keep per-subject narrowing when you adopt the helper
+
+`filter` builds the WHERE from the request; `scope` builds it from the **caller**:
+
+```ts
+crud.list('timeEntries', {
+  filter: (input) => ({ status: input.status }),      // what the caller ASKED for
+  scope:  (ctx)   => ({ ownerId: ctx.request.subject.id }),  // what it MAY SEE
+})
+```
+
+A WHERE built only from `input` can express *the rows the caller asked for*, never
+*the rows the caller may see*.
+
+`scope` is merged **last**, so a request field of the same name can never widen it —
+`?ownerId=someone-else` is simply overridden. That ordering is why the two are
+separate options rather than one: only one of them is a security boundary, and kept
+apart, *"does this list declare a `scope`?"* is a question a reviewer — or a future
+boot audit — can actually ask. Folded into `filter`, it becomes *"does this filter
+happen to read ctx somewhere in its body?"*, which nothing can check. Tenant scope still applies automatically; anything
+narrower — owner, team, role — does not. So replacing a hand-written handler that
+carried such a narrowing with `crud.list` **widens the result set, silently and
+without an error**. One app lost exactly that across eight list views.
+
+Use the same filter for `crud.count`, or the total contradicts the pages —
+"showing 10 of 4000" on a page holding ten rows.
+
+The reason this is an option rather than a reason to leave: hand-writing the query
+to get the narrowing also forfeits `serverOnly` stripping and the page-size clamp.
+A narrowing requirement should not cost you the safety rails.
+
 ## What they deliberately don't do — authorization
 
 A guard runs *before* the executor, so gating lives on the **descriptor**, not the handler — an executor cannot gate itself. Keep every write descriptor guarded:

package/templates/agent-docs/scheduling.md

@@ -208,7 +208,15 @@ timezone: 'Europe/Berlin'   // 09:00 Berlin — DST handled by effect's Cron
 
 ## The handler context
 
-The handler receives a `ScheduleContext` — the same `app` a mutation gets, plus firing metadata:
+The handler receives a `ScheduleContext` — the same `app` a mutation gets, plus firing metadata.
+
+> **The API is identical; the subject is not.** `ctx.app.store` here is **not
+> tenant-scoped** — a schedule runs as `system` with no tenant. Reads see every
+> tenant's rows, and a write to a `tenant()` table fails with
+> `TenantScopeViolation` unless you pass `tenantId` explicitly. See
+> [below](#a-schedule-runs-as-the-system-subject--no-tenant). This sentence is
+> here rather than only further down because "same shape as a mutation" is what
+> sets the expectation that gets violated.
 
 ```tsx
 handler: async (ctx) => {
@@ -250,6 +258,32 @@ Writes to a `tenant()` table need the same treatment: pass `tenantId`
 explicitly, or the write fails with `TenantScopeViolation` rather than landing
 somewhere arbitrary.
 
+### `ctx.app.storeForTenant(id)` — the fan-out shortcut
+
+Doing that by hand means every `.where('tenantId', …)` and every explicit
+`tenantId:` is one forgotten call away from reading or writing across tenants.
+`storeForTenant` hands you a store scoped to exactly one:
+
+```tsx
+handler: async (ctx) => {
+  for (const t of await ctx.app.store.select('tenants').all()) {
+    const scoped = ctx.app.storeForTenant(t.id)
+    await scoped.insert('digests', { body: summary })   // tenantId stamped, not passed
+  }
+}
+```
+
+Inside a REQUEST this is almost always the wrong tool — the subject already
+carries a tenant, and reaching for another one is a cross-tenant access with
+extra steps. It exists because the system subject has *no* tenant to infer.
+
+One implementation detail worth knowing, because it is counter-intuitive: the
+scoped store does **not** run as a `system` subject with a tenant attached. A
+system subject carries `tenantId: null` by construction and the tenant mixin
+special-cases it to skip scoping entirely — on a system subject, a null tenant
+means *all* tenants. So the scoped view runs as a `serviceAccount` bound to that
+one tenant, keeping the schedule's scopes.
+
 This behaves identically under `voltro dev` and `voltro serve`. It did not
 always — before 0.10.0, dev scoped schedules to `$TENANT` (default `acme`)
 while production ran them unscoped, so the same cron read one tenant in

package/templates/agent-docs/security.md

@@ -22,6 +22,54 @@ Please report suspected vulnerabilities **privately** — never in public issues
 
 You'll get an **acknowledgement within 3 business days**, an assessment once we've reproduced the issue, and a **coordinated disclosure** timeline agreed with you — with credit in the release notes if you'd like it. We don't run a paid bug-bounty program yet, but we genuinely value responsible disclosure.
 
+## Outbound HTTP is SSRF-guarded by default
+
+The `HttpClient` your handlers `yield*` refuses internal targets:
+
+- loopback, RFC-1918, CGNAT and link-local addresses — including the
+  `169.254.169.254` cloud-metadata endpoint
+- the hostnames `localhost`, `*.internal`, `*.local`
+- any non-`http(s)` scheme
+
+**Every redirect hop is revalidated, not just the URL you passed.** A public URL
+that `302`s to the metadata endpoint is the actual attack; checking only the
+initial target catches none of it.
+
+This matters because a caller-supplied URL is ordinary product surface — a
+scraper, a webhook-registration form, an importer, a "test this connection"
+button. Those reach `HttpClient` with whatever the user typed.
+
+### Allowing a target on purpose
+
+```ts
+// app.config.ts
+export default defineApiConfig({
+  http: { allowHosts: ['*.svc.cluster.local', 'billing.internal'] },
+})
+```
+
+An entry may be an exact host, a `*.suffix` wildcard (which does **not** match the
+apex — one that did would silently widen your exception), or `host:port` when only
+one port should be reachable.
+
+There is no boolean off-switch, deliberately: *"we call one internal service"* and
+*"we do not check URLs"* are different postures, and a boolean cannot tell them
+apart six months later.
+
+### In tests, allow the stub — don't mock the guard
+
+Use the same `allowHosts` to reach a local stub server (`['127.0.0.1:8787']`).
+That keeps the test on the real guarded code path with a narrow exception. Mocking
+the guard away instead means the production path is never exercised — which is
+exactly how this framework's own webhook delivery once ended up behind a
+`NODE_ENV` check.
+
+### What this does NOT cover
+
+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.
+
 ## Supply-chain assurance
 
 Every release passes automated supply-chain gates in CI before a single package is published: