@voltro/cli 0.33.0 → 0.35.0

package/templates/apps/frontend-saas/app.config.ts

@@ -11,7 +11,9 @@
 //     `renderMode: 'ssr'` so the gate runs per request.
 //
 // The pages read the api live with `useSubscription` and write with
-// `useMutation` / `useAction`; the auth forms POST to the api's `/auth/*`.
+// `useMutation` / `useAction` — imported from `src/lib/api.ts`, which binds them
+// ONCE to this api's generated procedure map so every tag and every input/output
+// type is checked by the compiler. The auth forms POST to the api's `/auth/*`.
 import { defineEnv, envVar } from '@voltro/env'
 
 // Public, build-time env (baked into the bundle; read via `publicEnv`).
@@ -35,11 +37,13 @@ export default {
   // grow the app to more languages.
   locales:       ['en', 'de'] as const,
   defaultLocale: 'en'         as const,
-  // The api this dashboard consumes. The NAME ('app') is the lookup key the
-  // hooks + the loader's `query` use: `useSubscription('app', 'projects.list')`,
-  // `useMutation('app', 'projects.create')`, `query('session.me', {})`. Its
-  // port is auto-discovered from the api's own app.config.ts, and codegen pulls
-  // its typed rpc surface (including the plugins' `billing.*` / `/auth`).
+  // The api this dashboard consumes. The NAME ('app') is the lookup key — spelled
+  // ONCE, in `src/lib/api.ts`'s `createHooks<AppProcedures>('app')`, and then
+  // never again: pages call `useSubscription('projects.list')` /
+  // `useMutation('projects.create')`. (A loader still names the tag itself:
+  // `query('session.me', {})`.) The api's port is auto-discovered from its own
+  // app.config.ts, and codegen pulls its typed rpc surface (including the
+  // plugins' `billing.*` / `/auth`) into that same map.
   apis: {
     app: { package: '@{{projectName}}/api' },
   },

package/templates/apps/frontend-saas/package.json

@@ -12,21 +12,23 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@{{projectName}}/api": "0.33.0",
-    "@voltro/cli": "0.33.0",
-    "@voltro/client": "0.33.0",
-    "@voltro/env": "0.33.0",
-    "@voltro/i18n": "0.33.0",
-    "@voltro/ui-shadcn": "0.33.0",
-    "@voltro/web": "0.33.0",
+    "@{{projectName}}/api": "0.35.0",
+    "@voltro/cli": "0.35.0",
+    "@voltro/client": "0.35.0",
+    "@voltro/env": "0.35.0",
+    "@voltro/i18n": "0.35.0",
+    "@voltro/ui-shadcn": "0.35.0",
+    "@voltro/web": "0.35.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.33.0",
+    "@voltro/devtools": "0.35.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "jsdom": "^30.0.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/frontend-saas/src/lib/api.ts

@@ -1,37 +1,32 @@
-// The row + payload shapes this dashboard reads off the api, kept LOCAL so the
-// pages are self-contained. They mirror the api's descriptor outputs
-// (`projects.list`, `invites.list`, `billing.subscription`); you can also
-// `import type` them from the api package — a type-only cross-app import is
-// browser-safe.
+// The TYPED hook surface for the `app` api — bound ONCE, here, and imported by
+// every page instead of `@voltro/client`.
+//
+// `AppProcedures` is emitted by codegen into the api's `rpcGroup.generated.ts`:
+// a type-level map of every rpc tag (the app's own AND the plugins', e.g.
+// `billing.*`) to the descriptor behind it. Feeding it to `createHooks` makes
+// the tag a literal union and the input/output types INFER:
+//
+//     const { data } = useSubscription('projects.list')   // rows, typed
+//     const create   = useMutation('projects.create')     // input + output typed
+//
+// So the row shapes this file used to declare by hand are gone. They were a
+// MIRROR of the api's descriptor outputs, kept in sync by nobody: the old
+// `useSubscription<ReadonlyArray<Project>>('app', 'projects.list')` asserted a
+// type nothing checked against the server, and a typo'd tag only showed up at
+// runtime. Both are compile errors now.
+//
+// `'app'` is the key this web app gave the api in `app.config.ts` → `apis`.
+// `import type` is erased, so the binding costs the browser bundle nothing.
+import { createHooks } from '@voltro/client'
+import type { AppProcedures } from '@{{projectName}}/api/rpcGroup'
 
-export interface Project {
-  readonly id: string
-  readonly name: string
-  readonly tenantId: string
-  readonly createdAt: string | Date
-}
-
-export interface Invite {
-  readonly id: string
-  readonly email: string
-  readonly status: string
-  readonly tenantId: string
-  readonly createdAt: string | Date
-}
-
-// `billing.subscription` streams `{ subscription: … | null }` — null before the
-// tenant has any subscription row (they're on the implicit free plan).
-export interface SubscriptionState {
-  readonly subscription: {
-    readonly plan: string
-    readonly status: string
-    readonly quantity: number
-    readonly currentPeriodEnd: string | null
-    readonly cancelAt: string | null
-  } | null
-}
+// Destructured on purpose — `react-hooks/rules-of-hooks` only treats a member
+// call as a hook when the object is PascalCase, so top-level `useX` identifiers
+// are what keep the React lint rules working at every call site.
+export const { useSubscription, useMutation, useAction } = createHooks<AppProcedures>('app')
 
-// The caller's resolved identity, from `session.me`. The SSR gate reads it.
+// The caller's resolved identity, from `session.me`. The SSR gate reads it, and
+// a LOADER is not a hook — it calls `ctx.query` — so this shape stays hand-written.
 export interface Identity {
   readonly type: string
   readonly id: string | null

package/templates/apps/frontend-saas/src/pages/dashboard/billing/page.tsx

@@ -6,10 +6,9 @@
 // row yet means the tenant is on the implicit free plan.
 import type { ReactNode } from 'react'
 import type { PageMeta } from '@voltro/web'
-import { useSubscription, useAction } from '@voltro/client'
 import { T, useT } from '@voltro/i18n'
 import { getCatalog } from '../../../locales/index'
-import type { SubscriptionState } from '../../../lib/api'
+import { useAction, useSubscription } from '../../../lib/api'
 
 export const renderMode = 'ssr' as const
 
@@ -17,13 +16,13 @@ export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
   title: getCatalog(locale)['meta.billing.title'],
 })
 
-interface CheckoutInput { plan: string; successUrl: string; cancelUrl: string }
-interface SeatsInput { quantity: number }
-
 export default function Billing(): ReactNode {
-  const { data } = useSubscription<SubscriptionState>('app', 'billing.subscription')
-  const checkout = useAction<CheckoutInput, { url: string }>('app', 'billing.startCheckout')
-  const seats = useAction<SeatsInput, unknown>('app', 'billing.changeSeats')
+  // `billing.*` is contributed by @voltro/plugin-billing and lands in the same
+  // generated map as the app's own procedures, so a plugin route is typed here
+  // exactly like a hand-written one — no local Checkout/Seats input mirrors.
+  const { data } = useSubscription('billing.subscription')
+  const checkout = useAction('billing.startCheckout')
+  const seats = useAction('billing.changeSeats')
 
   const sub = data?.subscription ?? null
   const planLabel = useT('billing.plan.free')

package/templates/apps/frontend-saas/src/pages/dashboard/page.test.tsx

@@ -1,7 +1,9 @@
 // @vitest-environment jsdom
 //
-// Projects page — the live list + the paywall branch. We mock `@voltro/client`
-// (useSubscription streams the rows; useMutation is the create) and drive the
+// Projects page — the live list + the paywall branch. We mock the app's TYPED
+// hook binding `src/lib/api.ts` (useSubscription streams the rows; useMutation
+// is the create) — mocking `@voltro/client` underneath it would leave the real
+// `createHooks` running over a stub, i.e. the wrong seam. We drive the
 // create form, asserting: the SSR'd rows render, the empty state shows, and a
 // `projects.create` that rejects with a typed `EntitlementExceeded` flips the
 // page into the upgrade CTA (NOT a raw error).
@@ -14,7 +16,15 @@ import enCatalog from '../../locales/en'
 
 const subData = vi.fn<() => { data: unknown }>()
 const mutate = vi.fn<(input: { name: string }) => Promise<unknown>>()
-vi.mock('@voltro/client', () => ({
+// Only the HOOKS are faked. `isEntitlementExceeded` comes through from the real
+// module — an earlier version of this file re-implemented it inside the mock,
+// which meant the paywall test asserted that a copy of the predicate agreed
+// with the literal the same test had just written. That passes in every world,
+// including the one where the framework hands `catch` a value with no `_tag`
+// at all. `import type` is erased, so importing the original pulls in nothing
+// but `@voltro/client`.
+vi.mock('../../lib/api', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('../../lib/api')>()),
   useSubscription: () => subData(),
   useMutation: () => ({ mutate, pending: false, error: undefined, data: undefined }),
 }))
@@ -104,10 +114,24 @@ describe('projects — paywall', () => {
   })
 
   test('a typed EntitlementExceeded flips the page into the upgrade CTA', async () => {
+    // The rejection value is the TYPED ERROR ITSELF — that is the framework's
+    // guarantee for `mutate` / `run` / `signal` / `upload`, and the whole reason
+    // this page can branch on `_tag` instead of string-matching a message.
     mutate.mockRejectedValue({ _tag: 'EntitlementExceeded', entitlement: 'projects', limit: 3 })
     render(createElement(Projects))
     await submit()
     expect(container.querySelector('.paywall')).not.toBeNull()
     expect(container.textContent).toContain('hit your plan limit')
   })
+
+  test('an UNTAGGED failure does not paywall — that branch is for a declared outcome', async () => {
+    // The negative control, and the exact state the app was in while a rejected
+    // write handed back a wrapper with no `_tag`: the create fails, and the user
+    // is shown nothing about why. A paywall that appears for every failure is
+    // as wrong as one that never appears.
+    mutate.mockRejectedValue(new Error('socket hang up'))
+    render(createElement(Projects))
+    await submit()
+    expect(container.querySelector('.paywall')).toBeNull()
+  })
 })

package/templates/apps/frontend-saas/src/pages/dashboard/page.tsx

@@ -7,10 +7,9 @@
 import type { ReactNode } from 'react'
 import { useState, type FormEvent } from 'react'
 import type { PageMeta } from '@voltro/web'
-import { useSubscription, useMutation } from '@voltro/client'
 import { T, useT } from '@voltro/i18n'
 import { getCatalog } from '../../locales'
-import { isEntitlementExceeded, type Project } from '../../lib/api'
+import { isEntitlementExceeded, useMutation, useSubscription } from '../../lib/api'
 
 export const renderMode = 'ssr' as const
 
@@ -19,8 +18,9 @@ export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
 })
 
 export default function Projects(): ReactNode {
-  const { data: live } = useSubscription<ReadonlyArray<Project>>('app', 'projects.list')
-  const { mutate, pending } = useMutation<{ name: string }, Project>('app', 'projects.create')
+  // Tag + row type both come from the generated procedure map — no annotation.
+  const { data: live } = useSubscription('projects.list')
+  const { mutate, pending } = useMutation('projects.create')
   const projects = live ?? []
   const [name, setName] = useState('')
   const [paywalled, setPaywalled] = useState(false)

package/templates/apps/frontend-saas/src/pages/dashboard/team/page.tsx

@@ -6,10 +6,9 @@
 import type { ReactNode } from 'react'
 import { useState, type FormEvent } from 'react'
 import type { PageMeta } from '@voltro/web'
-import { useSubscription, useMutation } from '@voltro/client'
 import { T, useT } from '@voltro/i18n'
 import { getCatalog } from '../../../locales/index'
-import { isEntitlementExceeded, type Invite } from '../../../lib/api'
+import { isEntitlementExceeded, useMutation, useSubscription } from '../../../lib/api'
 
 export const renderMode = 'ssr' as const
 
@@ -24,8 +23,8 @@ const STATUS_KEY: Record<string, 'team.status.pending' | 'team.status.accepted'
 }
 
 export default function Team(): ReactNode {
-  const { data: live } = useSubscription<ReadonlyArray<Invite>>('app', 'invites.list')
-  const { mutate, pending } = useMutation<{ email: string }, Invite>('app', 'invites.create')
+  const { data: live } = useSubscription('invites.list')
+  const { mutate, pending } = useMutation('invites.create')
   const invites = live ?? []
   const [email, setEmail] = useState('')
   const [outOfSeats, setOutOfSeats] = useState(false)

package/templates/apps/frontend-spa/package.json

@@ -12,20 +12,22 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@voltro/cli": "0.33.0",
-    "@voltro/client": "0.33.0",
-    "@voltro/env": "0.33.0",
-    "@voltro/i18n": "0.33.0",
-    "@voltro/ui-shadcn": "0.33.0",
-    "@voltro/web": "0.33.0",
+    "@voltro/cli": "0.35.0",
+    "@voltro/client": "0.35.0",
+    "@voltro/env": "0.35.0",
+    "@voltro/i18n": "0.35.0",
+    "@voltro/ui-shadcn": "0.35.0",
+    "@voltro/web": "0.35.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.33.0",
+    "@voltro/devtools": "0.35.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "jsdom": "^30.0.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/frontend-ssr/package.json

@@ -12,20 +12,22 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@voltro/cli": "0.33.0",
-    "@voltro/client": "0.33.0",
-    "@voltro/env": "0.33.0",
-    "@voltro/i18n": "0.33.0",
-    "@voltro/ui-shadcn": "0.33.0",
-    "@voltro/web": "0.33.0",
+    "@voltro/cli": "0.35.0",
+    "@voltro/client": "0.35.0",
+    "@voltro/env": "0.35.0",
+    "@voltro/i18n": "0.35.0",
+    "@voltro/ui-shadcn": "0.35.0",
+    "@voltro/web": "0.35.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.33.0",
+    "@voltro/devtools": "0.35.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "jsdom": "^30.0.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/frontend-ssr-api/package.json

@@ -12,21 +12,23 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@{{projectName}}/api": "0.33.0",
-    "@voltro/cli": "0.33.0",
-    "@voltro/client": "0.33.0",
-    "@voltro/env": "0.33.0",
-    "@voltro/i18n": "0.33.0",
-    "@voltro/ui-shadcn": "0.33.0",
-    "@voltro/web": "0.33.0",
+    "@{{projectName}}/api": "0.35.0",
+    "@voltro/cli": "0.35.0",
+    "@voltro/client": "0.35.0",
+    "@voltro/env": "0.35.0",
+    "@voltro/i18n": "0.35.0",
+    "@voltro/ui-shadcn": "0.35.0",
+    "@voltro/web": "0.35.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.33.0",
+    "@voltro/devtools": "0.35.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "jsdom": "^30.0.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/frontend-static-blog/package.json

@@ -12,19 +12,21 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@voltro/cli": "0.33.0",
-    "@voltro/client": "0.33.0",
-    "@voltro/env": "0.33.0",
-    "@voltro/i18n": "0.33.0",
-    "@voltro/web": "0.33.0",
+    "@voltro/cli": "0.35.0",
+    "@voltro/client": "0.35.0",
+    "@voltro/env": "0.35.0",
+    "@voltro/i18n": "0.35.0",
+    "@voltro/web": "0.35.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.33.0",
+    "@voltro/devtools": "0.35.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "jsdom": "^30.0.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/frontend-status/package.json

@@ -12,21 +12,23 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@{{projectName}}/api": "0.33.0",
-    "@voltro/cli": "0.33.0",
-    "@voltro/client": "0.33.0",
-    "@voltro/env": "0.33.0",
-    "@voltro/i18n": "0.33.0",
-    "@voltro/ui-shadcn": "0.33.0",
-    "@voltro/web": "0.33.0",
+    "@{{projectName}}/api": "0.35.0",
+    "@voltro/cli": "0.35.0",
+    "@voltro/client": "0.35.0",
+    "@voltro/env": "0.35.0",
+    "@voltro/i18n": "0.35.0",
+    "@voltro/ui-shadcn": "0.35.0",
+    "@voltro/web": "0.35.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.33.0",
+    "@voltro/devtools": "0.35.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "jsdom": "^30.0.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/mobile-app/README.md

@@ -27,6 +27,7 @@ pnpm ios        # or: pnpm android · pnpm start (Expo Go)
 
 | Path | What |
 |---|---|
+| `src/lib/api.ts` | the **typed hook binding** — `createHooks<AppProcedures>('app')`, imported by every screen |
 | `src/lib/deeplinks.ts` | the typed deep-link table + pure resolver (**tested**) |
 | `src/lib/sync.ts` | the background-sync decision layer (**tested**) |
 | `src/lib/notifications.ts` | build a `_voltro_devices` row from a push token (**tested**) |

package/templates/apps/mobile-app/package.json

@@ -12,8 +12,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@voltro/client": "0.33.0",
-    "@voltro/react-native": "0.33.0",
+    "@voltro/client": "0.35.0",
+    "@voltro/react-native": "0.35.0",
     "expo": "^52.0.0",
     "expo-constants": "~17.0.0",
     "expo-linking": "~7.0.0",
@@ -26,8 +26,10 @@
     "react-native": "0.76.5"
   },
   "devDependencies": {
+    "@{{projectName}}/api": "0.35.0",
     "@types/react": "^19.0.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/mobile-app/src/app/index.tsx

@@ -1,22 +1,29 @@
 // Home screen — the reactive end-to-end loop, on a phone.
 //
-// The SAME hooks as the web frontend: `useSubscription('app', 'notes.list')`
-// streams the server-side query; `useMutation('app', 'notes.create')` writes it.
-// When the mutation lands, the server pushes a delta and this list re-renders —
-// no refetch, no polling. (Requires the M0 client boot; see ../client.ts.)
+// The SAME hooks as the web frontend: `useSubscription('notes.list')` streams
+// the server-side query; `useMutation('notes.create')` writes it. When the
+// mutation lands, the server pushes a delta and this list re-renders — no
+// refetch, no polling. (Requires the M0 client boot; see ../client.ts.)
+//
+// Both come from `../lib/api`, which binds them ONCE to the api's generated
+// procedure map — so the tag autocompletes, a typo is a compile error, and the
+// row type is inferred rather than declared here.
 import { useState } from 'react'
 import { Link } from 'expo-router'
 import { FlatList, Pressable, Text, TextInput, View } from 'react-native'
-import { useMutation, useSubscription } from '@voltro/client'
 
-interface Note {
-  readonly id: string
-  readonly title: string
-}
+import { useMutation, useSubscription } from '../lib/api'
+
+// The dev AuthMiddleware resolves the tenant from the `x-tenant` header,
+// defaulting to 'acme'. `notes.create` guards that the submitted tenantId
+// matches the caller's (a typed TenantMismatch otherwise).
+const TENANT = 'acme'
 
 export default function Home() {
-  const notes = useSubscription<ReadonlyArray<Note>>('app', 'notes.list')
-  const createNote = useMutation<{ title: string }, Note>('app', 'notes.create')
+  // No row `interface` and no `<T>`: the shape comes from `notes.list`'s own
+  // output schema, including the client's `optimistic` marker.
+  const notes = useSubscription('notes.list')
+  const createNote = useMutation('notes.create')
   const [title, setTitle] = useState('')
 
   return (
@@ -32,7 +39,10 @@ export default function Home() {
           onPress={() => {
             if (title.trim().length === 0) return
             // Auto-optimistic: the list updates instantly, reconciles on ack.
-            createNote.mutate({ title: title.trim() })
+            // `tenantId` and `body` are REQUIRED by `notes.create`'s input
+            // schema — the old hand-written `useMutation<{ title: string }>`
+            // annotation hid that, so this call decoded-failed at runtime.
+            createNote.mutate({ tenantId: TENANT, title: title.trim(), body: '' })
             setTitle('')
           }}
           style={{ backgroundColor: '#2563eb', borderRadius: 8, paddingHorizontal: 16, justifyContent: 'center' }}

package/templates/apps/mobile-app/src/app/orders/[id].tsx

@@ -12,7 +12,7 @@ export default function OrderDetail() {
       <Text style={{ fontSize: 20, fontWeight: '700' }}>Order {id}</Text>
       <Text style={{ color: '#666' }}>
         Reached via the typed deep-link table. Fetch this order with
-        {' '}useSubscription('app', 'orders.get', {'{'} id {'}'}).
+        {' '}useSubscription('orders.get', {'{'} id {'}'}) from ../../lib/api.
       </Text>
     </View>
   )

package/templates/apps/mobile-app/src/lib/api.ts

@@ -0,0 +1,34 @@
+// The typed hook surface for the `app` api — bound ONCE, here, and imported by
+// every screen instead of `@voltro/client`.
+//
+// `AppProcedures` is emitted by codegen into the sibling api's
+// `rpcGroup.generated.ts`: a type-level map of every rpc tag to the descriptor
+// behind it. Feeding it to `createHooks` makes the tag a literal union and the
+// input/output types INFER:
+//
+//     const notes  = useSubscription('notes.list')   // rows, typed
+//     const create = useMutation('notes.create')     // input + output typed
+//
+// So no screen declares a row `interface` mirroring the api any more. The old
+// `useSubscription<ReadonlyArray<Note>>('app', 'notes.list')` spelled the api
+// name at every call site, left the tag an unchecked string (a typo was a
+// runtime error), and the `<T>` was an ASSERTION nothing compared against the
+// server. All three are compile-checked now.
+//
+// `'app'` is the key this project's api is registered under. The api is a
+// type-only import — `import type` is erased, so Metro never resolves it and
+// nothing server-side reaches the bundle. It is a devDependency for exactly
+// that reason; scaffold the pair (`create-project --api=api-backend --mobile`),
+// which is what this template's README already assumes.
+//
+// RUNTIME NOTE: the hooks are typed today and live once the mobile codegen
+// target lands — `buildApiHandles()` in ../client.ts still returns an empty map
+// (see the seam documented there), so screens render their loading state until
+// then. The TYPES are real either way; they come from the api's own descriptors.
+import { createHooks } from '@voltro/client'
+import type { AppProcedures } from '@{{projectName}}/api/rpcGroup'
+
+// Destructured on purpose — `react-hooks/rules-of-hooks` only treats a member
+// call as a hook when the object is PascalCase, so top-level `useX` identifiers
+// are what keep the React lint rules working at every call site.
+export const { useSubscription, useMutation, useAction } = createHooks<AppProcedures>('app')

package/templates/apps/mobile-app/voltro.mobile.ts

@@ -1,6 +1,8 @@
 // The api(s) this mobile app consumes — mirrors a web app.config.ts's `apis:`
-// map. The NAME ('app') is the lookup key the hooks use:
-// `useSubscription('app', 'notes.list')`, `useMutation('app', 'notes.create')`.
+// map. The NAME ('app') is the lookup key the hooks bind to: `src/lib/api.ts`
+// spells it ONCE via `createHooks<AppProcedures>('app')`, and every screen then
+// calls `useSubscription('notes.list')` / `useMutation('notes.create')` with no
+// api name and no hand-written result type.
 // The `package` resolves the sibling api in this project so codegen can pull its
 // typed rpc surface (end-to-end types on a phone). Scaffold the api with
 // `--api=api-backend`.

package/templates/baselines/bare/.env.example

@@ -5,6 +5,20 @@
 # override .env values, so CI can set DB_URL via env without touching
 # this file.
 
+# ── Environment ────────────────────────────────────────────────────────
+#
+# DECLARE IT. Every `voltro db …` / `voltro migrate` invocation resolves an
+# UNSET `NODE_ENV` to `production` — the same way `voltro serve` and `voltro
+# start` do — so a bare `pnpm migrate` with no NODE_ENV refuses rather than
+# applying an un-reviewed diff to what might be a production database. It also
+# decides which `_voltro_*` bookkeeping tables the command declares, and a
+# migration command that resolves it differently from the serving process
+# declares a DIFFERENT schema.
+#
+# `voltro dev` declares `development` for itself and needs nothing from here;
+# this line is what makes the explicit schema commands work locally.
+NODE_ENV=development
+
 # Postgres connection. Bring your own (host install, docker run,
 # cloud provider URL).
 DB_URL=postgres://app:app@localhost:5432/{{projectName}}

package/templates/baselines/bare/baseline.json

@@ -23,9 +23,9 @@
     "deploy/voltro.service.example"
   ],
   "packageJsonScripts": {
-    "dev":       "turbo run dev",
-    "build":     "turbo run build",
-    "test":      "turbo run test",
-    "typecheck": "turbo run typecheck"
+    "dev":       "pnpm -r --parallel dev",
+    "build":     "pnpm -r build",
+    "test":      "pnpm -r test",
+    "typecheck": "pnpm -r typecheck"
   }
 }

package/templates/baselines/compose/.env.example

@@ -5,6 +5,20 @@
 # override .env values, so CI can set DB_URL via env without touching
 # this file.
 
+# ── Environment ────────────────────────────────────────────────────────
+#
+# DECLARE IT. Every `voltro db …` / `voltro migrate` invocation resolves an
+# UNSET `NODE_ENV` to `production` — the same way `voltro serve` and `voltro
+# start` do — so a bare `pnpm migrate` with no NODE_ENV refuses rather than
+# applying an un-reviewed diff to what might be a production database. It also
+# decides which `_voltro_*` bookkeeping tables the command declares, and a
+# migration command that resolves it differently from the serving process
+# declares a DIFFERENT schema.
+#
+# `voltro dev` declares `development` for itself and needs nothing from here;
+# this line is what makes the explicit schema commands work locally.
+NODE_ENV=development
+
 # Postgres connection — points at the postgres service in
 # docker-compose.yml (port 5433 to avoid clashing with a host pg on 5432).
 # When you run inside the docker network (dev:docker / prod:up), the