@voltro/cli 0.52.0 → 0.54.0

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

@@ -379,7 +379,7 @@ Emits `CONSTRAINT <name> UNIQUE (col1, col2, ...)` inline in CREATE
 TABLE on every dialect. Standard SQL.
 
 This is what backs `ctx.store.upsert(..., { conflictColumns: ['a', 'b'] })`
-— see [Bulk operations](/docs/database/bulk-operations#upsert).
+— see [Bulk operations](/docs/database/bulk-operations#upsert-insert-or-update-on-conflict).
 
 ## GiST indexes (PostGIS spatial)
 
@@ -627,7 +627,7 @@ await ctx.store.update('notes', id, {
 
 Two layers of validation apply:
 
-1. **JSON validity** — that the stored bytes are well-formed JSON — is enforced automatically by the database on every dialect (see [Storage + validation per dialect](#storage--validation-per-dialect)). You don't declare anything.
+1. **JSON validity** — that the stored bytes are well-formed JSON — is enforced automatically by the database on every dialect (see [Storage + validation per dialect](#storage-validation-per-dialect)). You don't declare anything.
 2. **JSON *shape*** — that the value matches your expected structure — is up to you: enforce it at the table level with `table().validate(Schema)`:
 
 ```ts
@@ -689,7 +689,7 @@ mssql, sqlite 3.8+).
   depend on?"
 
 When you don't have a recursive structure, plain
-[`withCte()`](/docs/database/query-builder#ctes) is enough.
+[`withCte()`](/docs/database/query-builder#ctes-common-table-expressions) is enough.
 
 ## Shape
 
@@ -820,7 +820,7 @@ eager-load with `.with({...})` to get the per-field pre-filter.
 
 ## See also
 
-- [Plain CTEs](/docs/database/query-builder#ctes) — `withCte()` for
+- [Plain CTEs](/docs/database/query-builder#ctes-common-table-expressions) — `withCte()` for
   non-recursive named sub-queries
 - [Self-joins](/docs/database/self-joins) — for single-level
   parent/child queries
@@ -830,7 +830,7 @@ eager-load with `.with({...})` to get the per-field pre-filter.
   `unionAll`, the mechanism a recursive CTE is built on
 - [Joins](/docs/database/joins) — relation-based traversal when the
   graph depth is fixed (e.g. parent + immediate children)
-- [Aggregations](/docs/database/query-builder#aggregations) —
+- [Aggregations](/docs/database/query-builder#aggregates) —
   COUNT/SUM/AVG over a recursive CTE's result set
 
 
@@ -940,7 +940,7 @@ keep the branches' result sets bounded.
   the column-level "in A but not in B" case
 - [Aggregations](/docs/database/aggregations) — `count()` etc. on
   a set-op result is a common pattern
-- [CTEs](/docs/database/query-builder#ctes) — name a complex set-op
+- [CTEs](/docs/database/query-builder#ctes-common-table-expressions) — name a complex set-op
   result so you can reference it in a larger query
 
 
@@ -1044,7 +1044,7 @@ Non-correlated only. The inner query can NOT reference outer-row
 columns like `WHERE inner.userId = users.id`. For correlated
 sub-queries (a common shape: "user who has at least one post created
 in the last hour") use a [Self-join](/docs/database/self-joins) or
-an [Eager-load](/docs/database/joins#eager-loading) — both can
+an [Eager-load](/docs/database/joins#eager-loading-via-with-spec) — both can
 express the same query without the correlation reference.
 
 ## Reactivity
@@ -1069,7 +1069,7 @@ every dialect we ship. No per-dialect dispatch.
   with `count()` etc. for "count of X where Y belongs to Z"
 - [Self-joins](/docs/database/self-joins) — when the relationship
   can be expressed as a join instead
-- [CTEs](/docs/database/query-builder#ctes) — for naming a
+- [CTEs](/docs/database/query-builder#ctes-common-table-expressions) — for naming a
   sub-query you reuse multiple times in the same outer query
 
 

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

@@ -350,7 +350,7 @@ on it explicitly via `.expressionIndex(name, [...], { ... })`.
 
 - [Columns](/docs/database/columns) — `.computed(row => ...)` and
   `.default(() => ...)` for the app-side variants
-- [Indexes](/docs/database/indexes#expression) — `.expressionIndex()`
+- [Indexes](/docs/database/indexes#expression-indexes) — `.expressionIndex()`
   for indexing a generated column
 - [Full-text search](/docs/database/full-text-search) — the FTS
   pattern uses STORED tsvector generated columns
@@ -989,7 +989,7 @@ behavioural gaps are too large to paper over.
 ## See also
 
 - [Columns](/docs/database/columns) — the regular schema-DSL types
-- [Expression indexes](/docs/database/indexes#expression) — the
+- [Expression indexes](/docs/database/indexes#expression-indexes) — the
   framework's index API (`kind: 'gist' | 'gin'` on postgres)
 - [PostGIS docs](https://postgis.net/docs/) — the official manual,
   authoritative for every spatial function the framework re-exports

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

@@ -700,7 +700,7 @@ A handler that a `voltro dev` session or a test actually ran is reported with wh
 
 ### What the codemod does per kind
 
-- **`rename-column`** gets a real `transform`: it renames the field in the `*.entity.ts` AND chains **`.renamedFrom('old')`** (so the differ plans a catalog RENAME, not the lossy drop+create described [above](#renamedfromoldname)), then annotates the handler sites the blast radius found.
+- **`rename-column`** gets a real `transform`: it renames the field in the `*.entity.ts` AND chains **`.renamedFrom('old')`** (so the differ plans a catalog RENAME, not the lossy drop+create described [above](#renamedfrom-oldname)), then annotates the handler sites the blast radius found.
 - **`retype-column` / `split-column` / `drop-column` / `rename-table`** are reshaping changes with no single mechanical rewrite, so they get a **`manual`** codemod: a generated, numbered checklist of the edits + the annotation to add, printed for you to apply.
 
 `voltro evolve` produces the plan; it does not apply the schema change. **`voltro check` is the gate on the result**, and `voltro db apply` lands it — after `--write`, review the annotated handlers, then run those two.

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

@@ -309,7 +309,7 @@ The query builder has dedicated pages for the deeper topics:
 - **[Self-joins](/docs/database/self-joins)** — `.as(alias)` +
   `.innerJoin(table, alias, on)` + `.selectJoined({...})` for parent/
   child trees and CTE references.
-- **[CTEs](/docs/database/query-builder#ctes)** — `.withCte(name, sub)`
+- **[CTEs](/docs/database/query-builder#ctes-common-table-expressions)** — `.withCte(name, sub)`
   for named sub-queries reusable inside the outer SELECT.
 - **[Recursive CTEs](/docs/database/recursive-cte)** — `.recursiveCte`
   for tree walks (org hierarchy, comment threads, file folders).

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

@@ -445,7 +445,7 @@ framework runs on the post-commit change channel.
 **Reach for `reference()` first.** A real foreign key across a plugin boundary
 works and survives the plugin renaming its table, because `reference()` takes
 the table as a VALUE — see
-[plugins/overview](/docs/plugins/overview#pointing-your-table-at-a-plugins-row).
+[plugins/overview](/docs/plugins/overview).
 `pluginRef` is for the case where you have deliberately chosen NOT to have a
 key: it enforces nothing at the database level.
 

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

@@ -391,7 +391,7 @@ What the framework hides for you vs what's worth knowing. Per-dialect pages dril
 | `RETURNING *` on DELETE                   | yes             | no              | yes (10.0+)     | OUTPUT DELETED.* | yes | yes |
 | Parameterized `LIMIT ?`                   | yes             | no — integer-literal inlined | yes | no — integer-literal inlined | yes | yes |
 | `LIMIT N OFFSET N` syntax                 | yes             | yes             | yes             | no — `OFFSET … ROWS FETCH NEXT … ROWS ONLY` | yes | yes |
-| DEFAULT on TEXT columns                   | yes             | **NO** — auto-uses VARCHAR(255) | yes | yes (NVARCHAR(MAX)) | yes | yes |
+| DEFAULT on TEXT columns                   | yes             | **NO** — framework emits VARCHAR(255) | yes — framework still emits VARCHAR(255) (engine parity) | yes — framework emits NVARCHAR(450) (indexable) | yes | yes |
 | Native JSON column type                   | JSONB           | JSON            | JSON            | NVARCHAR(MAX)    | TEXT                | TEXT               |
 | JSON columns returned as objects          | yes             | yes             | yes             | **no — strings** — framework auto-parses | **no — strings** — framework auto-parses | **no — strings** — framework auto-parses |
 | Booleans                                  | proper booleans | 0/1 (TINYINT)   | 0/1             | BIT (proper bool) | 0/1 (INTEGER)     | 0/1 (INTEGER)      |
@@ -796,11 +796,48 @@ The framework's DDL emitter detects the case and switches to `VARCHAR(255)`:
 ```typescript
 text().default('json')                     // → VARCHAR(255) DEFAULT 'json'
 text().oneOf(['a', 'b', 'c']).default('a') // → VARCHAR(255) DEFAULT 'a' CHECK (col IN ('a','b','c'))
-text().nullable()                          // → TEXT (unchanged — no default to trip up)
+text().nullable()                          // → LONGTEXT (unchanged — no default to trip up)
 ```
 
 VARCHAR(255) is the framework's heuristic — enough for typical enum-like values, short status strings, format identifiers. If you need longer defaulted text, declare the column as `text().nullable()` + handle the missing-default case in application code, OR drop down to `unsafe()`.
 
+### Adding a default to an existing column
+
+The rule holds for a migration too, not only for `CREATE TABLE`. Adding
+`.default(…)` to a `text()` column that already exists **reshapes** the column
+rather than setting a default on it:
+
+```sql
+ALTER TABLE tickets MODIFY COLUMN `status` VARCHAR(255) NOT NULL DEFAULT 'active'
+```
+
+That is deliberate, and it is what makes the change appliable at all: a plain
+`ALTER TABLE … ALTER COLUMN status SET DEFAULT 'active'` is answered by MySQL
+with `BLOB, TEXT, GEOMETRY or JSON column 'status' can't have a default value`,
+so the migration would stop half-applied. Reshaping means the column has the same
+type whether the default was declared before or after the table existed.
+
+Two consequences worth knowing before you run it:
+
+- **It is a narrowing.** If a row already holds more than 255 characters, the
+  ALTER fails (`Data too long for column 'status'`) and the migration stops
+  before it. Check first, and pick the width yourself with
+  `text().maxLength(n).default(…)` if 255 is too small:
+
+  ```sql
+  SELECT COUNT(*) FROM tickets WHERE CHAR_LENGTH(status) > 255
+  ```
+
+- **Removing a default does not reshape back.** `DROP DEFAULT` is legal on any
+  mysql type, and widening a `VARCHAR(255)` back to `LONGTEXT` would fail for an
+  indexed column — so the column keeps its bounded type. Declare
+  `text().maxLength(255)` if you want that to be visible in the schema.
+
+SQL Server does the same thing for its own reason (an `NVARCHAR(MAX)` column
+cannot be indexed, so a defaulted text column is `NVARCHAR(450)`). On postgres a
+`TEXT` column takes a `DEFAULT` directly, and SQLite rebuilds the table to the
+declared shape — neither reshapes anything.
+
 ## JSON columns
 
 `json()` columns emit `JSON` (mysql's native binary JSON type since 5.7+). The driver auto-parses on read; same shape as postgres. No coercion overhead.
@@ -1055,7 +1092,7 @@ MariaDB's GTID format differs from MySQL's: `0-1-100` (domain-server-sequence) v
 - **`mariadb` schema package is wire-compatible with `mysql`**. If you migrate from MySQL → MariaDB, the framework re-emits DDL cleanly via `applySchema(..., 'mariadb')`. Production data round-trips through `mysqldump` without translation.
 - **`sql_mode=NO_BACKSLASH_ESCAPES`** is sometimes set on MariaDB deploys. The framework's identifier escaping handles it, but user-written `unsafe()` strings that hand-escape backslashes may produce wrong output. Leave that mode off if you can.
 - **Sequence-based ID columns**. MariaDB has true CREATE SEQUENCE; the framework doesn't use it (TypeID / ULID / Snowflake are client-side). If you reach for sequences for legacy reasons, they're outside the framework's auto-injection path.
-- **Hand-rolled `AUTO_INCREMENT` primary keys** work the same as on mysql: an `insert` / `insertMany` with no client-side `id` recovers the DB-generated id via `LAST_INSERT_ID()` (connection-pinned; `insertMany` recovers the whole consecutive range). See the [mysql page](/docs/database/dialects/mysql#auto_increment-ids--last_insert_id-recovery) for the worked example — the recovery path is identical on both engines.
+- **Hand-rolled `AUTO_INCREMENT` primary keys** work the same as on mysql: an `insert` / `insertMany` with no client-side `id` recovers the DB-generated id via `LAST_INSERT_ID()` (connection-pinned; `insertMany` recovers the whole consecutive range). See the [mysql page](/docs/database/dialects/mysql) for the worked example — the recovery path is identical on both engines.
 
 ## Where it lives
 
@@ -1187,6 +1224,31 @@ When the caller didn't supply an `orderBy` but did set `skip` (uncommon but lega
 
 The compiler inlines integer literals for TOP/OFFSET/FETCH NEXT values rather than parameter binding. Same rationale as MySQL — tedious has bind-as-INT issues with large or unexpected-typed numeric params.
 
+## Text columns with a DEFAULT — NVARCHAR(450)
+
+A plain `text()` column is `NVARCHAR(MAX)`, which SQL Server cannot index. A text
+column that carries a literal default or a closed value set is therefore emitted
+bounded, at `NVARCHAR(450)` — under the 900-byte single-column key limit, so it
+stays indexable:
+
+```typescript
+text().default('open')                 // → NVARCHAR(450) + a DEFAULT constraint
+text().oneOf(['open', 'closed'])       // → NVARCHAR(450) + a CHECK constraint
+text().nullable()                      // → NVARCHAR(MAX)
+```
+
+This holds for migrations as well as for `CREATE TABLE`: adding `.default(…)` to
+an existing text column retypes it to `NVARCHAR(450)` and then adds the default
+constraint, so the column has the same type whether the default was declared
+before or after the table existed. It is a narrowing — if a row already holds
+more than 450 characters, the `ALTER COLUMN` fails ("String or binary data would
+be truncated") and the migration stops there. Check first, and use
+`text().maxLength(n).default(…)` to choose a different width:
+
+```sql
+SELECT COUNT(*) FROM tickets WHERE LEN(status) > 450
+```
+
 ## JSON columns — NVARCHAR(MAX) + auto-parse
 
 `json()` columns emit `NVARCHAR(MAX)` in DDL — mssql has no native JSON type pre-2025. Validation goes through `ISJSON(col) = 1` CHECK constraints; serialization is application-side.

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

@@ -261,7 +261,7 @@ await ctx.store.upsert('orgSlugs', {
 ```
 
 Requires a composite UNIQUE constraint on the table — declare it via
-`.unique([cols])` in the schema (see [Indexes](/docs/database/indexes#composite-unique)).
+`.unique([cols])` in the schema (see [Indexes](/docs/database/indexes#composite-unique-constraints)).
 
 ## `insertIgnore` — keep existing on conflict
 
@@ -314,7 +314,7 @@ const count = await ctx.store.updateMany('posts', { hidden: true }, {
 // count: number of rows actually updated
 ```
 
-The `where` predicate is a regular [Predicate](/docs/database/query-builder#predicates)
+The `where` predicate is a regular [Predicate](/docs/database/query-builder)
 AST — same shape `.where()` uses. Sub-queries via `inSubquery` /
 `exists` are supported.
 
@@ -395,5 +395,5 @@ matters.
   `aggregate()` for read-side bulk reads
 - [Sub-queries](/docs/database/sub-queries) — `inSubquery` /
   `exists` in `updateMany` `where:` clauses
-- [Composite UNIQUE](/docs/database/indexes#composite-unique) — for
+- [Composite UNIQUE](/docs/database/indexes#composite-unique-constraints) — for
   the constraint that backs `upsert`'s `conflictColumns: ['a', 'b']`

package/templates/agent-docs/deployment.md

@@ -1119,6 +1119,14 @@ VOLTRO_LOG_FORMAT=json
 VOLTRO_LOG_LEVEL=info
 ```
 
+In `json` mode (the default off a TTY, so a pod gets it without configuration)
+EVERY line the framework emits is a parseable record — the boot banner, the app
+surface, `voltro db apply`'s plan summary, refusal detail, and every subsystem
+logger (schedule, broadcast, workflow, flow-control). A hand-formatted table or
+a `[tag]`-prefixed adapter line between JSON records is a bug, not a style: log
+collectors show it as unparsed noise. On a TTY the same surfaces render as the
+human-readable banners and tables.
+
 **Error reporting** — add `sentryPlugin()` from `@voltro/plugin-sentry`. It stays inert until `SENTRY_DSN` is set, and reported errors correlate to the request `traceId`:
 
 ```ts

package/templates/agent-docs/internationalization.md

@@ -78,6 +78,8 @@ Server-side, the active locale is determined by, in priority order:
 2. **`Accept-Language` header** — the browser/OS preference, q-weighted and sorted per RFC 4647.
 3. **`defaultLocale`** — last-resort fallback.
 
+**One resolver decides, and everything the server renders for that request reads its answer** — the page render and its `<I18nProvider>`, the `<html lang>` attribute, the ISR cache key (so a language switch cannot re-serve the previous locale's cached HTML), and the validation errors an [`<AutoForm>` renders on the no-JavaScript form-POST path](/docs/ui/forms-and-tables#forms-without-javascript). That last one is worth naming because a server has no `<html lang>` to read yet at the time it validates; deriving the locale a second way there would answer `en` for every request.
+
 The resolved locale is **guaranteed** to be one of the codes in `locales`. Any unsupported value (a cookie pointing at a code you no longer ship, a browser asking for `xx-YY`) falls through to the next signal. RFC 4647 lookup strips subtags one segment at a time — `de-CH-1996` → `de-CH` → `de` — so a `de` catalog serves a `de-CH` browser.
 
 The client **adopts what the server resolved**, reading it from the `<html lang>` attribute the server render sets, then falling back to the cookie and the default. `Accept-Language` is never read in the browser: `navigator.languages` can diverge from what the server saw.
@@ -96,7 +98,7 @@ The client **adopts what the server resolved**, reading it from the `<html lang>
 | `data-voltro-tz` | the IANA zone every date/time formatter renders in — set `timeZone` in `app.config.ts` |
 | `data-voltro-now` | the server's render instant, so `useRelativeTime` produces the same string in the hydration pass |
 
-Locale was already agreed; the zone and the clock were each read from the ambient runtime, which meant a server-rendered timestamp was a hydration mismatch waiting for a wide enough offset or a slow enough connection. See [Plurals & formatting → Timezones under SSR](/docs/i18n/formatting#timezones-under-ssr--the-setting-that-is-not-a-preference) — that is the page to read before you migrate hand-rolled `toLocaleString()` calls onto the hooks.
+Locale was already agreed; the zone and the clock were each read from the ambient runtime, which meant a server-rendered timestamp was a hydration mismatch waiting for a wide enough offset or a slow enough connection. See [Plurals & formatting → Timezones under SSR](/docs/i18n/formatting#timezones-under-ssr-the-setting-that-is-not-a-preference) — that is the page to read before you migrate hand-rolled `toLocaleString()` calls onto the hooks.
 
 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.
 
@@ -951,7 +953,7 @@ default, so call sites don't handle a missing-service error.
 > request, publishes it on the document, and every `@voltro/i18n` formatter on
 > both sides of the hydration boundary uses it. Read it with `useTimeZone()`
 > from `@voltro/i18n`. See
-> [Formatting → Timezones under SSR](/docs/i18n/formatting#timezones-under-ssr--the-setting-that-is-not-a-preference).
+> [Formatting → Timezones under SSR](/docs/i18n/formatting#timezones-under-ssr-the-setting-that-is-not-a-preference).
 >
 > The **server-side compute zone** — what `startOfDay` or a workflow's "same
 > time tomorrow" resolves against inside a handler — is still the SEAM only.

package/templates/agent-docs/introduction.md

@@ -505,7 +505,7 @@ export default defineWebSocket({
 })
 ```
 
-`auth: 'subject'` authenticates through the same chain as rpc/SSR **before** the upgrade (401 while it is still http) and binds the connection to the credential's expiry (close code `4001`); every gateway path is origin-checked at upgrade. Two gateways on one path refuse the boot; a plain GET on a gateway path answers `426`. App realtime stays [subscriptions](/docs/data/subscriptions) — full detail under [Raw WebSocket gateways](/docs/data/subscriptions#raw-websocket-gateways--definewebsocket).
+`auth: 'subject'` authenticates through the same chain as rpc/SSR **before** the upgrade (401 while it is still http) and binds the connection to the credential's expiry (close code `4001`); every gateway path is origin-checked at upgrade. Two gateways on one path refuse the boot; a plain GET on a gateway path answers `426`. App realtime stays [subscriptions](/docs/data/subscriptions) — full detail under [Raw WebSocket gateways](/docs/data/subscriptions#raw-websocket-gateways-definewebsocket).
 
 ## The web side (`apps/*/web/`)
 
@@ -518,6 +518,10 @@ export default defineWebSocket({
 | `src/pages/loading.tsx` | Pending UI shown while loaders resolve. |
 | `src/pages/(group)/` | Route group — does not contribute a URL segment, but layout/error files inside still apply. |
 | `src/*.island.tsx` | A client-side hydration island (split chunk). Used in `interactive: 'islands'` pages. |
+| `src/**/*.collection.ts` | A content collection declaration (`defineCollection`) — schema-typed markdown/JSON under `content/<name>/**`. See [Content collections](/docs/data/content-collections). |
+| `src/**/*.consumer.ts` | A queue consumer (`defineQueueConsumer`, @voltro/plugin-queue) — Schema-decoded, at-least-once, serial per partition. See [Queue](/docs/plugins/queue). |
+| `grpc.manifest.json` | The gRPC field-number manifest (checked in — append-only wire identity; deletes go `reserved`). See [gRPC surface](/docs/data/grpc). |
+| `content/<name>/**` | A collection's content files (markdown with frontmatter, or `.json` for data collections). Read by `getCollection`/`getEntry`. |
 
 Each page can opt into a render strategy via two exports:
 
@@ -540,6 +544,16 @@ export const searchParams = Schema.Struct({
 
 - `searchParams` (an `effect/Schema` struct — every field optional or with a default) types the page's query string: `useSearchParams(searchParams)` returns the decoded shape, and links built with `withQuery` type-check against it. Details: [Pages → Query strings](/docs/routing/pages#query-strings).
 
+Two more page exports change what the framework produces for a route:
+
+```tsx
+export const ogImage = ({ params, loaderData, locale }) => ({ type: 'div', props: { /* satori JSX */ } })
+export const intercept = { from: '/photos' }
+```
+
+- `ogImage` declares the page's `og:image` as a satori JSX template. `static` pages render the PNG at BUILD time into `dist/assets/og/`; `ssr` pages render it on demand over a signed route. The `og:image` / `twitter:image` / `twitter:card` tags are injected automatically unless your own `meta` already sets them. A declared font is REQUIRED (there is no bundled default), and an `ssr` route exporting it needs `VOLTRO_OG_SECRET` — `voltro start` refuses the boot otherwise. Details: [Loaders and meta → OG images](/docs/routing/loaders-and-meta#og-images-from-a-template-ogimage).
+- `intercept` makes the page an **intercepting route**: `from` names one or more ROUTE PATTERNS (`'/photos'`, `['/photos', '/albums/[id]']`), and a soft navigation arriving from one of them renders this page as an overlay above the still-mounted origin. Every hard load — and a soft navigation from anywhere else — renders it standalone. Details: [Intercepting routes](/docs/routing/intercepting-routes).
+
 ## Discovery in practice
 
 ```text
@@ -599,11 +613,28 @@ If yes, the promise belongs in the name — you cannot see a contract before you
 | `*.tracking.ts` | analytics happens nowhere else | `tracking/outside-tracking-file` |
 | `*.client.ts` | it and its imports are browser-safe | boot-time import walk, `client/not-browser-safe` |
 | `*.store.ts` | exactly one `defineStore`, no server state | `store/one-per-file`, `store/mirrors-server-state` |
+| `*.collection.ts` | declares content collections (`defineCollection`); frontmatter schema violations fail the build naming the file | the build's collection decode + reference validation |
+| `*.consumer.ts` | declares queue consumers (`defineQueueConsumer`, @voltro/plugin-queue); loading registers, the plugin's activation starts them | the queue runner (decode→DLQ, retry→DLQ, commit-per-message) |
+| `*.ws.ts` | default-exports one raw WebSocket gateway (`defineWebSocket`), mounting its own upgrade path beside the rpc socket | boot discovery on BOTH paths (`voltro dev` and `voltro serve`); two gateways on one path refuse the boot |
 
 A `*.component.tsx` promises exactly ONE component. It does not promise to export nothing else: types, and plain module-local values a `const COLUMNS = […]` beside the table that renders them, are fine and always were. What the rule counts is components — a declaration that renders — so an object, an array, a string or a `new` beside your component is not a second one, and neither is `export default Card` next to `export const Card`.
 
 The BOUNDARY rules (`internal/foreign-import`, `fixture/production-import`, `ui/unlinked`) are assertions about your import graph, so it is worth knowing which edges they follow: relative specifiers, your tsconfig `paths` aliases (read from the nearest `tsconfig.json`, so a per-app `@/*` works when you run `voltro doctor` at the repo root), `export … from` re-exports, and dynamic `import()`. A package import is a leaf — the walk stops at the edge of your app.
 
+## Contracts that are not suffixes
+
+The admission test above is about the PROMISE, not about the spelling — and three of the framework's conventions carry one without being a suffix on a filename. They are listed here because a reader looking for "what does the framework read out of my tree" would otherwise stop at the table:
+
+| Convention | Promise | Read by |
+|---|---|---|
+| `searchParams` page export | the page's query string decodes through this `effect/Schema` struct — every field optional or with a default | `useSearchParams(searchParams)`, `withQuery` link typing, and the render-mode scan (a page declaring BOTH `renderMode: 'isr'` and `searchParams` is refused) |
+| `ogImage` page export | this route's `og:image` is a satori JSX template, not a file you ship | the build (`static` → a hashed PNG in `dist/assets/og/`) and `voltro start` (`ssr` → a signed on-demand route, which needs `VOLTRO_OG_SECRET`) |
+| `intercept` page export | `from` names the routes a soft navigation may arrive from for this page to render as an overlay above them | the client router; a hard load renders the page standalone regardless |
+| `grpc.manifest.json` (app root) | field numbers are checked in and append-only — a deleted field goes `reserved`, never re-used | `voltro grpc proto` and the gRPC surface wiring, which derive wire identity from it rather than from declaration order |
+| `content/<name>/**` | the files a `*.collection.ts` declares — markdown with frontmatter, or `.json` for a data collection | `getCollection` / `getEntry`, the build's collection artifacts, and the dev server's watcher |
+
+The page exports are per-ROUTE and the last two are per-APP, which is the only reason they cannot be spellings: there is nothing to rename.
+
 ## `*.component.ui.tsx` — reads, never writes
 
 ```tsx