@voltro/cli 0.1.0

package/templates/apps/api-durable/mutations/orders.approve.mutation.server.ts

@@ -0,0 +1,43 @@
+// `orders.approve` — EXECUTOR (server-only).
+//
+// Injects the `approval` signal that wakes the parked `orders.fulfill`
+// run for this order. The workflow's `idempotencyKey` (`fulfill:<id>`)
+// makes its executionId a deterministic function of the payload, so we
+// re-derive it from `{ orderId, tenantId }` and address the signal by
+// executionId — no need to track the run handle from the place mutation.
+//
+// `ctx.workflows.signal(target, name, payload)` writes a `signal-sent`
+// row to the run's events log; the workflow's `awaitSignal('approval')`
+// poll picks it up (sub-second) and parses the payload against its
+// `{ approved: boolean }` schema.
+
+import { assertOwnTenant } from '@voltro/plugin-multitenancy/guard'
+import type { AppContext } from '@voltro/runtime'
+
+const execute = async (
+  input: { orderId: string; tenantId: string; approved: boolean },
+  ctx: AppContext,
+) => {
+  assertOwnTenant(input.tenantId, ctx.request.subject)
+
+  if (!ctx.workflows) {
+    throw new Error('orders.approve: workflow runtime is not available in this context')
+  }
+
+  // Deterministic executionId for the running fulfillment workflow —
+  // same payload the `order.placed` trigger started it with.
+  const executionId = await ctx.workflows.executionId('orders.fulfill', {
+    orderId:  input.orderId,
+    tenantId: input.tenantId,
+  })
+
+  const { eventId } = await ctx.workflows.signal(
+    { executionId },
+    'approval',
+    { approved: input.approved },
+  )
+
+  return { orderId: input.orderId, eventId }
+}
+
+export default execute

package/templates/apps/api-durable/mutations/orders.approve.mutation.ts

@@ -0,0 +1,23 @@
+// `orders.approve` — DESCRIPTOR (browser-safe).
+//
+// The human-approval surface: a client calls this with the order id +
+// the decision; the executor injects the matching `approval` signal into
+// the parked `orders.fulfill` run. This is a non-row-writing mutation
+// (it pokes a workflow, not the orders table), so it declares no
+// optimistic `target` and no `op` against `orders`.
+
+import { defineMutation } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const approveOrder = defineMutation({
+  name: 'orders.approve',
+  input: Schema.Struct({
+    orderId:  Schema.String,
+    tenantId: Schema.String,
+    approved: Schema.Boolean,
+  }),
+  output: Schema.Struct({
+    orderId: Schema.String,
+    eventId: Schema.String,
+  }),
+})

package/templates/apps/api-durable/mutations/orders.place.mutation.server.ts

@@ -0,0 +1,45 @@
+// `orders.place` — EXECUTOR (server-only, default export).
+//
+// Inserts the order in the mutation transaction, then emits a domain
+// event AFTER commit. `ctx.events.emit(...)` is post-commit safe: the
+// event is recorded + the `order.placed` trigger fans out only once the
+// row is durably written, so a rollback never starts a fulfillment
+// workflow for an order that doesn't exist.
+
+import { assertOwnTenant } from '@voltro/plugin-multitenancy/guard'
+import type { AppContext } from '@voltro/runtime'
+
+const execute = async (
+  input: { tenantId: string; customerName: string; amountCents: number },
+  ctx: AppContext,
+) => {
+  // Cross-tenant write guard — reject a caller spoofing input.tenantId.
+  assertOwnTenant(input.tenantId, ctx.request.subject)
+
+  // Framework auto-injects an `order_…` id + the tenant/audit columns.
+  const row = await ctx.store.insert('orders', {
+    status:       'placed',
+    customerName: input.customerName,
+    amountCents:  input.amountCents,
+    tenantId:     input.tenantId,
+  })
+
+  // Post-commit fan-out → the `order.placed` trigger starts the
+  // `orders.fulfill` workflow. `ctx.events` is only present when the
+  // runtime wired the events facade (it always is under `voltro dev`);
+  // guard so a unit-test ctx without it doesn't throw.
+  await ctx.events?.emit('order.placed', {
+    orderId:  row['id'] as string,
+    tenantId: input.tenantId,
+  })
+
+  return {
+    id:           row['id'] as string,
+    status:       row['status'] as string,
+    customerName: row['customerName'] as string,
+    amountCents:  row['amountCents'] as number,
+    tenantId:     row['tenantId'] as string,
+  }
+}
+
+export default execute

package/templates/apps/api-durable/mutations/orders.place.mutation.ts

@@ -0,0 +1,40 @@
+// `orders.place` — DESCRIPTOR (browser-safe: schema + target + typed
+// error only; NO node/database/server imports).
+//
+// `TenantMismatch` is imported from the `/guard` subpath, NOT the
+// package root — the root re-exports the schema mixin, which would drag
+// `@voltro/database` into the client rpcGroup bundle. `/guard` is the
+// browser-safe surface for the typed error you declare here.
+
+import { defineMutation } from '@voltro/protocol'
+import { TenantMismatch } from '@voltro/plugin-multitenancy/guard'
+import { Schema } from 'effect'
+
+export const placeOrder = defineMutation({
+  name: 'orders.place',
+  // Auto-optimistic: every query whose `source: 'orders'` matches gets a
+  // placeholder row prepended; the server delta replaces it on commit.
+  target: {
+    table: 'orders',
+    op: 'insert',
+    shape: (input: { tenantId: string; customerName: string; amountCents: number }) => ({
+      status: 'placed',
+      customerName: input.customerName,
+      amountCents: input.amountCents,
+      tenantId: input.tenantId,
+    }),
+  },
+  input: Schema.Struct({
+    tenantId:     Schema.String,
+    customerName: Schema.NonEmptyString,
+    amountCents:  Schema.Int.pipe(Schema.greaterThan(0)),
+  }),
+  output: Schema.Struct({
+    id:           Schema.String,
+    status:       Schema.String,
+    customerName: Schema.String,
+    amountCents:  Schema.Number,
+    tenantId:     Schema.String,
+  }),
+  error: TenantMismatch,
+})

package/templates/apps/api-durable/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@{{projectName}}/{{appName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "voltro dev .",
+    "test": "voltro test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@effect/platform": "^0.96.1",
+    "@effect/rpc": "^0.75.1",
+    "@voltro/cli": "0.1.0",
+    "@voltro/database": "0.1.0",
+    "@voltro/env": "0.1.0",
+    "@voltro/plugin-multitenancy": "0.1.0",
+    "@voltro/protocol": "0.1.0",
+    "@voltro/runtime": "0.1.0",
+    "@voltro/workflow": "0.1.0",
+    "effect": "^3.21.2"
+  },
+  "devDependencies": {
+    "@voltro/testing": "0.1.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/templates/apps/api-durable/schedules/nightlyReport.cron.tsx

@@ -0,0 +1,37 @@
+// `nightlyReport` — a cron schedule (single-file `*.cron.tsx`).
+//
+// Runs at 02:00 UTC every day. `timezone` is MANDATORY — the cron is
+// interpreted in this IANA zone, never the container's local TZ. The
+// expression is validated at boot (a typo throws in the discovery log,
+// it doesn't silently never-fire).
+//
+// The handler is "a mutation the clock invokes": `ctx.app` is the same
+// AppContext shape a mutation gets (store + interceptors). For durable
+// multi-step work, prefer the `workflow: { name, payload }` form
+// instead of a handler.
+//
+// Zero-config coordination: on `store: 'memory'` this runs single-
+// process; on a multi-instance SQL store the framework advisory-lock
+// coordinates so exactly one replica fires each tick.
+
+import { defineSchedule } from '@voltro/runtime'
+import { count, eq } from '@voltro/database'
+import { database } from '../database/schema'
+
+export default defineSchedule({
+  name:     'nightlyReport',
+  cron:     '0 2 * * *',     // 02:00 every day
+  timezone: 'UTC',
+  description: 'Logs a per-status order tally each night.',
+  handler: async (ctx) => {
+    // Tally placed-but-not-yet-shipped orders as a simple health signal.
+    const open = await ctx.app.store.query(
+      database.orders.where(eq('status', 'placed')).aggregate({ total: count() }).descriptor,
+    )
+    const total = (open[0] as { total?: number } | undefined)?.total ?? 0
+    console.info(`[nightlyReport] fired for ${ctx.scheduledAt.toISOString()} — ${total} order(s) still 'placed'`)
+  },
+  // optional, all default-safe:
+  onOverlap:    'skip',
+  maxRuntimeMs: 5 * 60_000,
+})

package/templates/apps/api-durable/startup/warm.startup.tsx

@@ -0,0 +1,33 @@
+// `warm` — a run-once startup hook (`*.startup.tsx`).
+//
+// Default-exports a function (no `define*` wrapper). Runs ONCE after
+// migrations + seeds, when the rpc server is listening. Use it for
+// long-lived boot work: warm a cache, open a broker consumer / upstream
+// websocket, start a background interval, register a process singleton —
+// and register a teardown via `onShutdown`.
+//
+// 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 for the process lifetime.
+//
+// NOTE: `StartupContext` lives on the `@voltro/cli/startup` subpath (the
+// runtime package stays free of the node:fs discovery code).
+
+import type { StartupContext } from '@voltro/cli/startup'
+
+export default async ({ store, log, onShutdown, id }: StartupContext) => {
+  log.info(`startup '${id}': warming order-fulfillment caches`)
+
+  // Example long-lived resource: a heartbeat interval. Replace with a
+  // real warm-up (preload a dashboard cache, open a consumer, …).
+  const timer = setInterval(() => {
+    void store // `store` is the already-migrated DataStore, ready to use.
+  }, 60_000)
+
+  // Teardown runs on SIGTERM / SIGINT, LIFO across all startups, each
+  // awaited with a hard 5s timeout. Always release what you acquire.
+  onShutdown(() => {
+    clearInterval(timer)
+    log.info(`startup '${id}': torn down`)
+  })
+}

package/templates/apps/api-durable/subscribers/orderChanges.subscribe.ts

@@ -0,0 +1,27 @@
+// `orderChanges` — a post-commit subscriber on the `orders` table.
+//
+// Fires AFTER commit (the row IS written), best-effort + fire-and-forget
+// (a throw logs and the next event still arrives; it can't back-pressure
+// the change stream). Use it for reactions that aren't part of the
+// write transaction — notify a fulfillment desk, mirror to a search
+// index, bump a metric. For crash-safe multi-step reactions, have the
+// subscriber start a workflow instead.
+//
+// `on: 'any'` matches insert / update / delete. `event.new` is present
+// on insert + update (null on delete); `event.old` on update + delete
+// (null on insert).
+
+import { defineSubscriber } from '@voltro/runtime'
+
+export default defineSubscriber({
+  table: 'orders',
+  on:    'any',
+  handler: async (event, ctx) => {
+    const row = (event.new ?? event.old) as { id?: string; status?: string } | null
+    ctx.log.info('order changed', {
+      op:     event.op,
+      id:     row?.id,
+      status: row?.status,
+    })
+  },
+})

package/templates/apps/api-durable/template.json

@@ -0,0 +1,6 @@
+{
+  "id": "api-durable",
+  "kind": "api",
+  "summary": "A cohesive order-fulfillment domain demonstrating the whole durable surface: a durable workflow (step / sleep / awaitSignal human-approval gate), an event trigger that starts it, a signal-injecting mutation, a nightly cron schedule, a table subscriber, a materialized aggregate, and a run-once startup hook.",
+  "tags": ["api", "durable", "workflow", "schedule", "subscriber", "aggregate", "startup", "events"]
+}

package/templates/apps/api-durable/tests/orders.place.test.ts

@@ -0,0 +1,91 @@
+// Unit tests with `@voltro/testing` — no database, no running server. Two
+// things get covered:
+//
+//   1. `orders.place` — the runnable primitive. `makeTestContext` hands the
+//      handler the SAME mixin-wrapped `ctx.store` it gets in production, so
+//      tenant auto-scoping + the `order_…` id injection behave exactly as at
+//      runtime.
+//   2. `orders.fulfill` — the workflow is descriptor-pinned. A real run PARKS
+//      on `awaitSignal('approval')` (a human-approval gate), so a plain
+//      `start()` never resolves in a unit test; a full run needs a signal
+//      (integration). Here we assert the wire contract (name / payload /
+//      success decode) and that the executor factory is wired.
+//
+// Run with `voltro test` (vitest).
+
+import { describe, it, expect } from 'vitest'
+import { Schema } from 'effect'
+import { makeTestContext, mockStore } from '@voltro/testing'
+import { database } from '../database/schema'   // registers orders / actors / tenants
+import placeOrder from '../mutations/orders.place.mutation.server'
+import { FulfillOrder } from '../workflows/order.fulfill.workflow'
+import buildExecute from '../workflows/order.fulfill.workflow.server'
+
+describe('orders.place', () => {
+  it('inserts an order, auto-stamped to the caller tenant', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'user_1', tenantId: 'acme' },
+      store:   mockStore({ orders: [] }),
+    })
+    const row = await placeOrder(
+      { tenantId: 'acme', customerName: 'Ada Lovelace', amountCents: 4200 },
+      ctx,
+    )
+
+    expect(row.status).toBe('placed')
+    expect(row.customerName).toBe('Ada Lovelace')
+    expect(row.amountCents).toBe(4200)
+    expect(row.tenantId).toBe('acme')      // tenant() stamped it from the subject
+    expect(row.id).toMatch(/^order_/)      // TypeID auto-injected
+  })
+
+  it('isolates tenants — t2 never sees t1 rows (REAL tenant scoping)', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'u1', tenantId: 't1' },
+      store:   mockStore({ orders: [] }),
+    })
+    await placeOrder({ tenantId: 't1', customerName: 'Grace', amountCents: 100 }, ctx)
+
+    // Re-scope the SAME store to a different tenant — the real WHERE filter
+    // hides t1's row from t2.
+    const seenByT2 = await ctx.withTenant('t2', (c) => c.store.query(database.orders.descriptor))
+    expect(seenByT2).toHaveLength(0)
+  })
+})
+
+describe('orders.fulfill (workflow descriptor)', () => {
+  it('declares the expected wire name', () => {
+    expect(FulfillOrder.name).toBe('orders.fulfill')
+  })
+
+  it('accepts a valid { orderId, tenantId } payload and rejects a malformed one', () => {
+    const decode = Schema.decodeUnknownSync(FulfillOrder.payloadSchema)
+    expect(decode({ orderId: 'order_1', tenantId: 'acme' })).toMatchObject({
+      orderId: 'order_1',
+      tenantId: 'acme',
+    })
+    expect(() => decode({ orderId: 'order_1' })).toThrow() // missing tenantId
+  })
+
+  it('declares a { orderId, outcome } success schema with a literal outcome', () => {
+    const decode = Schema.decodeUnknownSync(FulfillOrder.successSchema)
+    expect(decode({ orderId: 'order_1', outcome: 'shipped' })).toEqual({
+      orderId: 'order_1',
+      outcome: 'shipped',
+    })
+    expect(decode({ orderId: 'order_1', outcome: 'rejected' })).toEqual({
+      orderId: 'order_1',
+      outcome: 'rejected',
+    })
+    expect(() => decode({ orderId: 'order_1', outcome: 'delivered' })).toThrow() // not in the literal union
+  })
+
+  it('exposes an executor factory (ctx) => run — a real run needs an approval signal (integration)', () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'user_1', tenantId: 't1' },
+      store:   mockStore({ orders: [] }),
+    })
+    expect(typeof buildExecute).toBe('function')
+    expect(typeof buildExecute(ctx)).toBe('function')
+  })
+})

package/templates/apps/api-durable/triggers/order.placed.trigger.tsx

@@ -0,0 +1,21 @@
+// Event → workflow trigger. Auto-discovered (`*.trigger.tsx`); no
+// app.config wiring needed.
+//
+// When any handler emits `order.placed` (the `orders.place` mutation
+// does, post-commit), this trigger starts the `orders.fulfill`
+// workflow. The event payload IS the workflow payload here (both are
+// `{ orderId, tenantId }`), so no `payload` mapper is needed — pass one
+// when the shapes differ.
+//
+// `idempotencyKey` dedups deliveries: if the same event is re-delivered
+// (crash + replay), the matching key short-circuits the second start.
+
+import { defineEventTrigger } from '@voltro/runtime'
+
+export default defineEventTrigger<
+  { orderId: string; tenantId: string }
+>({
+  event:    'order.placed',
+  workflow: 'orders.fulfill',
+  idempotencyKey: (event) => `order.placed:${event.data.orderId}`,
+})

package/templates/apps/api-durable/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/apps/api-durable/workflows/order.fulfill.workflow.server.tsx

@@ -0,0 +1,103 @@
+// `orders.fulfill` — EXECUTOR (server-only).
+//
+// Durable order-fulfillment pipeline. The default export is a factory
+// `(ctx) => execute`; the CLI calls `workflow.toLayer(execute)` at boot
+// so the executor closes over the live `AppContext` (store, events, …).
+//
+// The flow, every step durable (replayed from its journaled result on a
+// crash/resume rather than re-run):
+//
+//   1. step 'reserve-stock' — flip the order to `reserved`.
+//   2. sleep                — a (short) durable delay; the wake time is
+//                             journaled in the engine. Bump to hours/days
+//                             for a real "hold before charging" window.
+//   3. awaitSignal 'approval' — PARK until a human sends the approval
+//                             signal (via the `orders.approve` mutation
+//                             or the dashboard "Send signal" button).
+//   4. step 'ship' / mark rejected — branch on the decision.
+//
+// `withCompensation` wraps the reserve step with saga-style rollback:
+// the finalizer runs only if the WHOLE workflow later fails, releasing
+// the reservation so a downstream failure doesn't strand held stock.
+
+import { step, sleep, awaitSignal, withCompensation } from '@voltro/workflow'
+import { Effect, Schema } from 'effect'
+import type { AppContext } from '@voltro/runtime'
+
+const Decision = Schema.Struct({ approved: Schema.Boolean })
+
+const buildExecute = (ctx: AppContext) =>
+  (payload: { orderId: string; tenantId: string }, _executionId: string) =>
+    Effect.gen(function* () {
+      const { orderId } = payload
+
+      // 1. Reserve stock. `withCompensation` registers an undo that runs
+      //    only if the workflow as a whole fails after this point.
+      yield* withCompensation(
+        step({
+          name:    'reserve-stock',
+          input:   { orderId },
+          success: Schema.Struct({ orderId: Schema.String }),
+          execute: Effect.tryPromise({
+            try:   async () => {
+              await ctx.store.update('orders', orderId, { status: 'reserved' })
+              return { orderId }
+            },
+            catch: (error) => error as never,
+          }),
+        }),
+        // Saga rollback: release the reservation on whole-workflow failure.
+        () =>
+          Effect.promise(() =>
+            ctx.store
+              .update('orders', orderId, { status: 'placed' })
+              .then(() => undefined),
+          ),
+      )
+
+      // 2. Durable delay. The wake is journaled — survives a restart.
+      yield* sleep({ name: 'settle-window', duration: '5 seconds' })
+
+      // 3. Human-approval gate. The run parks here until an external
+      //    caller sends a matching `approval` signal; the parsed payload
+      //    is journaled, so a post-signal replay returns it instantly.
+      const decision = yield* awaitSignal(ctx, {
+        name:   'approval',
+        schema: Decision,
+        // pollIntervalMs defaults to 200 (backoff → 5s); timeoutMs 24h.
+      })
+
+      if (!decision.approved) {
+        yield* step({
+          name:    'mark-rejected',
+          input:   { orderId },
+          success: Schema.Struct({ orderId: Schema.String }),
+          execute: Effect.tryPromise({
+            try:   async () => {
+              await ctx.store.update('orders', orderId, { status: 'rejected' })
+              return { orderId }
+            },
+            catch: (error) => error as never,
+          }),
+        })
+        return { orderId, outcome: 'rejected' as const }
+      }
+
+      // 4. Approved → ship.
+      yield* step({
+        name:    'ship',
+        input:   { orderId },
+        success: Schema.Struct({ orderId: Schema.String }),
+        execute: Effect.tryPromise({
+          try:   async () => {
+            await ctx.store.update('orders', orderId, { status: 'shipped' })
+            return { orderId }
+          },
+          catch: (error) => error as never,
+        }),
+      })
+
+      return { orderId, outcome: 'shipped' as const }
+    })
+
+export default buildExecute

package/templates/apps/api-durable/workflows/order.fulfill.workflow.tsx

@@ -0,0 +1,25 @@
+// `orders.fulfill` — DESCRIPTOR (browser-safe).
+//
+// Imports `workflow` from the `@voltro/workflow/define` subpath — the
+// browser-safe contract surface. The codegen value-imports this so the
+// web client can start the workflow over rpc; importing the executor's
+// server graph here would drag database/cluster into the browser bundle.
+
+import { workflow } from '@voltro/workflow/define'
+import { Schema } from 'effect'
+
+export const FulfillOrder = workflow({
+  name: 'orders.fulfill',
+  payload: {
+    orderId:  Schema.String,
+    tenantId: Schema.String,
+  },
+  success: Schema.Struct({
+    orderId: Schema.String,
+    outcome: Schema.Literal('shipped', 'rejected'),
+  }),
+  // Dedup concurrent starts for the same order — the `order.placed`
+  // trigger could (after a crash + replay) fan out twice; the same key
+  // collapses them to one run.
+  idempotencyKey: ({ orderId }) => `fulfill:${orderId}`,
+})

package/templates/apps/api-feature-flags/README.md

@@ -0,0 +1,63 @@
+# {{projectName}} / {{appName}}
+
+Voltro API scaffold (template: **api-feature-flags**) — feature flags with
+`@voltro/plugin-flags`: kill-switches, % rollout, targeting, and two ways to
+gate rpc calls.
+
+## Boot
+
+```bash
+pnpm install
+pnpm --filter @{{projectName}}/{{appName}} dev
+# → http://localhost:4000  (store: memory — zero infra)
+```
+
+## What this shows
+
+- **Flags as code** — declared in `app.config.ts`: a bare boolean is a
+  kill-switch (`newEditor: true`, `betaExport: false`); a rich definition adds
+  a deterministic `% rollout` (`gradualRollout: { rollout: 25 }`) and
+  OR-of-rules `targeting` (`proDashboard: { targeting: [{ metadata: { plan:
+  'pro' } }] }`).
+- **Two ways to gate** —
+  - **Declarative** (`gatedBy`): `notes.export` is mapped to `betaExport`. The
+    framework fails typed `FlagDisabled` BEFORE the handler runs when the flag
+    is off — no code in the handler.
+  - **In-handler** (`requireFlag`): `notes.create` calls
+    `requireFlag(ctx, 'newEditor')`, the Effect-native guard (same shape as
+    `requireScope` / `requireEntitlement`).
+- **Typed on the client** — both paths fail `FlagDisabled`, declared on the
+  procedure's `error:`, so the browser decodes it typed.
+
+## Try it
+
+```bash
+# newEditor is ON → requireFlag passes → note created:
+curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
+  -d '{"tag":"notes.create","input":{"tenantId":"acme","title":"Flagged note","body":"hi"}}'
+
+# betaExport is OFF → gatedBy blocks before the handler → typed FlagDisabled:
+curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
+  -d '{"tag":"notes.export","input":{}}'
+# → { ok:false, error:{ _tag:"FlagDisabled", flag:"betaExport" } }
+```
+
+Flip `betaExport: true` in `app.config.ts` (or toggle it at runtime with
+`store: 'postgres'`) and `notes.export` starts succeeding — no code change.
+
+## On the web side
+
+```tsx
+import { useFlag } from '@voltro/plugin-flags/web'
+const showBeta = useFlag('betaExport')      // evaluated for the signed-in subject
+{showBeta && <BetaExportButton />}
+```
+
+`useFlag` reads the synthesized `flags.evaluate` query, so client UI gating
+uses the SAME evaluation (targeting + rollout) as the server guards.
+
+## Runtime toggles
+
+Set `store: 'postgres'` to overlay runtime-toggleable flags (in
+`_voltro_feature_flags`) on the code baseline — flip a kill-switch without a
+deploy. The dashboard ships a **Flags** panel for exactly this.

package/templates/apps/api-feature-flags/actions/notes.export.action.server.ts

@@ -0,0 +1,11 @@
+import type { AppContext } from '@voltro/runtime'
+import { database } from '../database/schema'
+
+// Runs ONLY when the `betaExport` gate passes (see app.config.ts gatedBy).
+// The body itself is flag-agnostic — just counts the tenant's notes.
+const execute = async (_input: Record<string, never>, ctx: AppContext) => {
+  const rows = await ctx.store.query(database.notes.descriptor)
+  return { exported: rows.length }
+}
+
+export default execute

package/templates/apps/api-feature-flags/actions/notes.export.action.ts

@@ -0,0 +1,18 @@
+// "Export all notes" — gated DECLARATIVELY. There's no flag check in the
+// handler: the `gatedBy: { 'notes.export': 'betaExport' }` map in app.config.ts
+// makes the framework fail `FlagDisabled` BEFORE this handler runs whenever
+// `betaExport` is off. Flip the flag (config, or a postgres-store toggle) and
+// the same call starts succeeding — no code change.
+//
+// Declaring `error: FlagDisabled` surfaces the gate's rejection typed.
+
+import { defineAction } from '@voltro/protocol'
+import { FlagDisabled } from '@voltro/plugin-flags/errors'
+import { Schema } from 'effect'
+
+export const exportNotes = defineAction({
+  name: 'notes.export',
+  input: Schema.Struct({}),
+  output: Schema.Struct({ exported: Schema.Number }),
+  error: FlagDisabled,
+})