@voltro/cli 0.30.1 → 0.31.0

package/templates/agent-docs/plugins/clickhouse.md

@@ -0,0 +1,91 @@
+# ClickHouse
+
+> Production-grade OLAP AnalyticsSink over ClickHouse — self-hosted or ClickHouse Cloud — for billions of events with millisecond aggregates.
+
+
+
+---
+
+<!-- source: en/plugins/clickhouse.md -->
+## ClickHouse
+
+_Production-grade OLAP AnalyticsSink over ClickHouse — self-hosted or ClickHouse Cloud — for billions of events with millisecond aggregates._
+
+`@voltro/plugin-clickhouse` is the production `AnalyticsSink` for analytics at
+scale — native HTTP ingest into a ClickHouse cluster (self-hosted **or**
+ClickHouse Cloud, both via the official `@clickhouse/client`). The sink owns an
+`events` table inside the configured database (a MergeTree engine created on
+first boot) and implements all four contract methods. Reach for it when
+[postgres-lite](/docs/plugins/analytics-postgres) hits its ~10M events/day
+ceiling and you need millisecond aggregate queries over billions of rows. For
+the shared `AnalyticsSink` API and the `useAnalytics()` read methods, see
+[Analytics & warehouse sinks](/docs/plugins/analytics).
+
+## Install
+
+```
+pnpm add @voltro/plugin-clickhouse
+```
+
+## Wiring
+
+```ts
+// app.config.ts
+import { clickhouseAnalytics } from '@voltro/plugin-clickhouse'
+
+export default {
+  type:      'api' as const,
+  name:      'myApi',
+  store:     'postgres' as const,
+  analytics: clickhouseAnalytics({
+    url:      process.env.CLICKHOUSE_URL!,   // https://my-cluster.clickhouse.cloud
+    username: process.env.CLICKHOUSE_USER,
+    password: process.env.CLICKHOUSE_PASSWORD,
+    database: 'voltro_events',               // optional, default 'default'
+  }),
+}
+```
+
+At boot the plugin opens the client, pings the cluster (fail-fast on bad
+config), and creates the events table + any mirror tables. The client is closed
+on graceful shutdown.
+
+## Options
+
+`clickhouseAnalytics(options)`:
+
+| Option | Type | Default | Notes |
+|---|---|---|---|
+| `url` | `string` | — (**required**) | HTTP URL of the ClickHouse server, incl. protocol + port. |
+| `username` | `string` | — | |
+| `password` | `string` | — | |
+| `database` | `string` | `'default'` | The plugin creates the events table inside it on first boot. |
+| `table` | `string` | `'events'` | Override the events-table name. |
+| `mirrorTables` | `ReadonlyArray<string>` | `[]` (events-only) | Reactive tables to CDC-mirror into `voltro_mirror_<table>` (a `ReplacingMergeTree`) so analytical queries JOIN events against live user data. |
+| `mirrorPrimaryKey` | `string` | `'id'` | Primary-key column on the mirrored source rows. |
+
+`database`, `table`, and each `mirrorTables` entry are validated as SQL
+identifiers at boot (they're interpolated into DDL) — a bad name fails loudly at
+`app.config` eval, not on the first query.
+
+> **Connection details come from `options`, not env.** The plugin reads no
+> `CLICKHOUSE_*` variables itself — the example above wires `process.env` into
+> the options. Use `@voltro/env`'s `defineEnv` to declare them as secrets.
+
+## No raw-client escape hatch
+
+ClickHouse-specific features outside the cross-provider contract
+(HyperLogLog, dictionaries, materialised views) are not reachable through
+the plugin — it exposes no raw `@clickhouse/client` handle; the
+`AnalyticsSink` contract is the extension seam. Where you need them, query
+ClickHouse with your own client instance against the same tables.
+
+Using the Tag binds your handler to ClickHouse — stay on `useAnalytics()` for
+provider-portable code. The plugin also exports `EVENTS_TABLE_DDL` and
+`MIRROR_TABLE_DDL` for advanced schema work.
+
+## See also
+
+- [Analytics & warehouse sinks](/docs/plugins/analytics) — the shared
+  `AnalyticsSink` contract, the `useAnalytics()` read API, `composeAnalytics`,
+  and the CDC-mirror details.

package/templates/agent-docs/plugins/datadog.md

@@ -0,0 +1,105 @@
+# Datadog
+
+> Agentless Datadog metrics exporter — pushes the unified Metrics-API to Datadog's /api/v2/series HTTP intake.
+
+
+
+---
+
+<!-- source: en/plugins/datadog.md -->
+## Datadog
+
+_Agentless Datadog metrics exporter — pushes the unified Metrics-API to Datadog's /api/v2/series HTTP intake._
+
+`@voltro/plugin-datadog` pushes the framework's metrics straight to Datadog over HTTP — **no Agent, no OTLP collector**. It periodically snapshots the unified Metrics-API (the same Effect `MetricRegistry` that [`@voltro/plugin-prometheus`](/docs/plugins/prometheus) and the dashboard read) and POSTs to `/api/v2/series`.
+
+> **Have a Datadog Agent (or run an OTLP collector)?** Prefer the OTLP path: point `OTEL_EXPORTER_OTLP_ENDPOINT` at the Agent's OTLP port — the framework's [runtime metrics export](/docs/observability/overview#metrics-export) covers it without this plugin. Reach for this plugin when you have NO Agent (serverless, edge, a box you don't control).
+
+## Wiring
+
+```ts
+// app.config.ts
+import { datadogPlugin } from '@voltro/plugin-datadog'
+
+export default {
+  type: 'api' as const,
+  name: 'api',
+  plugins: [
+    datadogPlugin({
+      // apiKey defaults to DD_API_KEY; without it the plugin is a no-op.
+      site: 'datadoghq.com',          // DD_SITE; EU → 'datadoghq.eu', US3 → 'us3.datadoghq.com'
+      intervalMs: 30_000,
+      prefix: 'voltro.',              // optional metric-name prefix
+      tags: ['env:prod', 'service:api'],
+    }),
+  ],
+}
+```
+
+Without an API key the plugin logs a warning and stays inert — it never blocks boot, and a Datadog outage is fail-soft (logged, never thrown).
+
+## Mapping
+
+Every sample is submitted as a Datadog **gauge** (`type: 3`) at its current value, with metric labels turned into `key:value` tags (plus your global `tags`):
+
+| Framework metric | Datadog |
+|---|---|
+| counter (e.g. `voltro_rpc_requests_total`) | gauge at the cumulative value — use `.as_count()` / `diff()` in a Datadog query to recover the per-interval rate |
+| gauge (e.g. `voltro_subscriptions_active`) | gauge at the current value |
+| histogram (e.g. `voltro_rpc_duration_seconds`) | `<name>.count`, `<name>.sum`, `<name>.avg` (sum/count) |
+
+Counters are submitted cumulatively (stateless exporter — no previous-value tracking); Datadog query functions recover the rate. Summary/frequency metrics aren't produced by the framework and are skipped.
+
+## Deep integration — logs + traces + profiling
+
+Beyond agentless metrics, opt into the full trace-correlated stack:
+
+```ts
+datadogPlugin({
+  apiKey: env.DD_API_KEY,
+  service: 'api', env: 'prod', version: '1.4.2',  // DD unified service tagging
+  logs: true,        // forward the framework log sink → /api/v2/logs
+  traces: true,      // framework spans → the Datadog Agent's OTLP receiver
+  agentUrl: 'http://localhost:4318',  // or DD_TRACE_AGENT_URL
+  profiling: true,   // dd-trace continuous profiler (profiler-only mode)
+})
+```
+
+- **Logs (`logs:true`)** — every framework log line is batched + POSTed to Datadog's logs intake with `dd.trace_id` / `dd.span_id` (the lower 64 bits of the OTel trace id, as Datadog expects) so logs link to APM traces. Maps `level → status`, `scope → an attribute`, and the structured fields through.
+- **Traces (`traces:true`)** — the framework's OTel spans are routed to the **Datadog Agent's OTLP receiver** (Datadog's official OpenTelemetry ingestion). This is the deep path: the framework keeps owning the tracer (the in-app [Traces dashboard](/docs/observability/distributed-tracing) stays intact) and the Agent forwards to DD APM. `dd-trace` is **not** used as the tracer — it would have to become the global provider, which would break the in-app dashboard.
+- **Profiling (`profiling:true`)** — the official `dd-trace` continuous profiler, started in profiler-only mode (`tracing:false`) so it never hijacks the OTel tracer.
+
+`dd-trace` + the OTel exporter packages are optional, lazy-loaded dependencies.
+
+> **No Agent?** Metrics + logs are agentless (HTTP intake). Traces need an Agent — point `agentUrl` at it. If you already run an OTLP collector, you can also export traces+metrics via the framework's runtime OTLP path (`OTEL_EXPORTER_OTLP_ENDPOINT`) without this plugin.
+
+## Configuration
+
+| Option | Type | Default | Notes |
+|---|---|---|---|
+| `apiKey` | `string` | `DD_API_KEY` env | Needed for metrics + logs (agentless). Traces use the Agent and don't need it. |
+| `site` | `string` | `DD_SITE` env / `datadoghq.com` | EU → `datadoghq.eu`, US3 → `us3.datadoghq.com`, … |
+| `intervalMs` | `number` | `30000` | Metrics push interval. |
+| `prefix` | `string` | — | Prepended to every metric name (e.g. `voltro.`). |
+| `tags` | `string[]` | — | Added to every series + log (`['env:prod','service:api']`). |
+| `logs` | `boolean` | `false` | Forward the framework log sink → `/api/v2/logs`. |
+| `logsIntervalMs` | `number` | `5000` | Logs batch flush interval. |
+| `traces` | `boolean` | `false` | Route framework spans → the Agent's OTLP receiver. |
+| `agentUrl` | `string` | `DD_TRACE_AGENT_URL` / `http://localhost:4318` | `/v1/traces` is appended. |
+| `profiling` | `boolean` | `false` | dd-trace continuous profiler (profiler-only mode). |
+| `service` / `env` / `version` | `string` | `DD_SERVICE` / `DD_ENV` / `DD_VERSION` | DD unified service tagging — consistent across metrics, logs + traces. |
+| `name` | `string` | — | Disambiguates multiple instances. |
+
+## Troubleshooting
+
+| Symptom | Cause / fix |
+|---|---|
+| Boot logs `datadog inactive` | No `DD_API_KEY` **and** neither `traces` nor `profiling` enabled — nothing to do. Set a key (metrics/logs) or `traces`/`profiling`. |
+| Metrics/logs don't appear | `apiKey` missing or wrong `site` region. A failed POST is fail-soft — check `voltro logs` for `datadog series/logs POST failed`. |
+| `traces: true` but nothing in DD APM | The Agent's OTLP receiver must be enabled and reachable at `agentUrl` (`/v1/traces`). No Agent → traces won't ship (metrics/logs still do). |
+| Logs not linked to traces in DD | Correlation needs `dd.trace_id` — emitted only for log lines carrying `fields.traceId` (i.e. inside an rpc trace). Set `service` so DD groups them. |
+| In-app Traces dashboard intact? | Yes — the contributed OTLP exporter is added alongside the framework's buffer sink; it never replaces the tracer. |
+
+## Permissions
+
+The plugin declares `network:outbound:<site>` (metrics/logs) — plus `network:outbound:<agent-host>` when `traces`/`profiling` is on. It mounts no routes and intercepts nothing.

package/templates/agent-docs/plugins/deactivation.md

@@ -0,0 +1,114 @@
+# Deactivation
+
+> 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.
+
+
+
+---
+
+<!-- source: en/plugins/deactivation.md -->
+## Deactivation
+
+_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._
+
+`@voltro/plugin-deactivation` ships a single surface: the `deactivation()` schema mixin. A deactivated subject — typically a user who can no longer log in — has its data stay fully **visible** (assignments, history, audit trail). That's the deliberate opposite of `softDelete()`, which **hides** the row from default reads and anonymises PII for GDPR.
+
+**Status:** ✓ shipped.
+
+## What it adds
+
+The mixin contributes two columns:
+
+| Column | Type | Meaning |
+|---|---|---|
+| `deactivatedAt` | nullable timestamp | set ⇒ the subject is deactivated; `null` ⇒ active |
+| `deactivatedBy` | nullable reference → Actor | who performed the deactivation |
+
+It's a **pure schema mixin** (columns only), exactly like `audit()` — no read scoping, no delete interception. You set `deactivatedAt` with a normal `ctx.store.update(...)`.
+
+`deactivation()` transitively requires `audit()` (a deactivation is an audit-worthy event, and the timestamps sit together on the row), so `audit()` auto-stamps `updatedAt` / `updatedBy` alongside — the WHO/WHEN of the change is captured for free. Its stable id is `voltro/deactivation`.
+
+## Composing it
+
+```ts
+import { id, table, text } from '@voltro/database'
+import { deactivation } from '@voltro/plugin-deactivation'
+
+export const users = table('users', {
+  id:    id(),
+  email: text().unique(),
+  name:  text(),
+}).with(deactivation())
+```
+
+The dep resolver dedupes, so listing `audit()` explicitly alongside is harmless:
+
+```ts
+import { audit } from '@voltro/plugin-audit/mixin'
+import { deactivation } from '@voltro/plugin-deactivation'
+
+table('users', { /* … */ }).with(audit(), deactivation())
+```
+
+A project that doesn't want the barrel can import from the `./mixin` subpath:
+
+```ts
+import { deactivation } from '@voltro/plugin-deactivation/mixin'
+```
+
+## Deactivating + reactivating
+
+Both are plain updates — `audit()` records the actor and time:
+
+```ts
+// deactivate — update(table, primaryKey, patch)
+await ctx.store.update('users', userId, {
+  deactivatedAt: new Date(),
+  deactivatedBy: ctx.request.subject.id,
+})
+
+// reactivate
+await ctx.store.update('users', userId, {
+  deactivatedAt: null,
+  deactivatedBy: null,
+})
+```
+
+Because the row is never hidden, your own queries decide what "active" means — the user stays visible everywhere in the app while their login is refused.
+
+## Enforcing "a deactivated user can't log in"
+
+The mixin's promise is **self-enforcing** through `@voltro/plugin-auth`'s post-authentication subject-guard seam — you do **not** hand-roll a `deactivatedAt === null` check in an auth resolver. Import `deactivationGuard()` from the `/guard` subpath and wire it onto the auth plugin in one line:
+
+```ts
+import { authRoutesPlugin } from '@voltro/plugin-auth/plugin'
+import { deactivationGuard } from '@voltro/plugin-deactivation/guard'
+
+authRoutesPlugin({
+  store,
+  secret: process.env.VOLTRO_SESSION_SECRET!,
+  defaultTenantId: 'acme',
+  subjectGuards: [deactivationGuard()],
+})
+```
+
+The auth pipeline runs each subject guard **after** the credential check (password / MFA / magic-link / passkey) but **before** it issues a session. When the resolved user's `deactivatedAt` is set, `deactivationGuard()` vetoes: the login returns a **403** whose body `error` is `account_deactivated`, and **no session cookie is issued** — on every sign-in path. Reactivate the user (`deactivatedAt = null`) and the next login proceeds normally. See the [auth plugin's subject-guard seam](/docs/plugins/auth#post-authentication-subject-guards).
+
+`AccountDeactivated` — a `Schema.TaggedError` on the same `/guard` subpath — is the typed form of the rejection for code that prefers matching on `_tag === 'AccountDeactivated'` over the wire body. The `/guard` subpath is **server-only** and is not imported by the mixin, so a `*.entity.ts` importing `deactivation()` never drags the auth surface into the browser bundle.
+
+## Deactivation vs soft-delete
+
+| | `deactivation()` | `softDelete()` |
+|---|---|---|
+| Row visible in default reads | yes | no (hidden) |
+| PII | untouched | anonymised |
+| Typical use | user can't log in, data stays | GDPR erasure / "delete" |
+| Read scoping | none | filters hidden rows out |
+
+The two are **orthogonal and compose**. A user can be deactivated (visible) and later soft-deleted (hidden) — apply both mixins.
+
+## When to use which
+
+- **Deactivation** — revoke access but keep the subject's contributions intact and attributable (the common "disable an employee account" case).
+- **Soft-delete** — the user must disappear from the app and their PII must be scrubbed.
+- **Both** — start with deactivation, escalate to soft-delete if an erasure request arrives.

package/templates/agent-docs/plugins/duckdb.md

@@ -0,0 +1,82 @@
+# DuckDB
+
+> Embedded DuckDB AnalyticsSink — real column-store OLAP in-process, no external service to run.
+
+
+
+---
+
+<!-- source: en/plugins/duckdb.md -->
+## DuckDB
+
+_Embedded DuckDB AnalyticsSink — real column-store OLAP in-process, no external service to run._
+
+`@voltro/plugin-duckdb` is the embedded `AnalyticsSink` — it runs DuckDB
+**in-process** (via `@duckdb/node-api`) so you get real column-store +
+vectorized OLAP performance without deploying an external service. Events land
+in a `voltro_events` column-store table inside the DuckDB instance; the sink
+implements all four contract methods against it. It's the sweet spot between
+[postgres-lite](/docs/plugins/analytics-postgres) (no infra, but row-store) and
+[ClickHouse](/docs/plugins/clickhouse) (fastest, but an external cluster). The
+catch: it's single-process. For the shared `AnalyticsSink` API and the
+`useAnalytics()` read methods, see [Analytics & warehouse sinks](/docs/plugins/analytics).
+
+## Install
+
+```
+pnpm add @voltro/plugin-duckdb
+```
+
+`@duckdb/node-api` is an optional dependency — installed alongside the plugin.
+
+## Wiring
+
+```ts
+// app.config.ts
+import { duckdbAnalytics } from '@voltro/plugin-duckdb'
+
+export default {
+  type:      'api' as const,
+  name:      'myApi',
+  store:     'postgres' as const,
+  analytics: duckdbAnalytics({ path: '.voltro/analytics.duckdb' }),
+}
+```
+
+At boot the plugin opens the DuckDB connection and creates the events table; the
+connection + instance are closed on graceful shutdown.
+
+## Options
+
+`duckdbAnalytics(options?)` — all optional:
+
+| Option | Type | Default | Notes |
+|---|---|---|---|
+| `path` | `string` | in-memory | A file path (`.voltro/analytics.duckdb`) → durable across restarts, single-process. Omit or pass `:memory:` → events live in process memory, lost on restart (ephemeral dev / tests). |
+| `mirrorTables` | `ReadonlyArray<string>` | `[]` (events-only) | Reactive tables to CDC-mirror into `voltro_mirror_<table>` inside DuckDB so analytical queries JOIN events against live user data. |
+| `mirrorPrimaryKey` | `string` | `'id'` | Primary-key column on the mirrored source rows. |
+
+```ts
+analytics: duckdbAnalytics({
+  path: '.voltro/analytics.duckdb',
+  mirrorTables: ['users', 'teams'],
+})
+```
+
+## Tenant isolation
+
+Parity with [postgres-lite](/docs/plugins/analytics-postgres): `track` stamps the event's `tenantId` into a `tenant_id` column, and `aggregate`/`timeseries`/`topN` filter by the query's `tenantId` (injected by `useAnalytics()` from the caller's subject), so a tenant-scoped read never spans tenants. A query with no `tenantId` is an unscoped system read. Swapping `postgresAnalytics()` → `duckdbAnalytics()` preserves the same tenant semantics.
+
+## Single-process constraint
+
+DuckDB can't open the same file from two workers. For multi-instance
+deployments, either pin all analytics traffic to one replica
+(sticky-session style) or use [`@voltro/plugin-clickhouse`](/docs/plugins/clickhouse)
+instead. There is no provider escape-hatch Tag — the contract methods are the
+whole surface.
+
+## See also
+
+- [Analytics & warehouse sinks](/docs/plugins/analytics) — the shared
+  `AnalyticsSink` contract, the `useAnalytics()` read API, `composeAnalytics`,
+  and the CDC-mirror details (incl. the `voltro_mirror_<table>` JOIN pattern).

package/templates/agent-docs/plugins/flags.md

@@ -0,0 +1,146 @@
+# Feature flags
+
+> Feature flags — per-subject / per-tenant targeting, deterministic % rollouts, kill-switch, declarative rpc gating + client UI gating.
+
+
+
+---
+
+<!-- source: en/plugins/flags.md -->
+## Feature flags
+
+_Feature flags — per-subject / per-tenant targeting, deterministic % rollouts, kill-switch, declarative rpc gating + client UI gating._
+
+`@voltro/plugin-flags` is feature flags done the framework way: flags as code (or runtime-toggleable), evaluated per caller with **targeting + deterministic % rollout**, gating rpc calls declaratively and the UI via a hook.
+
+## Wiring
+
+```ts
+// app.config.ts
+import { flagsPlugin } from '@voltro/plugin-flags'
+
+export default {
+  type: 'api' as const,
+  name: 'api',
+  plugins: [
+    flagsPlugin({
+      flags: {
+        betaExport: false,                                            // kill-switch
+        newDashboard: { rollout: 25, description: 'Gradual rollout' }, // 25% of subjects
+        aiSummaries: { targeting: [{ metadata: { plan: 'pro' } }] },   // pro plans only
+      },
+      // Optional: fail a gated rpc with typed `FlagDisabled` BEFORE the handler runs.
+      gatedBy: { 'reports.export': 'betaExport' },
+    }),
+  ],
+}
+```
+
+A flag is a bare boolean (kill-switch) or `{ enabled?, rollout?, targeting?, rolloutBy?, variants?, offVariant?, schedule?, description? }`.
+
+## Evaluation order
+
+`enabled:false` (off for everyone) → **schedule** (time-box + ramp, see below) → **targeting** (OR-of-rules; each rule ANDs `subjectIds` / `tenantIds` / `subjectTypes` / `metadata`) → **% rollout** (0–100, deterministic FNV-1a bucket on the subject — or tenant via `rolloutBy:'tenant'` — so a caller stays in/out consistently across processes).
+
+## Multivariate / variant flags
+
+Beyond boolean on/off, a flag can carry a set of **variants** — named string / number / boolean / JSON values the flag resolves ONE of per subject. Allocation is deterministic and weighted: a subject stays in the same variant across calls and processes (an FNV-1a hash of `(flag:variant, id)`, independent of the % rollout bucket). Omit `weight` for an even split; `[{weight:3}, {weight:1}]` is a 75% / 25% split.
+
+```ts
+flagsPlugin({
+  flags: {
+    checkoutButton: {
+      variants: [
+        { name: 'control', value: 'Buy now' },
+        { name: 'urgent',  value: 'Buy now — 2 left!', weight: 2 }, // 2× exposure
+      ],
+    },
+    pricingConfig: {
+      // JSON / number variants, not just strings
+      variants: [
+        { name: 'a', value: { plan: 'pro', seats: 5 } },
+        { name: 'b', value: { plan: 'pro', seats: 10 } },
+      ],
+    },
+  },
+})
+```
+
+Resolve the served variant in the browser with `useVariant` / `useVariants`:
+
+```tsx
+import { useVariant } from '@voltro/plugin-flags/web'
+
+const v = useVariant('checkoutButton')   // { name, value, enabled } | undefined
+return <button>{String(v?.value ?? 'Buy now')}</button>
+```
+
+Server-side, `evaluateVariant(key, value, subject)` returns `{ name, value, enabled }`. A boolean flag surfaces a synthetic `{ name: 'on' | 'off', value, enabled }`, so every flag has a uniform variant shape. Set `offVariant: '<name>'` to make the boolean resolution (`isFlagEnabled` / `flags.evaluate`) treat one variant as "off".
+
+## Scheduled / time-boxed rollouts
+
+A flag can carry a `schedule`, evaluated against the current time:
+
+```ts
+flagsPlugin({
+  flags: {
+    // Time-boxed: off before activateAt, on inside, off at/after deactivateAt.
+    blackFridayBanner: {
+      schedule: { activateAt: '2026-11-27T00:00:00Z', deactivateAt: '2026-11-28T00:00:00Z' },
+    },
+    // Ramping rollout: exposure grows 0% → 100% linearly across the window.
+    gradualLaunch: {
+      schedule: { ramp: { from: 0, to: 100, startAt: '2026-07-01T00:00:00Z', endAt: '2026-07-08T00:00:00Z' } },
+    },
+  },
+})
+```
+
+Instants are epoch millis or ISO strings. A `ramp`'s interpolated percentage REPLACES the static `rollout` while active (before `startAt` ⇒ `from`%, after `endAt` ⇒ `to`%), so exposure increases smoothly over the window while every subject's in/out decision stays deterministic.
+
+## Audit trail of kill-switch flips
+
+On the `postgres` tier every `/toggle` flip is recorded to a durable, append-only `_voltro_feature_flag_audit` table (who, when, flag, old→new state). Read the trail — newest-first — via the inspect endpoint:
+
+```http
+GET /_voltro/inspect/plugins/flags/audit           # all flips, newest-first
+GET /_voltro/inspect/plugins/flags/audit?flag=beta # one flag's history
+```
+
+The `POST /toggle` body accepts an optional `actor` (the acting admin id) that is stored on the audit row. On the `memory` tier there is no durable audit (the endpoint returns an empty trail with a note).
+
+## Three ways to use a flag
+
+**1. Declarative gate** — `gatedBy: { '<rpcTag>': '<flag>' }` (exact tag or `/regex/`). An off flag fails the call with typed `FlagDisabled` before the handler runs (merged into every procedure's wire-error union → typed on the client).
+
+**2. In-handler guard:**
+
+```ts
+import { requireFlag, isFlagEnabled } from '@voltro/plugin-flags'
+
+export default (input, ctx) => Effect.gen(function* () {
+  yield* requireFlag(ctx, 'aiSummaries')      // fails FlagDisabled if off for the caller
+  // …or branch: if (isFlagEnabled(ctx, 'newDashboard')) { … }
+})
+```
+
+**3. Client UI gating** — the `flags.evaluate` query returns the caller's resolved flag set:
+
+```tsx
+import { useFlags, useFlag } from '@voltro/plugin-flags/web'
+
+const flags = useFlags()                 // { newDashboard: true, … }
+if (useFlag('newDashboard')) return <NewDashboard />
+```
+
+## Dashboard panel
+
+Both the local devtools dashboard and the cloud dashboard ship a **Flags** panel (api apps) — a live list of every resolved flag with its rollout % + a **kill-switch toggle**. Toggling flips the flag in the live registry immediately (gated on the `canToggleFlag` capability in cloud). Backed by the plugin's `/_voltro/inspect/plugins/flags/{list,toggle}` endpoints — the plugin declares `inspect:read` (the `list` read) **and** `inspect:write` (the state-mutating `toggle` POST).
+
+## Store
+
+`'memory'` (config-as-code, default) — flags live in `app.config`. `'postgres'` overlays runtime-toggleable overrides on the config baseline (the override wins, so toggling off in the DB beats the code default).
+
+## Permissions
+
+`rpc:intercept:{mutation,query,action}` only when `gatedBy` is set (otherwise none — the `flags.evaluate` route + guards need no interceptor).