@voltro/cli 0.38.0 → 0.39.0

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

@@ -341,16 +341,88 @@ 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 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.
+in `@voltro/client` is `typeof window`-guarded, so nothing crashes at import —
+and the **client runtime now builds on RN**: `@voltro/client`'s
+[`buildApiRuntime`](/docs/react-native/overview#building-the-client-on-react-native)
+constructs the `ApiHandle` (runtime + subscription cache + rpc client) over a
+WebSocket **you** inject, so RN passes its own `globalThis.WebSocket` and gets
+the same client stack the web app uses, without pulling in `@voltro/web`.
+
+Still open before the loop is proven end-to-end on a device: codegen emitting the
+api's rpc group for a mobile app, an RN persistence adapter, a NetInfo connection
+signal, and a reconnect supervisor. `@voltro/react-native` ships the
+mobile-specific plumbing around 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.
+
+## Building the client on React Native
+
+`startMobileApis()` connects every api your app declares and keeps them
+connected — over the **same** supervisor the web client uses, not a mobile copy
+of it: exponential backoff, generation tracking, and the stale-seed gate that
+must never carry one subject's rows into the next one's screens.
+
+```ts
+import { startMobileApis, toApiHandles } from '@voltro/react-native'
+import { mobileApis } from './.framework/mobileApis.generated'   // from `voltro codegen`
+
+const apis = mobileApis(() => 'ws://192.168.1.20:4000/ws')
+
+const supervisor = startMobileApis({
+  apis,
+  onChange: (clients) => setHandles(toApiHandles(apis, clients)),
+})
+// later: supervisor.dispose() — or supervisor.reconnect() after a sign-in
+```
+
+`buildApiRuntime()` from `@voltro/client` is the layer underneath, if you want
+one connection without supervision:
+
+```ts
+import { buildApiRuntime } from '@voltro/client'
+
+const built = await buildApiRuntime({
+  name: 'app',
+  wsUrl: 'ws://192.168.1.20:4000/ws',        // your machine's LAN address
+  group: rpcGroup,                            // from codegen
+  // RN provides a global WebSocket; the web client injects a tracked one.
+  webSocketConstructor: (url, protocols) => new globalThis.WebSocket(url, protocols as string[]),
+})
+// built = { runtime, cache, client, errorBus } → an ApiHandle for the provider
+```
+
+### The api binding is generated
+
+`voltro codegen` reads the app's `voltro.mobile.ts` and writes
+`.framework/mobileApis.generated.ts` — which apis this app talks to, and where
+each one's rpc group and descriptors come from. The template's `pnpm ios` /
+`pnpm start` scripts run it, so there is no separate step.
+
+```ts
+// voltro.mobile.ts
+export default {
+  apis: { app: { package: '@acme/api' } },
+}
+```
+
+Only the BINDING is generated. The procedure types ride the import of the api
+package's own `rpcGroup`, so a schema change needs no regeneration here.
+
+### `localhost` on a phone is the phone
+
+The ws URL is a runtime parameter, never baked into the generated file. A device
+pointed at `ws://localhost:4000/ws` connects to itself, times out and retries
+forever — which reads as a broken framework rather than a wrong host.
+`resolveDevWsUrl()` takes the LAN host Expo already knows:
+
+```ts
+import Constants from 'expo-constants'
+import { resolveDevWsUrl } from '@voltro/react-native'
+
+const wsUrl = process.env.EXPO_PUBLIC_API_WS_URL
+  ?? resolveDevWsUrl(Constants.expoConfig?.hostUri, 4000)
+```
 
 > **Scaffold a mobile app.** `voltro create-project acme --api=api-backend
 > --mobile` (or `voltro add-app mobile --template mobile-app`) scaffolds an Expo
@@ -362,6 +434,34 @@ The package **root is RN-safe** — no `node:*`, no `@voltro/database`, and Reac
 is reached only through the hooks (an optional peer). The `_voltro_devices` table
 declaration is server-side and lives at `@voltro/react-native/schema`.
 
+## Persisted stores on a device
+
+`defineStore({ persist })` reads during RENDER, and a render cannot await — so a
+device's async storage cannot back it directly. `createAsyncStoragePersistence()`
+hydrates the keys into memory once, then serves reads from memory and writes
+through asynchronously.
+
+```ts
+import AsyncStorage from '@react-native-async-storage/async-storage'
+import { setStoreStorage } from '@voltro/client'
+import { createAsyncStoragePersistence } from '@voltro/react-native'
+
+const persistence = createAsyncStoragePersistence({ storage: AsyncStorage })
+
+await persistence.hydrate()             // BEFORE the first render
+setStoreStorage(persistence.provider)
+```
+
+**`hydrate()` must be awaited before rendering.** An app that renders first shows
+empty state and flickers into the saved state a frame later; the template holds
+the Expo splash screen until it resolves. Writes to one key coalesce per tick, so
+a store written on every keystroke costs one round trip, and a failed write is
+reported through `onError` rather than thrown into the `set()` that caused it.
+
+A storage with no `getAllKeys()` and no explicit `keys: [...]` is a REFUSAL, not
+an empty hydration — an empty cache is indistinguishable from a first run, which
+is the hardest persistence bug there is to attribute.
+
 ## Device registration
 
 A device is registered **after** the OS issues its push token (APNs on iOS, FCM
@@ -425,7 +525,7 @@ host away, so a universal link, an App Link, and a custom-scheme URL all match
 the same path-only pattern:
 
 ```ts
-import { matchDeepLink, matchFirstDeepLink } from '@voltro/react-native'
+import { dispatchDeepLink, matchDeepLink } from '@voltro/react-native'
 import orderLink from './orders.deepLink'
 
 matchDeepLink('/orders/:id', '/orders/42') // → { id: '42' }
@@ -433,14 +533,22 @@ matchDeepLink('/orders/:id', '/orders/42/edit') // → null
 
 // Until `*.deepLink.ts` file discovery lands, register links by hand —
 // declaration order wins, so list more-specific patterns first.
-const hit = matchFirstDeepLink([orderLink], 'myapp://orders/42')
-hit?.params.id // '42'
+const params = dispatchDeepLink([orderLink], 'myapp://orders/42')
+params?.id // '42' — and the winning handler has already run
 ```
 
+**Use `dispatchDeepLink` for a TABLE, `runDeepLink` for one descriptor.**
+`matchFirstDeepLink` also exists and only inspects: because a table is a
+heterogeneous array, the descriptor it returns has an erased pattern, so its
+handler's declared params (`Record<string, never>`) reject the params returned
+alongside it. Matching and invoking in two steps therefore does not typecheck —
+which is why the dispatching version exists rather than being left to every
+caller to cast around.
+
 > **Seam — file discovery.** Wiring `*.deepLink.ts` into codegen (so the router
 > auto-collects every declared link) is one additive file, landing after the
 > current release settles. The descriptor shape above is **final**, so register
-> links via `matchFirstDeepLink()` until then.
+> links via `dispatchDeepLink()` until then.
 
 ## Background sync
 
@@ -471,21 +579,33 @@ function SyncIndicator() {
 `offlineFirstDefaults` is the mobile posture as a value you spread into your
 client config: local-first ON, optimistic mutations, sync-on-foreground, a
 5-minute cadence, and a retry backoff schedule. `useMobileConnectionStatus()`
-surfaces a `connected | degraded | offline` status — `offline` from
-`navigator.onLine`, `degraded` from failures the app reports.
+surfaces a `connected | degraded | offline` status.
+
+**Where "online" comes from is injected, not detected.** The default source reads
+`navigator.onLine`, which React Native does not have — so on a device it answers
+"online" forever, airplane mode included. Pass `netInfoOnlineSource(NetInfo)`:
 
 ```tsx
-import { offlineFirstDefaults, useMobileConnectionStatus } from '@voltro/react-native'
+import NetInfo from '@react-native-community/netinfo'
+import { netInfoOnlineSource, offlineFirstDefaults, useMobileConnectionStatus } from '@voltro/react-native'
+
+// Module scope: an inline call is a new object every render, and the hook would
+// resubscribe on each one.
+const onlineSource = netInfoOnlineSource(NetInfo)
 
-// Spread the mobile posture into your client config.
 const config = { ...offlineFirstDefaults, url }
 
 function ConnectionPill() {
-  const { status, reportFailure, reportSuccess } = useMobileConnectionStatus()
+  const { status, reportFailure, reportSuccess } = useMobileConnectionStatus({ onlineSource })
   return <span data-status={status}>{status}</span>
 }
 ```
 
+`isInternetReachable` is believed only when it is a boolean. NetInfo reports
+`null` while its probe is outstanding, and reading that as `false` flashes
+"offline" on every cold start and every network change — so a `null` falls back
+to the link-layer `isConnected`.
+
 ## What's shipped vs. a seam
 
 This package ships the credential-free plumbing above. The parts that need
@@ -498,4 +618,5 @@ not built here:
 | **Native module bindings** (camera, biometrics, secure token storage) | Need a native runtime this TS package cannot provide. |
 | **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. |
+| **`*.deepLink.ts` codegen discovery** | One additive file after the release settles; the descriptor shape is final, so register links via `dispatchDeepLink()` today. |
+| **Booting on a device** | Everything above is unit-tested without a simulator, and a simulator is the only thing that can prove the loop runs under Metro. That is an Expo/EAS CI step — the framework repository has no iOS/Android toolchain, and we say so rather than implying coverage we do not have. |

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

@@ -331,4 +331,4 @@ mailPlugin({ provider: 'resend', from: '…', allowlist: ['me@acme.com'] })
 
 - [Webhooks](/docs/plugins/webhooks) — mounting the provider bounce/complaint query
 - [Rate limiting](/docs/plugins/ratelimit) — the sibling interceptor plugin
-- [Multi-tenancy](/docs/multi-tenancy) — where per-tenant suppression scoping comes from
+- [Multi-tenancy](/docs/multi-tenancy/overview) — where per-tenant suppression scoping comes from

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

@@ -280,4 +280,4 @@ Bring your own backend entirely by passing any object that satisfies the
 ## See also
 
 - [Mutations](/docs/data/mutations) — the interceptor chain rate limiting hooks into
-- [Multi-tenancy](/docs/multi-tenancy) — where `subject.tenantId` comes from
+- [Multi-tenancy](/docs/multi-tenancy/overview) — where `subject.tenantId` comes from

package/templates/agent-docs/plugins.md

@@ -67,6 +67,8 @@ Status legend: ✓ shipped · ◐ partial · — planned.
 | `@voltro/plugin-rbac` | ✓ | Roles compile to scopes + the `permission()` handler guard + typed `ScopeError` |
 | `@voltro/plugin-ratelimit` | ✓ | Per-endpoint / per-subject / per-tenant limits; sliding-window / fixed-window / token-bucket; memory / postgres / redis stores |
 | `@voltro/plugin-billing` | ✓ | Subscriptions, plans, entitlements + usage metering over a pluggable provider (Stripe + mock); seat-based billing; proration, failed-payment retries, tax and the checkout seat stepper are Stripe's, via the official SDK; `requireEntitlement()` guard + `enforce` interceptor; `/billing/webhook` via plugin-webhooks; money as integer minor units |
+| `@voltro/plugin-licensing` | ✓ | Offline-verified EdDSA license keys + cloud-issued entitlement snapshots that feed plugin-billing; plan entitlements + pricing decided server-side, never baked into a published version. [→ details](/docs/plugins/licensing) |
+| `@voltro/plugin-ai-flows` | ✓ | Durable multi-step AI pipelines — deterministic or agentic, with human-in-the-loop, chaining and cadence; author flows in code (`defineFlow`) or as data (visual-editor rows), one engine runs both. [→ details](/docs/plugins/ai-flows) |
 | `@voltro/plugin-mail` | ✓ | Transactional email — Resend / Postmark / SendGrid / SES / Mailgun / SMTP, *.email.tsx templates, per-tenant suppression, send-time scheduling, bulk/batch send, per-send idempotency, durable via workflows |
 | `@voltro/plugin-storage` | ✓ | File storage — public (CDN-direct) + private (access policy + per-object grants), S3 / R2 / GCS / MinIO / filesystem providers, presigned URLs, `listRefs` browse/search, HTTP Range (206) serving, dashboard browser |
 | `@voltro/plugin-postgis` | ✓ | Postgres-native `geography` / `geometry` columns + spatial predicates (`ST_DWithin`, `ST_Contains`, `ST_Intersects`); GiST indexes via `.expressionIndex(..., { kind: 'gist' })`. No `ST_Distance` projection yet. Postgres-only by design (fails loud elsewhere). [→ details](/docs/plugins/postgis) |
@@ -432,7 +434,7 @@ Absent `framework` field → no compat check. Suitable for in-tree plugins that
 - **Mutate other plugins' state.** Plugins don't talk to each other directly. If two plugins need to coordinate, it's via the rpc layer (one plugin's interceptor sees the other's `subject.metadata`, for example).
 - **Bypass tenant scoping.** Interceptors run AFTER the runtime's tenant predicate merge. A mutation interceptor can't query rows from another tenant by manipulating `subject.tenantId`.
 - **Access raw secrets directly.** Plugins get config via their own factory function's options object. `lifecycle.env` exposes `process.env` but only the plugin's own factory chooses which env vars to read.
-- **Modify the core schema DSL or query builder.** Schema extension happens through schema mixins (the `*.mixin.ts` pattern in `@voltro/database`); not through plugin runtime hooks.
+- **Modify the core schema DSL or query builder.** Schema extension happens through schema mixins (`defineMixin` from `@voltro/database`); not through plugin runtime hooks.
 
 These boundaries hold for v1; some may relax for verified plugins once the marketplace ships.
 

package/templates/agent-docs/releases.md

@@ -1,6 +1,135 @@
 # Releases
 
-> The largest release in the framework's history — what breaks your boot, what changes at runtime, and why none of it is rewritten for you.
+> 0.35 through 0.38 in one pass — the boot-breaking access declarations, the stricter input handling, and the runtime behaviour that moved underneath you.
+
+
+
+---
+
+<!-- source: en/releases/upgrading-to-0-38.md -->
+## Upgrading to 0.38.0
+
+_0.35 through 0.38 in one pass — the boot-breaking access declarations, the stricter input handling, and the runtime behaviour that moved underneath you._
+
+0.35, 0.36, 0.37 and 0.38 landed within two days of each other, so this page covers
+them as one upgrade. It is much smaller than [0.34](/docs/releases/upgrading-to-0-34) —
+but two of the changes will stop your app from booting until you make a decision, and
+one changes how every request is validated.
+
+Run the upgrade first, fix the boot, then read what moved at runtime.
+
+## 1. Run `voltro update`
+
+```bash
+voltro update
+```
+
+Every breaking change below either ships a codemod that rewrites your source or prints
+written steps during the update. What a codemod cannot do is make an access decision on
+your behalf — that part is yours.
+
+## 2. What breaks your boot
+
+### A declared event must decide who may listen (0.35)
+
+`defineEvent`'s `guards:` was optional, and an empty list was skipped — so under
+`security.defaultDeny` an event with **no access declaration was subscribable by anyone
+who could open the socket**, while the identical shape was already refused for every
+procedure. The boot gate now covers `defineEvent` too.
+
+Declare an access decision on each event: a `guards:` list, or an explicit
+`openAccess: '<reason>'` when it genuinely is public.
+
+### Twelve first-party plugin routes now require a scope (0.35)
+
+Every first-party plugin rpc route now declares an access decision, and `defaultDeny` is
+enforced in the dispatch spine as defense in depth. Previously-open routes that now need
+a scope:
+
+| Route | Scope |
+|---|---|
+| `billing.startCheckout` / `portalUrl` / `previewChange` / `changePlan` / `changeSeats` / `invoices` | `billing:manage` |
+| `billing.reportUsage` | `billing:report` |
+| `governance.export` / `erase` | `admin:full` (was already enforced in-handler, now declared) |
+| `storage.mintUploadUrl` / `ingestUrl` | `storage:manage` |
+| `storage.listRefs` | `storage:browse` |
+
+**Migration:** grant each scope to the role or subjects that legitimately hold that
+capability — via an rbac role, `resolveScopes`, or api-key scopes. The codemod lists
+every affected route plus the open-by-design surfaces that did **not** change.
+
+### The framework table set no longer reads a runtime flag (0.35)
+
+`CDC`, `VOLTRO_UNDO` and `VOLTRO_TRACING_PERSIST` used to move the *declared* table set,
+which meant the migrate job's env and the pod's env could disagree — a green apply
+followed by a crash loop. `app.config.ts` gained `schema: { traces?, undo? }` to declare
+the two that still need a decision.
+
+### A failing `*.startup.ts` now refuses the boot (0.38)
+
+It used to warn and let the server come up. If your startup module is allowed to fail,
+handle the failure inside it — the framework will no longer serve traffic behind a
+startup that did not complete.
+
+## 3. What changed at runtime
+
+### An undeclared input field now rejects the call (0.37)
+
+A field a procedure's input schema does not declare **rejects** the request. It used to
+be silently discarded and the call ran with what was left. This is the change most likely
+to surface in a client you did not update in lockstep: an extra property that used to be
+ignored is now an error. Check any hand-built request payloads.
+
+### `IMPERSONATION_METADATA_KEY` moved to `@voltro/protocol` (0.38)
+
+It names the one reserved key in `Subject.metadata`, and `Subject` is protocol's type —
+two packages need it (plugin-auth writes the mark, plugin-audit reads it) and a plugin
+must not depend on another plugin. The codemod repoints the import, preserving an alias
+and the type-only form. Everything else stays where it was: `impersonationOf`,
+`isImpersonated`, `ImpersonationMark` and `impersonationAuditRedactor` are still exported
+from `@voltro/plugin-auth`.
+
+An audit row now also records when an action was taken through an **impersonated**
+session, on the default settings, and no redactor can remove that mark.
+
+### Upstream 401s report a different code (0.36)
+
+A 401 from an upstream now produces `code: 'unauthorized'`, not `code: 'session_expired'`.
+The connection vault's own failure — the case where we *do* know the credential is
+unusable — becomes `code: 'credential_unusable'`. If you branch on these codes, update
+the branch.
+
+### `RunStepStatus` gained `'skipped'` (0.35, plugin-ai-flows)
+
+A sixth member means an exhaustive `switch` stops compiling and a status-keyed lookup has
+a hole. A manual codemod fires on any app that names the type or its literals. Everything
+else in that release is additive.
+
+### The analytics CDC mirror versions from the change, not the clock (0.35)
+
+Under `changeScope: 'fleet'` (postgres CDC, mysql binlog) the mirror's version is derived
+from the change's own position in the totally-ordered fleet stream instead of each
+replica's clock. N replicas still issue N writes per change — that is the transport — but
+they are now **byte-identical**, so the sinks' existing guards dedupe them for free.
+
+This closed a real defect: under clock skew larger than the gap between two changes to one
+row, a peer's duplicate of the *older* image could take the higher version and win in the
+warehouse permanently and silently.
+
+**If you wrote a custom sink**, `AnalyticsMirrorImpl.maxVersion` is now **required** — a
+replica joining mid-stream seeds each key from the warehouse's high-water mark. All
+shipped warehouse sinks implement it; the codemod note covers a custom one. New tunable:
+`VOLTRO_ANALYTICS_MIRROR_VERSION_STATE_LIMIT` (default 100000).
+
+## The short checklist
+
+1. `voltro update` — let the codemods run.
+2. Declare access on every `defineEvent`.
+3. Grant the twelve plugin-route scopes to the roles that should hold them.
+4. Move `CDC` / undo / traces decisions into `app.config.ts`'s `schema: { … }`.
+5. Make sure your `*.startup.ts` cannot fail unintentionally.
+6. Audit client payloads for fields your input schemas do not declare.
+7. If you have a custom analytics sink, implement `maxVersion`.
 
 
 

package/templates/agent-docs/routing.md

@@ -758,7 +758,18 @@ That last case is how dynamic `static` routes work in dev / when `getStaticPaths
 
 _Server-side data fetch via `loader`, page-level `<head>` tags via `meta`, and how the build pipeline runs both._
 
-A **loader** is the page's server-side data hook. It runs before the React render (during SSR, during SSG, or per-request for ISR/SSR), and its result lands in `useLoaderData<T>()`. **Meta** is a sibling export that produces `<title>` + `<meta>` tags.
+A **loader** is the page's data hook. It runs before the React render (during SSR, during SSG, or per-request for ISR/SSR), and its result lands in `useLoaderData<T>()`. **Meta** is a sibling export that produces `<title>` + `<meta>` tags.
+
+> **It runs on the server AND again in the browser.** A loader is not a
+> server-only hook: it runs during SSR for the first paint, and runs AGAIN, in
+> the browser, on every in-app navigation to the route. Same function, different
+> environment — so anything server-only in it must be guarded with
+> `ctx.isServer`.
+>
+> This is the single most expensive thing to learn late, because a client-only
+> failure is invisible to every probe that does not NAVIGATE: a fresh page load,
+> a `curl`, any SSR check all take the server path and pass. Only clicking a
+> link inside the running app reaches the other one.
 
 Both are static module exports — the framework discovers them, the build pipeline runs them.
 
@@ -780,7 +791,8 @@ export const loader = async ({ params, headers }: {
   params: { id: string }
   headers: Readonly<Record<string, string>>
 }): Promise<Note> => {
-  // Server-side fetch — runs on the Node side, never in the browser.
+  // Runs during SSR *and* again in the browser on in-app navigation —
+  // guard anything server-only with `ctx.isServer`.
   const res = await fetch(`${INTERNAL_API}/notes/${params.id}`, {
     headers: { cookie: headers.cookie ?? '' },
   })
@@ -1026,6 +1038,7 @@ React alone.
 export const loader = async (ctx: {
   readonly params:   Readonly<Record<string, string>>  // URL params from [name] segments
   readonly pathname: string                             // matched path (no query string)
+  readonly isServer: boolean                            // true during SSR/SSG, false in the browser
   readonly search:   string                             // raw query string incl. `?`, or '' — filled on every path
   readonly signal:   AbortSignal                        // Aborts if the client disconnects mid-render
   readonly headers?: Readonly<Record<string, string>>  // Request headers (SSR/ISR only — empty for SSG/client)
@@ -1036,6 +1049,25 @@ export const loader = async (ctx: {
 }) => Promise<unknown>
 ```
 
+### Branch on `isServer`, not on what happens to be missing
+
+`isServer` is the supported way to ask which invocation this is. The two things
+that look like they answer the same question do not:
+
+- **`query` is absent in the browser**, so `if (ctx.query)` appears to work. It
+  branches on the ABSENCE OF A FUNCTION, which says nothing about why it is
+  absent and breaks the moment anything else becomes conditional.
+- **`headers` is `{}` in the browser, not `undefined`** — so `if (ctx.headers)`
+  is TRUE on both paths. A consumer wrote exactly that check and it silently did
+  nothing.
+
+```ts
+export const loader = async (ctx: LoaderContext) => {
+  if (ctx.isServer) seedStore(prefs, await ctx.query!('prefs.get'))
+  return null
+}
+```
+
 The loader context carries `pathname` and `search`, not a `request` object.
 
 `pathname` is deliberately query-free — a loader keyed on `?tab=2` would cache badly. `search` carries the raw query string (with its leading `?`, or `''`), filled identically on client navigation, `voltro dev` SSR and `voltro start` SSR. Parse it with `new URLSearchParams(ctx.search)`.

package/templates/agent-docs/templates/apibackends.md

@@ -1006,7 +1006,7 @@ export default async ({ store, log, onShutdown, id }: StartupContext) => {
 }
 ```
 
-A throw here does NOT block boot — it's logged; the rpc surface stays up. Distinct from `*.seed.ts` (runs once and RETURNS) and `*.cron.tsx` (periodic): a startup HOLDS a resource until shutdown. `StartupContext` is imported from the `@voltro/cli/startup` subpath.
+A throw here REFUSES the boot, naming the file and the cause — a startup is where an app arms things the request path depends on, and "serving without them" is the failure nobody sees. Catch the error inside the function if a failure is genuinely acceptable (a cache warm), so the decision sits where somebody made it. The function must also RETURN: start the work, hand back teardown via `onShutdown`, return — one that never returns refuses the boot after `VOLTRO_STARTUP_TIMEOUT_MS` (default 60 s), while a slow-but-successful startup is simply awaited. Distinct from `*.seed.ts` (runs once and RETURNS) and `*.cron.tsx` (periodic): a startup HOLDS a resource until shutdown. `StartupContext` is imported from the `@voltro/cli/startup` subpath.
 
 ## Try it
 

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

@@ -51,7 +51,7 @@ Deep links are typed and go through one table: a universal link, a custom-scheme
 
 ## Honest status — read before you expect the loop on a device
 
-The **pure logic** (`src/lib/*`) is real and unit-tested (`pnpm test`, no simulator). The **client wiring** — building the runtime + subscription cache + rpc client the hooks read — is **not yet implemented for React Native**: on the web it lives in `@voltro/web`'s web-coupled boot. Wiring an RN-safe equivalent is Phase **M0** of the framework's mobile plan. Until it lands, `buildApiHandles()` in `src/client.ts` returns an empty map and the screens show their loading state — deliberately, not a crash. Its header spells out exactly what M0 must build.
+The **pure logic** (`src/lib/*`) is real and unit-tested (`pnpm test`, no simulator), and the **client wiring now exists**: `src/client.ts` calls `@voltro/client`'s `buildApiRuntime` with RN's `globalThis.WebSocket`, so `buildApiHandle()` returns a live handle. What it still waits on is **codegen emitting this app's rpc group + descriptor map** (on web those come from the generated entry) — until that lands, `buildApiHandles()` returns an empty map and the screens show their loading state, deliberately rather than faking one. Its header spells out the remaining step.
 
 Booting the app on a device (`expo run:ios`) is your Expo/EAS CI step — there is no iOS/Android toolchain in the framework repo.