@voltro/cli 0.1.0

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

@@ -0,0 +1,128 @@
+# templates.custom
+
+> Add a template the CLI can scaffold from — a directory under voltro-templates/apps/ with a manifest and the files to copy.
+
+
+
+---
+
+<!-- source: en/templates/custom.md -->
+## Roll your own
+
+_Add a template the CLI can scaffold from — a directory under voltro-templates/apps/ with a manifest and the files to copy._
+
+Templates aren't magic. Each one is a directory under `voltro-templates/apps/<id>/` with a `template.json` manifest plus the files to scaffold. Drop a new directory and the CLI walks it on the next `voltro list-templates`.
+
+The directory NAME is the template id you pass to `--api` / `--web` / `--template`. The id must match `^[a-zA-Z][a-zA-Z0-9-]*$` — kebab-lowercase, no `@` or `/`.
+
+## Minimum viable template
+
+```text
+my-template/
+├── template.json
+├── package.json
+├── app.config.ts
+├── tsconfig.json
+└── src/
+    └── pages/
+        └── index.tsx
+```
+
+The `template.json` manifest (`id`, `kind`, `summary`, optional `tags`):
+
+```json
+{
+  "id":      "acme-internal-tool",
+  "kind":    "web",
+  "summary": "Internal tool starter — our team's auth + table conventions baked in.",
+  "tags":    ["internal", "tool"]
+}
+```
+
+`kind` is `'api'` or `'web'` — the CLI rejects an api template passed to `--web` (and vice-versa). `id` must equal the directory name, or the loader skips the dir.
+
+Now `voltro list-templates` includes it, and `voltro create-project x --web=acme-internal-tool` (web) or `--api=acme-internal-tool` (api) scaffolds it.
+
+## Token substitution
+
+Any file's CONTENT can contain placeholders. The scaffolder rewrites them from the app + project names you pass; the kebab form is what's persisted (folders, `package.json` `name`), camel/Pascal/snake are derived per use:
+
+| Token | Form | Example (`appName=my-app`, `projectName=acme-cms`) |
+|---|---|---|
+| `{{appName}}` | kebab | `my-app` |
+| `{{projectName}}` | kebab | `acme-cms` |
+| `{{appNameCamel}}` | camelCase | `myApp` |
+| `{{projectNameCamel}}` | camelCase | `acmeCms` |
+| `{{appNamePascal}}` | PascalCase | `MyApp` |
+| `{{projectNamePascal}}` | PascalCase | `AcmeCms` |
+| `{{capAppName}}` | PascalCase alias of `appNamePascal` | `MyApp` |
+| `{{capProjectName}}` | PascalCase alias of `projectNamePascal` | `AcmeCms` |
+| `{{appNameSnake}}` | snake_case (SQL / bucket names) | `my_app` |
+| `{{projectNameSnake}}` | snake_case | `acme_cms` |
+| `{{port}}` | the port allocated from the project's `portRange` (web apps) | `5191` |
+
+Example `app.config.ts`:
+
+```ts
+export default {
+  type: 'web' as const,
+  name: '{{capProjectName}}{{capAppName}}',
+  port: {{port}},
+}
+```
+
+Substitution is global across all files (content only — file NAMES aren't templated). The scaffolder also rewrites `package.json`'s `name` field on the fly so the scaffolded app gets a real pnpm-workspace name even if the template forgot to template it.
+
+## Where templates live
+
+The CLI loads templates from two places, in order:
+
+1. **Source mode** (dev): walks up from the CLI's own dir looking for a sibling `voltro-templates/apps/`. This is the source of truth in this repo.
+2. **Bundled fallback** (post-publish): a snapshot of `voltro-templates/apps/` shipped inside the CLI package.
+
+To add a template for the framework itself, drop a directory under `voltro-templates/apps/<id>/`. There is no env-var path override and no npm-package fetch — the loader is hardcoded to those two locations.
+
+## What's in a template
+
+| File | Purpose |
+|---|---|
+| `template.json` | Manifest with `id`, `kind`, `summary`, optional `tags`. Stripped — never lands in the scaffolded app. |
+| `package.json` | The scaffolded app's deps + scripts. Its `name` is rewritten on scaffold. |
+| `app.config.ts` | The app's framework config (port, name, plugins). |
+| `tsconfig.json` | TypeScript config. Usually extends a workspace base. |
+| `README.md` | Human-readable description; copied verbatim (with tokens substituted). |
+| everything else | Copied into the target app dir with token substitution. |
+
+The scaffolder copies every file except `template.json` (and obvious build artefacts — `node_modules/`, `dist/`, `.framework/`). No "templating engine" beyond the token-replacement walker.
+
+## Tips for good templates
+
+- **Start small.** A short index page + the right deps beats a 2000-line "everything imaginable".
+- **Inline comments explain the WHY.** Scaffolded code is read by the next dev. The shipped templates' comments are part of the value.
+- **Use the kit primitives.** Don't re-invent a Button when `@voltro/ui-shadcn` ships one.
+- **Leave room.** Show the pattern; don't fill every file with example data. The user will replace it.
+- **Test by scaffolding.** Before relying on it, `voltro create-project --web=my-template` against a clean directory. Boot it. Refine.
+
+## The framework's own templates
+
+Read `voltro-templates/apps/*/` for reference. Every shipped template's source is the best example of "what a good template looks like" — short, opinionated, idiomatic Voltro.
+
+## Listing templates
+
+```bash
+voltro list-templates
+voltro list-templates --json
+```
+
+For programmatic use (build + publish a catalogue page):
+
+```ts
+import { listTemplates } from '@voltro/cli'
+const all = await listTemplates()
+// [{ id, kind, summary, tags, path }, …]
+```
+
+## See also
+
+- [Scaffolding CLI](/docs/cli/scaffolding) — the consumer of templates.
+- [App templates overview](/docs/templates/overview) — the shipped catalogue.

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

@@ -0,0 +1,122 @@
+# Templates
+
+> Thirty-four dogfooded starter templates ship with the framework — twenty backend shapes, thirteen frontend shapes, and a serverless function library. Scaffold any of them with one CLI call.
+
+
+
+---
+
+<!-- source: en/templates/overview.md -->
+## Overview
+
+_Thirty-four dogfooded starter templates ship with the framework — twenty backend shapes, thirteen frontend shapes, and a serverless function library. Scaffold any of them with one CLI call._
+
+Voltro ships **thirty-four** starter templates across the **three kinds** you actually deploy: **twenty** backends (`api-*`), **thirteen** frontends (`frontend-*` plus `changelog`), and **one** serverless library (`edge-functions`). Each is a small, opinionated, dogfooded reference you scaffold once and then own — no update channel, no lock-in.
+
+The CLI loads templates by walking `voltro-templates/apps/<id>/`; the directory name IS the template id you pass to `--api` / `--web` / `--template`. Run `voltro list-templates` to see them live.
+
+```bash
+# A project with a backend + a blank frontend:
+voltro create-project acme --api=api-backend --web=frontend-blank
+
+# Add another app to an existing project later:
+voltro add-app marketing --template=frontend-landing --to acme
+```
+
+Each app gets its own port from the project's `portRange`, wired through `pnpm dev`, ready to edit.
+
+## Backend templates (`--api=<id>`)
+
+The four `api-backend*` shapes share the same minimal `notes` domain and differ only in the plugin/store wired on top. The other three are **feature showcases** — a cohesive domain that exercises one whole slice of the framework end to end.
+
+| Template | Best for |
+|---|---|
+| [`api-backend`](/docs/templates/api-backend) | The minimal Voltro backend: `app.config.ts` + schema + one streaming query + one tenant-guarded mutation. Start here. |
+| [`api-backend-mail`](/docs/templates/api-backend-mail) | `api-backend` + `@voltro/plugin-mail` and a React-Email welcome template you preview/send from the dashboard. |
+| [`api-backend-storage`](/docs/templates/api-backend-storage) | `api-backend` + `@voltro/plugin-storage` — public (CDN-direct) and private (policy + grants) objects with upload examples. |
+| [`api-backend-mariadb`](/docs/templates/api-backend-mariadb) | MariaDB-backed: binlog CDC real-time across replicas + file storage. The dogfooded shape for K8s multi-replica apps. |
+| [`api-durable`](/docs/templates/api-durable) | The whole **durable + reactive** surface in one order-fulfillment domain: a workflow (`step` / `sleep` / `awaitSignal` approval gate), an event trigger that starts it, a signal-injecting mutation, a cron schedule, a table subscriber, a materialized aggregate, and a run-once startup hook. |
+| [`api-ai`](/docs/templates/api-ai) | A **RAG support agent**: a `vectorEmbedding()` docs table, a search tool, a real `defineAgent` / `defineAgentExecutor` model loop, and a `generateObject` action. Boots zero-infra; needs an AI key only to *run* the agent. |
+| [`api-data-advanced`](/docs/templates/api-data-advanced) | The **advanced schema DSL**: the `*.entity.ts` / `*.relations.ts` split with eager `.with()`, full-text search, `dbEnum`, array / generated / encrypted columns, and declarative query caching — a small authors + books catalog. |
+| [`api-kv`](/docs/templates/api-kv) | **Durable `ctx.kv`** on an external-event-sync domain: a sync cursor you can't recompute plus TTL-bounded idempotency markers, contrasted with `ctx.store` (the rows) and `ctx.cache`. Exercises the full KV surface (getOrElse / has / set+TTL / list / delete). |
+| [`api-auth`](/docs/templates/api-auth) | **Real user auth** — `@voltro/plugin-auth` wired turnkey: password sign-up/in/out over HttpOnly session cookies + a strategy that resolves the session to a typed `Subject`. Zero-infra boot. |
+| [`api-rest`](/docs/templates/api-rest) | **Public REST + OpenAPI** — `defineRestRoute` endpoints (query/path/body, scope guards, `Idempotency-Key`) + `@voltro/plugin-openapi` (Swagger UI at `/docs`, generated from the descriptors). Zero-infra boot. |
+| [`api-saas`](/docs/templates/api-saas) | **The SaaS plugin bundle** — billing entitlements (a quota gate), in-app + console notifications, analytics events, and live presence, wired turnkey. One `projects.create` exercises billing + analytics + notifications together. |
+| [`api-observability`](/docs/templates/api-observability) | **Metrics + errors + tests** — `@voltro/plugin-prometheus` (`GET /metrics` + a custom counter), `@voltro/plugin-sentry` (inert without a DSN), tracing, and a `@voltro/testing` unit test. Zero-infra boot. |
+| [`api-webhooks`](/docs/templates/api-webhooks) | **First-class webhooks** — a signature-verified incoming `*.webhook.tsx` receiver (rejects forged traffic before your handler) + an outgoing `defineOutgoingEvent` a mutation emits via a durable signed delivery workflow. Zero-infra boot. |
+| [`api-search`](/docs/templates/api-search) | **Full-text search in sync** — `@voltro/plugin-search` mirrors every table write into an index via the post-commit change tap; the synthesized `search.query` rpc returns tenant-scoped hits. Memory backend (zero infra); one line to Typesense/Meilisearch/Algolia. |
+| [`api-feature-flags`](/docs/templates/api-feature-flags) | **Feature flags as code** — `@voltro/plugin-flags`: kill-switch / %-rollout / targeting, a declarative `gatedBy` map + an in-handler `requireFlag` guard (both fail typed `FlagDisabled`), `useFlag()` on the web. Memory store. |
+| [`api-ratelimit`](/docs/templates/api-ratelimit) | **Per-endpoint rate limiting** — `@voltro/plugin-ratelimit` intercepts rpc: a default + rules (sliding-window / token-bucket, by subject/tenant/…), typed `RateLimited` auto-merged into the error union. Memory store. |
+| [`api-rbac`](/docs/templates/api-rbac) | **Role → scope access control** — `@voltro/plugin-rbac`: a role map, an interceptor resolving roles to scopes, and an in-handler `permission(ctx, 'notes:write')` guard (typed `Forbidden`). `admin:full` bypasses. Config-only. |
+| [`api-moderation`](/docs/templates/api-moderation) | **Pre-commit content moderation** — `@voltro/plugin-moderation` checks fields before the handler: a `block` rule rejects with typed `ContentRejected`, a `flag` rule queues for review. keywordProvider / aiProvider. |
+| [`api-versioning`](/docs/templates/api-versioning) | **Row history + time-travel** — `@voltro/plugin-versioning` snapshots every write via the change tap; `rowHistory()` (every version) + `rowAsOf()` (value at a past instant), read through handlers. Memory store. |
+| [`api-backend-deactivation`](/docs/templates/api-backend-deactivation) | **The `deactivation()` mixin** — lock a user out (`deactivatedAt`) while the row stays VISIBLE/queryable — the deliberate opposite of `softDelete()`'s hide+anonymise. Pure schema. |
+| [`api-governance`](/docs/templates/api-governance) | **Field encryption + GDPR + consent + retention** — `@voltro/plugin-governance`: AES-256-GCM `.encrypted()` columns (plaintext to handlers, ciphertext at rest), admin-gated `governance.export`/`erase`, a consent ledger, retention sweeps. |
+
+All twenty are `kind: 'api'`.
+
+## Frontend templates (`--web=<id>`)
+
+Thirteen web shapes spanning every render mode — `static`, `spa`, `ssr`, `isr`, selective `islands` hydration — plus the reactive fullstack loop.
+
+**Every frontend template is bilingual (en/de) out of the box**, with the i18n strategy matched to its render mode: the hydrated/SSR shells use cookie i18n (`<LocaleSwitcher>`), the static/islands sites use URL-prefix i18n (`/de/…`, one pre-rendered HTML file per locale). `frontend-i18n` remains the dedicated URL-prefix reference. See [URL strategies](/docs/i18n/url-strategies) for why render mode decides.
+
+| Template | Render mode | Best for |
+|---|---|---|
+| [`frontend-blank`](/docs/templates/blank) | — | Empty React + Vite shell with a layout and an index page. Start here for any custom UI. |
+| [`frontend-app`](/docs/templates/app) | `full` · reactive | **The reactive end-to-end loop** — a web frontend WIRED to an api (`useSubscription` + `useMutation` + auto-optimistic). The only fullstack template; pairs with `api-backend`. |
+| [`frontend-dashboard`](/docs/templates/dashboard) | `static` + `ssr` | **Auth-gated app shell** — a silent `(marketing)` route group + a `/dashboard` area gated by a nested layout loader that `RedirectError`s to `/login`. Scoped error/loading/not-found. No backend. |
+| [`frontend-admin`](/docs/templates/admin) | `ssr` · reactive | **Auto-admin back-office** — discovers your api's entities at runtime (capability map) and renders a live, permission-gated `<DataTable>` + `<AutoForm>` per entity, with provenance + undo. Editable template code; pairs with any api. |
+| [`frontend-landing`](/docs/templates/landing) | `static` · `islands` | Marketing landing — hero, features grid, CTA. Zero JS by default; flip `interactive: 'islands'` for interactive pieces. |
+| [`frontend-docs`](/docs/templates/docs) | `static` (catch-all SSG) | Documentation site — catch-all `docs/[...slug].tsx`, per-section layout, `getStaticPaths` so every page pre-renders at build. |
+| [`frontend-i18n`](/docs/templates/i18n) | `static` · per-locale SSG | **Bilingual (en/de) URL-prefix i18n** — type-checked catalogs, `[locale]` mirror pages, per-locale `<title>`. Each language is its own crawlable URL. |
+| [`changelog`](/docs/templates/changelog) | `static` | Changelog / release-notes — MDX releases rendered to a list + per-release pages (highlighted code) + an RSS feed, powered by `@voltro/changelog`. |
+| [`frontend-static-blog`](/docs/templates/static-blog) | `static` + `islands` | **SSG from a content source**: dynamic `[slug]` routes pre-rendered via `getStaticPaths`, per-post `meta` from loader data, and ONE island (reading-progress bar) showing selective hydration. |
+| [`frontend-spa`](/docs/templates/spa) | `spa` | A **pure client-rendered** tool — state lives in the browser (`localStorage`), so there's nothing to SSR. Where a single-page app is the right call. |
+| [`frontend-ssr`](/docs/templates/ssr) | `ssr` + `isr` | **Server-rendered pages**: a per-request SSR page (`useServerRequest()` for cookies/headers) + ISR pages (`revalidate`, `staleWhileRevalidate`, tenant-aware caching). Needs a runtime, not a CDN. |
+| [`frontend-ssr-api`](/docs/templates/ssr-api) | `ssr` · fed by api | **SSR from your backend** — an `ssr` loader calls `query('notes.list', {})` over the sibling api's POST /rpc, so real rows are in the first paint + `<title>`; `useSubscription` upgrades to live. Pairs with `api-backend`. |
+| [`frontend-contact`](/docs/templates/contact) | `static` + serverless | **Static page + a serverless email form** — the headline "static frontend, serverless backend" combo. The page ships to a CDN; the function scales to zero. |
+
+All thirteen are `kind: 'web'`. The CLI rejects an api template passed to `--web` (and vice-versa) on a kind mismatch.
+
+## Serverless template (`--template=<id>` via `add-app`)
+
+| Template | Best for |
+|---|---|
+| [`edge-functions`](/docs/templates/edge-functions) | A **library of `*.serverless.ts` functions** covering the range of edge work — pure compute, request-header/geo, outbound HTTP (fire-and-forget + fetch-and-transform), Web Crypto HMAC verify, an LLM call, and status-controlled errors. Run with `voltro serverless dev`; ship to node / Cloudflare / Scaleway. No long-running server, no port. |
+
+`kind: 'serverless'` — added to a project with `voltro add-app <name> --template=edge-functions`.
+
+## Static + serverless combo
+
+The most common no-always-on-server shape: **a static page on a CDN + a serverless function for the one dynamic bit.** `frontend-contact` ships it whole — a static page whose island form POSTs to a bundled `*.serverless.ts` that sends mail. Or add `edge-functions` to any static web template and wire the page to whichever function it needs. The function's local dev server sends CORS headers (same as the edge hosts), so the cross-origin form works out of the box.
+
+## Baselines — the deploy layer
+
+A **baseline** is orthogonal to the app template: it's the deploy/ops files that say how to run + ship the stack. Pick one at create time with `--baseline=<id>`, or switch later with `voltro baseline set <id>`. Four ship:
+
+| Baseline | What it gives you | When to pick it |
+|---|---|---|
+| `bare` | `.env.example` + a sample systemd unit. No Docker, no Helm — you bring your own Postgres. | Solo dev, prototyping, environments where Docker is unavailable. |
+| `compose` | `docker/{api,web}.Dockerfile` + `docker-compose.yml` (Postgres) + dev (HMR) and prod (built images) variants. | Teams without k8s, VPS/self-host, reproducible onboarding. |
+| `compose-mariadb` | Like `compose` but MariaDB (binlog CDC, ROW) + MinIO object storage. The local mirror of the `helm` MariaDB shape. | Apps targeting MariaDB + CDC + file storage locally. |
+| `helm` | `charts/voltro-app/` Helm chart, per-env values (`dev`/`staging`/`prod`), Deployment + Service + Ingress, Postgres StatefulSet OR external MariaDB via a `db.dialect` switch. | k8s shops, GitOps (ArgoCD / Flux), multi-cluster prod. |
+
+```bash
+# Pick the app templates AND the baseline at once:
+voltro create-project acme --api=api-backend --web=frontend-blank --baseline=compose
+
+# Wire the Redis cache backend while scaffolding (injects the service into the baseline + .env):
+voltro create-project acme --api=api-backend --web=frontend-blank --baseline=compose --cache=redis
+
+# Switch the baseline later (destructive but backed up):
+voltro baseline set helm
+```
+
+Without `--baseline`, the interactive prompt lists the ids; press Enter to skip and add one later. Baseline files apply at the **workspace root** (where `pnpm-workspace.yaml` lives), not inside `apps/<project>/`.
+
+## Where to read next
+
+- [App templates reference](/docs/reference/templates) — the full catalogue table, by kind, with combos.
+- [Roll your own template](/docs/templates/custom) — add a template the CLI scaffolds from.
+- [Scaffolding CLI](/docs/cli/scaffolding) — the commands that consume templates.

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

@@ -0,0 +1,315 @@
+# templates.serverless
+
+> A library of standalone *.serverless.ts functions — pure compute, request-header/geo, outbound HTTP, Web Crypto HMAC, an LLM call, status-controlled errors. Run with voltro serverless; ship to node / Cloudflare / Scaleway. No server, no port.
+
+
+
+---
+
+<!-- source: en/templates/edge-functions.md -->
+## Edge functions
+
+_A library of standalone *.serverless.ts functions — pure compute, request-header/geo, outbound HTTP, Web Crypto HMAC, an LLM call, status-controlled errors. Run with voltro serverless; ship to node / Cloudflare / Scaleway. No server, no port._
+
+A standalone library of `*.serverless.ts` functions that walks the RANGE of what an edge function actually does: pure compute, reading the request's geo header, outbound HTTP (fire-and-forget AND fetch-and-transform), a Web Crypto HMAC verify, a one-shot LLM call, and status-controlled errors. There is NO long-running api here, no `voltro dev`, no port — each function is bundled + deployed on its own with `voltro serverless`, and scales to zero between requests. Every handler is **edge-safe** (no `node:*`), so the SAME file runs on Cloudflare Workers, Scaleway Functions, and your own node box. Template id: **`edge-functions`**.
+
+## Scaffold
+
+`edge-functions` is `kind: 'serverless'` — added to an existing project with `add-app`, not `create-project`:
+
+```bash
+voltro add-app fns --template=edge-functions --to acme
+```
+
+## What ships
+
+```text
+apps/acme/fns/                          # dir named by the app, not the template
+├── package.json                        # scripts: list, build, serve, typecheck
+├── tsconfig.json
+├── README.md
+└── functions/
+    ├── health.serverless.ts            # GET · pure Effect.sync diagnostic; ctx.env
+    ├── shareLink.serverless.ts         # POST · pure compute; runtime hints (memory/timeout/region)
+    ├── geoGreeting.serverless.ts       # GET · reads ctx.request.headers (edge geo)
+    ├── slackNotify.serverless.ts       # POST · ctx.waitUntil — background work after the response
+    ├── currencyConvert.serverless.ts   # POST · outbound HTTP via HttpClient; fetch + transform JSON
+    ├── verifySignature.serverless.ts   # POST · Web Crypto HMAC; ServerlessHttpError 401
+    ├── aiComplete.serverless.ts        # POST · an LLM call needing a secret (ctx.env); 502 mapping
+    └── resolveLink.serverless.ts       # GET · a lookup; 404 via ServerlessHttpError
+```
+
+There is no `app.config.ts`, no `database/`, no `queries/` — a serverless library is not an api. Each function is its own deploy artifact, discovered by filename (`*.serverless.ts`), bundled standalone. The app depends only on `@voltro/serverless` + `@voltro/cli` + `@effect/platform` (for `HttpClient`) + `effect`.
+
+## The shape — `defineServerless({...})`
+
+Every function default-exports one `defineServerless({...})` descriptor. The minimal shape is a `name`, an HTTP `method`, an `input`/`output` `effect/Schema`, and a `handler`. The `input` Schema is load-bearing: a malformed request becomes a typed `400` BEFORE your handler runs — you never hand-parse `JSON.parse(body)` and trust it. The handler receives `(input, ctx)` and returns an `Effect` (or a plain value via `Effect.sync`); `ctx` carries `env`, `request`, and `waitUntil`.
+
+```ts
+// functions/health.serverless.ts — the simplest function: a GET diagnostic
+import { Effect, Schema } from 'effect'
+import { defineServerless } from '@voltro/serverless'
+
+export default defineServerless({
+  name: 'health',
+  method: 'GET',
+  input: Schema.Struct({}),
+  output: Schema.Struct({
+    status: Schema.Literal('ok'),
+    region: Schema.String,
+    now: Schema.String,
+  }),
+  handler: (_input, ctx) =>
+    Effect.sync(() => ({
+      status: 'ok' as const,
+      // The provider injects region into the env (Scaleway SCW_REGION, your own
+      // VOLTRO_REGION on a node host). Cloudflare is global → 'edge'.
+      region: ctx.env.VOLTRO_REGION ?? ctx.env.SCW_REGION ?? ctx.env.AWS_REGION ?? 'edge',
+      now: new Date().toISOString(),
+    })),
+})
+```
+
+`ctx.env` is how a function reads config and secrets — there is no `defineEnv` here, the host injects the env at deploy time. `health` is pure (`Effect.sync`, no I/O), the cheapest thing an edge function can be.
+
+## Pure compute + runtime hints
+
+`shareLink` is still pure compute (`Effect.sync`, no I/O) but adds a `runtime` block — the memory/timeout/region hints the deploy targets honour. Pure-compute functions are trivially edge-safe and the fastest to cold-start:
+
+```ts
+// functions/shareLink.serverless.ts — id → short-lived share URL
+export default defineServerless({
+  name: 'share-link',
+  method: 'POST',
+  input: Schema.Struct({
+    resourceId: Schema.String.pipe(Schema.minLength(1)),
+    ttlMinutes: Schema.Number.pipe(Schema.greaterThan(0)),
+  }),
+  output: Schema.Struct({ url: Schema.String, expiresAt: Schema.Number }),
+  runtime: { memoryMb: 128, timeoutSeconds: 10, region: 'fr-par' },
+  handler: ({ resourceId, ttlMinutes }, ctx) =>
+    Effect.sync(() => {
+      const base = ctx.env.SHARE_BASE_URL ?? 'https://share.example'
+      const expiresAt = Date.now() + ttlMinutes * 60_000
+      return { url: `${base}/s/${encodeURIComponent(resourceId)}?exp=${expiresAt}`, expiresAt }
+    }),
+})
+```
+
+## Reading the request — edge geo
+
+`geoGreeting` reaches past the decoded `input` to the raw request via `ctx.request.headers` — here the geo header the edge host injects. Being close to the user is the whole point of running at the edge, and this reacts to where they are:
+
+```ts
+// functions/geoGreeting.serverless.ts — a localized greeting from the caller's country
+handler: ({ name }, ctx) =>
+  Effect.sync(() => {
+    // Cloudflare sets `cf-ipcountry`; other proxies use varied headers. We
+    // read whatever the host injected — the function code stays the same.
+    const country = (
+      ctx.request.headers.get('cf-ipcountry') ??
+      ctx.request.headers.get('x-vercel-ip-country') ??
+      ctx.request.headers.get('x-forwarded-country') ??
+      'XX'
+    ).toUpperCase()
+    const hello = HELLO[country] ?? 'Hello'
+    return { greeting: `${hello}, ${name ?? 'there'}!`, country }
+  }),
+```
+
+## Outbound HTTP — two patterns
+
+**Fire-and-forget** — `slackNotify` schedules delivery that OUTLIVES the response with `ctx.waitUntil(...)`. The caller gets `{ queued: true }` immediately; the actual POST runs in the background (on Cloudflare via the real `ExecutionContext.waitUntil`, best-effort elsewhere). A detached background POST needs no `HttpClient` features, so it uses the global `fetch`:
+
+```ts
+// functions/slackNotify.serverless.ts
+handler: ({ text }, ctx) =>
+  Effect.gen(function* () {
+    const webhook = ctx.env.SLACK_WEBHOOK_URL
+    if (!webhook) {
+      return yield* Effect.fail(
+        new ServerlessHttpError({ status: 503, message: 'slack-not-configured', detail: 'Set SLACK_WEBHOOK_URL.' }),
+      )
+    }
+    // Schedule the delivery in the background and respond NOW.
+    ctx.waitUntil(
+      fetch(webhook, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ text }),
+      }).catch(() => {
+        /* best-effort — a failed notification must not fail the request */
+      }),
+    )
+    return { queued: true }
+  }),
+```
+
+**Fetch-and-transform** — `currencyConvert` calls a third-party API with the framework-provided `HttpClient`, reads the JSON response (`yield* response.json`), transforms it, and maps an unanswerable upstream to a typed `422`. It hits a public, no-key FX endpoint so it runs out of the box:
+
+```ts
+// functions/currencyConvert.serverless.ts
+import { HttpClient, HttpClientRequest } from '@effect/platform'
+
+handler: ({ from, to, amount }, _ctx) =>
+  Effect.gen(function* () {
+    const base = from.toUpperCase()
+    const quote = to.toUpperCase()
+    const http = yield* HttpClient.HttpClient
+    const response = yield* http.execute(HttpClientRequest.get(`https://open.er-api.com/v6/latest/${base}`))
+    const body = (yield* response.json) as { rates?: Record<string, number> }
+    const rate = body.rates?.[quote]
+    if (typeof rate !== 'number') {
+      return yield* Effect.fail(
+        new ServerlessHttpError({ status: 422, message: 'unknown-currency', detail: `no rate ${base}->${quote}` }),
+      )
+    }
+    return { from: base, to: quote, amount, rate, result: Math.round(amount * rate * 100) / 100 }
+  }),
+```
+
+## Web Crypto — HMAC verify
+
+`verifySignature` uses the Web Crypto API (`crypto.subtle`) — available on every serverless host (Workers, Scaleway node, your own node) without ANY import — wrapped in `Effect.promise`. There's no `node:crypto` here precisely so the Cloudflare target keeps working. A mismatch is a `401` via `ServerlessHttpError`:
+
+```ts
+// functions/verifySignature.serverless.ts — HMAC-SHA256 verify
+const hmacHex = async (secret: string, payload: string): Promise<string> => {
+  const enc = new TextEncoder()
+  const key = await crypto.subtle.importKey('raw', enc.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign'])
+  return toHex(await crypto.subtle.sign('HMAC', key, enc.encode(payload)))
+}
+
+handler: ({ payload, signature }, ctx) =>
+  Effect.gen(function* () {
+    const secret = ctx.env.SIGNING_SECRET
+    if (!secret) {
+      return yield* Effect.fail(
+        new ServerlessHttpError({ status: 503, message: 'signing-not-configured', detail: 'Set SIGNING_SECRET.' }),
+      )
+    }
+    const expected = yield* Effect.promise(() => hmacHex(secret, payload))
+    if (!safeEqual(expected, signature.toLowerCase())) {
+      return yield* Effect.fail(new ServerlessHttpError({ status: 401, message: 'invalid-signature' }))
+    }
+    return { valid: true as const }
+  }),
+```
+
+## An LLM call needing a secret
+
+`aiComplete` calls a third-party API that needs a SECRET — the key lives in `ctx.env`, never in the bundle. It reads the JSON response and maps an upstream failure to a `502`. It uses the OpenAI chat-completions shape but points at any compatible endpoint via `OPENAI_BASE_URL`:
+
+```ts
+// functions/aiComplete.serverless.ts — one-shot LLM completion at the edge
+handler: ({ prompt, system }, ctx) =>
+  Effect.gen(function* () {
+    const apiKey = ctx.env.OPENAI_API_KEY
+    if (!apiKey) {
+      return yield* Effect.fail(
+        new ServerlessHttpError({ status: 503, message: 'ai-not-configured', detail: 'Set OPENAI_API_KEY.' }),
+      )
+    }
+    const baseUrl = ctx.env.OPENAI_BASE_URL ?? 'https://api.openai.com'
+    const model = ctx.env.OPENAI_MODEL ?? 'gpt-4o-mini'
+
+    const http = yield* HttpClient.HttpClient
+    const request = HttpClientRequest.post(`${baseUrl}/v1/chat/completions`).pipe(
+      HttpClientRequest.setHeader('authorization', `Bearer ${apiKey}`),
+      HttpClientRequest.bodyUnsafeJson({
+        model,
+        max_tokens: 400,
+        messages: [
+          ...(system ? [{ role: 'system', content: system }] : []),
+          { role: 'user', content: prompt },
+        ],
+      }),
+    )
+
+    const response = yield* http.execute(request)
+    if (response.status >= 400) {
+      const detail = yield* response.text
+      return yield* Effect.fail(new ServerlessHttpError({ status: 502, message: 'ai-call-failed', detail }))
+    }
+    const body = (yield* response.json) as { choices?: ReadonlyArray<{ message?: { content?: string } }> }
+    return { text: body.choices?.[0]?.message?.content ?? '' }
+  }),
+```
+
+## Status-controlled errors — `ServerlessHttpError`
+
+`ServerlessHttpError({ status, message, detail? })` is how a handler controls the HTTP status the caller sees — the throughline of the library. `resolveLink` (the read side of a link shortener) returns a `404` for an unknown code; the same mechanism produces `401` (bad signature), `422` (no FX rate), `502` (upstream LLM failure), and `503` (a secret not wired). Without it, an `Effect.fail` would surface as a generic `500`:
+
+```ts
+// functions/resolveLink.serverless.ts — short code → destination URL
+handler: ({ code }, _ctx) =>
+  Effect.gen(function* () {
+    const url = LINKS[code.toLowerCase()]
+    if (!url) {
+      return yield* Effect.fail(new ServerlessHttpError({ status: 404, message: 'unknown-code', detail: code }))
+    }
+    return { code, url }
+  }),
+```
+
+## Run locally
+
+The package scripts are the serverless workflow — there is no `voltro dev`:
+
+```bash
+voltro serverless list .                                   # what functions are here
+voltro serverless dev functions/health.serverless.ts       # ONE function on :8910
+curl http://localhost:8910/
+
+# functions that need config read it from the env:
+SLACK_WEBHOOK_URL=https://hooks.slack.com/... \
+  voltro serverless dev functions/slackNotify.serverless.ts
+```
+
+`voltro serverless serve .` runs ALL of them at once (each mounted at `/<name>`) — handy as a single self-hosted sidecar. The dev runner sends CORS headers — the same headers Cloudflare / Scaleway add at the edge — so a cross-origin browser POST works in dev exactly as it will in prod.
+
+## Deploy targets
+
+`voltro serverless build .` bundles every function so you can inspect the output; then ship them to one of three targets:
+
+```bash
+voltro serverless deploy --target node                     # self-host kit (Dockerfile + README)
+voltro serverless deploy --target cloudflare               # Cloudflare Workers
+voltro serverless deploy --target scaleway --namespace-id <id>   # Scaleway Functions
+```
+
+Set each function's secrets at deploy time (the host's env / secret store): `SLACK_WEBHOOK_URL`, `SIGNING_SECRET`, `OPENAI_API_KEY`, `SHARE_BASE_URL`, … The function host bills per invocation and idles to zero between requests.
+
+## Add your own
+
+Drop a new `functions/<name>.serverless.ts` exporting `export default defineServerless({ … })`. It's discovered automatically — no registry, no config entry.
+
+## `defineAction` (api) vs. `*.serverless.ts` (this) — the decision rule
+
+The framework's default for external I/O — an HTTP call, an email, an AI call — is a `defineAction` inside an always-on api. Reach for a `*.serverless.ts` instead ONLY when you specifically want one of:
+
+| You want… | Pick |
+|---|---|
+| External I/O as part of a reactive app (it sits next to queries / mutations / a DB) | `defineAction` in an api |
+| **Process isolation** — a function that can't take down your api | `*.serverless.ts` |
+| **Independent scaling** — one endpoint that spikes without scaling the whole api | `*.serverless.ts` |
+| **Independent release** — ship this one function without redeploying the api | `*.serverless.ts` |
+| **Scale-to-zero** for a rarely-hit endpoint (no always-on server) | `*.serverless.ts` |
+
+If none of those apply, an action in an api is the simpler, cheaper choice — it's typed end-to-end to the rpc client and shares the api's runtime, auth, and DB.
+
+## Pairs well with
+
+- [Serverless functions](/docs/deployment/serverless-functions) — the deploy + runtime model for `*.serverless.ts` (node / Cloudflare / Scaleway).
+- [Scale to zero](/docs/deployment/scale-to-zero) — why these idle to zero and bill per invocation.
+- [Static sites](/docs/deployment/static-sites) — pair a function with a pre-rendered page on a CDN.
+- [`frontend-contact`](/docs/templates/contact) — the static-page + ONE-serverless-backend starter; reach for `edge-functions` when you need MORE than one function.
+- [Actions](/docs/data/actions) — the in-api alternative for external I/O when you DON'T need process isolation / independent scaling.
+
+## Anti-patterns
+
+- **Reaching for `node:*` in a function.** The handler is edge-safe by design (it runs on a Cloudflare Worker). Use the framework `HttpClient` (or global `fetch`) for outbound HTTP and `crypto.subtle` (Web Crypto) for hashing — a `node:`-prefixed import breaks the Cloudflare/Scaleway targets.
+- **Skipping the input Schema.** The `defineServerless` `input` is what turns a malformed request into a typed `400` before your handler runs. Don't hand-parse the body and trust it.
+- **Returning a bare `Effect.fail` when you mean a specific status.** That surfaces as a generic `500`. Use `ServerlessHttpError({ status, message })` so the caller gets `401` / `404` / `422` / `502` / `503` — the whole point of the controlled-error functions.
+- **Pretending to succeed when a secret isn't wired.** Every config-dependent function here fails LOUD with a `503 *-not-configured` the caller can render. Don't swap that for a silent `{ ok: true }`.
+- **Treating the library like an api.** A `*.serverless.ts` is standalone — bundled + deployed on its own with `voltro serverless`, never discovered by `voltro dev`. If you find yourself wanting queries, subscriptions, or a database next to it, you want an api template + a `defineAction`, not this.