@voltro/cli 0.30.1 → 0.31.0

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

@@ -0,0 +1,270 @@
+# RBAC
+
+> Roles + permissions + the permission() handler guard. Roles compile to scopes.
+
+
+
+---
+
+<!-- source: en/plugins/rbac.md -->
+## RBAC
+
+_Roles + permissions + the permission() handler guard. Roles compile to scopes._
+
+`@voltro/plugin-rbac` adds role-based access control to Voltro. It builds **on top of the existing scope system** in `@voltro/protocol`: a role is a named bundle of permission strings, and the plugin **compiles roles to scopes** — there is no parallel "role axis". The `permission()` handler guard rejects a call when the caller's resolved scope set doesn't include the required permission, reusing the same `hasScope` / `admin:full` machinery a raw API-key scope goes through.
+
+## Install
+
+```ts
+// app.config.ts
+import { rbacPlugin } from '@voltro/plugin-rbac'
+
+export default {
+  type: 'api' as const,
+  name: 'myApi',
+  store: 'postgres' as const,
+  plugins: [
+    rbacPlugin({
+      // Declarative role → permission map. Each role lists the
+      // permission strings (== scope strings) it grants.
+      roles: {
+        viewer: ['notes:read', 'comments:read'],
+        editor: ['notes:read', 'notes:write', 'comments:read', 'comments:write'],
+        admin:  ['*'],   // wildcard — compiles to the admin:full bypass
+      },
+    }),
+  ],
+}
+```
+
+The plugin installs an interceptor that runs once per mutation / query / action, BEFORE the executor: it resolves the caller's role slugs, compiles them to a flat scope set, merges that with the subject's raw scopes, and stashes the result where `permission()` reads it.
+
+## Roles compile to scopes
+
+A role has no runtime identity once resolved — `compileRoles(['editor'], roleMap)` returns a flat permission-string set that IS a scope set. That set is checked through the same `hasScope` the framework uses for raw scopes, so a user with role `editor` and an API key minted with `scopes: ['notes:write']` are indistinguishable to `permission()`. The `'*'` wildcard in any granted role compiles to the `admin:full` blanket bypass.
+
+```ts
+import { compileRoles } from '@voltro/plugin-rbac'
+
+compileRoles(['viewer', 'editor'], {
+  viewer: ['notes:read'],
+  editor: ['notes:read', 'notes:write'],
+})
+// → ['notes:read', 'notes:write']   (deduped union)
+
+compileRoles(['admin'], { admin: ['*'] })
+// → ['admin:full']                  (wildcard → blanket bypass)
+```
+
+## Declarative `guards:` on the descriptor
+
+The framework enforces authorization **declaratively** from the descriptor — you don't have to remember an in-handler check (forgetting one is a silent authz hole). Add `guards:` to `defineMutation` / `defineQuery` / `defineAction`; the framework runs it in the dispatch spine **before the executor** (for a mutation, **before the transaction even opens**), fails with a typed `ScopeError`, and **auto-merges `ScopeError` into the wire error union** so the client decodes the denial typed.
+
+```ts
+export const updateNote = defineMutation({
+  name: 'notes.update',
+  input: Schema.Struct({ id: Schema.String, teamId: Schema.String, title: Schema.String }),
+  output: Schema.Struct({ id: Schema.String }),
+  guards: [{ scope: 'notes:write' }],        // ← enforced before the executor
+})
+```
+
+The check runs against the caller's **effective** scope set — raw subject scopes **∪** rbac role-derived scopes — so a role that grants `notes:write` satisfies the guard exactly like a raw API-key scope. `admin:full` bypasses every guard.
+
+- **Multiple scopes, AND:** `guards: [{ scope: ['notes:write', 'team:member'] }]` (default `mode: 'all'`).
+- **Multiple scopes, OR:** `guards: [{ scope: ['notes:write', 'notes:admin'], mode: 'any' }]`.
+- **Several guards:** every entry must pass (AND across the array).
+
+`guards:` is **browser-safe by construction**: it carries scope *strings* plus an optional **pure** `resource` extractor (`input → id`, the same discipline as `target.identify`) — never a server function, never a DB call. So a descriptor bundled value-level into the browser drags in nothing server-only.
+
+```ts
+guards: [{ scope: 'roadmaps:write', resource: (input) => input.teamId }]
+```
+
+The `resource` extractor is passed to a resource-aware scope resolver for row/resource-scoped (ReBAC-style) checks. With **no** resolver registered it is advisory — the guard checks the subject's global scopes. Register one and the guard scopes to the resource (see next).
+
+### Resource-scoped guards (multi-tenant / per-team)
+
+A subject-global guard asks "does the caller hold scope `S` anywhere". For a multi-tenant app whose subjects are minted with `scopes: []` and whose real permissions are **per-resource** (owner in team A, viewer in team B), that's the wrong question — you need "does the caller hold `S` **on this resource**". Register a resolver and the `resource` extractor stops being advisory:
+
+```ts
+// rbac path — compile per-resource roles through the same `roles` map:
+rbacPlugin({
+  roles: { owner: ['roadmaps:write'], viewer: ['roadmaps:read'] },
+  resolveResourceRoles: (subject, teamId) => db.rolesFor(subject.id, teamId), // → role slugs on THAT team
+})
+
+// or, without rbac, register a resolver directly against your own tables:
+import { setResourceScopeResolver } from '@voltro/protocol'
+setResourceScopeResolver(({ subject, scope, resource }) =>
+  Effect.succeed(/* does subject hold `scope` on `resource`? */),
+)
+```
+
+The framework asks the resolver per request, **before the executor** (mutations: before the transaction opens). A globally-held scope or `admin:full` still short-circuits **without** a resolver call; only the gap falls through. A resolver error fails **closed** (denies). The denial is the same typed `ScopeError` a global guard raises.
+
+## The `permission()` guard (in-handler)
+
+For authz that depends on **loaded data** (row ownership, cross-field rules) — anything the declarative `guards:` can't express as a pure scope check — gate **inside the handler**, the same way `assertOwnTenant` / `requireScope` do.
+
+Two forms, mirroring `scopes.ts`:
+
+```ts
+// Effect form — fails with typed ScopeError on the error channel.
+import { permission } from '@voltro/plugin-rbac'
+import { Effect } from 'effect'
+
+export default (input: { title: string }, ctx: AppContext) =>
+  Effect.gen(function* () {
+    yield* permission(ctx, 'notes:write')        // Effect<void, ScopeError>
+    // ... do the write ...
+  })
+```
+
+```ts
+// Sync form — throws ScopeError. For async (non-Effect) handlers.
+import { assertPermission } from '@voltro/plugin-rbac'
+
+const execute = async (input: { title: string }, ctx: AppContext) => {
+  assertPermission(ctx, 'notes:write')           // throws ScopeError
+  return ctx.store.insert('notes', { title: input.title })
+}
+```
+
+- **Multiple permissions = ALL required (AND):** pass an array — `permission(ctx, ['notes:write', 'admin:bypass'])` — or call `permission()` twice.
+- **OR semantics:** `anyPermission(ctx, ['notes:write', 'notes:admin'])` passes when the caller holds at least one.
+- **`'*'` / `admin:full` bypass:** a caller whose resolved set contains `admin:full` (or a role mapped to `'*'`) passes every check.
+- **Pure branch:** `can(ctx, 'notes:write')` returns a boolean without throwing — for in-handler branching.
+
+These guards fail with protocol's `ScopeError` (`Schema.TaggedError`, `{ required: string, message: string }`) — the **one denial tag the whole framework uses**: declarative `guards:` raise it too, so a client that matches `_tag === 'ScopeError'` (or `errorTag(err)`) recognizes both a descriptor-guard denial and a `permission()` denial with a single branch. The plugin registers `ScopeError` via `errorSchemas` so a `permission()` rejection decodes typed even on a descriptor with no `guards:`; declare `error: ScopeError` (from `@voltro/protocol`) on the descriptor too if you want it explicit in the procedure's own wire union.
+
+### `ctx.access` — the typed authorization slice
+
+Every handler context carries `ctx.access`, the cast-free face of the caller's **effective** scope set (raw ∪ rbac roles). Reach for it instead of poking at `ctx.request.subject.scopes`:
+
+```ts
+ctx.access.has('notes:write')            // boolean
+ctx.access.hasAny(['notes:write', 'notes:admin'])
+yield* ctx.access.require('notes:write') // Effect<void, ScopeError>
+ctx.access.scopes                        // the live effective set
+```
+
+It reads the same effective-scope seam the declarative `guards:` enforce, so `ctx.access.has(x)` and a `guards: [{ scope: x }]` entry can never disagree.
+
+## Row-level checks
+
+`permission()` covers the role/scope axis. Row-level rules ("can edit their OWN note") stay ordinary handler logic alongside it:
+
+```ts
+export default (input: { noteId: string }, ctx: AppContext) =>
+  Effect.gen(function* () {
+    yield* permission(ctx, 'notes:write')                       // role/scope gate
+    const note = yield* /* load note by id */
+    if (note.authorId !== ctx.request.subject.id) {
+      return yield* Effect.fail(new ScopeError({ required: 'notes:write', message: 'not author' }))
+    }
+    // ... safe to write ...
+  })
+```
+
+## Where roles come from
+
+By default the plugin reads role slugs from `subject.metadata.roles` (a `string[]`) — config-only, table-less. A project that assigns roles at runtime supplies its own resolver:
+
+```ts
+rbacPlugin({
+  roles: { /* … */ },
+  // Resolve the caller's role slugs. Tenant-aware: filter by the
+  // ACTIVE tenant via subject.tenantId.
+  resolveRoles: async (subject) => {
+    const rows = await db.userRoles.findAll({
+      where: and(eq('userId', subject.id), eq('tenantId', subject.tenantId)),
+    })
+    return rows.map((r) => r.roleSlug)
+  },
+  // Optional extra raw permissions merged in (per-row ACLs, flags).
+  resolvePermissions: async (subject) => /* string[] */,
+})
+```
+
+The resolver runs once per request; the result is stashed on a per-request slot so `permission()` and `useCan` read a stable resolved set. A resolver failure degrades to the subject's raw scopes — it never silently grants.
+
+## Tenant-aware roles
+
+`subject.tenantId` is the **active** tenant (a single value, not a map). A tenant-aware resolver returns the roles that apply for `subject.tenantId`, so a user who is `editor` in tenant A but has no role in tenant B passes `permission()` under A and is denied (`ScopeError`) under B. The optional `userRoles` table (below) carries `(userId, tenantId, roleSlug)` for exactly this filter; `tenantId: null` means a global role across every tenant.
+
+## Optional tables
+
+Config-only projects run table-less. Projects that assign roles at runtime opt into the `roles` + `userRoles` tables via `extendSchema`:
+
+```ts
+rbacPlugin({
+  roles: { /* … */ },
+  tables: true,                       // or { multitenant: true } for a FK to `tenants`
+  resolveRoles: /* DB resolver */,
+})
+```
+
+The tables emit on all six SQL dialects (postgres / mysql / mariadb / mssql / sqlite / turso) — `permissions` is a portable JSON column, never a postgres-only array. With `tables: true`, `userRoles.tenantId` is a plain nullable column; with `{ multitenant: true }` it's a nullable foreign key to the `tenants` table from `@voltro/plugin-multitenancy`.
+
+### Assign / revoke — `userRoleStore`
+
+You don't have to hand-write the `userRoles` CRUD or a DB resolver. `userRoleStore(dataStore)` gives tenant-aware `assign` / `revoke` / `rolesOf`, and `dataStoreRoleResolver(store)` adapts it into `resolveRoles`:
+
+```ts
+import { rbacPlugin, userRoleStore, dataStoreRoleResolver } from '@voltro/plugin-rbac'
+
+const roleStore = userRoleStore(dataStore)
+await roleStore.assign('user_123', 'editor', 't1')  // idempotent grant
+await roleStore.revoke('user_123', 'editor', 't1')
+
+rbacPlugin({
+  roles: { /* … */ },
+  tables: { multitenant: true },
+  resolveRoles: dataStoreRoleResolver(roleStore),   // scoped to subject.tenantId
+})
+```
+
+`rolesOf(userId, tenantId)` returns the tenant's assignments **plus** the global (`tenantId: null`) ones, so a global role grants everywhere.
+
+## React side (web)
+
+This plugin ships no client hook. The UI gate lives in
+[`@voltro/client`](/docs/ui/client-utilities/use-can) — feed the caller's
+resolved scopes to `<PermissionProvider>` and read them with `useCan`:
+
+```tsx
+import { PermissionProvider, useCan } from '@voltro/client'
+
+// Feed the caller's resolved scopes once, near the app root:
+// <PermissionProvider scopes={resolvedScopes}>…</PermissionProvider>
+
+const Page = () => {
+  const canEdit = useCan('notes:write')
+  return (
+    <div>
+      <h1>My note</h1>
+      {canEdit ? <button>Edit</button> : null}
+    </div>
+  )
+}
+```
+
+It sits there rather than here because scopes are a **framework** concept —
+`@voltro/protocol` owns `ScopeError`, `guards: [{ scope }]` and `ctx.access`, and
+rbac is only ONE way to produce them (an app can register its own
+`setResourceScopeResolver` over its own tables and never install this plugin).
+The hook CONSUMES scopes, which is generic; this plugin PRODUCES them, which is
+rbac-specific. Gating a button must not require an rbac dependency.
+
+What stays here is everything that IS rbac: the roles map, role→scope
+compilation, the `permission()` server guard, the role tables, and
+`resolveResourceRoles`.
+
+**`useCan` is for hiding buttons, NOT authorization** — a client can lie about
+its scopes. The server-side `permission()` guard is the real gate.
+
+## See also
+
+- [Multi-tenancy](/docs/multi-tenancy/overview) — tenant scoping IS authorisation
+- [Authentication](/docs/authentication/overview) — RBAC sits on top of auth; roles compile to the subject's scopes

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

@@ -0,0 +1,63 @@
+# SCIM
+
+> SCIM 2.0 provisioning — Users + Groups REST endpoints so an enterprise IdP (Okta, Entra, OneLogin) can create / update / deactivate users in your app.
+
+
+
+---
+
+<!-- source: en/plugins/scim.md -->
+## SCIM
+
+_SCIM 2.0 provisioning — Users + Groups REST endpoints so an enterprise IdP (Okta, Entra, OneLogin) can create / update / deactivate users in your app._
+
+`@voltro/plugin-scim` exposes the SCIM 2.0 endpoints enterprise IdPs use to provision users into your app. When an admin adds someone to your app in Okta/Entra, the IdP POSTs to your `/scim/v2/Users` endpoint; when they remove them, it PATCHes `active: false`. This is a hard requirement in most enterprise procurement.
+
+## Wiring
+
+```ts
+// app.config.ts
+import { scimPlugin } from '@voltro/plugin-scim'
+
+export default {
+  type: 'api' as const, name: 'api',
+  plugins: [scimPlugin({ token: process.env.SCIM_TOKEN! })],   // basePath defaults to /scim/v2
+}
+```
+
+Mounts `/scim/v2/Users` + `/scim/v2/Groups`, bearer-gated by `token` (paste it into the IdP's SCIM config). Contributes the `_voltro_scim_users` + `_voltro_scim_groups` tables.
+
+## Endpoints
+
+| Method + path | SCIM operation |
+|---|---|
+| `GET /scim/v2/Users?filter=userName eq "x"` | list / find a user (`userName` / `externalId` eq filters, `startIndex`/`count` pagination) |
+| `GET /scim/v2/Users/<id>` | read a user |
+| `POST /scim/v2/Users` | create (provision) — duplicate `userName` answers `409 uniqueness` (DB-unique, IdP-retry-safe) |
+| `PUT /scim/v2/Users/<id>` | replace |
+| `PATCH /scim/v2/Users/<id>` | partial update — incl. the `active:false` **deactivation** IdPs send |
+| `DELETE /scim/v2/Users/<id>` | delete |
+| `GET`/`POST`/`DELETE /scim/v2/Groups` | list (`displayName` / `externalId` eq filters, paginated) / create / delete groups |
+| `PUT`/`PATCH /scim/v2/Groups/<id>` | replace / **membership add-remove-replace** (how Okta/Entra push membership changes) |
+| `GET /scim/v2/ServiceProviderConfig` · `/Schemas` · `/ResourceTypes` | the RFC 7644 §4 discovery trio IdPs probe at connector setup |
+
+Requests + responses use the SCIM JSON envelope (schemas, `id`, `meta`, `ListResponse`); an unsupported `filter` is answered `400 invalidFilter` (never silently unfiltered). The pure mapping (`toScimUser`, `fromScimUser`, `applyScimPatch`, `applyScimGroupPatch`, `scimList`, `parseScimFilter`) is exported + unit-tested.
+
+## Notes
+
+- The bearer token is the trust boundary — keep it secret + rotate it via your IdP.
+- **An empty token is refused at boot.** `scimPlugin({ token })` throws while
+  `app.config.ts` evaluates if the token is empty or whitespace, so a deployment
+  with an unset `SCIM_TOKEN` fails to start rather than coming up and answering
+  the first anonymous request. This exists because
+  `scimPlugin({ token: process.env.SCIM_TOKEN ?? '' })` — the shape everyone
+  writes — used to turn the gate off silently, leaving SCIM Users and Groups (a
+  full directory dump, plus the endpoints that deactivate accounts) readable with
+  no credentials. The miss is likeliest in a preview environment or a fresh
+  cluster where the variable was never copied over, which is exactly where a
+  boot failure is cheap and an open directory is not.
+- `_voltro_scim_users` is the SCIM-side mirror; map it to your real `users` table in `onCreate`/sync logic if they differ.
+
+## Permissions
+
+`store:write` (the SCIM tables).

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

@@ -0,0 +1,116 @@
+# Search
+
+> 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.
+
+
+
+---
+
+<!-- source: en/plugins/search.md -->
+## Search
+
+_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._
+
+`@voltro/plugin-search` mirrors your tables into an external search engine. It rides the **ChangeEvent tap** — every insert/update/delete on a configured table maps into the index automatically; a typed `search.query` action reads it back, tenant-scoped, with a `useSearch` hook on the client.
+
+## Wiring
+
+```ts
+// app.config.ts
+import { searchPlugin } from '@voltro/plugin-search'
+
+export default {
+  type: 'api' as const,
+  name: 'api',
+  plugins: [
+    searchPlugin({
+      // backend: defaults to memory (dev). Swap for production:
+      // backend: typesenseBackend({ url, apiKey }) | meilisearchBackend({ ... }) | algoliaBackend({ ... })
+      indexes: {
+        posts: {
+          index: 'posts',
+          tenantField: 'tenantId',                       // index documents carry the tenant → query scopes by it
+          map: (row) => ({ id: String(row.id), title: String(row.title), body: String(row.body) }),
+        },
+      },
+    }),
+  ],
+}
+```
+
+## How sync works
+
+The plugin declares `onChangeEvent`. On every committed write to a configured table, `applyChange` maps the row via `map(row)` and upserts (insert/update) or removes (delete) the index document. No `*.subscribe.ts`, no manual indexing calls — the tap is the single sync path, and it runs under both `voltro dev` and `voltro serve`.
+
+For pre-existing rows, `backfillIndex(backend, spec, rows)` indexes the rows you supply (call it from a `*.startup.tsx` or a one-off script) — or use the **Reindex** button / `POST /reindex` inspect endpoint, which reads the table's current rows for you.
+
+## Querying
+
+`search.query` is a typed **action** (not a streaming query — search results aren't reactive):
+
+```tsx
+import { useSearch } from '@voltro/plugin-search/web'
+
+const { results, facets, run, pending } = useSearch('posts')
+run('voltro effect')                       // → results scoped to the caller's tenant
+run('voltro effect', { limit: 20, offset: 20 })   // offset paging — page 2
+```
+
+`results` are the hit documents; `facets` are the facet counts from the last run. The query is automatically filtered to the caller's `tenantId` (from the resolved Subject) against the index's `tenantField` — no cross-tenant leak.
+
+`run(q, { limit, offset })` pages the results: `offset` skips leading hits, `limit` bounds the window. It maps to each engine's native paging (memory slice, Typesense/Meilisearch `offset`, Algolia `offset`+`length`).
+
+## Query features
+
+Every option is plain JSON and round-trips through the action's Schema:
+
+```ts
+import { memoryBackend } from '@voltro/plugin-search'
+
+const backend = memoryBackend()
+const res = await backend.query('posts', {
+  q: 'kubernetis',                                   // matches the typo below
+  limit: 20,
+  offset: 20,                                        // offset paging
+  fuzziness: 'auto',                                 // typo tolerance (or a number: max edits, 0 = exact)
+  filters: [
+    { field: 'status', op: 'neq', value: 'draft' },  // negation
+    { field: 'score', op: 'gte', value: 50 },        // numeric range
+    { field: 'publishedAt', op: 'lt', value: '2026-06-01T00:00:00Z' }, // date range
+    { field: 'tag', op: 'in', value: ['a', 'b'] },   // set membership
+  ],
+  facets: ['status', 'tag'],                         // facet counts per field
+  highlight: { fields: ['title'], preTag: '<mark>', postTag: '</mark>' },
+  engineParams: { num_typos: 1 },                    // escape hatch → forwarded verbatim to the engine
+})
+// res.hits: [{ doc, highlights? }, …]   res.facets: { status: { open: 12, done: 3 }, … }
+```
+
+- **filters** — a list of clauses ANDed together, each `{ field, op, value }` with `op ∈ eq | neq | gt | gte | lt | lte | in | nin`. Range (`gt`/`lte`/…) and negation (`neq`/`nin`), not equality-only.
+- **facets** — per-value counts for the named fields (over the full matched set, before paging).
+- **highlight** — matched-term snippets per field, returned as `hit.highlights[field]`.
+- **fuzziness** — a max edit distance (`0` = exact) or `'auto'`.
+- **engineParams** — an escape-hatch bag forwarded verbatim into the underlying engine's search call. Ignored by the memory backend.
+
+Native support degrades honestly: memory, Typesense, Meilisearch and Algolia all do filters/facets/highlighting; Typesense honors a numeric typo count (`num_typos` 0–2) while Meilisearch and Algolia only toggle typo tolerance on/off (`fuzziness: 0` disables it, other values keep their built-in tolerance). A backend op fails with a typed `SearchBackendError`.
+
+## Backends
+
+| Backend | Notes |
+|---|---|
+| `memoryBackend` (default) | Fully in-process; dev + tests. Not for production scale. |
+| `typesenseBackend` | Optional dep `typesense`. Lazy-loaded. |
+| `meilisearchBackend` | Optional dep `meilisearch`. Lazy-loaded. |
+| `algoliaBackend` | Optional dep `algoliasearch`. Lazy-loaded. |
+
+A backend is the `SearchBackend` interface (`upsert` / `remove` / `query`) — bring your own (OpenSearch, Elastic, …).
+
+## Dashboard panel
+
+Both dashboards ship a **Search** panel (api apps): the configured indexes with per-index sync stats (docs synced/removed, last reindex) + the resolved backend, and a **Reindex** button per index that re-seeds it from the table's current rows (`backfillIndex`). Reindex gates on the `canReindexSearch` capability. Backed by `/_voltro/inspect/plugins/search/{indexes,reindex}`.
+
+The sync stats behind this panel are **durable and aggregated across replicas**. They live in a framework-owned `_voltro_search_stats` table (contributed via `extendSchema.tables`; the plugin declares `store:write`), one row per `(index, replica)`, each bumped with an atomic compare-and-set. `/indexes` sums every replica's row and takes the most-recent reindex — so the counts are truthful under multiple instances and survive a restart (they no longer reset with the process, and no replica under-reports the fleet total). Zero-infra dev/tests use an in-process stats store; `bindDataStore` swaps in the durable one at boot.
+
+## Permissions
+
+`store:changes:read` (the ChangeEvent tap) + `store:write` (the durable `_voltro_search_stats` counters) + `inspect:read` (dashboard panel) + `network:outbound:<host>` (for a remote backend).

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

@@ -0,0 +1,192 @@
+# Sentry
+
+> Deep Sentry integration — errors correlated to the distributed trace, breadcrumbs from the log sink, and opt-in performance traces.
+
+
+
+---
+
+<!-- source: en/plugins/sentry.md -->
+## Sentry
+
+_Deep Sentry integration — errors correlated to the distributed trace, breadcrumbs from the log sink, and opt-in performance traces._
+
+`@voltro/plugin-sentry` is the deep Sentry integration: every mutation/query/action failure becomes a Sentry issue **correlated to the active distributed trace** (trace_id + span_id) and carrying the request's recent log lines as breadcrumbs. Opt into performance traces and the framework's spans flow to Sentry as transactions.
+
+Uses the official `@sentry/node` SDK in **OpenTelemetry-consumer mode** — it consumes the framework's existing tracer (it never becomes the global provider), so the in-app [Traces dashboard](/docs/observability/distributed-tracing) stays intact.
+
+## Wiring
+
+```ts
+// app.config.ts
+import { sentryPlugin } from '@voltro/plugin-sentry'
+
+export default {
+  type: 'api' as const,
+  name: 'api',
+  plugins: [
+    sentryPlugin({
+      // dsn defaults to SENTRY_DSN; without a valid DSN the plugin is a no-op.
+      environment: 'production',   // or SENTRY_ENVIRONMENT
+      release: '1.4.2',            // or SENTRY_RELEASE
+      traces: true,                // route the framework's spans → Sentry (default off)
+      tracesSampleRate: 1.0,
+      profiling: true,             // continuous CPU profiler via @sentry/profiling-node
+    }),
+  ],
+}
+```
+
+`@sentry/*` are optional, lazy-loaded dependencies — non-users pay nothing.
+
+## Configuration
+
+| Option | Type | Default | Notes |
+|---|---|---|---|
+| `dsn` | `string` | `SENTRY_DSN` env | No valid DSN → the plugin is inert (no interceptors registered). |
+| `environment` | `string` | `SENTRY_ENVIRONMENT` env | Sentry `environment` tag + `deployment.environment` resource attribute. |
+| `release` | `string` | `SENTRY_RELEASE` env | Release-health + source-map matching; also `service.version`. |
+| `traces` | `boolean` | `false` | Route the framework's OTel spans to Sentry as transactions. Off → errors + breadcrumbs only. |
+| `tracesSampleRate` | `number` | `1.0` | Applied by the Sentry client (not a tracer sampler). Only relevant with `traces`. |
+| `profiling` | `boolean` | `false` | Continuous CPU profiler via `@sentry/profiling-node` (lazy; warns if not installed). |
+| `profilesSampleRate` | `number` | `1.0` | Only relevant with `profiling`. |
+| `maxBreadcrumbs` | `number` | `50` | Per-trace breadcrumb cap. |
+| `name` | `string` | — | Disambiguates multiple instances (`@voltro/plugin-sentry#<name>`). |
+
+## How the deep correlation works
+
+The framework is **Effect-native**: the active OTel span lives in Effect's fiber context, not the AsyncLocalStorage Sentry reads implicitly. So the plugin attaches trace context + breadcrumbs **explicitly** rather than relying on Sentry's ambient scope:
+
+```
+interceptMutation/Query/Action
+  └─ on failure → Sentry.withScope(scope => {
+       scope.setContext('trace', { trace_id, span_id })   // ← from ctx.traceId / ctx.spanId
+       scope.setTags({ 'rpc.tag', 'rpc.kind', 'subject.type', 'tenant.id' })
+       breadcrumbs.forEach(b => scope.addBreadcrumb(b))    // ← the trace's log lines
+       Sentry.captureException(error)
+     })
+```
+
+This guarantees the error links to its trace in Sentry **regardless** of the Effect/AsyncLocalStorage mismatch. Pure interruptions (client disconnects) are skipped.
+
+### Breadcrumbs
+
+The framework log sink feeds a bounded **per-trace** ring (capped per-trace + LRU + TTL), keyed on each log line's `traceId`. On an error the trace's breadcrumbs are attached to the event; traces that never error are reaped by the TTL. So a Sentry issue shows the exact log lines leading up to it — for that request only.
+
+## Traces (opt-in `traces:true`)
+
+The plugin contributes a `SentrySpanProcessor` to the framework's tracer (via the plugin observability surface — see [Observability › Routing traces to a vendor](/docs/observability/overview#routing-traces-to-a-vendor)). Every framework span becomes a Sentry transaction, sharing the same trace id the errors carry — so in Sentry you land on an error inside its full distributed trace.
+
+We deliberately do **not** install a `SentrySampler` as the tracer's sampler: that would gate recording for the WHOLE tracer and blind the framework's own in-app Traces buffer. The framework keeps its always-on sampler; `tracesSampleRate` is applied by the Sentry client.
+
+## Full-stack — browser → backend in ONE Sentry trace
+
+The plugin ships a browser half at `@voltro/plugin-sentry/web` so a click in the UI and the server work it triggers appear as **one trace** in Sentry. Turn it on in the web app's `app.config.ts`:
+
+```ts
+// apps/web/app.config.ts
+export default {
+  type: 'web' as const,
+  name: 'web',
+  apis: { app: { package: '@app/api' } },
+  sentry: {
+    dsn: 'https://<key>@oXXXX.ingest.sentry.io/XXXX', // public — safe in the browser bundle
+    environment: 'production',
+    release: '1.4.2',          // MUST match the api's `release` for unified release health
+    tracesSampleRate: 1.0,
+  },
+}
+```
+
+The framework's generated entry calls `initSentryBrowser()` before mount (no code to write). It needs `@voltro/plugin-sentry` as a dependency of the web app. Prefer the api `release` and the web `release` be identical.
+
+What it does:
+- **Inits `@sentry/react`** with `browserTracingIntegration` — page loads + client navigations become Sentry transactions, and unhandled errors / promise rejections are captured by the SDK's default global handlers.
+- **Unifies the trace.** Every framework rpc call (`useMutation`/`useSubscription`/`useAction`) already wraps itself in an Effect client span and propagates that span's W3C `traceId`+`spanId` to the api (the api's `sentryPlugin({ traces:true })` turns the server spans into Sentry transactions under that same trace id). The browser half subscribes to the framework's client-trace bus and emits a browser-side Sentry span into the **same** trace, parented at the client span — so Sentry's trace view shows the browser hop and the server transactions in one tree.
+
+> **Manual wiring** (no app.config field, e.g. an app that builds its own entry): call it yourself once at boot —
+> ```ts
+> import { initSentryBrowser } from '@voltro/plugin-sentry/web'
+> await initSentryBrowser({ dsn: import.meta.env.VITE_SENTRY_DSN })
+> ```
+> It's a no-op on the server (SSR) and without a DSN.
+
+The two halves are independent: the api plugin alone gives you server traces + errors; add the web half for the browser hop. For the FULL frontend→backend waterfall in Sentry, run **both** (`sentryPlugin({ traces:true })` on the api + `sentry: { dsn }` on the web app), with matching `release`.
+
+## Source maps (browser stack traces)
+
+The web bundle is minified, so browser errors arrive in Sentry with **minified** stack traces unless you upload source maps. The plugin does **not** upload them for you — it captures + correlates errors, but wiring the build to publish maps is a per-app build step (it needs your build output plus a Sentry auth token, neither of which the runtime plugin owns). Wire it once with Sentry's official tooling, keyed to the **same `release`** the plugin uses so the maps match the uploaded events:
+
+```sh
+# after the web build, from the web app dir — uploads maps for one release
+pnpm add -D @sentry/cli
+SENTRY_AUTH_TOKEN=… npx sentry-cli sourcemaps upload \
+  --org <org> --project <project> \
+  --release "$SENTRY_RELEASE" ./dist
+```
+
+Or add `@sentry/vite-plugin` to the web app's Vite config so the upload runs automatically on every production build. Either way, set `release` to the same value (e.g. the git SHA) on BOTH the api `sentryPlugin({ release })` and the web `sentry` field — the upload's `--release` must match or Sentry won't resolve the frames. Server stack traces are un-minified already (the api ships readable JS), so this is a browser-only concern.
+
+## Catching errors — what's automatic, what's manual
+
+Once the two halves are wired, most errors are captured **with no per-call code**:
+
+| Error | Captured | How |
+|---|---|---|
+| rpc handler throw (mutation/query/action) | ✅ auto | server interceptor → Sentry, trace-correlated + breadcrumbs |
+| Unhandled browser error / promise rejection | ✅ auto | `@sentry/react` global handlers (after `initSentryBrowser`) |
+| **React render error** (any page, incl. catch-all `[...slug]`, `error.tsx` boundary) | ✅ auto | the framework's route ErrorBoundary publishes to a client-error bus → the Sentry web bridge captures it. React swallows boundary-caught errors before `window.onerror`, so this bridge is what makes them reach Sentry — tagged with the route + component stack. |
+| **Loader failure** (page/layout `loader` reject) | ✅ auto | same route bus path |
+| Manual try/catch (event handler, async effect, anywhere) | ✋ one call | `reportClientError(error, context?)` |
+| **Every other server primitive** — REST route (`defineRestRoute`), aggregate, subscriber, schedule, workflow, webhook, startup | ✅ auto | each primitive's error path publishes to the framework's server-error bus → the plugin captures it, tagged `voltro.errorSource` + `voltro.name` (+ traceId for workflows) |
+
+### Manual capture — `reportClientError`
+
+Vendor-agnostic, ships with the framework (`@voltro/web` / re-exported from `@voltro/plugin-sentry/web`). Call it from anything the route boundary won't catch:
+
+```tsx
+import { reportClientError } from '@voltro/client'
+
+const onPay = async () => {
+  try {
+    await pay.run({ amount })
+  } catch (err) {
+    reportClientError(err, { feature: 'checkout', amount })  // → Sentry, tagged
+    toast.error('Payment failed')
+  }
+}
+```
+
+It's a no-op when no reporter is subscribed (Sentry not initialised), so library code can call it unconditionally. The Sentry web bridge forwards it with `voltro.errorSource: manual` + your `context`.
+
+### Catch-all / 404 routes
+
+A catch-all page (`[...slug].tsx`) or a scoped `not-found.tsx` that *renders* fine produces no error — a 404 isn't an exception. But if such a page (or anything under it) **throws** while rendering or in its loader, the route ErrorBoundary catches it and it's auto-captured — no `error.tsx` wiring needed (though an `error.tsx` still gets to render your fallback UI; both happen).
+
+### Server coverage — every primitive, not just rpc
+
+With the plugin active, errors from **every** server primitive reach Sentry — no per-handler code:
+
+- **rpc** (mutation / query / action, and the synthesized agent `send`/`messages`) — via the interceptors (richest context: subject, span id, breadcrumbs).
+- **Everything else** — REST routes (`defineRestRoute`), aggregates, subscribers, schedules, workflows, webhooks, startups — via the framework's **server-error bus**: each primitive's existing error path calls `publishServerError({ error, source, name, … })`, and the plugin subscribes once and captures it (tagged with the source + name; workflows also carry their `traceId` so the failure correlates to its trace + breadcrumbs).
+
+The bus is vendor-agnostic (`publishServerError` / `subscribeServerErrors` from `@voltro/protocol`) — the Sentry plugin is just the subscriber. Intentional control-flow throws (a REST handler's `throw { status: 4xx }`) are **not** reported — only unexpected 5xx-class failures.
+
+## Troubleshooting
+
+| Symptom | Cause / fix |
+|---|---|
+| Boot logs `sentry inactive — no valid DSN` | `dsn` / `SENTRY_DSN` is unset or malformed. The plugin registers no interceptors until a valid DSN is present. |
+| Errors arrive in Sentry but **not linked to a trace** | The `trace` context is set explicitly from `ctx.traceId` — present on every rpc call. If it's missing, the error came from outside an rpc handler (e.g. a bare `console.error`), which the interceptor doesn't see. |
+| Issue has **no breadcrumbs** | Breadcrumbs come from log lines carrying `fields.traceId`. Lines logged outside the request's trace (or after the trace was reaped by TTL) aren't attached. Raise `maxBreadcrumbs` if a trace logs heavily. |
+| `traces: true` but **no transactions in Sentry** | Confirm `tracesSampleRate > 0`. Spans are recorded always-on by the framework; the Sentry client applies the sample rate when building transactions. |
+| In-app Traces dashboard **went empty** after enabling Sentry | You contributed a sampler that drops spans. Don't — the framework's buffer is always-on by design (this plugin deliberately omits `SentrySampler`). |
+| Profiling requested but no profiles | `@sentry/profiling-node` isn't installed; boot logs a warning. `pnpm add @sentry/profiling-node`. |
+| Browser + server NOT in one trace | Run BOTH halves — `sentryPlugin({ traces:true })` on the api AND `sentry:{dsn}` on the web app. Errors-only on either side won't share a trace; you need `traces` on the api. |
+| Web `sentry` set but nothing in Sentry | `@voltro/plugin-sentry` must be a dependency of the WEB app (the generated entry imports `@voltro/plugin-sentry/web`). Confirm `dsn` is set — without it the browser half is a no-op. |
+
+## Notes
+
+- No DSN → the plugin is inert (logs a warning at boot, registers no interceptors).
+- A Sentry outage is **fail-soft**: a broken transport never masks the original handler error.
+- Permissions: `rpc:intercept:{mutation,query,action}` + `network:outbound:<dsn-host>`.