@quickback-dev/cli 0.64.0 → 0.64.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -10,7 +10,7 @@
10
10
  */
11
11
  import pc from "picocolors";
12
12
  // Version injected at build time by scripts/inject-version.ts
13
- const CLI_VERSION = "0.64.0";
13
+ const CLI_VERSION = "0.64.1";
14
14
  function getPackageVersion() {
15
15
  return CLI_VERSION;
16
16
  }
@@ -24,12 +24,14 @@ Lowest-to-highest privilege list. Lets access rules use `'role+'` shorthand to m
24
24
 
25
25
  Quickback ships its own custom HMAC-SHA256 JWT (not Better Auth's JWT plugin) so it can embed `orgId` and `role` claims the fast-path needs to reconstruct `AppContext` without a database round-trip. The signing secret is shared with Better Auth (`BETTER_AUTH_SECRET`) by default — users only manage one secret.
26
26
 
27
- > **Contract v2 is opt-in**
27
+ > **This JWT surface is opt-in by default**
28
28
  >
29
- > On `contract: { version: "v2" }`, Quickback emits this custom JWT surface only
30
- > when `auth.jwt` is present. If it is omitted, generated output has no generic
31
- > `/api/v2/token` endpoint, `src/lib/jwt.ts`, JWT middleware verify/mint fast-path,
32
- > or Quickback JWT imports. Generated `llms.txt` and RFC 8414 discovery metadata
29
+ > Contract v2 is the default since v0.64.0, and on it Quickback emits this custom
30
+ > JWT surface only when `auth.jwt` is present. If it is omitted, generated output
31
+ > has no generic `/api/v1/token` endpoint, no JWT middleware verify/mint
32
+ > fast-path, and no Quickback JWT imports. (`src/lib/jwt.ts` is still emitted when
33
+ > the project declares [`authz.scopes`](/define/scopes) — scope tokens are signed
34
+ > JWTs.) Pin `contract: { version: "v1" }` to emit it unconditionally. Generated `llms.txt` and RFC 8414 discovery metadata
33
35
  > also omit Bearer-JWT instructions, token endpoints, and JWT scopes that do not
34
36
  > exist. Better Auth cookie and signed session-token bearer authentication remain
35
37
  > available.
@@ -499,12 +499,13 @@ A modern Quickback project runs on **one Cloudflare Worker** that serves multipl
499
499
 
500
500
  When any subdomain is configured (`account.domain`, `cms.domain`, `auth.domain`, `api.domain`, `apps.<n>.domain`), the compiler always emits a unified backend host where **every compiler-emitted backend route** is reachable:
501
501
 
502
- - `/api/v1/*` and `/auth/v1/*` for the default contract, or `/api/v2/*` and
503
- `/auth/v2/*` when `contract.version` is `"v2"`
502
+ - `/api/v1/*` and `/auth/v1/*` by default, or `/api/v2/*` and `/auth/v2/*`
503
+ when `contract.routes` is `"v2"` (the URL axis — `contract.version` does
504
+ not move these)
504
505
  - `/storage/*` — R2 file storage
505
506
  - `/health`, `/openapi.json` — monitoring/discovery
506
507
  - `/account/*`, `/cms/*` — bundled SPAs (when enabled)
507
- - `/broadcast/v1/*` (realtime; `/broadcast/v2/*` under `contract.version: 'v2'`), `/mcp` (MCP), etc.
508
+ - `/broadcast/v1/*` (realtime; `/broadcast/v2/*` under `contract.routes: 'v2'`), `/mcp` (MCP), etc.
508
509
 
509
510
  The unified hostname is `quickback.{baseDomain}` by default (where baseDomain is extracted from your first configured subdomain). Override with `config.domain` if you prefer a different name.
510
511
 
@@ -215,7 +215,7 @@ providers: {
215
215
  }
216
216
  ```
217
217
 
218
- > The broadcast surface mounts at `/broadcast/v1` by default and `/broadcast/v2` under `contract.version: "v2"`.
218
+ > The broadcast surface mounts at `/broadcast/v1` by default and `/broadcast/v2` under `contract.routes: "v2"`. It tracks the URL axis, not `contract.version`.
219
219
 
220
220
  `wsTicket` tells the compiler how to authorize `/broadcast/v1/ws-ticket` and what scope to stamp into the short-lived websocket ticket:
221
221
 
@@ -70,14 +70,19 @@ update: { access: { roles: ["member", "admin", "owner"] }, routes: false },
70
70
  One blessed path — **RFC 5789 media-type dispatch** on the routes you already
71
71
  have. No subpath.
72
72
 
73
- - `PATCH /api/v2/<resource>/:id` with
73
+ Paths below use the default `/api/v1` prefix. Changesets are a contract-v2
74
+ **semantics** feature and v2 is the default, so they are available without
75
+ moving your URLs — set [`contract.routes`](/platform/api-contract#two-axes-semantics-and-routes)
76
+ to `"v2"` only if you also want the `/api/v2` prefix.
77
+
78
+ - `PATCH /api/v1/<resource>/:id` with
74
79
  `Content-Type: application/vnd.quickback.changeset+json` — apply a changeset
75
80
  to an existing root. Plain `application/json` keeps the flat-column PATCH.
76
- - `POST /api/v2/<resource>` with the same media type — create the root and its
81
+ - `POST /api/v1/<resource>` with the same media type — create the root and its
77
82
  children in one changeset.
78
83
 
79
84
  ```jsonc
80
- // PATCH /api/v2/projects/prj_1 (Content-Type: application/vnd.quickback.changeset+json)
85
+ // PATCH /api/v1/projects/prj_1 (Content-Type: application/vnd.quickback.changeset+json)
81
86
  {
82
87
  "patch": { "name": "Renamed" }, // sparse ROOT patch (optional)
83
88
  "tasks": {
@@ -49,9 +49,11 @@ auth: {
49
49
  },
50
50
  ```
51
51
 
52
- > **Contract v2 makes this surface opt-in**
52
+ > **This surface is opt-in by default**
53
53
  >
54
- > On `contract: { version: "v2" }`, the custom JWT surface is emitted only when `auth.jwt` is present. Omit it and the generated output has no token endpoint, no `src/lib/jwt.ts`, and no JWT fast-path — cookie and signed session-token bearer auth still work. Contract v1 always emits it. See [Auth & JWT config](/configure/auth).
54
+ > Contract v2 is the default since v0.64.0, and on it the custom JWT surface is emitted only when `auth.jwt` is present. Omit it and the generated output has no token endpoint and no JWT fast-path — cookie and signed session-token bearer auth still work. Pin `contract: { version: "v1" }` to get it unconditionally. See [Auth & JWT config](/configure/auth).
55
+ >
56
+ > `src/lib/jwt.ts` is still emitted when the project declares [`authz.scopes`](/define/scopes): scope tokens are signed JWTs, so the helper is required for minting and verifying them even with no credential lane.
55
57
 
56
58
 
57
59
  ---
@@ -79,7 +79,7 @@ providers: {
79
79
  }
80
80
  ```
81
81
 
82
- That tells `/broadcast/v1/ws-ticket` (the broadcast surface tracks `contract.version`, so `/broadcast/v2/ws-ticket` on contract-v2 projects) to authenticate with Better Auth, run the declared gate against `body.eventId`, and mint a short-lived ticket scoped to the resolved `events:<id>` lane. See [Realtime → Enabling Realtime](/platform/realtime#enabling-realtime) for the full per-arm semantics; all three forms fail closed at compile time (ambiguous names living in two vocabularies, missing `auth.roleHierarchy` for `+`, missing `authz.fga`, unknown FGA type/relation, missing organization column, non-tenant-scoped `scopeTable`).
82
+ That tells `/broadcast/v1/ws-ticket` (the broadcast surface tracks `contract.routes`, so `/broadcast/v2/ws-ticket` when that is `"v2"`) to authenticate with Better Auth, run the declared gate against `body.eventId`, and mint a short-lived ticket scoped to the resolved `events:<id>` lane. See [Realtime → Enabling Realtime](/platform/realtime#enabling-realtime) for the full per-arm semantics; all three forms fail closed at compile time (ambiguous names living in two vocabularies, missing `auth.roleHierarchy` for `+`, missing `authz.fga`, unknown FGA type/relation, missing organization column, non-tenant-scoped `scopeTable`).
83
83
 
84
84
  ### Namespace-backed tickets (per-matched-lane)
85
85
 
@@ -2,7 +2,7 @@
2
2
 
3
3
  Quickback ships **two parallel realtime primitives**, both backed by Cloudflare Durable Objects:
4
4
 
5
- - **`/broadcast/v1/*` — server fan-out.** One DO instance per subscription scope. Postgres-changes events from CRUD routes plus custom broadcast events flow out to every subscriber, with role filtering and per-role field masking applied. Best for "tell every client in this shared scope that something changed." The scope can be an organization, a specific user, or a compiler-resolved resource key like `events:evt_123`. The `/broadcast/v1` version segment tracks `contract.version` — contract-v2 projects mount the same surface at `/broadcast/v2` (no hidden v1 alias). Documented on this page. For **typed, targeted "this changed — refresh" signals** fired from an action after commit (with optional per-recipient narrowing), see [Named invalidations](/platform/realtime/named-invalidations).
5
+ - **`/broadcast/v1/*` — server fan-out.** One DO instance per subscription scope. Postgres-changes events from CRUD routes plus custom broadcast events flow out to every subscriber, with role filtering and per-role field masking applied. Best for "tell every client in this shared scope that something changed." The scope can be an organization, a specific user, or a compiler-resolved resource key like `events:evt_123`. The `/broadcast/v1` version segment tracks `contract.routes` — set it to `"v2"` and the same surface mounts at `/broadcast/v2` (no hidden v1 alias). `contract.version` selects the frame FORMAT, not the path: on v2 semantics (the default) frames are [CloudEvents 1.0](/platform/api-contract#contract-version-matrix) envelopes regardless of which prefix you serve them on. Documented on this page. For **typed, targeted "this changed — refresh" signals** fired from an action after commit (with optional per-recipient narrowing), see [Named invalidations](/platform/realtime/named-invalidations).
6
6
  - **`/realtime/<binding>/<room-id>` — bidirectional rooms.** One DO instance per room (per document, per interview, per game). Client↔client messages, presence, and CRDT-friendly state. Use these for collaborative editing. See [PartyServer rooms](/platform/realtime/partyserver-rooms).
7
7
 
8
8
  Both share the same auth model and ride on the same compiled worker; they solve different problems.
@@ -157,7 +157,7 @@ function PersonDetail({ personId }: { personId: string }) {
157
157
  Under the hood `useView` uses a **subscribe-then-snapshot** flow so no change
158
158
  slips through the gap between reading the surface and the socket going live:
159
159
 
160
- 1. Requests a **view-scoped ws-ticket** (`POST /broadcast/v1/ws-ticket` — `/broadcast/v2/ws-ticket` on contract-v2 projects — with
160
+ 1. Requests a **view-scoped ws-ticket** (`POST /broadcast/v1/ws-ticket` — `/broadcast/v2/ws-ticket` when `contract.routes` is `"v2"` — with
161
161
  `{ view, rootId }`) — gated by exactly the same `read.access` + firewall
162
162
  checks as the read endpoint — and opens a WebSocket scoped to
163
163
  `view:<view>:<rootId>`.
@@ -125,7 +125,7 @@ Each `invalidate.<binding>.<variant>(payload)` call queues **one** after-commit
125
125
 
126
126
  ## The wire frame
127
127
 
128
- Clients receive a broadcast frame on `/broadcast/v{n}` (the version tracks `contract.version`):
128
+ Clients receive a broadcast frame on `/broadcast/v{n}` (the segment tracks `contract.routes`):
129
129
 
130
130
  ```jsonc
131
131
  {
@@ -8,7 +8,7 @@ Open a WebSocket connection to the realtime worker:
8
8
 
9
9
  ```typescript
10
10
  const ws = new WebSocket("wss://api.yourdomain.com/broadcast/v1/websocket");
11
- // Note: /broadcast/v1 tracks contract.version — use /broadcast/v2 on contract-v2 projects.
11
+ // Note: /broadcast/v1 tracks contract.routes — use /broadcast/v2 when that is "v2".
12
12
  ```
13
13
 
14
14
  ## Authentication
@@ -377,8 +377,9 @@ For each feature, the compiler generates a routes file at `src/features/{name}/r
377
377
  | `POST /:id/{action}` | Record-based actions defined |
378
378
  | `POST /{action}` | Standalone actions defined |
379
379
 
380
- Routes are mounted under `/api/v1/{feature}` for the default contract or
381
- `/api/v2/{feature}` when `contract: { version: "v2" }` is selected.
380
+ Routes are mounted under `/api/v1/{feature}` by default, or
381
+ `/api/v2/{feature}` when `contract: { routes: "v2" }` is set. `contract.version`
382
+ selects semantics and leaves these paths alone.
382
383
 
383
384
  ## Migrations
384
385
 
@@ -105,7 +105,7 @@ interface ListResult {
105
105
  The client is constructed once from the resolved `apiUrl` and provided via React
106
106
  context (`ApiClientContext`), available throughout the component tree. It reads
107
107
  the Better Auth session cookie and calls the standard REST endpoints
108
- (`/api/v1/{table}`, or `/api/v2/…` on contract-v2 projects).
108
+ (`/api/v1/{table}`, or `/api/v2/…` when `contract.routes` is `"v2"`).
109
109
 
110
110
  ## Embedded Mode (Recommended)
111
111
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quickback-dev/cli",
3
- "version": "0.64.0",
3
+ "version": "0.64.1",
4
4
  "description": "CLI for Quickback — define your backend in TypeScript, compile to a fully wired Cloudflare Worker (or Bun / Node) with auth, database, migrations, security, CMS, and Account UI.",
5
5
  "author": "Kardoe Incorporated <paul@kardoe.com>",
6
6
  "license": "MIT",
@@ -24,12 +24,14 @@ Lowest-to-highest privilege list. Lets access rules use `'role+'` shorthand to m
24
24
 
25
25
  Quickback ships its own custom HMAC-SHA256 JWT (not Better Auth's JWT plugin) so it can embed `orgId` and `role` claims the fast-path needs to reconstruct `AppContext` without a database round-trip. The signing secret is shared with Better Auth (`BETTER_AUTH_SECRET`) by default — users only manage one secret.
26
26
 
27
- > **Contract v2 is opt-in**
27
+ > **This JWT surface is opt-in by default**
28
28
  >
29
- > On `contract: { version: "v2" }`, Quickback emits this custom JWT surface only
30
- > when `auth.jwt` is present. If it is omitted, generated output has no generic
31
- > `/api/v2/token` endpoint, `src/lib/jwt.ts`, JWT middleware verify/mint fast-path,
32
- > or Quickback JWT imports. Generated `llms.txt` and RFC 8414 discovery metadata
29
+ > Contract v2 is the default since v0.64.0, and on it Quickback emits this custom
30
+ > JWT surface only when `auth.jwt` is present. If it is omitted, generated output
31
+ > has no generic `/api/v1/token` endpoint, no JWT middleware verify/mint
32
+ > fast-path, and no Quickback JWT imports. (`src/lib/jwt.ts` is still emitted when
33
+ > the project declares [`authz.scopes`](/define/scopes) — scope tokens are signed
34
+ > JWTs.) Pin `contract: { version: "v1" }` to emit it unconditionally. Generated `llms.txt` and RFC 8414 discovery metadata
33
35
  > also omit Bearer-JWT instructions, token endpoints, and JWT scopes that do not
34
36
  > exist. Better Auth cookie and signed session-token bearer authentication remain
35
37
  > available.
@@ -499,12 +499,13 @@ A modern Quickback project runs on **one Cloudflare Worker** that serves multipl
499
499
 
500
500
  When any subdomain is configured (`account.domain`, `cms.domain`, `auth.domain`, `api.domain`, `apps.<n>.domain`), the compiler always emits a unified backend host where **every compiler-emitted backend route** is reachable:
501
501
 
502
- - `/api/v1/*` and `/auth/v1/*` for the default contract, or `/api/v2/*` and
503
- `/auth/v2/*` when `contract.version` is `"v2"`
502
+ - `/api/v1/*` and `/auth/v1/*` by default, or `/api/v2/*` and `/auth/v2/*`
503
+ when `contract.routes` is `"v2"` (the URL axis — `contract.version` does
504
+ not move these)
504
505
  - `/storage/*` — R2 file storage
505
506
  - `/health`, `/openapi.json` — monitoring/discovery
506
507
  - `/account/*`, `/cms/*` — bundled SPAs (when enabled)
507
- - `/broadcast/v1/*` (realtime; `/broadcast/v2/*` under `contract.version: 'v2'`), `/mcp` (MCP), etc.
508
+ - `/broadcast/v1/*` (realtime; `/broadcast/v2/*` under `contract.routes: 'v2'`), `/mcp` (MCP), etc.
508
509
 
509
510
  The unified hostname is `quickback.{baseDomain}` by default (where baseDomain is extracted from your first configured subdomain). Override with `config.domain` if you prefer a different name.
510
511
 
@@ -215,7 +215,7 @@ providers: {
215
215
  }
216
216
  ```
217
217
 
218
- > The broadcast surface mounts at `/broadcast/v1` by default and `/broadcast/v2` under `contract.version: "v2"`.
218
+ > The broadcast surface mounts at `/broadcast/v1` by default and `/broadcast/v2` under `contract.routes: "v2"`. It tracks the URL axis, not `contract.version`.
219
219
 
220
220
  `wsTicket` tells the compiler how to authorize `/broadcast/v1/ws-ticket` and what scope to stamp into the short-lived websocket ticket:
221
221
 
@@ -70,14 +70,19 @@ update: { access: { roles: ["member", "admin", "owner"] }, routes: false },
70
70
  One blessed path — **RFC 5789 media-type dispatch** on the routes you already
71
71
  have. No subpath.
72
72
 
73
- - `PATCH /api/v2/<resource>/:id` with
73
+ Paths below use the default `/api/v1` prefix. Changesets are a contract-v2
74
+ **semantics** feature and v2 is the default, so they are available without
75
+ moving your URLs — set [`contract.routes`](/platform/api-contract#two-axes-semantics-and-routes)
76
+ to `"v2"` only if you also want the `/api/v2` prefix.
77
+
78
+ - `PATCH /api/v1/<resource>/:id` with
74
79
  `Content-Type: application/vnd.quickback.changeset+json` — apply a changeset
75
80
  to an existing root. Plain `application/json` keeps the flat-column PATCH.
76
- - `POST /api/v2/<resource>` with the same media type — create the root and its
81
+ - `POST /api/v1/<resource>` with the same media type — create the root and its
77
82
  children in one changeset.
78
83
 
79
84
  ```jsonc
80
- // PATCH /api/v2/projects/prj_1 (Content-Type: application/vnd.quickback.changeset+json)
85
+ // PATCH /api/v1/projects/prj_1 (Content-Type: application/vnd.quickback.changeset+json)
81
86
  {
82
87
  "patch": { "name": "Renamed" }, // sparse ROOT patch (optional)
83
88
  "tasks": {
@@ -49,9 +49,11 @@ auth: {
49
49
  },
50
50
  ```
51
51
 
52
- > **Contract v2 makes this surface opt-in**
52
+ > **This surface is opt-in by default**
53
53
  >
54
- > On `contract: { version: "v2" }`, the custom JWT surface is emitted only when `auth.jwt` is present. Omit it and the generated output has no token endpoint, no `src/lib/jwt.ts`, and no JWT fast-path — cookie and signed session-token bearer auth still work. Contract v1 always emits it. See [Auth & JWT config](/configure/auth).
54
+ > Contract v2 is the default since v0.64.0, and on it the custom JWT surface is emitted only when `auth.jwt` is present. Omit it and the generated output has no token endpoint and no JWT fast-path — cookie and signed session-token bearer auth still work. Pin `contract: { version: "v1" }` to get it unconditionally. See [Auth & JWT config](/configure/auth).
55
+ >
56
+ > `src/lib/jwt.ts` is still emitted when the project declares [`authz.scopes`](/define/scopes): scope tokens are signed JWTs, so the helper is required for minting and verifying them even with no credential lane.
55
57
 
56
58
 
57
59
  ---
@@ -79,7 +79,7 @@ providers: {
79
79
  }
80
80
  ```
81
81
 
82
- That tells `/broadcast/v1/ws-ticket` (the broadcast surface tracks `contract.version`, so `/broadcast/v2/ws-ticket` on contract-v2 projects) to authenticate with Better Auth, run the declared gate against `body.eventId`, and mint a short-lived ticket scoped to the resolved `events:<id>` lane. See [Realtime → Enabling Realtime](/platform/realtime#enabling-realtime) for the full per-arm semantics; all three forms fail closed at compile time (ambiguous names living in two vocabularies, missing `auth.roleHierarchy` for `+`, missing `authz.fga`, unknown FGA type/relation, missing organization column, non-tenant-scoped `scopeTable`).
82
+ That tells `/broadcast/v1/ws-ticket` (the broadcast surface tracks `contract.routes`, so `/broadcast/v2/ws-ticket` when that is `"v2"`) to authenticate with Better Auth, run the declared gate against `body.eventId`, and mint a short-lived ticket scoped to the resolved `events:<id>` lane. See [Realtime → Enabling Realtime](/platform/realtime#enabling-realtime) for the full per-arm semantics; all three forms fail closed at compile time (ambiguous names living in two vocabularies, missing `auth.roleHierarchy` for `+`, missing `authz.fga`, unknown FGA type/relation, missing organization column, non-tenant-scoped `scopeTable`).
83
83
 
84
84
  ### Namespace-backed tickets (per-matched-lane)
85
85
 
@@ -2,7 +2,7 @@
2
2
 
3
3
  Quickback ships **two parallel realtime primitives**, both backed by Cloudflare Durable Objects:
4
4
 
5
- - **`/broadcast/v1/*` — server fan-out.** One DO instance per subscription scope. Postgres-changes events from CRUD routes plus custom broadcast events flow out to every subscriber, with role filtering and per-role field masking applied. Best for "tell every client in this shared scope that something changed." The scope can be an organization, a specific user, or a compiler-resolved resource key like `events:evt_123`. The `/broadcast/v1` version segment tracks `contract.version` — contract-v2 projects mount the same surface at `/broadcast/v2` (no hidden v1 alias). Documented on this page. For **typed, targeted "this changed — refresh" signals** fired from an action after commit (with optional per-recipient narrowing), see [Named invalidations](/platform/realtime/named-invalidations).
5
+ - **`/broadcast/v1/*` — server fan-out.** One DO instance per subscription scope. Postgres-changes events from CRUD routes plus custom broadcast events flow out to every subscriber, with role filtering and per-role field masking applied. Best for "tell every client in this shared scope that something changed." The scope can be an organization, a specific user, or a compiler-resolved resource key like `events:evt_123`. The `/broadcast/v1` version segment tracks `contract.routes` — set it to `"v2"` and the same surface mounts at `/broadcast/v2` (no hidden v1 alias). `contract.version` selects the frame FORMAT, not the path: on v2 semantics (the default) frames are [CloudEvents 1.0](/platform/api-contract#contract-version-matrix) envelopes regardless of which prefix you serve them on. Documented on this page. For **typed, targeted "this changed — refresh" signals** fired from an action after commit (with optional per-recipient narrowing), see [Named invalidations](/platform/realtime/named-invalidations).
6
6
  - **`/realtime/<binding>/<room-id>` — bidirectional rooms.** One DO instance per room (per document, per interview, per game). Client↔client messages, presence, and CRDT-friendly state. Use these for collaborative editing. See [PartyServer rooms](/platform/realtime/partyserver-rooms).
7
7
 
8
8
  Both share the same auth model and ride on the same compiled worker; they solve different problems.
@@ -157,7 +157,7 @@ function PersonDetail({ personId }: { personId: string }) {
157
157
  Under the hood `useView` uses a **subscribe-then-snapshot** flow so no change
158
158
  slips through the gap between reading the surface and the socket going live:
159
159
 
160
- 1. Requests a **view-scoped ws-ticket** (`POST /broadcast/v1/ws-ticket` — `/broadcast/v2/ws-ticket` on contract-v2 projects — with
160
+ 1. Requests a **view-scoped ws-ticket** (`POST /broadcast/v1/ws-ticket` — `/broadcast/v2/ws-ticket` when `contract.routes` is `"v2"` — with
161
161
  `{ view, rootId }`) — gated by exactly the same `read.access` + firewall
162
162
  checks as the read endpoint — and opens a WebSocket scoped to
163
163
  `view:<view>:<rootId>`.
@@ -125,7 +125,7 @@ Each `invalidate.<binding>.<variant>(payload)` call queues **one** after-commit
125
125
 
126
126
  ## The wire frame
127
127
 
128
- Clients receive a broadcast frame on `/broadcast/v{n}` (the version tracks `contract.version`):
128
+ Clients receive a broadcast frame on `/broadcast/v{n}` (the segment tracks `contract.routes`):
129
129
 
130
130
  ```jsonc
131
131
  {
@@ -8,7 +8,7 @@ Open a WebSocket connection to the realtime worker:
8
8
 
9
9
  ```typescript
10
10
  const ws = new WebSocket("wss://api.yourdomain.com/broadcast/v1/websocket");
11
- // Note: /broadcast/v1 tracks contract.version — use /broadcast/v2 on contract-v2 projects.
11
+ // Note: /broadcast/v1 tracks contract.routes — use /broadcast/v2 when that is "v2".
12
12
  ```
13
13
 
14
14
  ## Authentication
@@ -377,8 +377,9 @@ For each feature, the compiler generates a routes file at `src/features/{name}/r
377
377
  | `POST /:id/{action}` | Record-based actions defined |
378
378
  | `POST /{action}` | Standalone actions defined |
379
379
 
380
- Routes are mounted under `/api/v1/{feature}` for the default contract or
381
- `/api/v2/{feature}` when `contract: { version: "v2" }` is selected.
380
+ Routes are mounted under `/api/v1/{feature}` by default, or
381
+ `/api/v2/{feature}` when `contract: { routes: "v2" }` is set. `contract.version`
382
+ selects semantics and leaves these paths alone.
382
383
 
383
384
  ## Migrations
384
385
 
@@ -105,7 +105,7 @@ interface ListResult {
105
105
  The client is constructed once from the resolved `apiUrl` and provided via React
106
106
  context (`ApiClientContext`), available throughout the component tree. It reads
107
107
  the Better Auth session cookie and calls the standard REST endpoints
108
- (`/api/v1/{table}`, or `/api/v2/…` on contract-v2 projects).
108
+ (`/api/v1/{table}`, or `/api/v2/…` when `contract.routes` is `"v2"`).
109
109
 
110
110
  ## Embedded Mode (Recommended)
111
111