@voltro/cli 0.4.0 → 0.6.0

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

@@ -803,10 +803,31 @@ eager-load with `.with({...})` to get the per-field pre-filter.
   inject a default depth limit.
 - **No reactivity**: see above.
 
+## When NOT to use
+
+- **Single-level parent / child** — use a regular
+  [self-join](/docs/database/self-joins). A recursive CTE is overkill
+  at depth 1.
+- **Performance-critical hot path with a large result set** —
+  recursive queries can explode on wide trees. Profile with
+  `EXPLAIN ANALYZE` against realistic data. If the iteration count
+  runs into the thousands, consider materializing the computed
+  hierarchy into a separate table instead.
+- **Arbitrary graph algorithms** (shortest path, connected
+  components) — a recursive CTE can be bent into these but it gets
+  ugly fast. A graph database (Neo4j, the AGE extension) is the
+  better fit.
+
 ## See also
 
 - [Plain CTEs](/docs/database/query-builder#ctes) — `withCte()` for
   non-recursive named sub-queries
+- [Self-joins](/docs/database/self-joins) — for single-level
+  parent/child queries
+- [Sub-queries](/docs/database/sub-queries) — for non-recursive
+  "rows where a column matches another query" patterns
+- [Set operations](/docs/database/set-operations) — `union` /
+  `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) —

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

@@ -44,6 +44,45 @@ ctx.store.select('notes').select('id', 'title')   // SELECT id, title
 
 The return type narrows automatically — `{ id: string; title: string }[]`.
 
+## Single-row terminals on the typed builder
+
+`ctx.store.query(...)` takes the typed `database.<table>` builder and returns typed rows. `ctx.store.one` / `.first` / `.maybeOne` are the single-row terminals of that same path — so "I want one row" and "I want typed rows" compose, instead of forcing you to pick one:
+
+```ts
+import { eq } from '@voltro/database'
+
+// ONE row, typed. No cast, no explicit type argument — the row type
+// rides in on the builder.
+const user = await ctx.store.one(database.users.where(eq('id', id)))
+user.email        // string — not `row['email'] as string`
+```
+
+They accept the builder itself or its `.descriptor`, so a call site never reaches for `.descriptor` just to use a terminal:
+
+```ts
+await ctx.store.one(database.users.where(eq('id', id)))
+await ctx.store.one(database.users.where(eq('id', id)).descriptor)   // same thing
+```
+
+| Terminal | Returns | On zero rows | On 2+ rows |
+|---|---|---|---|
+| `.one(query)` | `R` | throws `NoRowFound` | throws `NoRowFound` |
+| `.first(query)` | `R \| null` | `null` | returns the first |
+| `.maybeOne(query)` | `R \| null` | `null` | returns the first |
+
+`one()` probes with `LIMIT 2`, not `LIMIT 1`. A one-row probe cannot tell "the row you meant" from "the first of several", so a filter that silently stopped being unique would keep handing back an arbitrary row. One extra row buys a loud failure at the moment the assumption breaks.
+
+Scoping is identical to `ctx.store.query()` — the tenant filter and the soft-delete filter both apply — because the terminals *are* `query()` underneath rather than a second read path. (A second scoping path is exactly the drift that makes one of them quietly leak across tenants.)
+
+`NoRowFound` is typed, so the hand-written not-found branch goes away:
+
+```ts
+// instead of: const rows = await ctx.store.query(...); if (!rows[0]) throw new NotFound()
+const note = await ctx.store.one(database.notes.where(eq('id', input.id)))
+```
+
+`voltro doctor` flags the hand-written version — see [the hand-roll detector](/docs/cli/build-and-start#the-hand-roll-detector).
+
 ## `where`
 
 Filters chain (AND-merged):
@@ -130,19 +169,29 @@ Each call adds ONE column + direction; chain for multi-column ordering:
 .limit(20).offset(40)
 ```
 
-For cursor pagination that avoids OFFSET's O(n) scan, use the standalone `paginateById` helper over `ctx.store.query(...)`:
+For cursor pagination that avoids OFFSET's O(n) scan, use `paginateBy` over `ctx.store.query(...)`:
 
 ```ts
-import { paginateById } from '@voltro/database'
+import { paginateBy } from '@voltro/database'
 
 const rows = await ctx.store.query(
-  paginateById(database.notes.orderBy('createdAt', 'desc').descriptor, req.cursor, 20),
+  paginateBy(database.notes.descriptor, 'createdAt', req.cursor, 20, 'desc'),
 )
-const nextCursor = rows.at(-1)?.id ?? null
+const nextCursor = rows.at(-1)?.createdAt ?? null
 return { rows, nextCursor }
 ```
 
-`paginateById(descriptor, cursor, limit)` adds a `WHERE id > cursor ORDER BY id LIMIT n` clause and preserves any existing predicate. Works for any sortable id scheme (TypeID, ULID, Snowflake, Numeric).
+`paginateBy(descriptor, column, cursor, limit, direction?)` adds the keyset predicate, sets the ORDER BY, and preserves any existing `where`.
+
+The `direction` argument controls **both** the comparison and the sort — a `desc` feed pages with `<`, not `>`. That pairing is the classic keyset bug: an ascending comparison under a descending sort returns the same first page forever.
+
+The cursor column must be unique, or monotonic enough that ties don't straddle a page boundary. For a timestamp with collisions, order by a tie-breaker and paginate on that:
+
+```ts
+paginateBy(database.notes.orderBy('createdAt', 'desc').descriptor, 'id', req.cursor, 20)
+```
+
+`paginateById(descriptor, cursor, limit)` is the `id`-column shorthand — literally `paginateBy(descriptor, 'id', cursor, limit)`. It works for any sortable id scheme (TypeID, ULID, Snowflake, Numeric). Note it sets the order to `id asc`, so passing a descriptor that already carries `.orderBy('createdAt', 'desc')` does **not** page by `createdAt` — use `paginateBy` when the sort column is the thing you want to page on.
 
 ## Aggregates
 
@@ -435,6 +484,72 @@ export const usersRelations = relations(users, ({ one, many, manyToMany }) => ({
 
 The framework auto-registers every `relations(...)` call at boot — you don't write a manual barrel.
 
+## `sourceKey` vs `foreignKey` — opposite directions
+
+Both options name exactly one column, and they name it on **opposite tables**. Read them as a sentence about the row you are standing on:
+
+| Option | The column lives on | It means |
+|---|---|---|
+| `sourceKey` | the **SOURCE** table | "the row **my** column points at" — **my parent** |
+| `foreignKey` | the **TARGET** table | "the rows that point **at me**" — **my children** |
+
+```typescript
+// sourceKey — users.defaultOrgId holds an ORG's id.
+// "The org my column points at." One org per user.
+relations(users, ({ one }) => ({
+  defaultOrg: one(orgs, { sourceKey: 'defaultOrgId' }),
+}))
+
+// foreignKey — posts.authorId holds a USER's id.
+// "The posts that point back at me." Many posts per user.
+relations(users, ({ many }) => ({
+  posts: many(posts, { foreignKey: 'authorId' }),
+}))
+```
+
+The mnemonic is in the option name: `sourceKey` is a key on the source, `foreignKey` is the foreign table's key back.
+
+`manyToMany` is the exception that proves it — **both** of its keys name columns on the JUNCTION table (`sourceKey` the one pointing at the source, `targetKey` the one pointing at the target), never on the source or target themselves.
+
+### The keys are validated at boot
+
+Once every table and every `relations()` block is loaded, the framework checks each relation's key options against the real column lists and refuses to boot on a mismatch — naming the option that would have been right:
+
+```text
+relation 'posts' on 'users': foreignKey 'defaultOrgId' is not a column on the
+target table 'posts'. It IS a column on the source 'users' — you want
+{ sourceKey: 'defaultOrgId' }. foreignKey names the column on the TARGET that
+points back at this table; sourceKey names the column on THIS table that holds
+the target's id.
+```
+
+Passing **both** keys is refused too. It is contradictory rather than merely redundant: a resolvable `sourceKey` decides the shape and `foreignKey` is then never read, so the declaration would silently mean less than it says.
+
+For `manyToMany`, a `sourceKey` / `targetKey` that is not a column on the through-table fails the same way, with the junction's column list in the message.
+
+### What the static check cannot catch: self-references
+
+When source and target are the **same table**, the column exists on both sides by definition — so `foreignKey: 'parentTeamId'` and `sourceKey: 'parentTeamId'` are both well-formed and no column check can tell which you meant. This case is caught by data instead, at query time, through the `one` cardinality contract below.
+
+### `one` means AT MOST one — enforced
+
+An eager-load branch now **fails** when a `one` relation matches more than one row for the same parent, instead of silently keeping the last match — on **both** eager paths, with the same message:
+
+```text
+relation 'parent' on 'teams' is declared `one`, but teams.parentTeamId matches
+MORE than one row for the same teams.id — so there is no single related row to
+return. Because this relation is self-referential, check which side the key is
+on: `foreignKey: 'parentTeamId'` means "rows whose parentTeamId points AT me"
+(my children — there can be many). If you meant "the row my parentTeamId points
+to" (my parent), that is `sourceKey: 'parentTeamId'`.
+```
+
+The check applies wherever the foreign key sits on the **target** ("every child points back at me") — the only shape in which a second match is expressible. There the single-query path over-fetches two rows and raises on the second; a `one` resolved through the target's primary key (`sourceKey: '…'`) still takes a single row in SQL, because a second one cannot exist.
+
+One honest limit remains: it is a **data** check, so it only fires when the data actually has multiplicity. A parent row with a single child — or a leaf with none — passes the wrong declaration silently and resolves to a plausible-looking `null`. That does not replace reading the table above before you type the option.
+
+**The bug this came from.** An app declared `parent: one(() => teams, { foreignKey: 'parentTeamId' })` on a self-referencing team hierarchy. It typechecked, it booted, and the emitted SQL matched the hand-written join it replaced — and `parent` came back `null`, because the declaration was loading *children*, and the test row happened to be a leaf. Both halves of this section exist because that shipped.
+
 ## Quick start — all three cardinalities
 
 ```typescript
@@ -685,7 +800,7 @@ A subscription opened with `.with({ profile: true })` registers against BOTH `us
 
 - **Two `one()` calls on the same target table need distinct relation names**. The framework keys eager loads by relation name, not by target table — `database.users.with({ profile: true })` reads the relation named `'profile'`. If you declare both `defaultOrg` and `billingOrg` both pointing at `orgs`, they're distinct relations and `with({ defaultOrg: true, billingOrg: true })` reads them independently.
 - **Self-referential 1:1 needs the thunk form**. `one(() => users)` for a "parent user" lookup. Without the thunk, the table reference would try to resolve before the table is registered and fail.
-- **`one()` on a target that has a many-to-the-same-source relation is unusual but legal**. The framework reads the relation declaration verbatim — if you say "one profile per user" and the actual data has two profiles for one user, the query returns one (LIMIT 1 in the subquery) and the other is silently invisible. Use `many()` if multiplicity is genuinely possible.
+- **`one()` on a target that has a many-to-the-same-source relation is unusual but legal**. The framework reads the relation declaration verbatim. If the data actually has two profiles for one user, an eager-load branch served by the [walker](./eager-loading#walker-fallback) now **fails** rather than handing you an arbitrary one of them — see [the `one` cardinality contract](./index.md#one-means-at-most-one-enforced). A branch the JSON-aggregation compiler can express resolves it in SQL instead (`LIMIT 1` in the subquery), and the extra row is invisible there. Use `many()` if multiplicity is genuinely possible.
 
 ## Where it lives
 
@@ -977,6 +1092,47 @@ database.users.with({
 
 `onJunction` composes with the target-side `where` / `orderBy` / `limit` / `offset` — `where` still filters the target (orgs), `onJunction` filters the junction (memberships). It compiles into the correlated subquery's WHERE alongside the source-key correlation, qualified to the junction-table alias, on every dialect (postgres / mysql / mariadb / mssql / sqlite / turso). Ignored on `one` / `many` branches (no junction table exists).
 
+## Junction columns in the result — `junction`
+
+Filtering on a junction column is one half; the other is *reading* it. `junction` projects the THROUGH-table row's own columns onto each target row, under `_junction`:
+
+```typescript
+database.users.with({
+  organizations: { junction: ['role', 'joinedAt'] },
+})
+// → each org carries org._junction.role / org._junction.joinedAt
+//   — the membership row that linked THIS user to THIS org
+```
+
+`junction: true` takes every column of the junction table instead of naming them:
+
+```typescript
+database.users.with({ organizations: { junction: true } })
+```
+
+It composes with everything else on the branch — `onJunction` still filters the membership, `where` / `orderBy` / `limit` still apply to the target, and nested `.with()` on the target still resolves:
+
+```typescript
+database.users.with({
+  organizations: {
+    onJunction: eq('role', 'admin'),
+    junction:   ['role', 'joinedAt'],
+    orderBy:    [{ column: 'name', direction: 'asc' }],
+    with:       { projects: true },
+  },
+})
+```
+
+### Why nested under `_junction` and not merged
+
+A junction and its target routinely share column names — `createdAt` is the obvious one, and `id` always collides. Merging membership fields onto the target row would silently overwrite real target data with junction data, and a name collision that corrupts a row is a worse failure than one extra level of nesting.
+
+### The cost — none; it stays one query
+
+A branch that asks for junction columns still compiles to the single-query [JSON-aggregation path](./eager-loading). Every dialect builds the `_junction` object natively: postgres carries the projection out of the correlated join as one `jsonb` value, sqlite / mysql / MariaDB carry the columns as aliased scalars and re-assemble them, mssql uses `FOR JSON PATH`'s dotted column aliases. No extra round trip, and nothing in the `.with()` tree is rerouted because one branch asked for junction data.
+
+What makes this correct rather than merely fast: the projection is computed INSIDE the per-parent join, so a target row linked to two parents carries each parent's own junction row — the same per-link result the walker produces by cloning. The two paths are checked against each other on a live engine per dialect, so the JSON result is identical to the walker's, not merely similar.
+
 ## Doubly-declared
 
 `many` and `one` are unidirectional — you declare from the source side and the reverse is a separate `relations(...)` call. `manyToMany` is the same: declare BOTH directions independently if you need both:
@@ -1055,12 +1211,12 @@ const rows = await store.query(
 // rows: Array<User & { organizations: Org[] }>
 ```
 
-The junction columns (role, joinedAt) are NOT in the resolved Org type. The framework eager-loads the TARGET side only. If you need junction columns, query the junction table directly.
+The junction columns (role, joinedAt) are NOT in the resolved Org type — a plain `manyToMany` branch eager-loads the TARGET side only. Ask for them with `junction:` (above) to get them under `_junction`, or query the junction table directly when the membership row itself is the thing you want.
 
 ## Caveats
 
 - **Same target appearing twice on the source needs distinct relation names**. If users have `organizations` (membership-based) AND `ownedOrgs` (1:N via `orgs.ownerId`), declare them as separate relations with separate names. The framework keys by relation name.
-- **`sourceKey` is the junction column pointing at THIS side**. Easy to confuse with the schema's `reference()` column name on the source table itself. The framework's error message at registration time helps: "no column 'userId' on org_memberships" if you mistype.
+- **`sourceKey` is the junction column pointing at THIS side**. Both keys name columns on the JUNCTION — easy to confuse with the `reference()` column on the source table itself. A key that isn't a column on the through-table fails the [boot validation](./index.md#the-keys-are-validated-at-boot) with the junction's real column list in the message, so the mistype can't reach a query.
 - **Cascade behaviour on the junction is separate from cascade on the parents**. `onDelete: 'cascade'` on `org_memberships.userId` removes memberships when the user is deleted, but doesn't touch `orgs`. Set it explicitly on each FK depending on lifecycle semantics.
 - **Junction extra columns aren't reactive through the m2m relation**. A write to `org_memberships.role` doesn't wake a subscription on `users.with({ organizations: true })` UNLESS the subscription's relevant-fields set includes `role` (which it doesn't by default — only the join keys are relevant for the m2m walk). If you want subscriptions to react to role changes, observe `org_memberships` directly.
 
@@ -1204,6 +1360,8 @@ FROM users;
 
 When the JSON-agg compiler can't express a particular spec — for example a relation that hasn't been registered, or a per-dialect edge case the emitter doesn't cover — the framework transparently falls back to a portable per-relation N+1 walker.
 
+Nothing in the eager spec routes here deliberately. [Junction columns](./many-to-many.md#junction-columns-in-the-result-junction) (`{ junction: [...] }` on a `manyToMany` branch) compile natively on every dialect, so asking for junction data does not reroute the query — let alone the rest of the `.with()` tree.
+
 The walker:
 
 1. Runs the parent query without any eager loading.

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

@@ -423,6 +423,7 @@ the framework ships richer types for specific use cases:
 - **`timestamp` without `tz`.** Use `timestamp()` which is `timestamptz`.
 - **Storing JSON blobs as `text`.** Use `json<T>()` for type-safety + JSONB performance.
 - **`references('table')`.** The constructor is `reference(() => table)` — singular, thunk-arg.
+- **Declaring a `timestamp()` column as `Schema.Number` in a descriptor's `output`.** That describes the *wire* type, not the domain type, so the schema has nothing left to convert and the handler ends up doing it by hand. Derive the row schema instead — [`rowSchema(table)`](/docs/data/queries#output-is-the-serializer-rowschema-table).
 
 
 
@@ -716,8 +717,11 @@ const row = await ctx.store.insert('todos', { title, done: false })
 // Test — deterministic id.
 await ctx.store.insert('todos', { id: 'todo_pinned_for_test', title, done: false })
 
-// Signup self-stamping — pass createdBy: userId in the same insert.
-await ctx.store.insert('users', { id: userId, createdBy: userId, email })
+// Signup self-stamping — the actor IS the row. Generate the id up front
+// so createdBy can point at the row being created, in the same insert.
+import { typeid } from 'typeid-js'
+const userId = typeid('user').toString()
+await ctx.store.insert('users', { id: userId, email, createdBy: userId })
 ```
 
 ## Branded TypeScript types

package/templates/agent-docs/deployment.md

@@ -1038,3 +1038,174 @@ Schedules and aggregates auto-coordinate via an advisory lock on SQL stores —
 - [ ] `VOLTRO_LOG_FORMAT=json`; `sentryPlugin()` + `SENTRY_DSN` for errors
 - [ ] `terminationGracePeriodSeconds` generous for graceful drain
 - [ ] `CACHE_BACKEND` / `KV_BACKEND` + a cross-replica change bus when running >1 replica
+
+
+
+---
+
+<!-- source: en/deployment/seats-and-team.md -->
+## Seats and team management
+
+_How teams are invited, what a seat is, exactly which actions occupy one, and how machine credentials stay seat-free._
+
+A Voltro seat is **one identified natural person**. Not a login, not a token, not a machine — a human. Everything on this page follows from that single definition.
+
+This page is the published boundary: what occupies a seat, what does not, and how the product makes both visible before an invoice does.
+
+## Membership is not a seat
+
+Two separate things, deliberately:
+
+| | What it answers | Cost |
+|---|---|---|
+| **Membership** | May this person act in this org? | Free — invite as many as you like |
+| **Seat** | Does this person consume one of your purchased seats? | Counted |
+
+A seat is occupied by **active work**. Watching is free: a manager following a deploy, a product owner reading logs, an accountant paying the invoice — all need a membership, none need a seat.
+
+## What occupies a seat
+
+The list below is the complete one the server consults. It is an **allowlist**, which has a consequence worth stating: an endpoint that is not on it is free, so a newly shipped feature can never quietly start costing you money.
+
+**Occupies a seat**
+
+- Deploy an app · roll a deployment back
+- Create or delete a project · create an app · create an environment
+- Register a custom domain
+- Change environment variables
+- Submit or approve a migration plan
+- Create a service token · invite a teammate
+
+**Free — no seat**
+
+- Read logs, view metrics, follow deployment status
+- View usage and invoices
+- View the team
+
+The same list is rendered inside the dashboard, on the team page, next to your live seat count. There is exactly one list — the server and the UI read the same file — so what you are told and what you are charged for cannot drift apart.
+
+### One person, one seat
+
+Occupancy is keyed on `(organisation, person)` and enforced by a unique constraint in the database, not by application logic. In practice:
+
+- Five machines, three rotated CLI tokens, two browser sessions → **one seat**.
+- A contractor working in five client organisations → **five seats**, one per client. Whoever works inside an org occupies a seat of that org; there are no cross-org seat pools.
+- Activity is recorded coarsely and debounced. Forty deploys in an afternoon are one write, not forty — the ledger records *that* you worked, not every request.
+
+## Inviting people
+
+Invite by **personal work email** — one address per person.
+
+1. An owner or admin sends the invitation. A pending invitation is created and a **single-use, expiring link** is emailed.
+2. The invitee opens the link. They can read who invited them, to which organisation, and in which role **without signing in** — the token is the authorisation for that preview, and it grants nothing else.
+3. They sign in (or sign up) with the invited address and accept.
+
+**The accepting account's email must equal the invited address.** This is where "personal accounts" stops being a clause and becomes a check: forwarding a link to a colleague, or into a shared inbox that another account reads, cannot produce a membership. Plus-tagged variants (`name+something@`) count as a different address — loosening that match is exactly how one invitation would start covering two people.
+
+Two supporting behaviours:
+
+- **Shared-looking addresses warn, but are not blocked.** `info@`, `team@`, `dev@` raise an inline warning. They are not refused, because `dev@` genuinely is one person at a two-person shop, and address patterns miss `buero@` and `kontakt@` anyway. The email match at acceptance is what actually enforces the rule.
+- **Resending rotates the token.** The old link stops working. That keeps revocation total and covers the usual reason for a resend — the first link landed somewhere the person no longer reads.
+
+Invitations can be revoked at any time. Revocation is immediate: acceptance requires a *pending* invitation.
+
+## Service tokens — CI without a seat
+
+CI needs a credential. If the only credential were user-bound, every team would paste a human's token into their pipeline — which is precisely the credential sharing the terms forbid. So machines get their own class:
+
+> **Service token:  org-scoped · no seat · individually revocable · automation scopes only**
+
+Valid scopes are `deploy`, `build`, `register` and `inventory` — an automation-only set. **Interactive development is not among them and never will be**: requesting it is rejected outright. That boundary is what stops the seat model from being bypassed by routing every developer's work through one machine credential.
+
+A token's value is shown **once**, at creation. Only its hash is stored, so there is no "show it again" and no support path that could reveal it. Revoking is a soft flip: the token stops working immediately, and the record of what it did survives.
+
+## Going over your seats
+
+Nothing is blocked. Person 21 on a 20-seat plan starts working immediately; the extra seat appears on the next invoice as the contractual true-up.
+
+Because nothing blocks, the warnings are the safeguard, not a nicety:
+
+| State | What you see |
+|---|---|
+| Below 80 % | Your seat count, plainly |
+| From 80 % | An advance warning on the team page |
+| Every seat occupied | The next person to work will be an additional seat |
+| Over | How many seats beyond your purchase, and that they will be invoiced |
+
+Suspension exists only for non-payment or abuse, through the contractual process. A developer is never locked out mid-sprint over a seat count.
+
+### Where your seat count comes from
+
+Two numbers can define your limit, and the more specific one always wins:
+
+| Situation | Your limit is |
+|---|---|
+| You have a paid subscription | Its **seat quantity** — what you bought |
+| No subscription | The seats **included** with your plan |
+| Free or Enterprise | Uncapped — Free is gated on projects × apps, Enterprise contractually |
+
+The team page names which of the two applies, so "of 40 on your subscription" and "of 10 included with Team" are never confused. If you buy 40 seats on a plan that includes 10, your limit is 40 — the number you paid for governs.
+
+A cancelled subscription stops granting its quantity and you return to the free tier's limits. A **failed payment does not**: while a card is being retried your team keeps working, because locking an organisation out over a bank decline is a support incident, not enforcement.
+
+## Self-hosted
+
+Seats work the same way when you run Voltro yourself, and self-hosted development is **attributed to a person** — which is what makes the model measurable rather than aspirational.
+
+> **Signing in.** Voltro Cloud accounts are authenticated by WorkOS — always, in every environment. There is no password, no fixed code, and no local fallback: if WorkOS cannot verify you, you are not signed in.
+
+### Getting a personal credential
+
+Generate one from your team page ("Your CLI credential"), then store it:
+
+```bash
+voltro cloud login --token <token>
+```
+
+It is **org-scoped and personal**. Org-scoped because a contractor working in five client organisations occupies five seats, one per client — so generate one per organisation you work in. Personal because the control plane records who it belongs to, and that link is the whole basis of self-hosted attribution.
+
+### What is sent
+
+`voltro dev` reports a coarse **daily heartbeat**:
+
+> **organisation · person · project slug · CLI version · UTC day**
+
+Never source, never schema, never data, never file names, never command arguments. That is the complete list, and it is asserted by a test that fails if a field is added — so growing it takes a deliberate decision, not a careless commit. What we do with it, on what legal basis, and for how long is set out in the [Privacy Policy](https://voltro.cloud/legal/privacy) under "Developer and usage data".
+
+If you license Voltro for a team, note that you are responsible for informing the people concerned. Administrators see who occupies a seat and the date of last activity — never what anyone did.
+
+Three properties you can rely on:
+
+- **Debounced.** At most one report per day per project. Restarting your dev server forty times is one heartbeat.
+- **Offline-tolerant.** A failed send is remembered and flushed on a later run. Working on a train is a gap in a chart, not a licence problem.
+- **It never fails a command.** Every error path is swallowed. Telemetry that can break `voltro dev` eventually will.
+
+Not logged in? Nothing is sent, nothing is warned about, and nothing is slower. That is the normal case for most local development.
+
+### Machine credentials are refused
+
+`voltro dev` requires a **personal** credential. A service token belongs to no person, so it is rejected with an explanation rather than silently counted:
+
+```
+voltro dev needs a personal login — the stored credential belongs to no user.
+```
+
+Without that boundary, a team could route every developer's work through one shared machine token and occupy zero seats. Deploying with a service token stays fine — deploying is not developing.
+
+### From activity to an invoice
+
+A nightly job closes the loop, and your team page shows both halves side by side:
+
+| | What it is |
+|---|---|
+| **Live count** | Who occupies a seat right now — moves as people work |
+| **Billing period** | The rolled-up figure for the month, including the self-hosted share |
+
+The rollup is idempotent, so a retried job cannot double-count. The two numbers differ between runs by design: one is what your team is doing, the other is what a bill would say, and showing only one of them is how a customer ends up arguing with a dashboard.
+
+Air-gapped and enterprise deployments attest seats contractually instead; no telemetry path is required.
+
+## Related
+
+- [Voltro Cloud](./voltro-cloud.md) — the control plane these features live in
+- [Self-hosting](./self-hosting.md) — running Voltro yourself

package/templates/agent-docs/internationalization.md

@@ -558,6 +558,8 @@ relativeTime(comment.postedAt, { now: renderedAt })   // measure against a fixed
 
 It picks the **largest unit that fits**, so a 90-minute delta reads "1 hour ago", not "90 minutes ago". Anything under a second renders through the `second` unit at 0 — "now" — which avoids the "0 seconds ago" flicker hand-rolled versions produce. `numeric: 'auto'` is the default, so English gets "yesterday" rather than "1 day ago".
 
+**It is not a drop-in replacement for a hand-rolled helper.** Apps that wrote their own usually picked abbreviated, app-specific wording — "2 hr ago", "vor 2 Std." — whereas this hook emits `Intl.RelativeTimeFormat` output: "2 hours ago" / "vor 2 Stunden". Adopting it is a **visible copy change**, so treat it as a design decision rather than a find-and-replace. What you get in exchange is every locale for free and the unit-selection edge cases handled; what you give up is control over the exact phrasing.
+
 ### `useFormatNumber` and `useFormatCurrency`
 
 ```tsx

package/templates/agent-docs/plugins.md

@@ -24,7 +24,7 @@ The framework ships some plugins; you write your own; the contract is small enou
 - [plugin-soft-delete](/docs/plugins/soft-delete) — `softDelete()` schema mixin (hide on delete, `hardDelete()` bypass)
 - [plugin-rbac](/docs/plugins/rbac) — roles + permissions + the `permission()` guard
 - [plugin-ratelimit](/docs/plugins/ratelimit) — per-endpoint / per-subject / per-tenant request limits
-- [plugin-billing](/docs/plugins/billing) — subscriptions, plans, entitlements + usage metering (Stripe + mock provider); seats, mid-cycle proration + dunning; money as integer minor units
+- [plugin-billing](/docs/plugins/billing) — subscriptions, plans, entitlements + usage metering (Stripe + mock provider); seat-based billing on Stripe's own proration, retries, tax and checkout; money as integer minor units
 - [plugin-licensing](/docs/plugins/licensing) — offline-verified EdDSA license keys + cloud-issued entitlement snapshots that feed plugin-billing; plan entitlements + pricing decided server-side, never baked into a published version
 - [plugin-mail](/docs/plugins/mail) — transactional email (Resend / Postmark / SendGrid / SES / Mailgun / SMTP, templates, suppression, scheduling, batch, idempotency)
 - [plugin-storage](/docs/plugins/storage) — file storage: public (CDN-direct) + private (access policy + per-object grants), S3 / R2 / GCS / MinIO / filesystem
@@ -65,7 +65,7 @@ Status legend: ✓ shipped · ◐ partial · — planned.
 | `@voltro/plugin-soft-delete` | ✓ | `softDelete()` schema mixin — `deletedAt` / `deletedBy`; `delete` → UPDATE, `hardDelete()` bypass |
 | `@voltro/plugin-rbac` | ✓ | Roles compile to scopes + the `permission()` handler guard + typed `ScopeError` |
 | `@voltro/plugin-ratelimit` | ✓ | Per-endpoint / per-subject / per-tenant limits; sliding-window / fixed-window / token-bucket; memory / postgres / redis stores |
-| `@voltro/plugin-billing` | ✓ | Subscriptions, plans, entitlements + usage metering over a pluggable provider (Stripe + mock); seat-based billing + mid-cycle proration + dunning (failed-payment retries); `requireEntitlement()` guard + `enforce` interceptor; `/billing/webhook` via plugin-webhooks; money as integer minor units |
+| `@voltro/plugin-billing` | ✓ | Subscriptions, plans, entitlements + usage metering over a pluggable provider (Stripe + mock); seat-based billing; proration, failed-payment retries, tax and the checkout seat stepper are Stripe's, via the official SDK; `requireEntitlement()` guard + `enforce` interceptor; `/billing/webhook` via plugin-webhooks; money as integer minor units |
 | `@voltro/plugin-mail` | ✓ | Transactional email — Resend / Postmark / SendGrid / SES / Mailgun / SMTP, *.email.tsx templates, per-tenant suppression, send-time scheduling, bulk/batch send, per-send idempotency, durable via workflows |
 | `@voltro/plugin-storage` | ✓ | File storage — public (CDN-direct) + private (access policy + per-object grants), S3 / R2 / GCS / MinIO / filesystem providers, presigned URLs, `listRefs` browse/search, HTTP Range (206) serving, dashboard browser |
 | `@voltro/plugin-postgis` | ✓ | Postgres-native `geography` / `geometry` columns + spatial predicates (`ST_DWithin`, `ST_Contains`, `ST_Intersects`); GiST indexes via `.expressionIndex(..., { kind: 'gist' })`. No `ST_Distance` projection yet. Postgres-only by design (fails loud elsewhere). [→ details](/docs/plugins/postgis) |
@@ -816,7 +816,7 @@ definePlugin({
     {
       id: 'overview',
       slot: 'page',                                 // 'page' | 'widget' | 'nav'
-      query: 'overview',                            // mounted at /plugins/audit/overview
+      route: 'overview',                            // mounted at /plugins/audit/overview
       label: 'Audit log',
       icon: 'shield',                               // optional lucide-react icon name
       bundleUrl: 'https://cdn.example.com/audit/v1/dashboard.mjs',
@@ -841,7 +841,7 @@ curl http://localhost:4000/_voltro/inspect/plugins/dashboard-mounts | jq
 ```
 
 Boot validates within-plugin id uniqueness AND that `slot: 'page'`
-mounts carry a `query`. Cross-plugin ids are namespaced as
+mounts carry a `route`. Cross-plugin ids are namespaced as
 `<plugin-alias>:<mount.id>` (e.g. `audit:overview`).
 
 The actual dashboard-host runtime — the React shell that dynamic-imports

package/templates/agent-docs/reference.md

@@ -128,12 +128,44 @@ Returns:
 
 | Field | Meaning |
 |---|---|
-| `data` | Latest typed query output, or `undefined` before the first snapshot. |
+| `data` | Latest typed query output; `undefined` while `loading` is `true`. |
+| `loading` | `true` until the first snapshot arrives. Discriminates the result — see below. |
+| `isEmpty` | The snapshot that arrived is empty. Always `false` while `loading`. |
 | `error` | Subscription setup error, if no snapshot could be delivered. |
 | `revision` | Server revision counter. |
 | `emittedAt` | Timestamp for the latest server delta. |
 | `pendingPatches` | Number of active optimistic patches applied to this cache entry. |
 
+The result type `SubscriptionState<T>` is a **discriminated union on `loading`**:
+
+```ts
+type SubscriptionState<T> =
+  | { loading: true;  data: undefined; isEmpty: false }
+  | { loading: false; data: T;         isEmpty: boolean }
+// both members also carry revision, emittedAt, error and pendingPatches
+```
+
+So `loading` is a type guard, not a flag beside `data` — narrow on it and `data`
+is `T`, with no `?? []` and no `!`:
+
+```tsx
+const { data, loading } = useSubscription<Team[]>('app', 'teams.list')
+if (loading) return <Skeleton/>
+return <TeamsTable teams={data}/>   // data is Team[]
+```
+
+Because it is a union, an `interface X extends SubscriptionState<...>` does not
+compile — TypeScript cannot extend a union. Intersect instead:
+
+```ts
+type TeamsState = SubscriptionState<ReadonlyArray<Team>> & { readonly canEdit: boolean }
+```
+
+`loading` means **no data has arrived yet**, not "the subscription is still
+warming up". A cold-start failure leaves `loading` true and sets `error`, so a
+component branching on `loading` alone renders a skeleton forever — check
+`error`.
+
 Use `{ skip }` to defer until inputs are ready:
 
 ```tsx
@@ -159,7 +191,7 @@ Returns:
 
 | Field | Meaning |
 |---|---|
-| `mutate(input)` | Calls the mutation and resolves the typed output. |
+| `mutate(input, options?)` | Calls the mutation and resolves the typed output. `options` is `{ onSuccess, onError, notify }` — see [Mutations](/docs/data/mutations). |
 | `pending` | `true` while a call is in flight. |
 | `error` | Last failure, or `undefined`. |
 | `data` | Last successful result, or `undefined`. |
@@ -189,6 +221,28 @@ await invite.run({ email })
 
 Returns `run`, `pending`, `error`, and `lastResult`.
 
+`run` takes the same options bag as `useMutation`'s `mutate` —
+`{ onSuccess, onError, notify }`:
+
+```tsx
+const invite = useAction('app', 'invites.send')
+
+await invite.run({ email }, {
+  onSuccess: (out) => toast.success(`sent ${out.id}`),
+  onError:   (e)   => toast.error(readError(e)),
+})
+```
+
+Same load-bearing semantic: supplying an error handler (`onError` **or**
+`notify.error`) marks the failure **handled**, so `run` resolves with `undefined`
+instead of rejecting — that is what removes the `try/catch`. With no options it
+rejects exactly as before, so unhandled failures stay loud.
+
+**The callback form is for single-shot writes.** A loop or a multi-step sequence
+relies on the promise *throwing* to stop; once the failure is handled the promise
+resolves and the loop keeps going. Sequenced writes want the bare `run(input)`
+plus a real `try/catch` — see [Actions](/docs/data/actions).
+
 ## `useWorkflow(apiName, workflowName)`
 
 Starts and controls a discovered `*.workflow.tsx`. Starting returns a `WorkflowRunHandle` immediately; it does not wait for the workflow's success payload.
@@ -811,8 +865,42 @@ await ctx.store.delete('notes', noteId)
 const rows = await ctx.store.query(database.notes.descriptor)
 ```
 
+`ctx.store.query` returns the row type the builder already knew — `database.notes`
+resolves to that table's row, so `rows[0].title` is a `string` with no cast. A
+hand-built descriptor still resolves to the untyped `Row`.
+
 Mutations receive a transactional store view. Actions and streams receive a normal store view; writes from them are not automatically rolled back as one unit.
 
+## `ctx.load` / `ctx.loadMany` — request-scoped batching
+
+`relations()` + `.with()` is the right answer whenever the shape of the related
+data is known statically: it compiles to ONE query. Reach for it first.
+
+This is for the case it cannot express — assembly whose shape depends on the
+DATA. A breadth-first walk over a tree is the canonical example: each level's
+ids come from the level above, so no declarative relation spec covers it, and
+the natural code is one query per node.
+
+```ts
+let level = [await ctx.load('nodes', rootId)]
+while (level.length > 0) {
+  const childIds = level.flatMap((n) => n?.childIds ?? [])
+  if (childIds.length === 0) break
+  level = [...await ctx.loadMany('nodes', childIds)]
+}
+```
+
+Every `load` issued in the same tick for the same table is coalesced into one
+`WHERE id IN (...)`, so that walk costs one query per LEVEL, not per node.
+Repeated ids — a diamond where two parents share a child — are fetched once.
+A missing row is `null` rather than a throw, because a dangling edge in a graph
+walk is usually data; use `.one()` when absence is an error.
+
+The cache lives exactly as long as the request. That is a correctness
+requirement, not a tuning choice: a longer-lived cache would serve one
+subject's rows to another (a data-isolation bug on a tenant-scoped store) and
+would go stale across a mutation in the same request.
+
 ## `ctx.cache`
 
 Async cache facade for request handlers: