@voltro/cli 0.30.1 → 0.31.0

package/templates/agent-docs/_manifest.json

@@ -341,294 +341,336 @@
       "title": "AI Flows",
       "description": "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.",
       "pkg": "@voltro/plugin-ai-flows",
-      "doc": "plugins/ai-flows.md"
+      "doc": "plugins/ai-flows.md",
+      "module": "agent-docs/plugins/ai-flows.md"
     },
     {
       "slug": "analytics-postgres",
       "title": "Postgres analytics",
       "description": "First-party lite AnalyticsSink — stores events in the main DataStore, cross-dialect, zero external infra. ~10M events/day ceiling.",
       "pkg": "@voltro/plugin-analytics-postgres",
-      "doc": "plugins/analytics-postgres.md"
+      "doc": "plugins/analytics-postgres.md",
+      "module": "agent-docs/plugins/analytics-postgres.md"
     },
     {
       "slug": "atlassian",
       "title": "Atlassian",
       "description": "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.",
       "pkg": "@voltro/plugin-atlassian",
-      "doc": "plugins/atlassian.md"
+      "doc": "plugins/atlassian.md",
+      "module": "agent-docs/plugins/atlassian.md"
     },
     {
       "slug": "audit",
       "title": "Audit",
       "description": "Mutation audit log — sinks (console/memory/custom), include/exclude filters, the audit() mixin, testing with the memory buffer.",
       "pkg": "@voltro/plugin-audit",
-      "doc": "plugins/audit.md"
+      "doc": "plugins/audit.md",
+      "module": "agent-docs/plugins/audit.md"
     },
     {
       "slug": "auth",
       "title": "Auth",
       "description": "Password + session-cookie auth — overview. Full docs in the Authentication section.",
       "pkg": "@voltro/plugin-auth",
-      "doc": "plugins/auth.md"
+      "doc": "plugins/auth.md",
+      "module": "agent-docs/plugins/auth.md"
     },
     {
       "slug": "auth-auth0",
       "title": "Auth0",
       "description": "Auth0 AuthStrategy — verifies Auth0-issued JWTs via the tenant's JWKS (no client secret) and maps a namespaced custom claim → tenantId.",
       "pkg": "@voltro/plugin-auth-auth0",
-      "doc": "plugins/auth-auth0.md"
+      "doc": "plugins/auth-auth0.md",
+      "module": "agent-docs/plugins/auth-auth0.md"
     },
     {
       "slug": "auth-clerk",
       "title": "Clerk",
       "description": "Clerk AuthStrategy — verifies Clerk-issued __session JWTs via the Frontend API JWKS (no secret key) and maps org_id → tenantId.",
       "pkg": "@voltro/plugin-auth-clerk",
-      "doc": "plugins/auth-clerk.md"
+      "doc": "plugins/auth-clerk.md",
+      "module": "agent-docs/plugins/auth-clerk.md"
     },
     {
       "slug": "auth-kinde",
       "title": "Kinde",
       "description": "Kinde AuthStrategy — verifies Kinde-issued JWTs via JWKS at the configured issuer (no client secret) and maps org_code → tenantId.",
       "pkg": "@voltro/plugin-auth-kinde",
-      "doc": "plugins/auth-kinde.md"
+      "doc": "plugins/auth-kinde.md",
+      "module": "agent-docs/plugins/auth-kinde.md"
     },
     {
       "slug": "auth-oidc",
       "title": "OIDC (generic)",
       "description": "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.",
       "pkg": "@voltro/plugin-auth-oidc",
-      "doc": "plugins/auth-oidc.md"
+      "doc": "plugins/auth-oidc.md",
+      "module": "agent-docs/plugins/auth-oidc.md"
     },
     {
       "slug": "auth-supabase",
       "title": "Supabase Auth",
       "description": "Supabase Auth (GoTrue) AuthStrategy — verifies Supabase-issued JWTs via the project's JWKS and maps app_metadata.tenant_id → tenantId.",
       "pkg": "@voltro/plugin-auth-supabase",
-      "doc": "plugins/auth-supabase.md"
+      "doc": "plugins/auth-supabase.md",
+      "module": "agent-docs/plugins/auth-supabase.md"
     },
     {
       "slug": "auth-workos",
       "title": "WorkOS",
       "description": "WorkOS AuthStrategy — verifies WorkOS AuthKit / SSO JWTs via JWKS (no API key) and maps org_id → tenantId.",
       "pkg": "@voltro/plugin-auth-workos",
-      "doc": "plugins/auth-workos.md"
+      "doc": "plugins/auth-workos.md",
+      "module": "agent-docs/plugins/auth-workos.md"
     },
     {
       "slug": "billing",
       "title": "Billing",
       "description": "Subscriptions, plans, entitlements, and usage metering over a pluggable provider (Stripe + mock). Money is integer minor units.",
       "pkg": "@voltro/plugin-billing",
-      "doc": "plugins/billing.md"
+      "doc": "plugins/billing.md",
+      "module": "agent-docs/plugins/billing.md"
     },
     {
       "slug": "broadcast",
       "title": "Broadcast",
       "description": "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.",
       "pkg": "@voltro/plugin-broadcast",
-      "doc": "plugins/broadcast.md"
+      "doc": "plugins/broadcast.md",
+      "module": "agent-docs/plugins/broadcast.md"
     },
     {
       "slug": "cdc-out",
       "title": "CDC-out (reverse-ETL)",
       "description": "Declaratively mirror table changes outward to external sinks (webhook / Kafka / Snowflake / BigQuery) through a durable outbox — ordered per pipe, at-least-once from enqueue, retried with backoff, dead-lettered.",
       "pkg": "@voltro/plugin-cdc-out",
-      "doc": "plugins/cdc-out.md"
+      "doc": "plugins/cdc-out.md",
+      "module": "agent-docs/plugins/cdc-out.md"
     },
     {
       "slug": "clickhouse",
       "title": "ClickHouse",
       "description": "Production-grade OLAP AnalyticsSink over ClickHouse — self-hosted or ClickHouse Cloud — for billions of events with millisecond aggregates.",
       "pkg": "@voltro/plugin-clickhouse",
-      "doc": "plugins/clickhouse.md"
+      "doc": "plugins/clickhouse.md",
+      "module": "agent-docs/plugins/clickhouse.md"
     },
     {
       "slug": "datadog",
       "title": "Datadog",
       "description": "Agentless Datadog metrics exporter — pushes the unified Metrics-API to Datadog's /api/v2/series HTTP intake.",
       "pkg": "@voltro/plugin-datadog",
-      "doc": "plugins/datadog.md"
+      "doc": "plugins/datadog.md",
+      "module": "agent-docs/plugins/datadog.md"
     },
     {
       "slug": "deactivation",
       "title": "Deactivation",
       "description": "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.",
       "pkg": "@voltro/plugin-deactivation",
-      "doc": "plugins/deactivation.md"
+      "doc": "plugins/deactivation.md",
+      "module": "agent-docs/plugins/deactivation.md"
     },
     {
       "slug": "duckdb",
       "title": "DuckDB",
       "description": "Embedded DuckDB AnalyticsSink — real column-store OLAP in-process, no external service to run.",
       "pkg": "@voltro/plugin-duckdb",
-      "doc": "plugins/duckdb.md"
+      "doc": "plugins/duckdb.md",
+      "module": "agent-docs/plugins/duckdb.md"
     },
     {
       "slug": "flags",
       "title": "Feature flags",
       "description": "Feature flags — per-subject / per-tenant targeting, deterministic % rollouts, kill-switch, declarative rpc gating + client UI gating.",
       "pkg": "@voltro/plugin-flags",
-      "doc": "plugins/flags.md"
+      "doc": "plugins/flags.md",
+      "module": "agent-docs/plugins/flags.md"
     },
     {
       "slug": "governance",
       "title": "Governance",
       "description": "Data governance — retention TTL sweep, GDPR export + erasure, consent ledger, and field-level encryption for .encrypted() columns. Builds on audit + soft-delete.",
       "pkg": "@voltro/plugin-governance",
-      "doc": "plugins/governance.md"
+      "doc": "plugins/governance.md",
+      "module": "agent-docs/plugins/governance.md"
     },
     {
       "slug": "licensing",
       "title": "Licensing",
       "description": "Offline-verified EdDSA license keys + cloud-issued entitlement snapshots that feed plugin-billing; pricing decided server-side, never baked into a published version.",
       "pkg": "@voltro/plugin-licensing",
-      "doc": "plugins/licensing.md"
+      "doc": "plugins/licensing.md",
+      "module": "agent-docs/plugins/licensing.md"
     },
     {
       "slug": "logship",
       "title": "Log shipping",
       "description": "Ship structured logs to Better Stack / Axiom / Loki / any HTTP sink — batched, redacted, fail-soft. Rides the framework log-sink hook.",
       "pkg": "@voltro/plugin-logship",
-      "doc": "plugins/logship.md"
+      "doc": "plugins/logship.md",
+      "module": "agent-docs/plugins/logship.md"
     },
     {
       "slug": "mail",
       "title": "Mail",
       "description": "Transactional email — Resend / Postmark / SendGrid / SMTP, React-Email templates with auto-discovery, per-tenant suppression, bounce/complaint handling, durable delivery via workflows.",
       "pkg": "@voltro/plugin-mail",
-      "doc": "plugins/mail.md"
+      "doc": "plugins/mail.md",
+      "module": "agent-docs/plugins/mail.md"
     },
     {
       "slug": "moderation",
       "title": "Moderation",
       "description": "Moderate user content before it commits — keyword denylist or AI provider, block or flag via rpc interceptor, plus an in-handler redact helper.",
       "pkg": "@voltro/plugin-moderation",
-      "doc": "plugins/moderation.md"
+      "doc": "plugins/moderation.md",
+      "module": "agent-docs/plugins/moderation.md"
     },
     {
       "slug": "multitenancy",
       "title": "Multi-tenancy",
       "description": "The tenant() schema mixin (auto-scope reads + auto-fill writes), the assertOwnTenant write-guard, and the typed TenantMismatch error.",
       "pkg": "@voltro/plugin-multitenancy",
-      "doc": "plugins/multitenancy.md"
+      "doc": "plugins/multitenancy.md",
+      "module": "agent-docs/plugins/multitenancy.md"
     },
     {
       "slug": "notifications",
       "title": "Notifications",
       "description": "Unified notifications — one send API across email / Slack / SMS / push / in-app, with per-user channel preferences, an in-app inbox, and delivery records.",
       "pkg": "@voltro/plugin-notifications",
-      "doc": "plugins/notifications.md"
+      "doc": "plugins/notifications.md",
+      "module": "agent-docs/plugins/notifications.md"
     },
     {
       "slug": "openapi",
       "title": "OpenAPI",
       "description": "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.",
       "pkg": "@voltro/plugin-openapi",
-      "doc": "plugins/openapi.md"
+      "doc": "plugins/openapi.md",
+      "module": "agent-docs/plugins/openapi.md"
     },
     {
       "slug": "postgis",
       "title": "PostGIS",
       "description": "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.",
       "pkg": "@voltro/plugin-postgis",
-      "doc": "plugins/postgis.md"
+      "doc": "plugins/postgis.md",
+      "module": "agent-docs/plugins/postgis.md"
     },
     {
       "slug": "posthog",
       "title": "PostHog",
       "description": "Track-only AnalyticsSink that forwards events to PostHog's /capture endpoint — compose it with a second sink that owns reads.",
       "pkg": "@voltro/plugin-posthog",
-      "doc": "plugins/posthog.md"
+      "doc": "plugins/posthog.md",
+      "module": "agent-docs/plugins/posthog.md"
     },
     {
       "slug": "presence",
       "title": "Presence",
       "description": "Ephemeral realtime presence — who's online in a channel, with heartbeat, live roster, and per-member metadata (status, cursor). Works cross-instance.",
       "pkg": "@voltro/plugin-presence",
-      "doc": "plugins/presence.md"
+      "doc": "plugins/presence.md",
+      "module": "agent-docs/plugins/presence.md"
     },
     {
       "slug": "prometheus",
       "title": "Prometheus",
       "description": "Prometheus exporter — scrapes the unified Metrics-API at GET /metrics in text exposition format.",
       "pkg": "@voltro/plugin-prometheus",
-      "doc": "plugins/prometheus.md"
+      "doc": "plugins/prometheus.md",
+      "module": "agent-docs/plugins/prometheus.md"
     },
     {
       "slug": "ratelimit",
       "title": "Rate limiting",
       "description": "Per-endpoint, per-subject and per-tenant request limits via the rpc interceptors. Sliding-window / fixed-window / token-bucket, memory / postgres / redis stores.",
       "pkg": "@voltro/plugin-ratelimit",
-      "doc": "plugins/ratelimit.md"
+      "doc": "plugins/ratelimit.md",
+      "module": "agent-docs/plugins/ratelimit.md"
     },
     {
       "slug": "rbac",
       "title": "RBAC",
       "description": "Roles + permissions + the permission() handler guard. Roles compile to scopes.",
       "pkg": "@voltro/plugin-rbac",
-      "doc": "plugins/rbac.md"
+      "doc": "plugins/rbac.md",
+      "module": "agent-docs/plugins/rbac.md"
     },
     {
       "slug": "scim",
       "title": "SCIM",
       "description": "SCIM 2.0 provisioning — Users + Groups REST endpoints so an enterprise IdP (Okta, Entra, OneLogin) can create / update / deactivate users in your app.",
       "pkg": "@voltro/plugin-scim",
-      "doc": "plugins/scim.md"
+      "doc": "plugins/scim.md",
+      "module": "agent-docs/plugins/scim.md"
     },
     {
       "slug": "search",
       "title": "Search",
       "description": "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.",
       "pkg": "@voltro/plugin-search",
-      "doc": "plugins/search.md"
+      "doc": "plugins/search.md",
+      "module": "agent-docs/plugins/search.md"
     },
     {
       "slug": "sentry",
       "title": "Sentry",
       "description": "Deep Sentry integration — errors correlated to the distributed trace, breadcrumbs from the log sink, and opt-in performance traces.",
       "pkg": "@voltro/plugin-sentry",
-      "doc": "plugins/sentry.md"
+      "doc": "plugins/sentry.md",
+      "module": "agent-docs/plugins/sentry.md"
     },
     {
       "slug": "soft-delete",
       "title": "Soft delete",
       "description": "The softDelete() schema mixin — deletedAt / deletedBy columns, delete() redirected to an UPDATE, default reads filtered, hardDelete() bypass.",
       "pkg": "@voltro/plugin-soft-delete",
-      "doc": "plugins/soft-delete.md"
+      "doc": "plugins/soft-delete.md",
+      "module": "agent-docs/plugins/soft-delete.md"
     },
     {
       "slug": "sso-saml",
       "title": "SAML SSO",
       "description": "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.",
       "pkg": "@voltro/plugin-sso-saml",
-      "doc": "plugins/sso-saml.md"
+      "doc": "plugins/sso-saml.md",
+      "module": "agent-docs/plugins/sso-saml.md"
     },
     {
       "slug": "storage",
       "title": "Storage",
       "description": "File storage behind one StorageService — public objects served direct from the bucket/CDN, private objects gated by an access policy + per-object grants. S3 / R2 / GCS / MinIO / filesystem / memory providers, presigned URLs, a dashboard browser.",
       "pkg": "@voltro/plugin-storage",
-      "doc": "plugins/storage.md"
+      "doc": "plugins/storage.md",
+      "module": "agent-docs/plugins/storage.md"
     },
     {
       "slug": "tinybird",
       "title": "Tinybird",
       "description": "Hosted-ClickHouse AnalyticsSink over Tinybird's Events API + Pipes — pay-as-you-go OLAP without operating a cluster.",
       "pkg": "@voltro/plugin-tinybird",
-      "doc": "plugins/tinybird.md"
+      "doc": "plugins/tinybird.md",
+      "module": "agent-docs/plugins/tinybird.md"
     },
     {
       "slug": "versioning",
       "title": "Row versioning",
       "description": "Full row history + time-travel. audit() records who/when; versioning records what-changed-to-what — a value snapshot of every row on every write, with as-of queries.",
       "pkg": "@voltro/plugin-versioning",
-      "doc": "plugins/versioning.md"
+      "doc": "plugins/versioning.md",
+      "module": "agent-docs/plugins/versioning.md"
     },
     {
       "slug": "webhooks",
       "title": "Webhooks",
       "description": "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.",
       "pkg": "@voltro/plugin-webhooks",
-      "doc": "plugins/webhooks.md"
+      "doc": "plugins/webhooks.md",
+      "module": "agent-docs/plugins/webhooks.md"
     }
   ],
   "templates": {

package/templates/agent-docs/cli.md

@@ -1193,8 +1193,10 @@ inquiries.publicFeed  reviewed=public by design; returns only published rows
 The reason is required: `reviewed=` with no why is the claim without the
 evidence, and doctor refuses it. A bare tag is always available and is the honest
 alternative. The two are counted and printed apart, and
-`--write-authz-allowlist` **preserves** reviewed lines rather than flattening
-them back to debt.
+`--write-authz-allowlist` is **additive**: it keeps the existing file verbatim —
+entries, comments, grouping, order — and appends only tags it does not already
+contain. It cannot remove a line. Removing one is your edit, or it happens on its
+own when an executor gains a guard and its line stops mattering.
 
 #### Reading the whole list
 

package/templates/agent-docs/database/migrations.md

@@ -3281,7 +3281,7 @@ sides (key-sorted, space-free) before comparing. Update the framework.
 
 Cross-dialect: object literal defaults are now emitted to DDL on **every**
 dialect, in each one's json idiom — postgres `'<json>'::jsonb`, mysql/mariadb
-`(CAST('<json>' AS JSON))` (a literal default is rejected on a JSON column),
+`(CONVERT('<json>' USING utf8mb4))` (a literal default is rejected on a JSON column),
 mssql/sqlite a `'<json>'` string literal — and the comparison canonicalises
 each engine's introspected form (postgres reorders + spaces; mysql wraps in
 `cast(…)`; mssql wraps in `('…')`). Arrays are unaffected (an array default
@@ -3289,6 +3289,19 @@ stays as-is — its `json[]` vs native `array()` column is ambiguous). If you
 need a per-insert dynamic value instead of a fixed literal, use a factory
 `.default(() => ({ … }))` (the store applies it at insert).
 
+> **`CAST(… AS JSON)` is MySQL-only, and shipping it for both cost a
+> part-applied migration.** MariaDB has no JSON *type* — the column is
+> `LONGTEXT` with `CHECK (json_valid(...))` — so `AS JSON` is not a cast target
+> it accepts, and `json().default([])` died mid-plan with
+> `ERROR 1064 … near 'JSON))'`. The obvious MariaDB spelling
+> `DEFAULT ('[]')` then fails on MySQL with
+> `ERROR 1101 BLOB, TEXT, GEOMETRY or JSON column can't have a default value`,
+> because a parenthesised literal is still a literal there. `CONVERT(… USING
+> utf8mb4)` is the one expression both accept; measured against MariaDB 11.8.8
+> and MySQL 8.4.10, and covered by an integration test that boots both.
+> Reported against 0.30.2, fixed in 0.31.0.
+
+
 ## MySQL `db plan` / `db apply` crashes: `Cannot read properties of undefined (reading 'toLowerCase')`
 
 MySQL 8 returns `information_schema` result columns in UPPERCASE

package/templates/agent-docs/internationalization.md

@@ -29,8 +29,8 @@ export default {
   type:  'web' as const,
   name:  'myApp',
   port:  5191,
-  // Codes the app SHIPS catalogs for. Every code listed here MUST
-  // have a corresponding `src/locales/<code>.ts` file or boot fails.
+  // The languages this app serves. Drives `<html lang>`, the resolved
+  // locale, and the `locale` your page `meta` receives.
   locales: ['en', 'de'] as const,
   // Fallback locale when no cookie / Accept-Language matches a
   // supported one. MUST be in `locales`. Pick your source-of-truth
@@ -39,7 +39,29 @@ export default {
 }
 ```
 
-The framework's generated `.framework/app.tsx` wraps the Router in `<I18nProvider>` automatically. You don't write the provider yourself; you don't import `@voltro/i18n` in your layout. Each code in `locales` must have a matching `src/locales/<code>.ts` catalog file — a missing file fails boot, not silently at runtime.
+The framework's generated `.framework/app.tsx` wraps the Router in `<I18nProvider>` automatically when your app **ships catalogs**. You don't write the provider yourself; you don't import `@voltro/i18n` in your layout.
+
+### Declaring languages is not the same as adopting the catalogs
+
+`locales:` states which languages the app serves. Whether `@voltro/i18n` gets
+wired is decided separately, by whether `src/locales/<code>.ts` exists for every
+listed code:
+
+| `locales:` | `src/locales/*` | what you get |
+|---|---|---|
+| declared | present | `<I18nProvider>` wired, `useT()` works, plus the language facts |
+| declared | absent | the language facts ONLY — `<html lang>`, the resolved locale, `meta.locale`. Bring your own i18n stack. |
+| absent | — | everything falls back to `'en'` |
+
+The second row exists because the two used to be one switch, and that made
+`locales:` unusable for an app with its own i18n: declaring it demanded catalog
+files and failed the boot, so the option got left out — and then `<html lang>`
+was `"en"` and every page's `meta` received `locale: 'en'`, for every visitor, in
+an app that is not English. That is worse than useless: a page that trusted the
+value would have rendered the wrong language.
+
+`voltro dev` prints which mode it is in, so a declared-but-unwired app is never a
+silent surprise.
 
 ## Locale resolution order
 
@@ -59,6 +81,35 @@ The client **adopts what the server resolved**, reading it from the `<html lang>
 
 See [Catalogs](/docs/i18n/catalogs) for the type-safe catalog convention and the component hooks, [Plurals & formatting](/docs/i18n/formatting) for CLDR plural selection and the `Intl`-backed date / number / relative-time hooks, and [URL strategies](/docs/i18n/url-strategies) for cookie-only vs URL-prefix routing.
 
+## The cookie names are exported
+
+`LOCALE_COOKIE` and `THEME_COOKIE` come from **`@voltro/i18n`** (and from `@voltro/ui-shadcn` if you use the kit):
+
+```ts
+import { LOCALE_COOKIE, THEME_COOKIE } from '@voltro/i18n'
+```
+
+Import them rather than retyping `'voltro:locale'`. A cookie name the framework READS and your app WRITES is a public API, and it is the only kind where both sides can disagree without anything failing: nothing throws, no page breaks, the resolver simply finds nothing and falls back to `Accept-Language`. The symptom is a preference that stops working for the subset of users whose browser language differs from their choice — the least likely thing anyone tests.
+
+> Until 0.31.0 the only package exporting these was `@voltro/ui-shadcn`, and `voltro doctor` told you to import from there. An app on this package and not on the shadcn kit had no constant to reach for, and would have had to adopt a UI kit for two strings. Reported by a consumer, who added that the rule "does not fire for us, and we think that is correct-by-accident".
+
+## `Could not find required 'intl' object` during SSR
+
+This throw has two causes that produce byte-identical output: there is no provider above the component, or there IS one and it was built from a **different physical copy** of `react-intl`. React contexts are object identities, so a provider from one copy is invisible to a `useT()` from the other.
+
+`voltro dev` knows whether it supplied a provider for that request, and since 0.31.0 it also counts the live copies. The diagnosis printed with the failure names both:
+
+```text
+── voltro diagnosis ───────────────────────────────────────────────────
+ssr-dev DID wrap this render in <I18nProvider>, and this process
+holds 2 live copies of @voltro/i18n bound to
+2 distinct react-intl instances.
+```
+
+**Do not use `pnpm ls` to rule this out.** It enumerates versions ON DISK; the failure is module INSTANCES in a running process, and one file loaded down two paths is two instances. A consumer reported a 500 on every SSR page with exactly one version of each installed — they were right, and the check we had published could not observe the cause. If the count says one of each, it is a framework bug and the diagnosis says so.
+
+The framework keeps both packages on one SSR instance by bundling them together (`ssr.noExternal`) and deduping them, in `voltro dev`, `voltro build` and `voltro start` alike. The remaining way to get a second copy is in your own code: building a provider from `react-intl` **directly** rather than from `@voltro/i18n`.
+
 
 
 ---