@voltro/cli 0.1.0

package/templates/agent-docs/schema-driven-ui.md

@@ -0,0 +1,607 @@
+# Schema-driven UI
+
+> Project the typed descriptor graph into UI — forms, tables, pickers, and reactive components, all bound to a descriptor with near-zero glue.
+
+
+
+---
+
+<!-- source: en/ui/overview.md -->
+## Overview
+
+_Project the typed descriptor graph into UI — forms, tables, pickers, and reactive components, all bound to a descriptor with near-zero glue._
+
+You already own a typed schema on **both** sides of the wire: the entity DSL
+(`*.entity.ts`) and the descriptor schemas (`defineQuery` / `defineMutation`
+carry `effect/Schema` for input, output, and `target`). Schema-driven UI
+**projects that into the frontend** — so a form, a table, or a picker is a
+*binding to a descriptor* the framework already has, not hand-written glue.
+
+Here's that idea live — a form bound to a mutation and a table bound to a query,
+sharing one reactive backend. Add a row and it appears instantly, pushed from
+the server (it's your own throwaway sandbox; it resets on refresh):
+
+```tsx
+<AutoForm api="app" mutation="todos.create" submitLabel="Add todo" />
+<DataTable api="app" query="todos.list" />
+```
+
+## Why this isn't "yet another admin generator"
+
+Auto-generated CRUD UIs fail because they generate against a *dead* REST/SQL
+schema and hit a wall the moment you need anything custom. Voltro's version is
+different on one axis: the generated UI binds to a **reactive, auto-optimistic
+backend**. A `<DataTable>` is not a dead grid you refetch — it's a live
+subscription that updates on any write, with optimistic patches derived from
+the mutation descriptor's `target`, for free. The generation is the *delivery*;
+the reactivity is the *value*.
+
+## Binding symmetry — everything binds to a descriptor
+
+| UI piece | binds to | gives you |
+|---|---|---|
+| a **form** | a **mutation** (`todos.create`) | fields from its input Schema, validation, submit, op-correct optimistic |
+| a **field / picker** | a **query** (`users.search`) | live options, debounce, pagination |
+| a **table** | a **query** (`todos.list`) | live rows, sort, pagination, row-action mutations |
+| a **filter panel** | a **query**'s input | faceted controls + a live result count |
+| a **detail view** | a **query** + relations | a live record + its eager-loaded relations |
+
+There's no new data layer to learn. Customization is only ever choosing *how* a
+binding renders — never re-plumbing the binding.
+
+## The customization ladder (never lose the binding)
+
+This is where 99% of schema→UI generators die: they nail the happy path, then
+force a config DSL until it's worse than hand-written JSX — or you eject and
+lose everything. The one rule that avoids both:
+
+> Customization is a ladder of ever-smaller overrides, and on **no rung do you
+> lose the binding** (schema validation + mutation submit + optimistic; for a
+> picker, the live query). Eject from the *rendering* is never eject from the
+> *binding*.
+
+| Rung | How | You lose |
+|---|---|---|
+| 0 — schema annotation | `widget` / `label` on the field | nothing (zero form code) |
+| 1 — per-field render-prop | `<Field name="x">{f => <MyWidget .../>}</Field>` | nothing — state/validation/submit stay |
+| 2 — widget registry | map a widget-kind → component app-wide | nothing |
+| 3 — layout override | arrange `<Field/>`s in your own JSX | nothing |
+| eject — headless | `useFormBinding` / `useDataTable` + your JSX | only the auto-rendering — the binding stays |
+
+`<AutoForm>` / `<DataTable>` are sugar over a **headless core**
+(`useFormBinding` / `useDataTable`) — which is exactly why ejecting from the
+rendering keeps everything underneath.
+
+## Localizing the built-in strings
+
+The components render a handful of user-facing labels — `Clear`, `Actions`,
+`Search…`, the workflow status words (`Running` / `Succeeded` / …), presence's
+"X is editing" sentence, and so on — with **English defaults**. Localize them
+all at once by wrapping the app in `UiStringsProvider`, instead of threading a
+prop through every component:
+
+```tsx
+import { UiStringsProvider } from '@voltro/web'
+
+<UiStringsProvider
+  strings={{
+    filters: { clear: 'Zurücksetzen', resultCount: (n) => `${n} Ergebnisse` },
+    dataTable: { actions: 'Aktionen' },
+    workflow: { status: { running: 'Läuft' } },
+    presence: { editingOne: (name, verb) => `${name} ist am ${verb}` },
+  }}
+>
+  <App />
+</UiStringsProvider>
+```
+
+Overrides **deep-merge** onto the defaults — supply only the sections and keys
+you change; everything else stays English. Interpolated strings (counts, names)
+are functions so a locale can reorder or pluralize. Providers nest (an inner one
+merges onto the outer), and a per-component prop (e.g. `<AgentChat placeholder>`)
+still wins over the context for a one-off tweak. `useUiStrings()` reads the
+active strings; `defaultUiStrings` is the English baseline.
+
+## Packaging
+
+Three layers, all re-exported by `@voltro/web` so apps import everything from
+the framework's web entry:
+
+- **Headless bindings** (`useFormBinding`, `useDataTable`, `useQueryField`, …)
+  → `@voltro/client` — pure logic, no kit dependency; works with any
+  presentation (incl. an MUI/Mantine adapter).
+- **The widget seam + components** (`<AutoForm>` / `<Field>` / `<DataTable>` /
+  `<AsyncSelect>` + the registry + accessible HTML defaults) → `@voltro/ui`.
+- **The styled kit** (Tailwind `shadcnWidgets` + tokens) → `@voltro/ui-shadcn`,
+  which plugs into the seam via `<WidgetRegistryProvider widgets={shadcnWidgets}>`.
+
+## In this section
+
+- **[Forms & tables](./forms-and-tables)** — `<AutoForm>`, `<DataTable>`,
+  query-bound pickers, the widget seam, skeletons, filters.
+- **[Reactive components](./reactive-components)** — workflow progress, presence
+  / multiplayer, AI chat — UI over the framework's durable + reactive backend.
+- **[Client utilities](./client-utilities/use-can)** — `useCan`, `useDerived`,
+  `useProvenance`, `useUndo`, `usePreview`, async validation, `<RecordView>`,
+  the typed analytics catalog, the offline outbox, windowed subscriptions.
+
+
+
+---
+
+<!-- source: en/ui/forms-and-tables.md -->
+## Forms & tables
+
+_<AutoForm> binds to a mutation, <DataTable> to a query — fields and columns from the Schema, validation and live updates for free._
+
+Import components from `@voltro/web`, headless hooks from `@voltro/client`.
+
+## `<AutoForm>` — bind to a MUTATION
+
+A form binds to **one mutation's** input `Schema`. This cleanly resolves
+create-vs-update: they're *different mutations with different input schemas*, so
+they're naturally different forms — no "CRUD mode" switch.
+
+```tsx
+import { AutoForm } from '@voltro/web'
+
+// fields from the mutation's input schema; client+server share the schema;
+// submits via the mutation with op-correct optimistic (insert prepends, etc.)
+<AutoForm api="app" mutation="todos.create" onSuccess={(t) => navigate(`/todos/${t.id}`)} />
+
+// update: bind the update mutation + pass the existing row
+<AutoForm api="app" mutation="todos.update" defaults={row} />
+```
+
+Here it is **live** — a real `<AutoForm>` bound to a throwaway demo API (your
+own sandbox; data resets on refresh). Add a todo and watch it appear in the
+table below, pushed from the server:
+
+```tsx
+<AutoForm api="docs" mutation="todos.create" submitLabel="Add todo" />
+<DataTable api="docs" query="todos.list" />
+```
+
+A combined create-or-edit screen is a three-line wrapper:
+
+```tsx
+{row
+  ? <AutoForm api="app" mutation="todos.update" defaults={row} />
+  : <AutoForm api="app" mutation="todos.create" />}
+```
+
+### The customization ladder
+
+- **Rung 0 — zero config.** Fields render from the schema: a `Schema.Literal`
+  union → `select`; string → text; boolean → checkbox; `Date` → date; nested
+  object → a `custom` placeholder asking for a render-prop.
+- **Rung 1 — one custom widget** via a `<Field>` render-prop:
+  ```tsx
+  import { AutoForm, Field, AsyncSelect } from '@voltro/web'
+
+  <AutoForm api="app" mutation="todos.create">
+    {() => (
+      <>
+        <Field name="title" />                                            {/* auto */}
+        <Field name="assigneeId">
+          {(w) => <AsyncSelect {...w} api="app" source="users.search" />} {/* live picker */}
+        </Field>
+      </>
+    )}
+  </AutoForm>
+  ```
+- **Rung 2 — swap a widget kind app-wide** via the registry:
+  ```tsx
+  import { WidgetRegistryProvider } from '@voltro/web'
+  import { shadcnWidgets } from '@voltro/ui-shadcn'
+  <WidgetRegistryProvider widgets={shadcnWidgets}>{/* AutoForms render styled */}</WidgetRegistryProvider>
+  ```
+- **Rung 3 — own the layout.** Pass children + arrange `<Field>`s (columns,
+  sections, tabs); each still auto-renders.
+- **Eject (headless).** `useFormBinding('app', 'todos.create')` returns
+  `{ fields, values, errors, isValid, pending, setValue, submit, reset }` for
+  100% custom JSX — the binding stays.
+
+## `<DataTable>` — bind to a QUERY
+
+Columns come from the query's output `Schema`; rows are a LIVE subscription
+(update on any write, no refetch); headers sort client-side.
+
+```tsx
+import { DataTable } from '@voltro/web'
+
+<DataTable
+  api="app"
+  query="todos.list"
+  rowActions={(row) => <button onClick={() => del.mutate({ id: row.id })}>Delete</button>}
+/>
+```
+
+**Live** — the same demo todos, with per-row actions wired to the toggle +
+delete mutations. Open this page in a second tab and toggle or delete a row:
+the other tab updates instantly, no refetch — that's the reactive query, not a
+poll.
+
+```tsx
+<DataTable
+  api="docs"
+  query="todos.list"
+  rowActions={(row) => (
+    <>
+      <button onClick={() => toggle.mutate({ id: row.id, done: !row.done })}>Done</button>
+      <button onClick={() => del.mutate({ id: row.id })}>Delete</button>
+    </>
+  )}
+/>
+```
+
+Headless eject: `useDataTable('app', 'todos.list', { initialSort, pageSize })`
+→ `{ columns, rows, loading, error, sort, toggleSort, loadMore, hasMore }`.
+`pageSize` opts into LIVE grow-the-window pagination (a "Load more" button; the
+query applies `.limit(input.limit)`) — rows stay reactive as the window grows.
+`renderCell` / `rowKey` / `emptyText` / `loadMoreText` cover the common overrides.
+
+## Query-bound pickers
+
+A picker binds to a query the way a form binds to a mutation. `<AsyncSelect>`
+(or the headless `useQueryField`) drives a debounced, LIVE typeahead off a
+source query — the option list updates reactively when the rows change:
+
+```tsx
+const picker = useQueryField('app', 'users.search', { labelField: 'name', valueField: 'id' })
+// → { options, loading, term, search(term) }
+```
+
+Three cases need zero config because the schema says enough: an `enum` →
+`select` (the options ARE the union); a `reference()` column → defaults to
+`async-select` on the conventional `users.search`; a create-on-the-fly combobox
+= a picker bound to a query (search) AND a mutation (`tags.create`).
+
+## Skeletons — shape-matched loading, no CLS
+
+While a bound query/mutation loads, render a placeholder shaped like the real
+thing — derived from the same descriptor, so the swap causes zero layout shift.
+
+```tsx
+import { FormSkeleton, TableSkeleton } from '@voltro/web'
+<FormSkeleton api="app" mutation="todos.create" />   {/* right field count */}
+<TableSkeleton api="app" query="todos.list" rows={8} /> {/* right columns */}
+```
+
+## Filters — the read-side AutoForm
+
+A query's INPUT Schema IS the filter spec. `<QueryFilters>` generates a control
+per filterable input field; values map to the query input; the result + count
+update LIVE (the query is a subscription).
+
+```tsx
+import { QueryFilters } from '@voltro/web'
+
+<QueryFilters api="app" query="todos.list">
+  {(f) => <DataTable api="app" query="todos.list" /* … */ />}
+</QueryFilters>
+```
+
+Headless core: `useQueryFilters('app', 'todos.list')` →
+`{ filters, values, setFilter, clear, rows, count, loading }`.
+
+## The schema rule (load-bearing)
+
+A descriptor's `input` MUST be `effect/Schema` — that's what the form, the wire,
+and the capability map introspect. **Never put Zod (or another validator) in a
+`*.mutation.ts` / `*.query.ts` descriptor.** Client-side EXTRA validation
+(beyond the descriptor) may use any Standard-Schema validator.
+
+
+
+---
+
+<!-- source: en/ui/reactive-components.md -->
+## Reactive components
+
+_Drop-in UI for durable workflows, presence/multiplayer, and AI chat — bound to backend primitives the framework already has, never polling._
+
+UI over the framework's durable + reactive backend. Each has a headless hook
+(the escape hatch) + a styled component. Components from `@voltro/web`, hooks
+from `@voltro/client`.
+
+## Workflow-aware UI
+
+No other framework has a UI vocabulary for durable execution. Bind to a workflow
+run id; the timeline + wait-states push reactively (no status-poll endpoint to
+wire). `useWorkflowRunState('app', runId)` is the headless aggregator over the
+EXISTING run/steps/events subscriptions → `{ status, steps, currentStep,
+waitingFor, error, traceId, cancel, resume, signal, update }`.
+
+```tsx
+import { WorkflowProgress, WorkflowStatusBadge, ApprovalControls } from '@voltro/web'
+import { useWorkflowRunState } from '@voltro/client'
+
+const run = useWorkflowRunState('app', runId)
+<WorkflowProgress api="app" runId={runId} />       {/* live step timeline */}
+<WorkflowStatusBadge api="app" runId={runId} />    {/* status + failing step + trace hint */}
+
+// Approve/Reject a parked awaitSignal — renders ONLY while the run waits on it:
+<ApprovalControls
+  when={run.waitingFor?.name === 'approval'}
+  onApprove={() => run.signal('approval', { approved: true })}
+  onReject={() => run.signal('approval', { approved: false })}
+/>
+```
+
+Signal/update payloads are schema-typed (declared on the workflow's `messages`
+metadata) — don't pass stringly-typed blobs.
+
+## Reactive multiplayer
+
+`@voltro/plugin-presence` ships ephemeral "who's online" per channel. Combined
+with the reactive engine, live-collaboration primitives become drop-ins —
+prop-driven so the kit stays plugin-agnostic. Feed them the roster from
+`usePresence` (`@voltro/plugin-presence/web`):
+
+```tsx
+import { PresenceAvatars, EditingIndicator } from '@voltro/web'
+import { usePresence, useTyping } from '@voltro/plugin-presence/web'
+
+const members = usePresence(`doc:${docId}`, { meta: { name, field: 'title' } })
+<PresenceAvatars members={members} max={5} />
+<EditingIndicator members={members} selfKey={myId} field="title" />
+
+const typing = useTyping(`thread:${threadId}`, { selfKey: myId })  // { active, isTyping, start, stop }
+```
+
+Live cursors ride an ephemeral broadcast lane, NEVER the durable presence table
+— don't write cursor positions at 60fps to a swept table.
+
+## AI chat — `<AgentChat>`
+
+A complete chat over an agent's synthesized `*.send` + `*.messages` — durable +
+reactive, so reconnect/reload-surviving for free. Render from the persisted
+`parts` (text / reasoning / tool / source / file) so reload === live.
+
+```tsx
+import { AgentChat, AgentStream, AppAgent } from '@voltro/web'
+import { useAgentChat } from '@voltro/client'
+
+const threadId = useRef(`thread_${crypto.randomUUID().replace(/-/g, '')}`).current
+<AgentChat api="app" agent="support" threadId={threadId} />
+
+// Headless — render your own bubbles from chat.messages[i].parts:
+<AgentStream api="app" agent="support" threadId={threadId}>
+  {(chat) => chat.messages.map((m) => /* … */)}
+</AgentStream>
+```
+
+`<AppAgent>` is the end-user "do it for me" agent: `<AgentChat>` + a tools
+disclosure (it acts AS the logged-in subject, so its ceiling is the subject's
+permissions). Don't hand-wire `useResumableAgentStream` + a bubble list for a
+standard chat — `<AgentChat>` is the supported path; reach for the resumable
+hook directly only for a TRANSIENT (non-persisted) run over a `*.stream.ts`.
+
+
+
+---
+
+<!-- source: en/ui/client-utilities/use-can.md -->
+## useCan
+
+_Gate UI on the same scope strings the server enforces — reactive permissions._
+
+Gate UI on the SAME scope strings the server's `requireScope` checks — one
+source of truth, no separate frontend permission list. Feed the subject's scopes
+(from your session query) to `<PermissionProvider>`; `useCan` reads them.
+
+```tsx
+import { PermissionProvider, useCan } from '@voltro/web'
+
+<PermissionProvider scopes={session.scopes}>…</PermissionProvider>
+const canDelete = useCan('todos:delete')   // ADMIN bypasses; deny-by-default
+```
+
+UX only — the server still enforces. Pairs with `<AutoForm>` / `<DataTable>` to
+auto-hide actions the subject can't perform.
+
+
+
+---
+
+<!-- source: en/ui/client-utilities/use-derived.md -->
+## useDerived
+
+_A value computed from reactive sources, recomputed only when a source changes._
+
+A value computed from reactive sources (subscription snapshots), recomputed only
+when a source changes, same reference otherwise — the formula layer.
+
+```tsx
+const total = useDerived({ cart: cart ?? [], tax }, ({ cart, tax }) =>
+  cart.reduce((s, i) => s + i.price, 0) * (1 + tax))
+```
+
+A derived value that needs the DB is a computed *query* (server), not this.
+
+
+
+---
+
+<!-- source: en/ui/client-utilities/use-preview.md -->
+## usePreview
+
+_Mutation dry-run — the {old,new} diff in a rolled-back transaction before commit._
+
+"What will this change?" The app exposes a preview action that runs the real
+handler in a transaction the framework **rolls back** (`previewInRollback` +
+`buildPreview` from `@voltro/runtime`); `usePreview` returns the `{old,new}` diff
+before commit. Actions (external I/O) aren't previewable — same boundary as undo.
+
+```tsx
+const p = usePreview('app', 'todos.update.preview')
+const diff = await p.preview({ id, title })  // { rows, summary } — nothing committed
+```
+
+
+
+---
+
+<!-- source: en/ui/client-utilities/use-async-validation.md -->
+## useAsyncValidation
+
+_DB-backed field validation as the user types — debounced, typed, over a query._
+
+Async checks that need the DB (uniqueness, cross-row rules) run reactively as the
+user types, debounced + typed, over a query — the same query gates submit.
+
+```tsx
+const email = useAsyncValidation('app', 'users.emailAvailable', value, {
+  input: (v) => ({ email: v }),
+  interpret: (r) => ({ valid: r.available, message: r.available ? undefined : 'Email taken' }),
+})  // email.status: 'idle' | 'checking' | 'valid' | 'invalid'
+```
+
+
+
+---
+
+<!-- source: en/ui/client-utilities/record-view.md -->
+## RecordView
+
+_Live read-only detail view for one record plus its eager-loaded relations._
+
+The read counterpart to `<AutoForm>`: a live detail view for one record + its
+eager-loaded relations (scalars → a definition list; arrays → nested tables).
+`useRecord('app', 'users.get', { id })` is the headless core.
+
+```tsx
+import { RecordView } from '@voltro/web'
+<RecordView api="app" query="users.get" input={{ id }} />
+```
+
+
+
+---
+
+<!-- source: en/ui/client-utilities/use-provenance.md -->
+## useProvenance
+
+_Last-write attribution (actor + traceId) for a (table, id, column)._
+
+"Why is this value here?" Last-write attribution (audit actor + traceId) for a
+`(table, id, column)`, over `/_voltro/inspect/provenance`. Out-of-band /
+un-audited rows report no attribution (never a fabricated actor); computed
+values are set-level. Available in dev.
+
+```tsx
+const prov = useProvenance('app', 'invoices', invoiceId, 'status')
+// → { value, lastWrite: { actor, at, traceId }, attribution, found }
+```
+
+
+
+---
+
+<!-- source: en/ui/client-utilities/use-undo.md -->
+## useUndoLog
+
+_Universal end-user undo + redo over mutations, server-persisted via synthesized inverses._
+
+End-user Ctrl-Z over mutations, **server-backed**. When undo capture is on, the
+framework records each mutation's change-set (the CDC `{old,new}` per row) into
+`_voltro_undo_log` — inside the mutation's own transaction, so a rolled-back
+write leaves no entry. Three built-in rpc procedures expose it, typed
+end-to-end via codegen:
+
+- `__voltro.undo.log` — a reactive, **subject-scoped** feed of your recent
+  undoable actions (newest first).
+- `__voltro.undo.apply` / `__voltro.undo.redo` — undo / redo one invocation by id.
+
+`useUndoLog(api)` is the client controller:
+
+```tsx
+const undo = useUndoLog('app')
+// → { entries, loading, canUndo, canRedo, undo, redo, undoLast, redoLast }
+
+<button disabled={!undo.canUndo} onClick={() => undo.undoLast()}>Undo</button>
+<button disabled={!undo.canRedo} onClick={() => undo.redoLast()}>Redo</button>
+```
+
+Undo applies the synthesized inverse as a **normal store write** — it traverses
+the same tenant/RBAC guards, is reactive (the affected rows reappear / vanish
+live, even across tabs), and is audited. It is **per-actor** (you can't undo
+another subject's action), refuses on a concurrent-change **conflict** or past
+an **action** boundary (an external side effect), and is idempotent. Because the
+stack lives on the server, it survives a page reload.
+
+## Enabling — `VOLTRO_UNDO`
+
+Capture has a per-mutation cost (a read-before-write on update/delete + a
+log-row insert), so it's **on outside production, off in production** by default;
+set `VOLTRO_UNDO=on|off` to override (the same environment-aware default the
+durable trace persistence uses). When off, the table isn't created, nothing is
+captured, and the built-ins aren't served or codegen'd.
+
+## Boundaries
+
+Captures writes made through `ctx.store` (the same scope CDC covers) — raw
+`unsafe()` SQL writes and the bulk helpers (`updateMany` / `deleteMany` /
+`upsert`) aren't captured. Undo of an action-crossing invocation is refused
+(the engine's "can't undo past an external effect" wall).
+
+
+
+---
+
+<!-- source: en/ui/client-utilities/analytics-catalog.md -->
+## Analytics catalog
+
+_Typed analytics — defineEvent + createAnalytics; track is compile-checked._
+
+Declared, Schema-typed events: `track` is typed against the catalog (wrong name
+/ payload = a compile error) + validated at runtime. One discoverable taxonomy.
+
+```tsx
+const analytics = createAnalytics([
+  defineEvent('checkout.started', Schema.Struct({ plan: Schema.String })),
+], sink)
+analytics.track('checkout.started', { plan: 'pro' })   // typed + validated
+```
+
+Builds on `defineTracking` (the declarative per-component event map).
+
+
+
+---
+
+<!-- source: en/ui/client-utilities/use-outbox.md -->
+## useOutbox
+
+_Queue mutations offline, replay them in order on reconnect._
+
+Queue mutations while offline, replay IN ORDER on reconnect — over the existing
+optimistic layer. Replay stops at the first conflict to preserve causality. NOT
+multi-device CRDT (single-user/device, honest about its limits).
+
+```tsx
+const outbox = useOutbox({ send })
+// → { queue, enqueue, replay, online, pending, conflicts }
+```
+
+
+
+---
+
+<!-- source: en/ui/client-utilities/use-windowed-subscription.md -->
+## useWindowedSubscription
+
+_Subscribe to only the visible viewport of a huge table — live and bounded._
+
+For a huge table, subscribe to only the visible viewport (offset+limit from
+scroll); the server pushes deltas only for in-window rows — live AND bounded.
+
+```tsx
+const w = useWindowedSubscription('app', 'rows.list', { rowHeight: 32, viewportHeight: 480, total })
+<div style={{ height: 480, overflow: 'auto' }} onScroll={w.onScroll}>
+  <div style={{ height: w.topSpacer }} />
+  {w.rows.map(/* … */)}
+  <div style={{ height: w.bottomSpacer }} />
+</div>
+```

package/templates/agent-docs/security.md

@@ -0,0 +1,42 @@
+# Security
+
+> 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.
+
+
+
+---
+
+<!-- source: en/security/overview.md -->
+## Overview
+
+_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._
+
+Security is a first-class concern, not an afterthought. This page is the public summary of how we handle it; the machine-readable policy also ships as a `SECURITY.md` inside every `@voltro/*` package.
+
+## Reporting a vulnerability
+
+Please report suspected vulnerabilities **privately** — never in public issues or channels.
+
+- **Email [support@voltro.dev](mailto:support@voltro.dev)** with the subject `SECURITY`.
+- Include the affected package(s) and version(s), the impact, and a minimal reproduction if you have one.
+
+You'll get an **acknowledgement within 3 business days**, an assessment once we've reproduced the issue, and a **coordinated disclosure** timeline agreed with you — with credit in the release notes if you'd like it. We don't run a paid bug-bounty program yet, but we genuinely value responsible disclosure.
+
+## Supply-chain assurance
+
+Every release passes automated supply-chain gates in CI before a single package is published:
+
+- **Dependency audit.** The production dependency graph is audited on every build (`pnpm audit --prod`); a HIGH or CRITICAL advisory **fails the release**. Known-but-unfixed-upstream transitives are pinned deliberately, not waved through.
+- **Inbound-license allowlist.** Every third-party runtime dependency's license is checked against an allowlist — a disallowed license **fails the release**. The aggregated attributions ship as `THIRD-PARTY-NOTICES.md` in each package.
+- **SBOM.** A CycloneDX Software Bill of Materials of the third-party runtime graph is generated for, and attached to, each release. If your procurement or security team needs it, request it at [support@voltro.dev](mailto:support@voltro.dev).
+- **Release integrity.** Publishing is gated behind organization 2FA and a narrowly-scoped, short-lived automation token, and is all-or-nothing (two-phase) so consumers never see a half-published release.
+
+## Supported versions
+
+Voltro is pre-1.0 and ships in lockstep — all `@voltro/*` packages share one version. **Only the latest published release receives security fixes.** Pin exact versions in production and upgrade promptly.
+
+## Your data stays yours
+
+Voltro is **self-hosted**: it runs next to *your* database, with *your* connection string, *your* backups, and *your* access controls. **When you self-host**, the framework never proxies your data through Voltro infrastructure — there is no phone-home and no hosted control plane in the request path; the runtime is a library that lives in your own deployment.
+
+Managed **Voltro Cloud** is coming as a separate, opt-in deploy target. Choosing it means running your workload on Voltro-operated infrastructure under its own data-processing terms — a deliberate choice, not the default. Self-hosting remains the default and keeps the guarantees above.