@voltro/cli 0.1.0

package/templates/agent-docs/ai.md

@@ -0,0 +1,1845 @@
+# AI
+
+> How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework.
+
+
+
+---
+
+<!-- source: en/ai/overview.md -->
+## Overview
+
+_How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework._
+
+AI in Voltro isn't a library you bolt on. It's a primitive: agents are files, tools are files, embeddings are columns, streaming is the same WebSocket that carries queries + mutations.
+
+The implementation is the [Vercel AI SDK](https://sdk.vercel.ai) wrapped behind the `@voltro/ai` surface so the provider choice (Anthropic, OpenAI, the Vercel AI Gateway, mock-for-tests) is one env var — or a per-agent / per-call override carrying its own key.
+
+## The model
+
+```text
+                 ┌─────────────────────────────────────────┐
+                 │  Vercel AI SDK                          │
+                 │   anthropic / openai / gateway / mock    │
+                 └────────────────┬────────────────────────┘
+                                  │
+                                  ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  @voltro/ai                                                      │
+│    generateText(...) / generateObject(...)                       │
+│    streamText(...)                                                │
+│    embed(...) / embedMany(...)                                    │
+└────┬─────────────────────────┬──────────────────────────────────┘
+     │                         │
+     ▼                         ▼
+┌──────────────────────────────┐   ┌──────────────────────────────────┐
+│  *.agent.tsx (descriptor)    │   │  *.tool.tsx                      │
+│   defineAgent({ name, input })│   │   defineTool({ name, input,      │
+│  *.agent.server.tsx (executor)│   │     output })                    │
+│   defineAgentExecutor(desc, { │   │   typed + wired on the executor  │
+│     system, tools, model })   │   │                                  │
+└──────────────────────────────┘   └──────────────────────────────────┘
+```
+
+## What's in this section
+
+- [Providers](/docs/ai/providers) — Anthropic, OpenAI, the Vercel AI Gateway, mock; per-config keys (BYOK), switching at runtime, model-wrapping middleware
+- [Agents](/docs/ai/agents) — `*.agent.tsx` shape, system prompts, tool wiring
+- [Tools](/docs/ai/tools) — `*.tool.tsx` shape, validation, side effects
+- [Streaming](/docs/ai/streaming) — tokens-over-WebSocket, client hooks, backpressure
+- [RAG](/docs/ai/rag) — pgvector, embedding mixin, hybrid search
+- [Cost tracking](/docs/ai/cost-tracking) — the token `usage` returned on every call
+
+## Why one surface
+
+The Vercel AI SDK is excellent. It also rev'd its public API three times in 2024. Wrapping it gives us:
+
+1. **One break** when the SDK changes shape — we update `@voltro/ai`, your code keeps working.
+2. **One mock implementation** for tests — `AI_PROVIDER=mock` makes every call deterministic.
+3. **Provider portability** — switch the provider with one env var, no call-site changes.
+
+## Conceptual differences vs. raw SDK
+
+| Vercel AI SDK | `@voltro/ai` |
+|---|---|
+| `generateText(...)` | `generateText({ prompt, system })` returns an Effect |
+| `streamText(...)` | `streamText({ prompt, system })` returns an Effect Stream |
+| Embeddings via `embedMany([texts])` | `embed(text)` / `embedMany(texts)` |
+| Tool definitions are loose objects | `defineTool({ name, input, output, … })` with Schema |
+| Provider is hardcoded in code | `AI_PROVIDER` env var |
+
+## When NOT to use Voltro's AI surface
+
+- **You need bleeding-edge SDK features** before they land in `@voltro/ai`. Drop down to the raw SDK via `import { anthropic } from '@ai-sdk/anthropic'`.
+- **You're calling AI from outside an executor.** Workers, CLI scripts, etc. can still use `@voltro/ai` directly when they provide the right env/config.
+
+For 95% of app code inside actions, streams, workflows, and agent helpers, use `@voltro/ai` instead of importing provider SDKs directly. The portability and test mock surface stay in one place.
+
+
+
+---
+
+<!-- source: en/ai/providers.md -->
+## Providers
+
+_Anthropic, OpenAI, the Vercel AI Gateway, mock-for-tests, per-config keys (BYOK), and switching providers via env vars without touching code._
+
+`@voltro/ai` exposes one surface behind a provider abstraction. Pick yours via `AI_PROVIDER`. The same free functions — `generateText({ prompt })`, `generateObject({ prompt, schema })`, `streamText({ prompt })` — work against any provider.
+
+There is no `ctx.ai`. AI lives in the free functions you import from `@voltro/ai`, not on the request context.
+
+## Supported providers
+
+| Provider | `AI_PROVIDER` value | Default model | Key env var | Notes |
+|---|---|---|---|---|
+| Anthropic | `anthropic` | `claude-opus-4-8` | `ANTHROPIC_API_KEY` | Claude. Best for agentic tool use + long context. |
+| OpenAI | `openai` | `gpt-5.5` | `OPENAI_API_KEY` | GPT models via `@ai-sdk/openai`. |
+| Gateway | `gateway` | none (required) | `AI_GATEWAY_API_KEY` | The Vercel AI Gateway: ANY model the AI SDK can reach through ONE key, addressed by a `creator/model` id (`openai/gpt-5.5`, `anthropic/claude-opus-4-8`, `google/gemini-2.5-pro`). No per-vendor `@ai-sdk/*` package needed. |
+| Mock | `mock` | `mock` | none | Deterministic responses for tests + CI. Echoes the prompt (or scripted output). |
+
+`mock` is the **default** — `voltro dev` runs key-free out of the box, and every smoke test stays deterministic without a network call. Set `AI_PROVIDER=anthropic` / `openai` / `gateway` to use a real model.
+
+**Direct provider vs gateway:** reach for a direct provider (`anthropic` / `openai`) when you want that vendor's own key + native behaviour. Reach for `gateway` when you want "any model, one key" without adding a new `@ai-sdk/*` package — the model id carries the vendor (`openai/gpt-5.5`). All four packages stay pinned to the same `@ai-sdk/provider` major; mixing a newer-major provider package in would break the shared model type.
+
+## Setting the provider
+
+```bash
+AI_PROVIDER=anthropic AI_MODEL=claude-opus-4-8 ANTHROPIC_API_KEY=sk-ant-… voltro dev
+```
+
+Env vars `providerFromEnv()` reads:
+
+| Var | Default | Notes |
+|---|---|---|
+| `AI_PROVIDER` | `mock` | `mock` \| `anthropic` \| `openai` \| `gateway`. |
+| `AI_MODEL` | per provider (see below) | Override the model. Defaults: `claude-opus-4-8` (anthropic), `gpt-5.5` (openai), `mock` (mock). **REQUIRED for `gateway`** — a `creator/model` id; boot throws if unset. |
+
+Provider API keys are read by the underlying `@ai-sdk/*` packages from their standard env vars — `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `AI_GATEWAY_API_KEY`. The framework doesn't read a separate `AI_API_KEY`. (To give a SINGLE agent its own key from code instead of env, see [Per-config key + base URL](#per-config-key--base-url) below.)
+
+## Anthropic
+
+```bash
+AI_PROVIDER=anthropic
+AI_MODEL=claude-opus-4-8
+ANTHROPIC_API_KEY=sk-ant-…
+```
+
+Anthropic-specific:
+
+- **Prompt caching** — automatic for long, repeated prefixes via the AI SDK.
+- **Tool calling** — Claude's native tool format; the framework's `defineTool(...)` adapts to it.
+
+For long contexts Claude is the practical pick — fewer "context overflow" surprises.
+
+## OpenAI
+
+```bash
+AI_PROVIDER=openai
+AI_MODEL=gpt-5.5
+OPENAI_API_KEY=sk-…
+```
+
+Backed by `@ai-sdk/openai`. `AI_MODEL` is a plain OpenAI model id (`gpt-5.5`, `gpt-4o-mini`, …). For a self-hosted / Azure-style / proxy endpoint, set `baseURL` on a `ProviderConfig` (see [Per-config key + base URL](#per-config-key--base-url)) rather than an env var.
+
+## Vercel AI Gateway
+
+```bash
+AI_PROVIDER=gateway
+AI_MODEL=openai/gpt-5.5            # creator/model id — REQUIRED, no default
+AI_GATEWAY_API_KEY=…
+```
+
+The gateway reaches EVERY model the AI SDK can address through ONE key — you never add a per-vendor `@ai-sdk/*` package. The model id encodes the vendor: `openai/gpt-5.5`, `anthropic/claude-opus-4-8`, `google/gemini-2.5-pro`. There's no sensible default model (the id IS the choice), so `AI_PROVIDER=gateway` with no `AI_MODEL` throws at boot with a pointer to fix it.
+
+Use the gateway when you want to switch models across vendors freely from config; use a direct provider when you want that vendor's own key + native quirks (Anthropic prompt-caching, etc.).
+
+### Live model catalog — `getAvailableModels`
+
+A model-picker UI shouldn't hard-code a model list that goes stale. `getAvailableModels()` lists the gateway's models live — each with its modality + pricing — so the picker is always current:
+
+```ts
+import { getAvailableModels } from '@voltro/ai'
+
+// Reads AI_GATEWAY_API_KEY; pass { apiKey, baseURL } to target a specific gateway.
+const models = await getAvailableModels({ modality: 'language' })   // filter optional
+// → GatewayModelInfo[]: { id, name, description?, modality, pricing? }
+//   id        — the creator/model id you pass as the model ('openai/gpt-5.5')
+//   modality  — 'language' | 'embedding' | 'image' | 'unknown'
+//   pricing   — { inputPer1M, outputPer1M, cachedInputPer1M? } (USD per 1M tokens)
+```
+
+Pricing is normalised to **USD per 1,000,000 tokens**, the same shape as the cost toolkit's `ModelPrice` — so a catalog entry can feed the [cost ledger](/docs/ai/cost-tracking) directly (`estimateCostUsd(usage, { model, price })`). `getAvailableModels` is `async` (a plain Promise, not an Effect) and `gatewayProvider` is injectable for tests, so a picker query can call it without a live gateway in CI.
+
+## Per-config key + base URL
+
+Every `ProviderConfig` accepts an optional `apiKey` and `baseURL`. When EITHER is set, the framework builds a **dedicated provider instance** from it (`createOpenAI({ apiKey })` / `createAnthropic(...)` / `createGateway(...)`) instead of the env-default singleton. Omit both → it falls back to the standard env var. The mock provider ignores both.
+
+```ts
+// A one-off call against a specific key + endpoint:
+const r = yield* generateText({
+  prompt,
+  provider: { name: 'openai', model: 'gpt-5.5', apiKey: process.env.TEAM_OPENAI_KEY, baseURL: 'https://my-proxy/v1' },
+})
+```
+
+This is the mechanism behind **per-agent keys** and **BYOK** (bring-your-own-key): a `defineAgentExecutor` can carry a static `model: { name, model, apiKey }`, OR a `model: (input) => ({ …, apiKey: input.apiKey })` function that derives the key from the request. The key stays server-side (the executor file never reaches the browser) and is NOT persisted — only the prompt is stored in `agent_messages`. The full pattern (dynamic model picker, cost/tier routing, BYOK, and the security footguns) lives in [Agents → Per-agent model + key](/docs/ai/agents#per-agent-model--key).
+
+## Mock (for tests)
+
+```bash
+AI_PROVIDER=mock
+```
+
+Every call returns deterministic output (it echoes the prompt, or a scripted turn sequence). Useful for:
+
+- CI runs where you don't want real API calls
+- Unit tests of agents — assert on the call shape, not the output
+- Local dev when you're offline
+
+Configure the mock per-test. `useMockAi` installs a process-global mock provider that every `generateText` / `generateObject` / `streamText` / `runAssistant` call resolves to (overriding `AI_PROVIDER`); call `reset()` to restore:
+
+```ts
+import { useMockAi } from '@voltro/ai/test'
+
+let mock: ReturnType<typeof useMockAi>
+beforeEach(() => {
+  mock = useMockAi({
+    // canned generateText / generateObject text
+    generate: { text: 'Mocked summary text.' },
+    // streamText token sequence (drives runAssistant deltas)
+    stream:   ['Hello, ', 'world.'],
+    // scripted tool-call → text turns for the tool loop (one per step)
+    turns: [
+      { toolCalls: [{ name: 'searchDocs', input: { query: 'x' } }] },
+      { text: 'Based on the docs.' },
+    ],
+  })
+})
+afterEach(() => { mock.reset() })
+```
+
+`mockAi({...})` returns a `MockAi` value with the same fixture shape — handy as a test helper for code that wants a mock to assert against.
+
+`throwNTimes(n, value)` is a helper for retry tests — a function that throws the first `n` calls, then returns `value`.
+
+## The call surface
+
+One-shot text:
+
+```ts
+import { generateText } from '@voltro/ai'
+import { Effect } from 'effect'
+
+export default (input: { prompt: string }) =>
+  Effect.gen(function* () {
+    const { text, usage } = yield* generateText({ prompt: input.prompt })
+    return { text }
+  })
+```
+
+`GenerateTextOptions` is `{ prompt, system?, provider?, fallbacks?, maxTokens? }`. There is no `messages`/`effort` shape — the prompt is a single string the SDK wraps as the user turn; `system` steers it. `fallbacks` is a [provider fallback chain](#fallback-chain--survive-a-provider-outage).
+
+Structured output:
+
+```ts
+import { generateObject } from '@voltro/ai'
+import { Schema } from 'effect'
+
+const Summary = Schema.Struct({ title: Schema.String, bullets: Schema.Array(Schema.String) })
+
+const { object } = yield* generateObject({ prompt: input.text, schema: Summary })
+```
+
+## Switching providers per call
+
+Pass `provider` to override the env default for one call:
+
+```ts
+import { generateText } from '@voltro/ai'
+
+const r = yield* generateText({
+  prompt,
+  system,
+  provider: { name: 'anthropic', model: 'claude-opus-4-8' },
+})
+```
+
+`provider` is a `ProviderConfig` — a **discriminated union on `name`**, so each provider only accepts the fields that apply to it:
+
+```ts
+type ProviderConfig =
+  | { name: 'mock';      model?: string; mockText?: string; script?: MockScript }  // mock-only fields
+  | { name: 'anthropic'; model: AnthropicModel; apiKey?: string; baseURL?: string }
+  | { name: 'openai';    model: OpenAIModel;    apiKey?: string; baseURL?: string }
+  | { name: 'gateway';   model: `${string}/${string}`; apiKey?: string; baseURL?: string }  // creator/model
+```
+
+The mock-only `mockText` / `script` can't appear on a real provider (the type rejects it), the gateway's `model` is a `creator/model`-typed string (a bare `'gpt-5.5'` is a compile error, not a boot crash), and the per-provider model-id types (`AnthropicModel` / `OpenAIModel`) are **open unions** — known ids autocomplete, but any string the provider ships tomorrow still type-checks. Use `provider` for per-request model selection (e.g. a cheaper model on a fallback path), or to pin a specific key/endpoint (see [Per-config key + base URL](#per-config-key--base-url)).
+
+For runtime provider switching across a whole layer, bind an `AiServiceImpl` to the `AiService` Context tag at boot and read it with `yield* AiService` — `defaultAiService` (backed by `providerFromEnv`) is the default.
+
+## Fallback chain — survive a provider outage
+
+Pass an ordered `fallbacks` list to fall through to another provider/model when the primary FAILS. When the primary call fails — after its own retries — the call re-runs against `fallbacks[0]`, then `fallbacks[1]`, … until one succeeds; exhausting every option surfaces the LAST provider's typed error. So an Anthropic outage transparently drains to OpenAI (or the gateway) when a key is configured:
+
+```ts
+import { generateText } from '@voltro/ai'
+
+const r = yield* generateText({
+  prompt,
+  provider:  { name: 'anthropic', model: 'claude-opus-4-8' },
+  fallbacks: [
+    { name: 'openai',  model: 'gpt-5.5' },
+    { name: 'gateway', model: 'google/gemini-2.5-pro' },
+  ],
+})
+```
+
+- **Applies to `generateText`, `generateObject`, `generateObjectWithTools`, and the stream surface.** For streaming, use `streamTextWithFallback(options)` or `streamTextWithRetry(options, retry)` — the latter retries each provider `maxAttempts` times BEFORE moving to the next. A plain `streamText` uses only the primary.
+- **Only a provider (`generation`) failure falls through.** A `decode` failure — the model answered but the output didn't satisfy the schema — surfaces immediately, because another provider won't fix a schema/prompt problem.
+- **Streams fall through only before content flows.** Once any token/tool event has streamed the answer is committed and a later error surfaces as-is (re-running elsewhere would duplicate output); a deliberate `cancelled` never triggers a fallback.
+- **No `fallbacks` ⇒ unchanged single-provider behavior.**
+
+Typed errors are preserved end-to-end: a fully-exhausted chain fails with the last `AiError` on the Effect channel (generate) or a terminal `error` event (stream). Cost/usage is attributed to whichever provider actually served the call (the observability span + metrics stamp its `provider`/`model`).
+
+## Middleware — wrap every model call
+
+Language-model **middleware** wraps every model the framework resolves — for `generateText`, `generateObject`, `streamText`, and agents alike — so you add cross-cutting behavior (logging, reasoning extraction, default settings, caching, guardrails) in ONE place without touching call sites. It's the AI SDK's `wrapLanguageModel` seam, exposed as a process-global stack you install once at boot:
+
+```ts
+import { setAiMiddleware, loggingMiddleware } from '@voltro/ai'
+
+// Typically in a *.startup.tsx boot hook (or app.config layers):
+setAiMiddleware(loggingMiddleware())
+```
+
+Every subsequent call is wrapped; nothing else changes. `setAiMiddleware(...)` returns the previous stack (restore it in a test), `getAiMiddleware()` reads it, `clearAiMiddleware()` empties it. With an empty stack the model is passed through untouched — zero overhead on the default path.
+
+**Built-ins** (all re-exported from `@voltro/ai`):
+
+- `loggingMiddleware({ log? })` — logs each call's model + token usage (dev default: `console`; pass `log` to route into your logger/metrics).
+- `extractReasoningMiddleware({ tagName })` — split inline `<think>…</think>` reasoning out of the answer text into the reasoning channel, for models that don't emit native reasoning parts.
+- `defaultSettingsMiddleware({ settings })` — pin default call settings (temperature, `maxOutputTokens`, `providerOptions`) for every call.
+- `simulateStreamingMiddleware()` — make a generate-only model satisfy the streaming path (emits the full text as one delta).
+
+**Custom middleware** is any object implementing `transformParams` / `wrapGenerate` / `wrapStream` (typed `AiMiddleware`):
+
+```ts
+import { setAiMiddleware, type AiMiddleware } from '@voltro/ai'
+
+const redactPII: AiMiddleware = {
+  transformParams: async ({ params }) => params,   // scrub params.prompt before it leaves
+}
+setAiMiddleware(redactPII, loggingMiddleware())    // applied in order — the first entry is outermost
+```
+
+Middleware is **server-only** — install it where the app boots, never from a browser-safe descriptor.
+
+## Embeddings — a separate axis
+
+Embeddings use their own provider env, not `AI_PROVIDER`:
+
+```bash
+AI_EMBED_PROVIDER=openai          # mock (default) | openai | voyage | cohere
+AI_EMBED_MODEL=text-embedding-3-small
+```
+
+The default is `mock` (deterministic, key-free). Real embedding providers (`openai` / `voyage` / `cohere`) resolve their AI-SDK package via a lazy, server-only dynamic import — install the package (e.g. `@ai-sdk/openai`) to use them. See [RAG](/docs/ai/rag).
+
+## Provider quirks
+
+- **Anthropic 429s** burst — burst rate limits trip before the monthly quota. Handle retries with `Effect.retry` in your executor.
+- **Mock determinism** — every test using `useMockAi` is isolated; fixtures don't bleed across `describe` blocks.
+
+
+
+---
+
+<!-- source: en/ai/agents.md -->
+## Agents
+
+_`*.agent.tsx` files — definition, system prompts, tool wiring, streaming responses, and turn structure._
+
+A Voltro **agent** is a server-side LLM workflow with a typed input, a system prompt, an optional tool list, and a streaming response. The file convention is `*.agent.tsx`.
+
+Agents bridge two worlds: they're chat-completion-shaped (messages in, tokens out) but they live inside the framework's executor model — the synthesized `<name>.send` is an **action**, so it gets `ctx` and can do external I/O. (Actions are not transactional; an agent run is not rolled back.)
+
+## Defining an agent — descriptor + executor
+
+Like queries/mutations, an agent is **two files paired by basename** — the browser/server boundary again:
+
+- **`*.agent.tsx` — the descriptor** (`defineAgent` from `@voltro/ai/agent`): just `name` + `input` schema. Browser-safe, so codegen value-imports it into `rpcGroup.generated.ts` — the web client is typed **end-to-end** for the synthesized routes.
+- **`*.agent.server.tsx` — the executor** (`defineAgentExecutor` from `@voltro/ai`, default-exported): system prompt, tools (which import server services), per-agent **model + API key**, and `maxSteps`. Server-only — secrets never reach the browser.
+
+```tsx
+// apps/api/agents/support.agent.tsx — DESCRIPTOR (browser-safe)
+import { defineAgent } from '@voltro/ai/agent'
+import { Schema } from 'effect'
+
+export const support = defineAgent({
+  name:  'support',                                  // → support.send / support.messages
+  input: Schema.Struct({ prompt: Schema.String, plan: Schema.optional(Schema.String) }),
+})
+```
+
+```tsx no-check
+// apps/api/agents/support.agent.server.tsx — EXECUTOR (server-only)
+import { defineAgentExecutor } from '@voltro/ai'
+import { support } from './support.agent'
+import { searchDocs } from '../tools/searchDocs.tool'
+
+export default defineAgentExecutor(support, {
+  system: (input) => `You are a friendly support agent for the Voltro framework.
+Be concise. The user is on the ${input.plan ?? 'free'} plan.`,
+  tools:  { searchDocs },
+  model:  { name: 'openai', model: 'gpt-5.5', apiKey: process.env.SUPPORT_OPENAI_KEY },
+  maxSteps: 8,
+  // Provider-specific knobs forwarded to the SDK — most importantly REASONING
+  // EFFORT (see "Reasoning effort" below). Pin it low for a routing/help agent.
+  providerOptions: { openai: { reasoningEffort: 'low' } },
+})
+```
+
+The framework pairs the two by basename and synthesizes, per agent `name`, two procedures:
+
+- `<name>.send` — an **action** that appends the user turn + streams an assistant turn (delta-persisted to `agent_messages`). Wire input: the descriptor's `input` fields + `threadId` + `order`.
+- `<name>.messages` — a **reactive query** (`source: 'agent_messages'`) that streams the persisted turns — including the live one being typed — to the browser.
+
+**Codegen emits both routes into `rpcGroup.generated.ts`**, so `useAction` / `useSubscription` resolve them with full types. (Older code hand-wrote thread/send/list actions just to get a typed client — that's no longer needed; the agent path is the typed, supported way.)
+
+`tools` is a `Record<string, AnyTool>` (the same shape `runAssistant` takes), keyed however you like — the tool's own `name` is what the model sees.
+
+## Per-agent model + key
+
+`model` on the executor overrides the global default per agent — and carries its own key:
+
+```tsx
+defineAgentExecutor(support, {
+  model: {
+    name:  'openai',           // 'openai' | 'anthropic' | 'gateway' | 'mock'
+    model: 'gpt-5.5',          // for gateway: a 'creator/model' id, e.g. 'openai/gpt-5.5'
+    apiKey: process.env.SUPPORT_OPENAI_KEY,  // OPTIONAL — see fallback below
+  },
+  // …
+})
+```
+
+**Env is the fallback.** Each `model` field is optional:
+
+- Omit `apiKey` → the provider reads its standard env var (`OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `AI_GATEWAY_API_KEY`).
+- Omit `model` entirely → the agent inherits `AI_PROVIDER` / `AI_MODEL` from env (the global default).
+
+So one agent can run GPT-5.5 on a dedicated key while another inherits the env default — no global-only constraint. The key lives in `*.agent.server.tsx`, which never reaches the browser.
+
+### Dynamic model — a function of the input (model picker / routing / BYOK)
+
+`model` may also be a **function** of the decoded input (like `system`) — it returns a full `ProviderConfig` (incl. `apiKey`), runs server-side, and `undefined` falls back to env for that call. Two patterns:
+
+**Model picker / routing** — the input selects among server-owned configs (UI picker, cost/size routing, plan tiers):
+
+```tsx
+// descriptor: input: Schema.Struct({ prompt: Schema.String, tier: Schema.Literal('fast', 'smart') })
+export default defineAgentExecutor(support, {
+  model: (input) => input.tier === 'smart'
+    ? { name: 'openai', model: 'gpt-5.5' }
+    : { name: 'openai', model: 'gpt-4o-mini' },
+})
+```
+
+**BYOK (bring your own key)** — the caller supplies their OWN key; you fold it into the returned config:
+
+```tsx
+// descriptor: input: Schema.Struct({ prompt: Schema.String, apiKey: Schema.String })
+export default defineAgentExecutor(support, {
+  model: (input) => ({ name: 'openai', model: 'gpt-5.5', apiKey: input.apiKey }),
+})
+```
+
+> **Security.** The input is client-controlled, so the real footgun is letting it pick an **expensive model on a key YOU pay for** — for a picker, constrain the choice with a `Schema.Literal` in the descriptor's `input` and map to **server-owned** configs (don't do `(input) => ({ model: input.model })`). **BYOK is the legitimate exception:** returning `apiKey: input.apiKey` is the whole point — the cost is on the user's key. The key is NOT persisted (only the prompt is stored in `agent_messages`); just make sure your logging/tracing doesn't capture it.
+
+## Reasoning effort + provider tuning (`providerOptions`)
+
+`providerOptions` on the executor is forwarded verbatim to the underlying SDK call — the outer key is the provider id, the inner record its options. The headline use is **reasoning effort**: a reasoning model (`gpt-5.x`) defaults to a HIGH effort that spends many seconds "thinking" before the first token — even for a one-line answer. A navigation / help / Q&A assistant doesn't need that; pin it low (or `minimal`) for a dramatically faster first token at negligible quality cost:
+
+```tsx
+export default defineAgentExecutor(support, {
+  // …
+  providerOptions: { openai: { reasoningEffort: 'low' } },        // or 'minimal'
+  // anthropic equivalent: { anthropic: { thinking: { type: 'disabled' } } }
+})
+```
+
+The same `providerOptions` field is accepted by the one-shot free functions too — `generateText`, `generateObject`, `generateObjectWithTools`, and `streamText` — for the same per-call provider tuning.
+
+## Conversation memory — automatic
+
+The synthesized `<name>.send` sends the **whole persisted thread** to the model on every turn (the prior user/assistant turns + the new prompt), so the assistant remembers earlier messages. You don't thread history yourself — appending the user turn before the model call (which the synthesized send does) is enough. A custom `runAssistant` caller can pass an explicit `messages` array for the same effect; with none, it falls back to the single `prompt`.
+
+## Anatomy of an agent run
+
+```text
+client → <name>.send({ threadId, prompt, order })
+   │
+   ▼  append user turn → runAssistant(store, { threadId, prompt, system, tools, order })
+   │
+   ▼  streamText runs the loop: model calls tool? → server runs tool → result back to model
+   │  (loop until done, up to maxSteps)
+   │
+   ▼  token/tool deltas throttle-patched onto the live agent_messages row
+   │
+   ▼  <name>.messages subscription re-fires → client renders the next chunk
+   │
+   ▼  done → streaming:false on the row
+```
+
+Multiple rounds of tool calls are handled inside `runAssistant` / `streamText` — you don't loop manually unless you write a custom executor.
+
+## The system prompt
+
+System prompts go in the agent definition's `system` field, NOT in the messages array. Why:
+
+- It keeps the prompt out of the per-turn message history — the durable `agent_messages` rows hold the conversation, not the boilerplate instructions.
+- The framework can apply prompt caching to it automatically (Anthropic supports cached system prompts).
+- Versioning is easier — change the prompt, deploy, every call uses the new one.
+
+The `system` field lives on the **executor**. Template it with per-call values (locale, persona, plan-specific instructions) — the function receives the input typed from the descriptor's schema:
+
+```tsx
+// support.agent.server.tsx — `plan` comes from the descriptor's input schema
+export default defineAgentExecutor(support, {
+  system: (input) => `You are speaking with a user on the ${input.plan ?? 'free'} plan.`,
+  // …
+})
+```
+
+The system function receives the typed input + can return a string. It's called fresh on every request.
+
+## Wiring tools
+
+```tsx
+import { searchDocs } from '../tools/searchDocs.tool'
+import { createTicket } from '../tools/createTicket.tool'
+
+export const supportAgent = defineAgent({
+  name:   'support',
+  // …
+  tools:  { searchDocs, createTicket },
+})
+```
+
+Tool definitions are typed — the agent doesn't need any string-keyed routing. The agent's input/output is Schema-validated; so is every tool call's input/output. See [Tools](/docs/ai/tools).
+
+## Turn structure — the zero-config default
+
+For the persisted, reactive chat (what `defineAgent` synthesizes), the client subscribes to the agent's `<name>.messages` query and sends turns through its `<name>.send` action. No token-stream handling — tokens land as throttled patches on the live `agent_messages` row, which the subscription re-fires:
+
+```tsx
+// client side — the durable pattern
+const { data: messages = [] } = useSubscription('app', 'support.messages', { threadId })
+const send = useAction('app', 'support.send')
+
+const sendMessage = (prompt: string) =>
+  send.run({ threadId, prompt, order: messages.length })
+```
+
+The server side is generated — you don't write the send action or the messages query when you declare a `defineAgent`. The thread tables (`agent_threads`, `agent_messages`) are auto-provided + auto-migrated.
+
+### Transient runs — `useAgent`
+
+When you DON'T want persistence (an ephemeral playground, a one-off completion), wrap a `defineStream` rpc with the `useAgent` client hook — it derives `tokens` from the run's token events and accumulates `history`:
+
+```tsx
+// client side — transient
+const support = useAgent('app', 'support.run')
+
+const sendMessage = (text: string) => {
+  support.send({ message: text, history: support.history })
+  // support.tokens streams in; on done it folds into support.history
+}
+```
+
+### Fully custom run loop — `defineStream`
+
+The agent path (descriptor + executor) is the default for the persisted, reactive chat. When you need a *fully custom* loop (mix conversation with bespoke side effects, your own persistence, a non-standard stream shape), don't try to bend the agent synthesis — write a `defineStream` rpc and drive it with the `streamText` free function, then consume it client-side with `useAgent` (transient) or persist deltas yourself:
+
+```tsx
+// streams/thread.run.stream.ts (+ thread.run.stream.server.ts)
+import { streamText } from '@voltro/ai'
+import { Stream } from 'effect'
+
+export default (input: { prompt: string }, ctx) =>
+  streamText({ prompt: input.prompt, system: 'You are concise.' }).pipe(
+    Stream.tap((event) => /* persist / forward `event` */ Stream.empty),
+  )
+```
+
+## Persisted, reactive chat (under the hood)
+
+The durable pattern above is built on a delta-persistence layer that makes the conversation itself the durable, reactive record. Tokens reach the browser via a **reactive query**, not a raw socket.
+
+Thread + message CRUD: `createThread`, `appendMessage`, `getMessages`, `getThread`. Streaming-turn helpers:
+
+- `appendStreamingMessage(store, { threadId, tenantId?, order })` — insert one assistant row with `streaming: true` and empty `parts`; returns its id.
+- `patchStreamingMessage(store, id, parts)` — patch the row's `parts` (mirrors text to `content`) as deltas arrive; throttle at the call site.
+- `runAssistant(store, { threadId, tenantId?, prompt, system?, tools?, order, throttleMs? })` — does the whole turn: inserts the streaming row, consumes `streamText`, accumulates token deltas into a text part + records tool calls/results as tool parts, throttle-patches the row (default 100ms), then flips `streaming: false` with the final `parts`.
+
+The pattern to feature:
+
+1. A **send action** appends the user message and calls `runAssistant`.
+2. A **reactive query with `source: 'agent_messages'`** streams the persisted rows — including the live `streaming: true` row being patched — to the browser. Each throttled patch mutates the row → the subscription re-fires → the client sees the next chunk.
+
+```tsx
+// actions/chat.send.action.server.ts
+import { appendMessage, runAssistant } from '@voltro/ai'
+import { Effect } from 'effect'
+
+export default (input: { threadId: string; text: string; order: number }, ctx) =>
+  Effect.gen(function* () {
+    yield* appendMessage(ctx.store, { threadId: input.threadId, role: 'user', content: input.text, order: input.order })
+    yield* runAssistant(ctx.store, { threadId: input.threadId, prompt: input.text, order: input.order + 1 })
+    return { ok: true }
+  })
+```
+
+```tsx
+// queries/chat.messages.query.ts → source: 'agent_messages'
+// queries/chat.messages.query.server.ts
+import { getMessages } from '@voltro/ai'
+export default async (input: { threadId: string }, ctx) => getMessages(ctx.store, input.threadId)
+```
+
+```tsx
+// client — a normal subscription; no token-stream handling
+const { data: messages } = useSubscription('app', 'chat.messages', { threadId })
+const send = useAction('app', 'chat.send')
+```
+
+The `agent_messages` row carries `streaming` (live typewriter flag), `order` (thread position), `stepOrder` (sub-position within a turn, for LLM↔tool steps), and `parts` (the structured `text` + `tool` payload the feed renders). Both `agent_threads` and `agent_messages` are tenant-scoped — the active org id is stamped on every row. Full worked example in [Streaming](/docs/ai/streaming#streaming-deltas-through-a-reactive-query-persisted-no-raw-socket).
+
+## Constraining responses (JSON, schema)
+
+For non-chat agents where you want structured output:
+
+```tsx
+import { Schema } from 'effect'
+
+const SummarySchema = Schema.Struct({
+  title:    Schema.String,
+  bullets:  Schema.Array(Schema.String),
+  priority: Schema.Literal('low', 'medium', 'high'),
+})
+
+import { generateObject } from '@voltro/ai'
+
+const { object: summary } = await Effect.runPromise(generateObject({
+  schema: SummarySchema,
+  system: 'Summarise the input into a JSON object.',
+  prompt: input.text,
+}))
+// summary is typed { title: string, bullets: string[], priority: 'low' | 'medium' | 'high' }
+```
+
+`generateObject` converts the Effect Schema to JSON Schema for the provider, then decodes the model output back through the schema, so refinements/brands hold and malformed output surfaces as a typed `AiError({ reason: 'decode' })`.
+
+`generateObject` is single-shot — it takes no tools. When a batch agent needs BOTH adaptive tool-calling (fetch detail on demand) AND a final schema-constrained object, use `generateObjectWithTools`:
+
+```tsx
+import { generateObjectWithTools } from '@voltro/ai'
+
+const { object: summary } = yield* generateObjectWithTools({
+  schema:  SummarySchema,
+  system:  'Drill into the ticket with the tools, then summarise.',
+  prompt:  input.text,
+  tools:   { getIssueComments, getIssueChangelog },  // looped on demand
+  maxSteps: 16,                                       // LLM↔tool round-trips, default 8
+})
+```
+
+It runs the LLM↔tool loop (`stopWhen` at `maxSteps`) and constrains the terminal answer to the schema, decoding it through the same Effect Schema as `generateObject`. The tools reach the caller's runtime services (see [Tools → Effect tool bodies reach app services](/docs/ai/tools#effect-tool-bodies-reach-app-services)).
+
+## Cancelling mid-stream
+
+For the transient `useAgent` path, `cancel()` interrupts the in-flight run; the server-side stream scope tears down (which aborts the upstream model call):
+
+```tsx
+const support = useAgent('app', 'support.run')
+support.cancel()    // interrupts the run; the server-side scope tears down
+```
+
+## When agents are the wrong tool
+
+- **Single-shot summarisation / classification** — use an action with `generateText` / `generateObject`. Agents shine for multi-turn / tool-using flows.
+- **Background processing** — use a workflow. Agents are request-scoped; workflows survive crashes + can run for hours.
+
+See [RAG](/docs/ai/rag) for the canonical "agent + tool + vector search" pattern.
+
+
+
+---
+
+<!-- source: en/ai/tools.md -->
+## Tools
+
+_`*.tool.tsx` files — Schema-validated tool definitions agents can call, with side effects, retries, and tenant scoping._
+
+A **tool** is a function the agent can call. It has a name, a description, a Schema-typed input + output, and a handler. The framework's discovery picks up every `*.tool.tsx` file; the agent runtime composes them into the model's tool list.
+
+Tools are the bridge between the LLM ("I want to look up the user's plan") and your data ("here's the row from `users`").
+
+## Defining a tool
+
+```tsx
+// apps/api/tools/searchDocs.tool.tsx
+import { defineTool } from '@voltro/ai'
+import { Schema } from 'effect'
+
+export const searchDocs = defineTool({
+  name:        'search-docs',
+  description: 'Search Voltro documentation. Returns up to 5 results.',
+  input:       Schema.Struct({ query: Schema.String }),
+  output:      Schema.Array(Schema.Struct({
+    title:   Schema.String,
+    snippet: Schema.String,
+    href:    Schema.String,
+  })),
+})
+
+export default async ({ query }, ctx) => {
+  const rows = await ctx.store.select('docs')
+    .where('body', 'fts', query)
+    .limit(5)
+    .all()
+  // Project to the declared `output` shape. When `output` is set, the
+  // framework decodes the handler's return value through it before
+  // handing the result to the model — returning raw `docs` rows here
+  // would fail that decode.
+  return rows.map((r) => ({
+    title:   r.title,
+    snippet: r.body.slice(0, 160),
+    href:    `/docs/${r.id}`,
+  }))
+}
+```
+
+The export shape is the same as agents: a `defineTool({...})` config + a default-exported async handler.
+
+## How the agent uses it
+
+Tools are wired on the agent's **executor** (`*.agent.server.tsx`) — they import server services, so they stay out of the browser:
+
+```tsx
+// apps/api/agents/support.agent.server.tsx
+import { defineAgentExecutor } from '@voltro/ai'
+import { support } from './support.agent'
+import { searchDocs } from '../tools/searchDocs.tool'
+
+export default defineAgentExecutor(support, {
+  tools: { searchDocs },
+})
+```
+
+At call time, the framework:
+
+1. Translates each tool into the provider's native tool format (Anthropic's `tools` shape).
+2. Includes them in the chat-completion request.
+3. When the model returns a tool-call message, looks up the matching tool, validates the input against the Schema, runs the handler, validates the output, and feeds the result back to the model.
+4. Loops until the model returns a final text response (or hits `maxTurns`).
+
+You don't write the tool-call loop. The framework does.
+
+## Description prompt engineering
+
+The model's only signal for "when should I call this tool" is the `description`. Be specific:
+
+```ts
+// BAD
+description: 'Search docs.'
+
+// GOOD
+description: `Search the Voltro framework documentation. Use this when the
+user asks how to use a feature, how to debug something, or what an API
+does. Returns up to 5 results ranked by relevance.`
+```
+
+Include:
+
+- **When to call** — the situations this tool handles
+- **What it returns** — shape + ranking hints
+- **What it doesn't do** — sets boundaries against over-calling
+
+For tools that should ONLY be called once per turn, say so in the description. The model usually listens.
+
+## Tool input validation
+
+Schema validates the model's tool-call arguments before your handler sees them. Invalid inputs → the framework feeds an error back to the model + asks it to retry:
+
+```ts
+input: Schema.Struct({
+  query:  Schema.String.pipe(Schema.minLength(1), Schema.maxLength(200)),
+  limit:  Schema.Number.pipe(Schema.between(1, 20)).pipe(Schema.optional),
+})
+```
+
+The model sees a structured "your input was invalid for these reasons" message + reformulates. The user never sees the failure — it's a model-internal retry.
+
+## Tools with side effects
+
+Tools that write (`createTicket`, `bookMeeting`, `sendEmail`) get the same `ctx` as mutations:
+
+```tsx
+export const createTicket = defineTool({
+  name:        'create-ticket',
+  description: 'Open a support ticket for the user.',
+  input:       Schema.Struct({
+    subject: Schema.String,
+    body:    Schema.String,
+  }),
+  output:      Schema.Struct({ id: Schema.String }),
+})
+
+export default async (input, ctx) => {
+  if (ctx.subject.type !== 'user') {
+    throw new Error('Tool only available for signed-in users.')
+  }
+  const t = await ctx.store.insert('tickets', {
+    ...input,
+    userId:   ctx.subject.id,
+    tenantId: ctx.subject.tenantId,
+  })
+  return { id: t.id }
+}
+```
+
+The tool's subject is the **calling agent's subject** — i.e. the user who invoked the agent. Tools cannot impersonate other users.
+
+## Tenant scoping
+
+Tools inherit `ctx.subject.tenantId` from the agent's caller. Reads via `ctx.store` auto-scope to that tenant; writes need `assertOwnTenant`. Same rules as mutations.
+
+The model cannot pass a different `tenantId` to escalate — even if it tries (a `system_prompt` injection attempt), the framework's tenant scope is enforced at the data layer, not the tool layer.
+
+## Effect tool bodies reach app services
+
+A tool body written as an inline `execute(input) => Effect` may `yield*` any Effect service the **caller's runtime** provides — `JiraService`, `EffectStore`, `HttpClient`, your own `Context.Tag` layers. The loop primitives (`streamText`, `runAssistant`, `generateObjectWithTools`) capture the ambient runtime (`Effect.runtime`) and thread it into the tool-execution context, so a tool run inside a workflow step or action that already has the service in scope can call it directly:
+
+```tsx
+import { defineTool } from '@voltro/ai'
+import { JiraService } from '@voltro/plugin-atlassian'
+import { Effect, Schema } from 'effect'
+
+export const getIssueComments = defineTool({
+  name:        'getIssueComments',
+  description: 'Fetch all comments of a Jira issue.',
+  input:       Schema.Struct({ jiraKey: Schema.String }),
+  output:      Schema.Array(Schema.Struct({ author: Schema.NullOr(Schema.String), body: Schema.String })),
+  execute: ({ jiraKey }) =>
+    Effect.gen(function* () {
+      const jira = yield* JiraService            // ← provided by the caller's runtime
+      const raw = yield* jira.getComments(jiraKey)
+      return raw.map((c) => ({ author: c.author?.displayName ?? null, body: c.body }))
+    }).pipe(Effect.catchAll(() => Effect.succeed([]))),  // degrade → empty, never abort the loop
+})
+```
+
+Catch the service's failures inside the body (the body's error channel is `never`): an uncaught failure surfaces to the model as a tool error. Tools that close over their data instead (a pure `execute` over a pre-fetched payload, or a `(input, ctx)` handler writing via `ctx.store`) don't need the runtime at all — both forms work side by side.
+
+## Tools that call other tools
+
+A tool can use another tool's handler internally:
+
+```tsx
+import searchDocsHandler from '../tools/searchDocs.tool'
+
+export default async (input, ctx) => {
+  const docs = await searchDocsHandler({ query: input.query }, ctx)
+  // …
+}
+```
+
+Avoid calling `streamText` / `generateText` from inside a tool body to spawn a nested agent — it's an easy way to build an accidental runaway loop (the model calls the tool, the tool runs another model that calls the tool again). The framework doesn't stop you, but for chained work, model the chain as a workflow and start it through its generated RPC boundary instead.
+
+## Tools as a wedge for testability
+
+A tool's input + output are typed + Schema-validated. That makes them trivial to unit-test:
+
+```ts
+import tool from './searchDocs.tool'
+import { makeTestContext, mockStore } from '@voltro/testing'
+
+test('searchDocs finds relevant docs', async () => {
+  const ctx = makeTestContext({
+    store: mockStore({ docs: [{ id: 'foo', title: 'Foo', body: 'bar baz' }] }),
+  })
+  const out = await tool({ query: 'bar' }, ctx)
+  expect(out).toEqual([{ title: 'Foo', snippet: 'bar baz', href: '/docs/foo' }])
+})
+```
+
+`makeTestContext` / `mockStore` come from **`@voltro/testing`** — a separate package you add as a devDependency per app (`pnpm --filter @my-app/api add -D @voltro/testing vitest`); see [Testing → Unit testing](/docs/testing/unit-testing).
+
+For tests that exercise the model loop (not just the tool body), use `mockAi` / `useMockAi` from `@voltro/ai/test` to install a deterministic provider — see [Providers](/docs/ai/providers#mock-for-tests).
+
+No agent involved, no model call. Just the tool's logic. This is the right unit boundary — agents are integration tests; tools are unit tests.
+
+## App-as-an-agent — expose existing procedures as tools
+
+You don't have to hand-wrap every endpoint as a `*.tool.tsx`. A query /
+mutation / action descriptor already IS a safe LLM-tool spec — typed input,
+RBAC-scoped, validated, audited — so annotate it `exposeAsTool` and synthesize
+the toolset with `appTools`. The synthesized tool runs the REAL handler under
+the calling subject: **the agent can do nothing the subject couldn't** (no new
+authorization path), by construction.
+
+```ts
+// Opt a descriptor in (a description is REQUIRED — the model needs it):
+export const listOrders = defineQuery({
+  name: 'orders.list', input: ListInput, output: Schema.Array(Order), source: 'orders',
+  exposeAsTool: { description: "List the current tenant's orders." },
+})
+export const createOrder = defineMutation({
+  name: 'orders.create', input: CreateInput, output: Order, target: { table: 'orders', op: 'insert' },
+  exposeAsTool: { description: 'Create an order.', confirm: true },   // writes confirm by default
+})
+```
+
+```ts
+// Server-side: synthesize + run. `entries` = { descriptor, invoke } bound to
+// the request ctx (the serve layer provides them).
+import { appTools, generateObjectWithTools } from '@voltro/ai'
+
+const tools = appTools(entries, { allow: ['orders.*'], includeWrites: true })
+const { object } = yield* generateObjectWithTools({ prompt, tools, schema: Result })
+```
+
+Safety defaults (don't override blindly): **reads are included, writes are
+opt-in** (`includeWrites: true`) and **confirm by default**. Put destructive
+tags on `deny`. `exposeAsTool: true` alone does NOT expose — a tool with no
+description is unusable; always use the object form. The annotations also
+surface in the capability manifest, so a coding agent discovers what's
+tool-exposable.
+
+The end-user-facing counterpart is **`<AppAgent>`** (from `@voltro/web`) — a
+"do it for me" chat whose ceiling is the logged-in subject's own permissions.
+See [Schema-driven UI → Reactive components](/docs/ui/reactive-components).
+
+## Anti-patterns
+
+- **Tools that take freeform JSON.** The model writes JSON poorly. Use Schema everywhere; let the framework reject bad inputs.
+- **Tools without descriptions.** The model has nothing to go on — it'll either over-call (every turn) or never call.
+- **Long-running tools.** Tool calls block the agent's turn. For anything > 5s, queue a workflow and return a handle the agent can poll.
+- **Tools that throw on common errors.** A throw stops the agent. Return a typed error variant so the model can recover.
+
+
+
+---
+
+<!-- source: en/ai/streaming.md -->
+## Streaming
+
+_AI token streams with defineStream, useAgentStream, and streamText — plus cancel, retry, and resumable streams._
+
+AI streaming in Voltro uses the same stream primitive as any other one-shot server-to-client feed:
+
+- `*.stream.ts` declares the `defineStream` descriptor.
+- `*.stream.server.ts` returns an Effect `Stream`.
+- `useAgentStream` consumes the stream on the client.
+
+For durable chat that survives reloads, do not stream raw tokens to React state. Persist token deltas into `agent_messages` and expose them through a reactive query.
+
+## Transient Stream
+
+Descriptor:
+
+```ts
+// apps/api/streams/support.run.stream.ts
+import { AgentEvent } from '@voltro/ai/events'   // browser-safe Schema entry — NOT '@voltro/ai' (server-only)
+import { defineStream } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const supportRun = defineStream({
+  name:    'support.run',
+  input:   Schema.Struct({ message: Schema.String }),
+  element: AgentEvent,
+})
+```
+
+Server executor:
+
+```ts
+// apps/api/streams/support.run.stream.server.ts
+import { streamText } from '@voltro/ai'
+
+export default (input: { message: string }) =>
+  streamText({
+    system: 'You are concise and helpful.',
+    prompt: input.message,
+  })
+```
+
+`streamText` emits `AgentEvent` elements. The `_tag`s are: `token` (text delta), `reasoning` (the model's thinking, separate from the answer), `toolCall`, `toolResult`, `source` (a cited RAG/web source — `url` or `document` variant), `file` (an inline file the model produced, usually an image: `mediaType` + base64 `data`), `message`, `error` (carries `retryable`), and `done`. The stream NEVER fails — an upstream error arrives as a terminal `error` event.
+
+## Cancel, retry
+
+A "Stop" button needs to end an in-flight run out of band. Pass a `streamId` and call `cancelStream(streamId)` from a separate action/mutation — it aborts the provider call (token spend stops) and the stream ends on a terminal, non-retryable `cancelled` error.
+
+```ts
+import { streamText, cancelStream } from '@voltro/ai'
+
+// executor — register the run under a client-chosen id
+streamText({ prompt: input.message, streamId: input.streamId })
+
+// a separate stop.action.server.ts
+export default (input: { streamId: string }) => ({ cancelled: cancelStream(input.streamId) })
+```
+
+The registry is **in-process**: `cancelStream` only aborts a stream running on the same node and returns `false` when the id isn't known locally. On a multi-replica deployment, route the cancel call to the node that owns the stream (sticky by `streamId`), or pair it with the resumable-stream store's `markDone` so other nodes stop tailing. Single-node dev/self-host needs nothing extra.
+
+`streamText` also accepts an external `signal` (`AbortSignal`) and SDK-level `maxRetries` (retries the provider HTTP call before any bytes stream). For recovering from an immediate provider error, `streamTextWithRetry(options, { maxAttempts, backoffMs })` re-runs the stream — but ONLY while nothing has streamed yet, so it never duplicates tokens; once content flows, a later error is surfaced as-is.
+
+## Resumable Streams
+
+A resumable stream survives a client disconnect: close the tab mid-answer, reopen, and the assistant keeps streaming from where it left off. `resumableStreamText` runs the model ONCE (the producer, as a daemon that outlives the connection) and persists every event to a store; every consumer replays past its cursor then tails to the end.
+
+```ts
+// support.run.stream.server.ts
+import { resumableStreamText, memoryResumableStreamStore } from '@voltro/ai'
+
+const store = memoryResumableStreamStore() // single node — see below for multi-node
+
+export default (input: { message: string; streamId: string; fromSeq?: number }) =>
+  resumableStreamText({
+    streamId: input.streamId,
+    store,
+    options: { prompt: input.message },
+    fromSeq: input.fromSeq, // a reconnect passes the last `seq` it rendered
+  })
+```
+
+It returns a `Stream<SeqEvent>` — each element is `{ seq, event }`. The descriptor declares `element: SeqEvent` (import the Schema from `@voltro/ai/events`, the browser-safe entry — the `@voltro/ai` root is server-only) and an optional `fromSeq` on its input.
+
+On the client, `useResumableAgentStream('app', 'support.run')` does the rest: it unwraps each `SeqEvent` (so `.events` are the plain inner events), tracks the highest `seq`, and on a transport drop BEFORE the run's terminal event it auto-reconnects with `fromSeq` = the last seq it rendered (exponential backoff; the no-progress cap resets whenever a reconnect delivers a new event, so a long flaky stream survives any number of well-spaced drops). The server replays past the cursor, then continues — one seamless stream.
+
+For multi-node deployments use `dataStoreResumableStreamStore(ctx.store)` — it persists to the framework's own database (`streamEventsTable` + `streamStateTable`, register them in your `database/index.ts`) and elects exactly ONE producer per `streamId` via an atomic claim, so only one node runs the model while every node's consumers tail the shared log. Sweep finished streams with `gcResumableStreams(store, { olderThan })`.
+
+For the fastest path, `redisResumableStreamStore(redis, { ttlSeconds })` backs the log with a Redis LIST (`RPUSH`/`LRANGE`) plus a `SET … NX` producer claim — TTL evicts finished/abandoned streams without a sweep. `@voltro/ai` takes no Redis dependency; you inject a tiny `ResumableRedis` client (five methods: `setNx` / `rpush` / `lrange` / `set` / `exists`) adapting ioredis / node-redis. All three backends satisfy the same `ResumableStreamStore` interface, so they swap without touching the producer/consumer code.
+
+## Client
+
+```tsx
+import { useAgentStream } from '@voltro/client'
+import type { AgentEvent } from '@voltro/ai'
+
+const support = useAgentStream<AgentEvent>('app', 'support.run')
+const text = support.events
+  .filter((event) => event._tag === 'token')
+  .map((event) => event.text)
+  .join('')
+
+return (
+  <>
+    <button
+      disabled={support.status === 'streaming'}
+      onClick={() => support.start({ message: prompt })}
+    >
+      Send
+    </button>
+    <button onClick={support.cancel}>Cancel</button>
+    <pre>{text}</pre>
+  </>
+)
+```
+
+`useAgent` is a convenience wrapper over `useAgentStream` for transient chat UIs. It derives `tokens` and `history` so you do not have to filter raw events yourself.
+
+## Durable Chat
+
+A plain transient stream is request-scoped: a reload loses the in-flight text (use a resumable stream, above, if you only need reconnect-resume). For product chat you usually want the full DURABLE history too — persist the assistant turn and stream the persisted rows through a query:
+
+1. A send action appends the user message.
+2. The action calls `runAssistant(...)`.
+3. `runAssistant` inserts one `agent_messages` row with `streaming: true`.
+4. Token/tool deltas patch that row.
+5. A query with `source: 'agent_messages'` re-runs and updates the UI.
+
+```ts
+// actions/chat.send.action.server.ts
+import { appendMessage, getMessages, runAssistant } from '@voltro/ai'
+import { Effect } from 'effect'
+
+export default (
+  input: { threadId: string; text: string },
+  ctx,
+) =>
+  Effect.gen(function* () {
+    const existing = yield* getMessages(ctx.store, input.threadId)
+    const order = existing.length
+
+    yield* appendMessage(ctx.store, {
+      threadId: input.threadId,
+      role: 'user',
+      content: input.text,
+      order,
+    })
+
+    yield* runAssistant(ctx.store, {
+      threadId: input.threadId,
+      prompt: input.text,
+      order: order + 1,
+    })
+
+    return { ok: true }
+  })
+```
+
+```ts
+// queries/chat.messages.query.ts declares source: 'agent_messages'
+// queries/chat.messages.query.server.ts
+import { getMessages } from '@voltro/ai'
+
+export default (input: { threadId: string }, ctx) =>
+  getMessages(ctx.store, input.threadId)
+```
+
+```tsx
+const { data: messages } = useSubscription('app', 'chat.messages', { threadId })
+const send = useAction('app', 'chat.send')
+
+await send.run({ threadId, text })
+```
+
+This pattern survives reloads, works across tabs, and can be driven by workflows.
+
+## Stream vs Persisted Query
+
+| Need | Use |
+|---|---|
+| Playground token stream | `defineStream` + `useAgentStream` |
+| Cancelable one-shot generation | `streamText({ streamId })` + `cancelStream` |
+| Reconnect-resume an in-flight stream | `resumableStreamText` + a stream store |
+| Chat history after reload | Action + `agent_messages` query |
+| Cross-tab live conversation | Action + `agent_messages` query |
+| Crash/retry semantics | Workflow patches persisted rows |
+
+## Anti-Patterns
+
+- **Saving only the final text for chat.** Persist deltas so the UI can show live progress and survive reloads.
+- **Using `useAgentStream` for blocking calls.** Use an action with `generateText` or `generateObject`.
+- **Using streams as subscriptions.** If the data is durable state, expose it through a query.
+
+
+
+---
+
+<!-- source: en/ai/rag.md -->
+## RAG (retrieval-augmented generation)
+
+_Vectors + the vectorEmbedding mixin + hybrid search + rerank — the canonical recipe for grounding agents in your data._
+
+Retrieval-Augmented Generation: instead of hoping the model remembers your docs, you **retrieve** relevant passages at call-time + put them in the prompt. The model answers from what you handed it, not from training data.
+
+Voltro's RAG primitives live in three places:
+
+- **Storage** — vector columns + HNSW indexes ([Vector columns](/docs/database/vectors)). Index-accelerated on postgres; MariaDB runs the distance operators natively; the other dialects store vectors but fall back to a sequential scan.
+- **Embedding generation** — `embed(text)` from `@voltro/ai` + the `vectorEmbedding()` mixin
+- **Retrieval helpers** — `nearestNeighbours(...)`, `hybridSearch(...)` on `ctx.store`, `rerank(...)` from `@voltro/ai`
+
+## The minimal RAG pipeline
+
+```tsx
+// apps/api/database/docs.entity.ts
+import { table, id, text, vectorEmbedding } from '@voltro/database'
+import { tenant } from '@voltro/plugin-multitenancy'
+
+export const docs = table('docs', {
+  id:   id(),
+  body: text(),
+}).with(
+  vectorEmbedding({
+    from:       'body',
+    model:      'text-embedding-3-small',
+    dimensions: 1536,
+  }),
+  tenant(),
+)
+```
+
+The mixin:
+
+- Adds an `embedding: vector(1536)` column with an HNSW index.
+- On INSERT, the runtime calls `embed(body)` (from `@voltro/ai`) + stores the vector.
+- On UPDATE of `body`, re-embeds.
+
+You write `body`. The vector handles itself.
+
+> **Embeddings default to `mock`.** Out of the box `embed` uses a deterministic, key-free mock provider (it hashes the text into a stable vector — reproducible, but not semantic). The `model: 'text-embedding-3-small'` string is stored but ignored by the mock. To get real embeddings, set `AI_EMBED_PROVIDER=openai` (or `voyage` / `cohere`) and install that provider's package (e.g. `@ai-sdk/openai`). See [Providers](/docs/ai/providers#embeddings-a-separate-axis).
+
+## Querying
+
+```tsx
+// apps/api/tools/searchDocs.tool.tsx
+import { defineTool } from '@voltro/ai'
+import { Schema } from 'effect'
+
+export const searchDocs = defineTool({
+  name:        'search-docs',
+  description: 'Search the user knowledge base. Returns up to 5 passages.',
+  input:       Schema.Struct({ query: Schema.String }),
+  output:      Schema.Array(Schema.Struct({
+    body:     Schema.String,
+    href:     Schema.String,
+    distance: Schema.Number,
+  })),
+})
+
+export default async ({ query }, ctx) => {
+  const results = await ctx.store.select('docs')
+    .nearestNeighbours(query, 5)                  // embeds `query`, limit 5
+    .all()
+
+  return results.map((r) => ({
+    body:     r.body,
+    href:     `/docs/${r.id}`,
+    // `distance` is a DISTANCE — lower = closer. Keep the runtime field
+    // name so consumers don't sort it backwards (a "score" would imply
+    // higher = better). Invert it explicitly if you want a similarity.
+    distance: r.distance,
+  }))
+}
+```
+
+That's it. The runtime:
+
+1. Embeds the `query` string (via `@voltro/ai`'s `embed`).
+2. Runs `ORDER BY embedding <=> $1 LIMIT 5` (via the HNSW index on postgres; sequential scan elsewhere).
+3. Returns rows with a `distance` field.
+
+## Wiring into an agent
+
+```tsx
+// apps/api/agents/help.agent.tsx — descriptor (browser-safe)
+import { defineAgent } from '@voltro/ai/agent'
+import { Schema } from 'effect'
+
+export const help = defineAgent({ name: 'help', input: Schema.Struct({ prompt: Schema.String }) })
+```
+
+```tsx
+// apps/api/agents/help.agent.server.tsx — executor (server-only)
+import { defineAgentExecutor } from '@voltro/ai'
+import { help } from './help.agent'
+import { searchDocs } from '../tools/searchDocs.tool'
+
+export default defineAgentExecutor(help, {
+  system: `You are a helpful support agent. When the user asks how to do
+something, ALWAYS call search-docs first to ground your answer in the
+docs. Then summarise + cite the relevant passage.`,
+  tools:  { searchDocs },
+})
+```
+
+The two agent files are all you write — the framework synthesizes `help.send` + `help.messages` (codegen-typed for the client). The model decides when to call `search-docs`; the system prompt nudges it strongly — "always call first" is usually enough.
+
+## Chunking strategy
+
+Voltro doesn't ship a markdown chunker — that's app-specific. The right strategy depends on your data:
+
+| Data | Chunk by | Why |
+|---|---|---|
+| Markdown docs | H2 sections (≤2k tokens each) | Self-contained units; preserves heading context. |
+| API references | Function / type | Each row IS the chunk. |
+| Long-form articles | Sliding window with 200-token overlap | Preserves cross-paragraph context. |
+| Code | File / function | Each row IS the chunk. |
+| Customer support tickets | Per-ticket | Each row IS the chunk. |
+
+For markdown chunking, a 30-line helper is enough:
+
+```ts
+const chunkBySection = (md: string): string[] => {
+  const out: string[] = []
+  let current = ''
+  for (const line of md.split('\n')) {
+    if (line.startsWith('## ') && current) {
+      out.push(current)
+      current = line
+    } else {
+      current += '\n' + line
+    }
+  }
+  if (current) out.push(current)
+  return out
+}
+```
+
+Ingest:
+
+```ts
+for (const chunk of chunkBySection(md)) {
+  await ctx.store.insert('docs', { body: chunk })
+  // The vectorEmbedding mixin handles the embedding side-effect.
+}
+```
+
+## Hybrid search
+
+Pure vector similarity misses exact-match queries ("does X support Y" — the keyword "Y" is more reliable than its embedding). Combine vector + full-text:
+
+```ts
+import { hybridSearch } from '@voltro/database'
+
+const results = await ctx.store.select('docs').use(hybridSearch({
+  vector: { col: 'embedding', query },
+  fts:    { indexName: 'docsBody', query },
+  alpha:  0.6,    // 0 = pure FTS, 1 = pure vector
+})).limit(5).all()
+```
+
+The FTS clause narrows the candidate set; the vector clause ranks it, fused with Reciprocal Rank Fusion. For a knowledge base it routinely beats either alone — for technical docs, lean toward `alpha=0.4-0.6` (FTS-weighted).
+
+## Re-ranking
+
+For top-shelf retrieval quality, run a **re-ranker** over the top-N hits. `rerank` ships in `@voltro/ai`:
+
+```ts
+import { rerank } from '@voltro/ai'
+
+const candidates = await searchDocs(query, 20)
+const reranked = yield* rerank({
+  query,
+  documents: candidates,
+  getText:   (d) => d.body,
+  provider:  'cohere',
+  model:     'rerank-english-v3.0',
+  topN:      5,
+})
+const top5 = reranked.map((r) => r.document)
+```
+
+Re-rankers are slower than vector search but much more accurate. Use the cheap vector search to narrow to ~20 candidates, then the rerank model to pick the top 5. Total latency: ~150-300ms vs. 50ms for vector-only. The default `provider: 'mock'` scores by lexical overlap — deterministic and key-free for tests; the `cohere` / `voyage` providers resolve their SDK lazily (install the provider package to use them).
+
+## Citing sources
+
+The model needs source info in its context to cite:
+
+```ts
+const docs = await searchDocs(query, 5)
+const context = docs.map((d, i) => `[${i + 1}] ${d.body}\n(source: ${d.href})`).join('\n\n')
+
+const messages = [
+  { role: 'system', content: `Sources:\n${context}\n\nAnswer using ONLY these sources. Cite as [1], [2], etc.` },
+  { role: 'user',   content: input.question },
+]
+```
+
+For UI that links each citation: parse `[1]`, `[2]` patterns out of the model's output + map back to `docs[0].href`, `docs[1].href`. The agent SDK doesn't do this automatically — it's render-layer work.
+
+## Tenant isolation
+
+The `vectorEmbedding()` mixin + `tenant()` mixin compose correctly:
+
+```ts
+const docs = table('docs', {
+  id:   id(),
+  body: text(),
+}).with(
+  vectorEmbedding({ from: 'body', dimensions: 1536 }),
+  tenant(),
+)
+```
+
+Searches across `docs` are **automatically tenant-scoped**. The runtime AND-merges the tenant filter before the ANN order/limit, so Tenant A's queries never surface Tenant B's vectors — even though the vectors live in the same column.
+
+## Cost considerations
+
+Embedding cost (only with a REAL provider configured — the default `mock` provider is free and offline):
+
+- `text-embedding-3-small` (OpenAI, `AI_EMBED_PROVIDER=openai`): roughly $0.02 per 1M tokens.
+- `voyage-3` (`AI_EMBED_PROVIDER=voyage`): roughly $0.12 per 1M tokens.
+
+Check the provider's current pricing — these are rough figures.
+
+Storage cost:
+
+- 1536-dim float32: ~6KB/row + ~3KB HNSW overhead = ~9KB/row.
+- 10k docs: ~100MB. Cheap.
+- 1M docs: ~10GB. Plan around it.
+
+Re-embedding cost (rebuilding the column with a new model) = full corpus × embedding cost. Pick your model + dimensions deliberately.
+
+## When NOT to use RAG
+
+- **The data fits in the context window.** If you have 50 docs and Claude can hold 200k tokens, just stuff them all in. Simpler, more accurate.
+- **The data IS the prompt.** For "translate this paragraph", you don't need retrieval.
+- **You need exact lookups.** RAG returns "similar" results; if you need "exactly this customer's order", use a regular query.
+
+RAG is for when the corpus is too big for context + the answer is in a small slice of it.
+
+
+
+---
+
+<!-- source: en/ai/cost-tracking.md -->
+## Cost tracking
+
+_Token usage on every call plus the shipped cost toolkit — estimateCostUsd + a price table, the _voltro_ai_usage ledger, spend sums, and per-tenant budget guards._
+
+LLMs are usage-priced, so you need to know how many tokens each call burned. Every `@voltro/ai` call returns a **token usage tally** on its result. That's the shipped primitive.
+
+On top of the raw tally, `@voltro/ai` ships a cost toolkit: a price table + `estimateCostUsd`, a reactive `_voltro_ai_usage` ledger (`recordAiUsage`), spend sums (`aiSpendUsd`), and a per-tenant budget guard (`requireAiBudget` → typed `AiBudgetExceeded`). (`@voltro/plugin-audit` is separate — it records **mutation invocations**, not AI calls.)
+
+## Token usage on every call
+
+`generateText` and `generateObject` return `usage` alongside the result:
+
+```ts
+import { generateText } from '@voltro/ai'
+import { Effect } from 'effect'
+
+export default (input: { prompt: string }) =>
+  Effect.gen(function* () {
+    const { text, usage } = yield* generateText({ prompt: input.prompt })
+    // usage = { inputTokens, outputTokens, totalTokens }
+    //   each is `number | undefined` (provider-reported)
+    return { text, tokens: usage.totalTokens }
+  })
+```
+
+```ts
+const { object, usage } = yield* generateObject({ prompt, schema })
+// same usage shape
+```
+
+## Token usage on a streamed run
+
+A `streamText` run ends with a terminal `done` event that carries the same usage shape:
+
+```ts
+import { streamText } from '@voltro/ai'
+import { Stream, Effect } from 'effect'
+
+yield* streamText({ prompt }).pipe(
+  Stream.runForEach((event) =>
+    Effect.sync(() => {
+      if (event._tag === 'done') {
+        // event.finishReason — 'stop' | 'tool-calls' | 'error' | …
+        // event.usage = { inputTokens, outputTokens, totalTokens }
+      }
+    }),
+  ),
+)
+```
+
+The `done` event's `usage` is the run total across every LLM↔tool round-trip.
+
+## Pricing a call — `estimateCostUsd`
+
+`estimateCostUsd(usage, { model })` turns a token tally into a USD
+`CostBreakdown` using the built-in price table (`MODEL_PRICING_DEFAULTS`, USD
+per 1M tokens). An unknown model — or the `mock` provider — prices at
+**zero**, so cost accounting never breaks a call.
+
+The defaults cover the major providers — Anthropic (`claude-*`), OpenAI
+(`gpt-*`), and Google Gemini (`gemini-*`) — so a non-Claude call is priced too
+(a `gpt-4o` or `gemini-2.5-pro` call is a real number, not a silent zero). A
+gateway `creator/model` id (`openai/gpt-4o`) prices by its bare model segment.
+
+```ts
+import { generateText, estimateCostUsd } from '@voltro/ai'
+
+const model = 'claude-opus-4-8'
+const { text, usage } = yield* generateText({ prompt, provider: { name: 'anthropic', model } })
+const cost = estimateCostUsd(usage, { model })
+// cost = { inputTokens, outputTokens, inputCostUsd, outputCostUsd, totalCostUsd, costSource }
+//   costSource: 'estimated' (price-table or zero) | 'gateway' (real reported cost)
+```
+
+Override the price for a model the table doesn't know, or for
+negotiated / volume pricing:
+
+```ts
+estimateCostUsd(usage, { model, price: { inputPer1M: 2.5, outputPer1M: 10 } })
+```
+
+### The built-in prices are point-in-time defaults — override them app-wide
+
+`MODEL_PRICING_DEFAULTS` are public **list prices as of January 2026** and
+**WILL drift** as providers re-price. Treat them as a sane default for the
+budget guard + cost dashboard, not a contract. To encode current or negotiated
+rates once, at boot, without editing the framework, call `setModelPricing` — a
+process-global override map merged OVER the defaults (a user entry for a model
+id wins):
+
+```ts
+import { setModelPricing } from '@voltro/ai'
+
+// Wire your ai config's `pricing` map through this at boot.
+setModelPricing({
+  'gpt-4o':          { inputPer1M: 2.5, outputPer1M: 10 },  // corrected list price
+  'my-tuned-model':  { inputPer1M: 0.8, outputPer1M: 2.4 }, // a model the defaults don't know
+})
+```
+
+Every `estimateCostUsd` / `recordAiUsage` / budget call then reads the merged
+map. `priceForModel(model)` returns the effective price (or `undefined` if
+unknown). For a gateway-routed model, the gateway's REPORTED per-call cost still
+wins over any static rate (see below).
+
+## Real gateway cost — `gatewayCostUsd` + `actualCostUsd`
+
+The static price table only knows the models it lists. A **gateway**-routed
+model the table doesn't carry would otherwise estimate to **zero** — wrong,
+not just imprecise. The fix: the Vercel AI Gateway reports the ACTUAL
+per-call cost in the result's provider metadata, and the toolkit prefers it.
+
+`gatewayCostUsd(providerMetadata)` pulls `providerMetadata.gateway.cost` (a
+USD number or numeric string) out of a generate/stream result, returning
+`undefined` for a direct provider / the mock (so you fall back to the table):
+
+```ts
+import { generateText, gatewayCostUsd, recordAiUsage } from '@voltro/ai'
+
+const model = 'openai/gpt-5.5'   // a gateway id the static table doesn't list
+const r = yield* generateText({ prompt, provider: { name: 'gateway', model } })
+const actualCostUsd = gatewayCostUsd(r.providerMetadata)   // the gateway's real charge, or undefined
+
+const cost = yield* recordAiUsage(ctx.store, {
+  tenantId: ctx.request.subject.tenantId,
+  provider: 'gateway',
+  model,
+  operation: 'generateText',
+  usage: r.usage,
+  actualCostUsd,          // when set → persisted verbatim, costSource: 'gateway'
+})
+// cost.costSource === 'gateway' (authoritative) when actualCostUsd was present,
+// else 'estimated' (price table or zero).
+```
+
+`estimateCostUsd(usage, { model, actualCostUsd })` honours the same rule: a
+present `actualCostUsd` wins (split across input/output by token share for
+the breakdown, `costSource: 'gateway'`); absent, it uses the price table
+(`costSource: 'estimated'`). A cost dashboard can flag `estimated` rows and
+un-priced (zero) models so you know which numbers are real vs derived.
+
+## The usage ledger — `recordAiUsage` + `aiUsageTable`
+
+`recordAiUsage(store, {...})` prices a call and writes one row to the
+`_voltro_ai_usage` ledger (`aiUsageTable`), returning the same
+`CostBreakdown`. The table is **reactive** and auto-migrated whenever the
+app ships any `*.agent.tsx`; a non-agent app that wants plain-call
+tracking imports `aiUsageTable` into its `database/index.ts` barrel. Cost
+is stored as integer **micro-USD** (`costMicroUsd`, USD × 1e6) — the same
+"money = integer minor units" rule the billing plugin uses.
+
+```ts
+import { generateText, recordAiUsage } from '@voltro/ai'
+
+const model = 'claude-opus-4-8'
+const { text, usage } = yield* generateText({ prompt, provider: { name: 'anthropic', model } })
+const cost = yield* recordAiUsage(ctx.store, {
+  tenantId:  ctx.request.subject.tenantId,
+  provider:  'anthropic',
+  model,
+  operation: 'generateText',     // or 'generateObject' | 'streamText' | 'agent' | your own
+  usage,
+})
+// cost.totalCostUsd — surface it without a re-query
+```
+
+A row carries `{ tenantId, provider, model, operation, agent, inputTokens,
+outputTokens, costMicroUsd, costSource, calledAt }`. `costSource` is
+`'gateway'` (the actual reported cost) or `'estimated'` (price-table / zero) —
+pass `actualCostUsd` (see above) to record the real gateway charge.
+
+## Spend + budgets — `aiSpendUsd` / `requireAiBudget`
+
+`aiSpendUsd(store, { tenantId?, since? })` sums recorded spend (USD).
+Because `aiUsageTable` is reactive, a `defineQuery` with
+`source: '_voltro_ai_usage'` that calls it is a **live spend meter** — the
+same reactive-query machinery as everything else.
+
+```ts
+const spentThisMonth = yield* aiSpendUsd(ctx.store, {
+  tenantId: ctx.request.subject.tenantId,
+  since:    startOfMonth(),
+})
+```
+
+`requireAiBudget(store, { tenantId, limitUsd, addUsd?, since? })` gates a
+call against a per-tenant cap — the precedent is billing's
+`requireEntitlement`. It fails with a typed, client-marshalable
+`AiBudgetExceeded` when `reserved + addUsd` would exceed `limitUsd`. Call it
+BEFORE the provider call (estimate `addUsd` from the prompt); record the
+real cost after.
+
+**Atomic across replicas — a hard cap, not a soft one.** The guard RESERVES
+`addUsd` on a single per-tenant counter row (`_voltro_ai_budget`) via a bounded
+compare-and-set loop — the same store-level atomic-consume the storage and
+billing plugins use. So N concurrent calls (same replica or across replicas)
+reserve **exactly** the budgeted amount and the rest fail — no overshoot. (This
+replaces an older check-then-act sum that concurrent callers could all read
+under-cap and all pass.) The reservation is optimistic: it does NOT auto-release
+if the provider call later fails, which for a rolling budget is the correct
+conservative bound. Pass `addUsd: 0` for a check-only UI pre-flight that reserves
+nothing. A rolling `since` window rotates to a fresh counter (the prior window's
+row ages out via retention).
+
+```ts
+import { generateText, requireAiBudget, recordAiUsage, AiBudgetExceeded } from '@voltro/ai'
+import { Effect } from 'effect'
+
+export default (input: { prompt: string }, ctx) =>
+  Effect.gen(function* () {
+    const tenantId = ctx.request.subject.tenantId
+    // Refuse if this tenant is already at/over its monthly cap.
+    yield* requireAiBudget(ctx.store, { tenantId, limitUsd: 50, addUsd: 0.25, since: startOfMonth() })
+
+    const model = 'claude-opus-4-8'
+    const { text, usage } = yield* generateText({ prompt: input.prompt, provider: { name: 'anthropic', model } })
+    yield* recordAiUsage(ctx.store, { tenantId, provider: 'anthropic', model, operation: 'generateText', usage })
+    return { text }
+  })
+```
+
+Declare `error: AiBudgetExceeded` on the descriptor so the rpc layer
+surfaces the rejection typed; the client pattern-matches on
+`{ _tag: 'AiBudgetExceeded', limitUsd, spentUsd, attemptedUsd }` (`spentUsd` is
+the amount already reserved on the counter).
+
+## Per-call observability — automatic spans + metrics
+
+Every `generateText` / `generateObject` / `generateObjectWithTools` /
+`streamText` call is automatically wrapped in a **`voltro.ai.call`** OTel span
+(attributes `ai.provider` / `ai.model` / `ai.operation`) and records metrics into
+the framework's global metric registry — the same one
+[`@voltro/plugin-prometheus`](/docs/plugins/prometheus) exposes at `/metrics` and
+the dashboard reads at `/_voltro/inspect/metrics`. No wiring needed:
+
+| Metric | Type | What |
+| --- | --- | --- |
+| `voltro_ai_calls_total` | counter | Calls, labelled `provider` / `model` / `operation` / `status`. |
+| `voltro_ai_call_errors_total` | counter | Calls that errored. |
+| `voltro_ai_call_duration_seconds` | histogram | Provider call latency. |
+| `voltro_ai_input_tokens_total` / `voltro_ai_output_tokens_total` | counter | Prompt / completion tokens. |
+| `voltro_ai_cost_microusd_total` | counter | Estimated spend (micro-USD), priced off the merged table. |
+
+Labels carry only provider / model / operation ids — never prompt or response
+content, never a key. Cost here is the *estimated* figure from the price table
+(for a live-priced budget cap, use `requireAiBudget`; for the authoritative
+gateway charge, use `recordAiUsage({ actualCostUsd })`).
+
+## Deliberately your call
+
+The toolkit prices + records + gates; a few things stay explicit by design:
+
+- **Recording the LEDGER is opt-in per call.** The free functions
+  (`generateText` etc.) have no store or tenant, so they can't self-write the
+  `_voltro_ai_usage` row — call `recordAiUsage` where you have `ctx` (an agent
+  send handler is the natural spot). The metrics above ARE automatic; the durable
+  per-row ledger is the opt-in part.
+- **The built-in prices are point-in-time list prices.** Call `setModelPricing`
+  to override app-wide, pass `price` per call for negotiated rates, or
+  `actualCostUsd` (from `gatewayCostUsd`) for the gateway's real per-call charge.
+
+For quota tied to billing TIERS (not a raw USD cap), see
+[`@voltro/plugin-billing`](/docs/plugins/billing)'s entitlements —
+`requireEntitlement(ctx, 'aiCalls', n)`.
+
+
+
+---
+
+<!-- source: en/ai/data-copilot.md -->
+## Data copilot
+
+_Natural-language questions over your data — the model proposes a query, every table/column is validated against a manifest (hallucinated names are refused, not executed), and the validated read-only descriptor runs AS the calling subject so tenant + row scoping always apply._
+
+The data copilot turns a **natural-language question** into a **validated,
+read-only query** and returns the rows — without ever trusting the model with
+your schema. The model proposes a query shape; the framework **validates every
+table and column against a manifest** and refuses anything it doesn't recognise
+(a hallucinated column is a typed rejection, never a blind `WHERE`). The
+validated descriptor is a plain `SELECT` that runs **as the calling subject**, so
+tenant and row scoping apply exactly as they do for any other query.
+
+> **Read-only in v1.** The copilot only ever reads. Trust hinges on validation —
+> one hallucinated number burns it — so schema-validation is non-negotiable, not
+> a nicety.
+
+## Server: the `copilot.ask` action
+
+`@voltro/ai`'s `runDataCopilot(question, schema, { propose })` builds the grammar
+prompt, asks the model for a constrained proposal, and validates it against your
+`CopilotSchema`. It returns either a read-only `descriptor` or a typed
+`CopilotRejected`. You run the descriptor as the subject and shape the answer:
+
+```ts
+// copilot.ask.action.ts — the browser-safe descriptor
+import { defineAction } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const ask = defineAction({
+  name: 'copilot.ask',
+  input:  Schema.Struct({ question: Schema.String }),
+  output: Schema.Union(
+    Schema.Struct({ ok: Schema.Literal(true),  rows:   Schema.Array(Schema.Record({ key: Schema.String, value: Schema.Unknown })) }),
+    Schema.Struct({ ok: Schema.Literal(false), reason: Schema.String }),
+  ),
+})
+```
+
+```ts
+// copilot.ask.action.server.ts — the server executor (imports @voltro/ai)
+import { Effect } from 'effect'
+import { runDataCopilot, generateObject, CopilotProposalSchema, type CopilotSchema } from '@voltro/ai'
+
+// The manifest the model is constrained to — only these tables/columns exist.
+const schema: CopilotSchema = {
+  tables: [{ name: 'todos', columns: [
+    { name: 'id', type: 'string' }, { name: 'title', type: 'string' },
+    { name: 'done', type: 'boolean' }, { name: 'dueAt', type: 'date' },
+  ] }],
+}
+
+const execute = (input: { question: string }, ctx: AppContext) =>
+  Effect.gen(function* () {
+    const v = yield* Effect.promise(() =>
+      runDataCopilot(input.question, schema, {
+        propose: ({ system, prompt }) =>
+          Effect.runPromise(
+            generateObject({ system, prompt, schema: CopilotProposalSchema }).pipe(Effect.map((r) => r.object)),
+          ),
+      }),
+    )
+    if (!v.ok) return { ok: false as const, reason: v.rejection.reason }
+    // The validated SELECT runs AS the subject → tenant + row scope apply.
+    const rows = yield* Effect.promise(() => ctx.store.query(v.descriptor as never))
+    return { ok: true as const, rows: rows as ReadonlyArray<Record<string, unknown>> }
+  })
+
+export default execute
+```
+
+## Client: `useDataCopilot` + `<DataCopilot>`
+
+The hook is a thin binding over `useAction` — it imports **nothing** from
+`@voltro/ai` (server-only), so the copilot engine never reaches the browser
+bundle:
+
+```tsx
+import { useDataCopilot } from '@voltro/client'
+
+const copilot = useDataCopilot('app', 'copilot.ask')
+await copilot.ask('how many open todos are due this week?')
+// copilot.answer: { ok: true, rows } | { ok: false, reason }
+// copilot.pending, copilot.error, copilot.reset()
+```
+
+Or drop in the headless `<DataCopilot>` component (a prompt box + the
+refusal-or-rows answer), styled with `data-voltro-*` hooks:
+
+```tsx
+import { DataCopilot } from '@voltro/ui'
+
+<DataCopilot api="app" action="copilot.ask" placeholder="Ask about your data…" />
+```
+
+## What makes it safe
+
+- **Schema-constrained.** Every proposed table, projection column, filter column,
+  order column, operator, and aggregate is checked against the manifest. Unknown
+  → a typed `CopilotRejected` (`unknown-table` / `unknown-column` / …), never an
+  executed query.
+- **Read-only.** The descriptor is always a `SELECT`; the copilot can't write.
+- **Runs as the subject.** Tenant scope + row visibility apply because the
+  descriptor runs through the same store path as any handler — a caller in tenant
+  A never sees tenant B's rows.
+- **Bounded.** The row count is capped (`COPILOT_MAX_LIMIT`) so a question can't
+  pull the whole table.
+
+
+
+---
+
+<!-- source: en/ai/app-builder.md -->
+## AI app-builder
+
+_Turn a natural-language prompt into a real app — graph + files — gated by the framework's own `voltro check` (errors-as-LLM-API), never auto-written. Drive it from the CLI (`voltro generate`) or the cloud dashboard, with an in-browser live preview of the result._
+
+The app-builder turns a **natural-language prompt** into a working app — the app
+GRAPH (tables + procedures + routes) plus the FILES that realise it — and it does
+so **without ever trusting the model to be right**. Every candidate is run through
+the framework's own `voltro check`; a structurally-invalid proposal is re-prompted
+with its typed diagnostics and **never written**. Nothing hits your tree (or
+deploys) without an explicit accept.
+
+## The loop (errors-as-LLM-API)
+
+```
+prompt ─▶ model proposes { graph, artifacts } ─▶ voltro check(graph)
+             ▲                                        │
+             └────── diagnostics fed back ◀── fails ──┤
+                                                       └── passes ─▶ proposal
+```
+
+The model only ever sees the framework's **capability grammar** (the primitives +
+your existing tables/procedures), and the real allow-list is `runCheck` — so a
+hallucinated table or an unbound route is caught and corrected, not shipped. After
+a bounded number of failed rounds the run is rejected; either way nothing is
+written.
+
+## From the CLI — `voltro generate`
+
+```bash
+voltro generate "add a comments table with a list + create"          # dry-run: prints the proposal
+voltro generate "add a comments table with a list + create" --write  # applies the accepted artifacts
+```
+
+Reads the committed capability manifest (`app.manifest.generated.json`) as the
+grammar, gates every candidate through `voltro check`, and writes **only** an
+accepted proposal **only** with `--write` (dry-run by default — the guardrail).
+See [Scaffolding](/docs/cli/scaffolding#generate-ai-app-builder) for the full flag
+list.
+
+## From the cloud dashboard
+
+The dashboard's **`/builder`** panel drives the `apps.generateAppGraph` action,
+which runs the same loop server-side and returns a **proposal for review** — it
+never writes or deploys. The whole surface is behind the **`aiBuilder` feature
+flag** (off by default → a typed `FlagDisabled`), so you opt projects in
+deliberately. A model provider (`AI_PROVIDER` / `AI_MODEL` + key) backs the
+generation.
+
+## Live preview — runs in your browser
+
+Below an accepted proposal, the builder renders a **live, interactive preview**
+that runs the generated app's data behaviour **entirely in your browser** — an
+in-memory reactive store + an interpreter over the proposal graph + the columns
+parsed from the entity artifacts. No server, no provisioning, no compile. Try it
+right here — add a row and watch it appear in that table's live list, reactively:
+
+```tsx
+// Fed a sample generated proposal — the { graph, artifacts } apps.generateAppGraph returns.
+<GeneratedAppPreview graph={proposal.graph} artifacts={proposal.artifacts} />
+```
+
+Each generated table gets a real create form (fields + widgets derived from its
+columns) and a live list; submitting the form writes to the in-memory store, which
+pushes to the open list — the same write→push reactivity the real runtime gives.
+
+## Guardrails
+
+- **Never auto-writes.** CLI: dry-run unless `--write`. Cloud: a proposal you
+  review, never an auto-deploy.
+- **`voltro check` gate.** A proposal is accepted only when `runCheck(graph).ok`;
+  a structurally-invalid one is re-prompted, then rejected — never written.
+- **Flag-gated (cloud).** `aiBuilder` is off by default; the endpoint fails
+  `FlagDisabled` until an operator turns it on.
+- **Size caps.** Generation is bounded by file count + total bytes.
+
+## What the preview is — and isn't
+
+The preview **simulates** the app from its spec: it interprets the graph + parsed
+columns against an in-memory store, giving faithful CRUD + reactivity without any
+infrastructure. It does **not** execute the literal generated TypeScript against a
+database — the **deployed** app does that, running the real artifacts on a real
+store. So the preview is a true feel for how the app behaves, not a bit-for-bit
+run of the code.