<!-- generated by voltro/scripts/gen-agent-docs.mjs — do not edit -->
## Deep reference (read on demand)

Each row below is a file to open WHEN you work on that topic — not loaded into
context by default. Topics live in the installed `@voltro/cli`; plugin depth is
each plugin's own README.

### Topics

| Topic | Open | Summary |
|---|---|---|
| **What's new in 0.52.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
| AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
| Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
| Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |
| CLI | `node_modules/@voltro/cli/templates/agent-docs/cli.md` | The voltro CLI — every command, grouped by purpose, with the flags that actually matter. |
| Configuration | `node_modules/@voltro/cli/templates/agent-docs/configuration.md` | Typed, schema-validated environment variables with a structural public/secret boundary. Declare once in app.config.ts; read public vars in the browser, secrets only on the server — and let the build fail loudly if you ever cross the line. |
| Data | `node_modules/@voltro/cli/templates/agent-docs/data.md` | How Voltro's reactive data layer works — queries, mutations, actions, streams, all over one WebSocket with typed errors and tracked dependencies. |
| database.advancedQueries | `node_modules/@voltro/cli/templates/agent-docs/database/advancedqueries.md` | Btree, GIN, GiST, BRIN, HNSW — when to use what, plus partial + expression + composite indexes. |
| database.columnTypes | `node_modules/@voltro/cli/templates/agent-docs/database/columntypes.md` | Postgres-native ENUM types via dbEnum() — cheap ADD VALUE migrations, full type-narrowing. Falls back to CHECK constraints on other dialects. |
| database.hosting | `node_modules/@voltro/cli/templates/agent-docs/database/hosting.md` | Run Voltro on any hosted Postgres, MySQL, MariaDB, or SQL Server — Supabase, Neon, Vercel Postgres, Railway, Render, Fly.io, AWS RDS, PlanetScale, Azure SQL, and more. Connection strings, pooling, gotchas. |
| database.migrations | `node_modules/@voltro/cli/templates/agent-docs/database/migrations.md` | Voltro's planner-based migration system — diff your declared schema against the live DB, classify each change, refuse-to-apply anything risky without explicit intent. Dev auto-applies, prod refuses. |
| Database | `node_modules/@voltro/cli/templates/agent-docs/database/misc.md` | Branch the live schema and REHEARSE your migration on it — apply the plan to a throwaway copy, flag every lossy operation, prove it converges, drop the branch. Plus the branch primitive itself (namespace snapshot on Postgres, Neon copy-on-write fast-path). |
| Database | `node_modules/@voltro/cli/templates/agent-docs/database/overview.md` | How Voltro talks to Postgres — the schema DSL, the query builder, mixins, migrations, and the reactive engine's relationship to all of it. |
| database.querying | `node_modules/@voltro/cli/templates/agent-docs/database/querying.md` | Three cardinalities, one DSL. Declaration via relations(), eager loading via .with(), reactive invalidation via the two-stage dependency-graph + per-field pre-filter. |
| database.scaling | `node_modules/@voltro/cli/templates/agent-docs/database/scaling.md` | Transparent read-replica routing with read-your-writes (RYW) consistency, multi-instance RYW via Redis, region-aware replica selection, and the per-dialect adapter surface. |
| database.schema | `node_modules/@voltro/cli/templates/agent-docs/database/schema.md` | Five generation schemes — TypeID (default), ULID, numeric, Snowflake, custom. Decision matrix, auto-injection lifecycle, cursor pagination, branded TypeScript types. |
| database.seedsDialects | `node_modules/@voltro/cli/templates/agent-docs/database/seedsdialects.md` | Six SQL backends, one schema DSL. Decision matrix, configuration, boot-log shape, and the cross-dialect feature parity table the framework hides for you. |
| database.transactions | `node_modules/@voltro/cli/templates/agent-docs/database/transactions.md` | How ctx.store behaves inside mutations, workflows, and explicit transaction blocks. |
| Deployment | `node_modules/@voltro/cli/templates/agent-docs/deployment.md` | Voltro Cloud (coming soon) — the managed runtime for your Voltro project. Today the Free control plane registers + observes your self-hosted apps. |
| Internationalization | `node_modules/@voltro/cli/templates/agent-docs/internationalization.md` | Voltro's i18n layer (@voltro/i18n) — an opinionated wrap over react-intl, auto-wired from a single app.config.ts field, with cookie + Accept-Language locale resolution. |
| Introduction | `node_modules/@voltro/cli/templates/agent-docs/introduction.md` | Scaffold a Voltro project and boot it locally in under a minute. |
| Local-first & Mobile | `node_modules/@voltro/cli/templates/agent-docs/local-first-mobile.md` | "@voltro/local-first — CRDT text merge (crdtText/mergeCrdtStates), the offline sync-queue + SyncClient wire, presence/awareness, durable persistence, and the localFirst table mixin. Pure and browser-safe; the React hooks live behind a subpath." |
| Multi-tenancy | `node_modules/@voltro/cli/templates/agent-docs/multi-tenancy.md` | Multi-tenancy as a runtime primitive — the tenant() mixin, ctx.subject.tenantId, automatic read scoping, explicit write gates. |
| Observability | `node_modules/@voltro/cli/templates/agent-docs/observability.md` | OpenTelemetry tracing in Voltro — the auto-emitted spans for every primitive, span attributes and nesting, the three enabling modes (console / OTLP / buffer), and adding your own spans with Effect.withSpan. |
| Plugins | `node_modules/@voltro/cli/templates/agent-docs/plugins.md` | How Voltro plugins compose into the runtime, what they can intercept, the catalogue, and writing your own. |
| Reference | `node_modules/@voltro/cli/templates/agent-docs/reference.md` | The client-side hook surface, grouped by purpose. |
| Releases | `node_modules/@voltro/cli/templates/agent-docs/releases.md` | 0.35 through 0.38 in one pass — the boot-breaking access declarations, the stricter input handling, and the runtime behaviour that moved underneath you. |
| Routing | `node_modules/@voltro/cli/templates/agent-docs/routing.md` | Voltro's file-based router — pages, layouts, render modes, loaders, navigation, islands. The web side of the framework. |
| Scheduling | `node_modules/@voltro/cli/templates/agent-docs/scheduling.md` | Deployment-agnostic scheduled jobs in Voltro — one *.cron.tsx definition that runs unchanged on a single box, a multi-instance fleet, or an external scheduler. |
| Schema-driven UI | `node_modules/@voltro/cli/templates/agent-docs/schema-driven-ui.md` | Project the typed descriptor graph into UI — forms, tables, pickers, and reactive components, all bound to a descriptor with near-zero glue. |
| Security | `node_modules/@voltro/cli/templates/agent-docs/security.md` | How Voltro handles security — reporting a vulnerability, the supply-chain gates (dependency audit, inbound-license allowlist, SBOM), supported versions, and why self-hosting keeps your data yours. |
| templates.apiBackends | `node_modules/@voltro/cli/templates/agent-docs/templates/apibackends.md` | The minimal Voltro backend — app.config + schema + one streaming query + one tenant-guarded mutation. Tenant-aware out of the box. |
| templates.appShells | `node_modules/@voltro/cli/templates/agent-docs/templates/appshells.md` | A marketing landing page — hero, features, CTA. Static-rendered with zero JS on the wire by default. |
| templates.custom | `node_modules/@voltro/cli/templates/agent-docs/templates/custom.md` | Add a template the CLI can scaffold from — a directory under voltro-templates/apps/ with a manifest and the files to copy. |
| templates.mobile | `node_modules/@voltro/cli/templates/agent-docs/templates/mobile.md` | An Expo (React Native) app that is the third consumer of your api — the same typed hooks (useSubscription / useMutation), offline-first by default, typed deep links, and device registration for push. Expo owns Metro; voltro dev runs the sibling api. |
| Templates | `node_modules/@voltro/cli/templates/agent-docs/templates/overview.md` | Dozens of dogfooded starter templates ship with the framework — backend shapes, frontend shapes, a serverless function library, and an Expo mobile app. voltro list-templates is the authority; scaffold any of them with one CLI call. |
| templates.serverless | `node_modules/@voltro/cli/templates/agent-docs/templates/serverless.md` | 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. |
| Testing | `node_modules/@voltro/cli/templates/agent-docs/testing.md` | Voltro's test story — the @voltro/testing package, the test pyramid (unit handlers/tools → workflow runner → e2e), and the voltro test / voltro e2e CLI commands. |
| Workflows | `node_modules/@voltro/cli/templates/agent-docs/workflows.md` | Durable Effect workflows in Voltro — what they are, when to use them, and the current runtime boundaries. |

### Plugins (seeder lists only the INSTALLED ones)

| Plugin | Open | Summary |
|---|---|---|
| ai-flows | `node_modules/@voltro/cli/templates/agent-docs/plugins/ai-flows.md` (or `node_modules/@voltro/plugin-ai-flows/README.md`) | Durable multi-step AI pipelines — deterministic or agentic, with human-in-the-loop, chaining, and cadence. Author flows in code (defineFlow) or as data (visual-editor rows); one engine runs both. |
| analytics-postgres | `node_modules/@voltro/cli/templates/agent-docs/plugins/analytics-postgres.md` (or `node_modules/@voltro/plugin-analytics-postgres/README.md`) | First-party lite AnalyticsSink — stores events in the main DataStore, cross-dialect, zero external infra. ~10M events/day ceiling. |
| atlassian | `node_modules/@voltro/cli/templates/agent-docs/plugins/atlassian.md` (or `node_modules/@voltro/plugin-atlassian/README.md`) | JiraService + ConfluenceService over the Atlassian REST / Greenhopper / Agile APIs, with a per-subject PAT resolver, transient retry, SSRF guard, an avatar proxy, and per-tenant caching. |
| audit | `node_modules/@voltro/cli/templates/agent-docs/plugins/audit.md` (or `node_modules/@voltro/plugin-audit/README.md`) | Mutation audit log — sinks (console/memory/custom), include/exclude filters, the audit() mixin, testing with the memory buffer. |
| auth | `node_modules/@voltro/cli/templates/agent-docs/plugins/auth.md` (or `node_modules/@voltro/plugin-auth/README.md`) | Password + session-cookie auth — overview. Full docs in the Authentication section. |
| auth-auth0 | `node_modules/@voltro/cli/templates/agent-docs/plugins/auth-auth0.md` (or `node_modules/@voltro/plugin-auth-auth0/README.md`) | Auth0 AuthStrategy — verifies Auth0-issued JWTs via the tenant's JWKS (no client secret) and maps a namespaced custom claim → tenantId. |
| auth-clerk | `node_modules/@voltro/cli/templates/agent-docs/plugins/auth-clerk.md` (or `node_modules/@voltro/plugin-auth-clerk/README.md`) | Clerk AuthStrategy — verifies Clerk-issued __session JWTs via the Frontend API JWKS (no secret key) and maps org_id → tenantId. |
| auth-kinde | `node_modules/@voltro/cli/templates/agent-docs/plugins/auth-kinde.md` (or `node_modules/@voltro/plugin-auth-kinde/README.md`) | Kinde AuthStrategy — verifies Kinde-issued JWTs via JWKS at the configured issuer (no client secret) and maps org_code → tenantId. |
| auth-oidc | `node_modules/@voltro/cli/templates/agent-docs/plugins/auth-oidc.md` (or `node_modules/@voltro/plugin-auth-oidc/README.md`) | Generic OIDC AuthStrategy — verifies any OpenID-Connect IdP's JWTs via JWKS (Okta, Keycloak, Cognito, Azure AD, Google Workspace). Discovery or explicit JWKS URL; maps a claim → tenantId. |
| auth-social | `node_modules/@voltro/cli/templates/agent-docs/plugins/auth-social.md` (or `node_modules/@voltro/plugin-auth-social/README.md`) | First-party Sign in with Google / GitHub / Apple — mandatory PKCE + state, JWKS-verified ID tokens, a deliberate account-linking policy, no identity vendor. |
| auth-supabase | `node_modules/@voltro/cli/templates/agent-docs/plugins/auth-supabase.md` (or `node_modules/@voltro/plugin-auth-supabase/README.md`) | Supabase Auth (GoTrue) AuthStrategy — verifies Supabase-issued JWTs via the project's JWKS and maps app_metadata.tenant_id → tenantId. |
| auth-workos | `node_modules/@voltro/cli/templates/agent-docs/plugins/auth-workos.md` (or `node_modules/@voltro/plugin-auth-workos/README.md`) | WorkOS AuthStrategy — verifies WorkOS AuthKit / SSO JWTs via JWKS (no API key) and maps org_id → tenantId. |
| billing | `node_modules/@voltro/cli/templates/agent-docs/plugins/billing.md` (or `node_modules/@voltro/plugin-billing/README.md`) | Subscriptions, plans, entitlements, and usage metering over a pluggable provider (Stripe + mock). Money is integer minor units. |
| broadcast | `node_modules/@voltro/cli/templates/agent-docs/plugins/broadcast.md` (or `node_modules/@voltro/plugin-broadcast/README.md`) | Cross-replica reactivity over a pub/sub bus (Redis / NATS) for non-postgres dialects — closes the single-instance gap so a write on one pod surfaces on another. |
| cdc-out | `node_modules/@voltro/cli/templates/agent-docs/plugins/cdc-out.md` (or `node_modules/@voltro/plugin-cdc-out/README.md`) | Declaratively mirror table changes outward to external sinks (webhook, plus a CdcSink interface for custom sinks) through a durable outbox — ordered per pipe, at-least-once from enqueue, retried with backoff, dead-lettered. |
| clickhouse | `node_modules/@voltro/cli/templates/agent-docs/plugins/clickhouse.md` (or `node_modules/@voltro/plugin-clickhouse/README.md`) | Production-grade OLAP AnalyticsSink over ClickHouse — self-hosted or ClickHouse Cloud — for billions of events with millisecond aggregates. |
| datadog | `node_modules/@voltro/cli/templates/agent-docs/plugins/datadog.md` (or `node_modules/@voltro/plugin-datadog/README.md`) | Agentless Datadog metrics exporter — pushes the unified Metrics-API to Datadog's /api/v2/series HTTP intake. |
| deactivation | `node_modules/@voltro/cli/templates/agent-docs/plugins/deactivation.md` (or `node_modules/@voltro/plugin-deactivation/README.md`) | A schema mixin that marks a subject as deactivated (can't log in) while keeping its data fully visible — the deliberate opposite of soft-delete. |
| duckdb | `node_modules/@voltro/cli/templates/agent-docs/plugins/duckdb.md` (or `node_modules/@voltro/plugin-duckdb/README.md`) | Embedded DuckDB AnalyticsSink — real column-store OLAP in-process, no external service to run. |
| flags | `node_modules/@voltro/cli/templates/agent-docs/plugins/flags.md` (or `node_modules/@voltro/plugin-flags/README.md`) | Feature flags — per-subject / per-tenant targeting, deterministic % rollouts, kill-switch, declarative rpc gating + client UI gating. |
| governance | `node_modules/@voltro/cli/templates/agent-docs/plugins/governance.md` (or `node_modules/@voltro/plugin-governance/README.md`) | Data governance — retention TTL sweep, GDPR export + erasure, consent ledger, and field-level encryption for .encrypted() columns. Builds on audit + soft-delete. |
| licensing | `node_modules/@voltro/cli/templates/agent-docs/plugins/licensing.md` (or `node_modules/@voltro/plugin-licensing/README.md`) | Offline-verified EdDSA license keys + cloud-issued entitlement snapshots that feed plugin-billing; pricing decided server-side, never baked into a published version. |
| logship | `node_modules/@voltro/cli/templates/agent-docs/plugins/logship.md` (or `node_modules/@voltro/plugin-logship/README.md`) | Ship structured logs to Better Stack / Axiom / Loki / any HTTP sink — batched, redacted, fail-soft. Rides the framework log-sink hook. |
| mail | `node_modules/@voltro/cli/templates/agent-docs/plugins/mail.md` (or `node_modules/@voltro/plugin-mail/README.md`) | Transactional email — Resend / Postmark / SendGrid / SMTP, React-Email templates with auto-discovery, per-tenant suppression, bounce/complaint handling, durable delivery via workflows. |
| moderation | `node_modules/@voltro/cli/templates/agent-docs/plugins/moderation.md` (or `node_modules/@voltro/plugin-moderation/README.md`) | Moderate user content before it commits — keyword denylist or AI provider, block or flag via rpc interceptor, plus an in-handler redact helper. |
| multitenancy | `node_modules/@voltro/cli/templates/agent-docs/plugins/multitenancy.md` (or `node_modules/@voltro/plugin-multitenancy/README.md`) | The tenant() schema mixin (auto-scoped reads, auto-filled inserts, tenant-resolved keyed writes), the assertOwnTenant write-guard, and the typed TenantMismatch error. |
| notifications | `node_modules/@voltro/cli/templates/agent-docs/plugins/notifications.md` (or `node_modules/@voltro/plugin-notifications/README.md`) | Unified notifications — one send API across email / Slack / SMS / push / in-app, with per-user channel preferences, an in-app inbox, and delivery records. |
| openapi | `node_modules/@voltro/cli/templates/agent-docs/plugins/openapi.md` (or `node_modules/@voltro/plugin-openapi/README.md`) | Generate an OpenAPI 3.1 spec + Swagger-UI docs from your defineRestRoute descriptors and (opt-in) your rpc procedures. Your routes ARE the API docs — nothing hand-maintained. |
| postgis | `node_modules/@voltro/cli/templates/agent-docs/plugins/postgis.md` (or `node_modules/@voltro/plugin-postgis/README.md`) | Postgres-native geography / geometry columns, geometry constructors (point/line/polygon/multi/GeoJSON), spatial predicates (ST_DWithin, ST_Within, ST_Contains, ST_Intersects, ST_Buffer, bbox &&), ST_Distance projection + <-> KNN ordering, and GiST indexes via expressionIndex. Postgres-only by design. |
| posthog | `node_modules/@voltro/cli/templates/agent-docs/plugins/posthog.md` (or `node_modules/@voltro/plugin-posthog/README.md`) | Track-only AnalyticsSink that forwards events to PostHog's /capture endpoint — compose it with a second sink that owns reads. |
| presence | `node_modules/@voltro/cli/templates/agent-docs/plugins/presence.md` (or `node_modules/@voltro/plugin-presence/README.md`) | Ephemeral realtime presence — who's online in a channel, with heartbeat, live roster, and per-member metadata (status, cursor). Works cross-instance. |
| prometheus | `node_modules/@voltro/cli/templates/agent-docs/plugins/prometheus.md` (or `node_modules/@voltro/plugin-prometheus/README.md`) | Prometheus exporter — scrapes the unified Metrics-API at GET /metrics in text exposition format. |
| ratelimit | `node_modules/@voltro/cli/templates/agent-docs/plugins/ratelimit.md` (or `node_modules/@voltro/plugin-ratelimit/README.md`) | Per-endpoint, per-subject and per-tenant request limits via the rpc interceptors. Sliding-window / fixed-window / token-bucket, memory / postgres / redis stores. |
| rbac | `node_modules/@voltro/cli/templates/agent-docs/plugins/rbac.md` (or `node_modules/@voltro/plugin-rbac/README.md`) | Roles + permissions + the permission() handler guard. Roles compile to scopes. |
| row-history | `node_modules/@voltro/cli/templates/agent-docs/plugins/row-history.md` (or `node_modules/@voltro/plugin-row-history/README.md`) | Full row history + time-travel. audit() records who/when; row-history records what-changed-to-what — a value snapshot of every row on every write, with as-of queries. |
| scim | `node_modules/@voltro/cli/templates/agent-docs/plugins/scim.md` (or `node_modules/@voltro/plugin-scim/README.md`) | SCIM 2.0 provisioning — Users + Groups REST endpoints so an enterprise IdP (Okta, Entra, OneLogin) can create / update / deactivate users in your app. |
| search | `node_modules/@voltro/cli/templates/agent-docs/plugins/search.md` (or `node_modules/@voltro/plugin-search/README.md`) | Keep an external search index (Typesense / Meilisearch / Algolia) in sync with your tables via the ChangeEvent tap, query it tenant-scoped through a typed action + hook. |
| sentry | `node_modules/@voltro/cli/templates/agent-docs/plugins/sentry.md` (or `node_modules/@voltro/plugin-sentry/README.md`) | Deep Sentry integration — errors correlated to the distributed trace, breadcrumbs from the log sink, and opt-in performance traces. |
| soft-delete | `node_modules/@voltro/cli/templates/agent-docs/plugins/soft-delete.md` (or `node_modules/@voltro/plugin-soft-delete/README.md`) | The softDelete() schema mixin — deletedAt / deletedBy columns, delete() redirected to an UPDATE, default reads filtered, hardDelete() bypass. |
| sso-saml | `node_modules/@voltro/cli/templates/agent-docs/plugins/sso-saml.md` (or `node_modules/@voltro/plugin-sso-saml/README.md`) | Enterprise SAML 2.0 SSO — SP-initiated login, ACS assertion consumer, SP metadata. Signature verification via @node-saml/node-saml; framework session minting built in. |
| storage | `node_modules/@voltro/cli/templates/agent-docs/plugins/storage.md` (or `node_modules/@voltro/plugin-storage/README.md`) | File storage behind one StorageService — public objects served direct from the bucket/CDN, private objects gated by an access policy + per-object grants. S3 / MinIO (R2 and GCS via their S3 interop) / Azure / database / filesystem / memory providers, presigned URLs, a dashboard browser. |
| tinybird | `node_modules/@voltro/cli/templates/agent-docs/plugins/tinybird.md` (or `node_modules/@voltro/plugin-tinybird/README.md`) | Hosted-ClickHouse AnalyticsSink over Tinybird's Events API + Pipes — pay-as-you-go OLAP without operating a cluster. |
| webhooks | `node_modules/@voltro/cli/templates/agent-docs/plugins/webhooks.md` (or `node_modules/@voltro/plugin-webhooks/README.md`) | First-class outgoing + incoming webhooks — declared events with a webhook: block, defineIncomingWebhook in *.webhook.tsx files, runtime subscriptions, durable delivery via @effect/workflow, HMAC signing, provider presets, and idempotency. |