@quickback-dev/cli 0.66.0 → 0.66.2

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.
Files changed (228) hide show
  1. package/README.md +7 -4
  2. package/dist/commands/build.d.ts +51 -0
  3. package/dist/commands/build.d.ts.map +1 -0
  4. package/dist/commands/build.js +793 -0
  5. package/dist/commands/build.js.map +1 -0
  6. package/dist/commands/build.test.d.ts +2 -0
  7. package/dist/commands/build.test.d.ts.map +1 -0
  8. package/dist/commands/build.test.js +150 -0
  9. package/dist/commands/build.test.js.map +1 -0
  10. package/dist/commands/check.d.ts +2 -2
  11. package/dist/commands/check.js +4 -4
  12. package/dist/commands/check.js.map +1 -1
  13. package/dist/commands/create.d.ts +1 -1
  14. package/dist/commands/create.js +7 -7
  15. package/dist/commands/create.js.map +1 -1
  16. package/dist/commands/deploy.d.ts +6 -6
  17. package/dist/commands/deploy.js +23 -23
  18. package/dist/commands/deploy.js.map +1 -1
  19. package/dist/commands/example.js +1 -1
  20. package/dist/commands/example.js.map +1 -1
  21. package/dist/commands/mcp.js +1 -1
  22. package/dist/commands/mcp.js.map +1 -1
  23. package/dist/commands/migrate.d.ts +1 -1
  24. package/dist/commands/migrate.js +3 -3
  25. package/dist/commands/migrate.js.map +1 -1
  26. package/dist/commands/migrations.js +2 -2
  27. package/dist/commands/migrations.js.map +1 -1
  28. package/dist/commands/push.js +1 -1
  29. package/dist/commands/push.js.map +1 -1
  30. package/dist/commands/start.js +1 -1
  31. package/dist/commands/start.js.map +1 -1
  32. package/dist/cursor/quickback.mdc +1 -1
  33. package/dist/index.js +18 -15
  34. package/dist/index.js.map +1 -1
  35. package/dist/lib/auth.js +1 -1
  36. package/dist/lib/auth.js.map +1 -1
  37. package/dist/lib/compiler-floor.d.ts +1 -1
  38. package/dist/lib/compiler-floor.js +1 -1
  39. package/dist/lib/file-loader.js +2 -2
  40. package/dist/lib/file-loader.js.map +1 -1
  41. package/dist/lib/file-writer.d.ts +2 -0
  42. package/dist/lib/file-writer.d.ts.map +1 -1
  43. package/dist/lib/file-writer.js +16 -0
  44. package/dist/lib/file-writer.js.map +1 -1
  45. package/dist/lib/file-writer.test.js +16 -0
  46. package/dist/lib/file-writer.test.js.map +1 -1
  47. package/dist/lib/migrations/file-envelopes.js +3 -3
  48. package/dist/lib/migrations/file-envelopes.js.map +1 -1
  49. package/dist/lib/prepare-output.test.js +1 -1
  50. package/dist/lib/prepare-output.test.js.map +1 -1
  51. package/dist/lib/schema-sync/index.js +1 -1
  52. package/dist/lib/schema-sync/index.test.js +1 -1
  53. package/dist/lib/schema-sync/index.test.js.map +1 -1
  54. package/dist/lib/wrangler-resources.d.ts.map +1 -1
  55. package/dist/lib/wrangler-resources.js +5 -2
  56. package/dist/lib/wrangler-resources.js.map +1 -1
  57. package/dist/lib/wrangler-resources.test.js +6 -0
  58. package/dist/lib/wrangler-resources.test.js.map +1 -1
  59. package/dist/skill/SKILL.md +24 -9
  60. package/dist/skill/docs/api/crud.md +7 -0
  61. package/dist/skill/docs/api/index.md +1 -1
  62. package/dist/skill/docs/api/openapi.md +1 -1
  63. package/dist/skill/docs/changelog/index.md +27 -1
  64. package/dist/skill/docs/configure/agents.md +1 -1
  65. package/dist/skill/docs/configure/domains.md +1 -1
  66. package/dist/skill/docs/configure/index.md +11 -5
  67. package/dist/skill/docs/configure/providers.md +6 -3
  68. package/dist/skill/docs/configure/single-tenant.md +7 -3
  69. package/dist/skill/docs/configure/variables.md +3 -3
  70. package/dist/skill/docs/define/access.md +10 -0
  71. package/dist/skill/docs/define/actions/defining.md +35 -7
  72. package/dist/skill/docs/define/actions/index.md +1 -1
  73. package/dist/skill/docs/define/actions/record-and-standalone.md +7 -4
  74. package/dist/skill/docs/define/actions/scoped-db.md +68 -21
  75. package/dist/skill/docs/define/areas.md +1 -1
  76. package/dist/skill/docs/define/diagnostics.md +1 -0
  77. package/dist/skill/docs/define/encryption.md +1 -1
  78. package/dist/skill/docs/define/feature.md +17 -8
  79. package/dist/skill/docs/define/firewall.md +2 -0
  80. package/dist/skill/docs/define/guards.md +27 -3
  81. package/dist/skill/docs/define/index.md +1 -1
  82. package/dist/skill/docs/define/relationships.md +7 -0
  83. package/dist/skill/docs/define/schema.md +44 -14
  84. package/dist/skill/docs/define/security.md +1 -1
  85. package/dist/skill/docs/define/transitions.md +35 -4
  86. package/dist/skill/docs/define/triggers.md +14 -3
  87. package/dist/skill/docs/define/views.md +33 -0
  88. package/dist/skill/docs/index.md +2 -2
  89. package/dist/skill/docs/platform/auth/api-keys.md +2 -2
  90. package/dist/skill/docs/platform/auth/using-auth.md +37 -0
  91. package/dist/skill/docs/platform/database/d1.md +15 -3
  92. package/dist/skill/docs/platform/database/neon.md +4 -4
  93. package/dist/skill/docs/platform/email/index.md +1 -1
  94. package/dist/skill/docs/platform/queues/handlers.md +1 -1
  95. package/dist/skill/docs/platform/queues/using-queues.md +1 -1
  96. package/dist/skill/docs/platform/realtime/using-realtime.md +6 -4
  97. package/dist/skill/docs/platform/schedules/index.md +1 -1
  98. package/dist/skill/docs/platform/storage/index.md +3 -3
  99. package/dist/skill/docs/platform/storage/r2.md +87 -37
  100. package/dist/skill/docs/platform/storage/using-r2.md +99 -19
  101. package/dist/skill/docs/platform/webhooks/inbound.md +40 -0
  102. package/dist/skill/docs/start/deploy-browser.md +40 -45
  103. package/dist/skill/docs/start/deploy-owner-access.md +60 -52
  104. package/dist/skill/docs/start/deploy.md +4 -4
  105. package/dist/skill/docs/start/first-api.md +2 -2
  106. package/dist/skill/docs/start/hand-crafted.md +3 -3
  107. package/dist/skill/docs/start/index.md +3 -3
  108. package/dist/skill/docs/start/patterns.md +17 -2
  109. package/dist/skill/docs/start/quickstart.md +3 -3
  110. package/dist/skill/docs/start/template-blog.md +2 -2
  111. package/dist/skill/docs/start/template-cloudflare.md +3 -3
  112. package/dist/skill/docs/start/template-empty.md +1 -1
  113. package/dist/skill/docs/start/templates.md +1 -1
  114. package/dist/skill/docs/tooling/claude-skill.md +1 -1
  115. package/dist/skill/docs/tooling/cli.md +21 -16
  116. package/dist/skill/docs/tooling/cloud-compiler/authentication.md +2 -2
  117. package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +5 -3
  118. package/dist/skill/docs/tooling/cloud-compiler/index.md +1 -1
  119. package/dist/skill/docs/tooling/cloud-compiler/local-compiler.md +2 -2
  120. package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +74 -1
  121. package/dist/skill/docs/tooling/output.md +23 -2
  122. package/dist/skill/docs/tooling/troubleshooting.md +1 -1
  123. package/dist/skill/docs/ui/account/customization.md +1 -1
  124. package/dist/skill/docs/ui/account/environment-variables.md +2 -2
  125. package/dist/skill/docs/ui/account/features/admin.md +1 -1
  126. package/dist/skill/docs/ui/account/features/api-keys.md +10 -8
  127. package/dist/skill/docs/ui/account/features/avatars.md +24 -8
  128. package/dist/skill/docs/ui/account/features/index.md +16 -11
  129. package/dist/skill/docs/ui/account/features/organizations.md +3 -2
  130. package/dist/skill/docs/ui/account/hooks.md +2 -0
  131. package/dist/skill/docs/ui/account/index.md +10 -5
  132. package/dist/skill/docs/ui/account/with-quickback.md +2 -2
  133. package/dist/skill/docs/ui/admin/actions.md +97 -3
  134. package/dist/skill/docs/ui/admin/components.md +4 -6
  135. package/dist/skill/docs/ui/admin/connecting.md +15 -3
  136. package/dist/skill/docs/ui/admin/index.md +71 -6
  137. package/dist/skill/docs/ui/admin/inline-editing.md +38 -4
  138. package/dist/skill/docs/ui/admin/record-layouts.md +22 -21
  139. package/dist/skill/docs/ui/admin/schema-format.md +39 -2
  140. package/dist/skill/docs/ui/admin/schema-registry.md +107 -7
  141. package/dist/skill/docs/ui/admin/security.md +19 -4
  142. package/dist/skill/docs/ui/admin/table-views.md +59 -12
  143. package/package.json +1 -1
  144. package/src/cursor/quickback.mdc +1 -1
  145. package/src/skill/SKILL.md +24 -9
  146. package/src/skill/docs/api/crud.md +7 -0
  147. package/src/skill/docs/api/index.md +1 -1
  148. package/src/skill/docs/api/openapi.md +1 -1
  149. package/src/skill/docs/changelog/index.md +27 -1
  150. package/src/skill/docs/configure/agents.md +1 -1
  151. package/src/skill/docs/configure/domains.md +1 -1
  152. package/src/skill/docs/configure/index.md +11 -5
  153. package/src/skill/docs/configure/providers.md +6 -3
  154. package/src/skill/docs/configure/single-tenant.md +7 -3
  155. package/src/skill/docs/configure/variables.md +3 -3
  156. package/src/skill/docs/define/access.md +10 -0
  157. package/src/skill/docs/define/actions/defining.md +35 -7
  158. package/src/skill/docs/define/actions/index.md +1 -1
  159. package/src/skill/docs/define/actions/record-and-standalone.md +7 -4
  160. package/src/skill/docs/define/actions/scoped-db.md +68 -21
  161. package/src/skill/docs/define/areas.md +1 -1
  162. package/src/skill/docs/define/diagnostics.md +1 -0
  163. package/src/skill/docs/define/encryption.md +1 -1
  164. package/src/skill/docs/define/feature.md +17 -8
  165. package/src/skill/docs/define/firewall.md +2 -0
  166. package/src/skill/docs/define/guards.md +27 -3
  167. package/src/skill/docs/define/index.md +1 -1
  168. package/src/skill/docs/define/relationships.md +7 -0
  169. package/src/skill/docs/define/schema.md +44 -14
  170. package/src/skill/docs/define/security.md +1 -1
  171. package/src/skill/docs/define/transitions.md +35 -4
  172. package/src/skill/docs/define/triggers.md +14 -3
  173. package/src/skill/docs/define/views.md +33 -0
  174. package/src/skill/docs/index.md +2 -2
  175. package/src/skill/docs/platform/auth/api-keys.md +2 -2
  176. package/src/skill/docs/platform/auth/using-auth.md +37 -0
  177. package/src/skill/docs/platform/database/d1.md +15 -3
  178. package/src/skill/docs/platform/database/neon.md +4 -4
  179. package/src/skill/docs/platform/email/index.md +1 -1
  180. package/src/skill/docs/platform/queues/handlers.md +1 -1
  181. package/src/skill/docs/platform/queues/using-queues.md +1 -1
  182. package/src/skill/docs/platform/realtime/using-realtime.md +6 -4
  183. package/src/skill/docs/platform/schedules/index.md +1 -1
  184. package/src/skill/docs/platform/storage/index.md +3 -3
  185. package/src/skill/docs/platform/storage/r2.md +87 -37
  186. package/src/skill/docs/platform/storage/using-r2.md +99 -19
  187. package/src/skill/docs/platform/webhooks/inbound.md +40 -0
  188. package/src/skill/docs/start/deploy-browser.md +40 -45
  189. package/src/skill/docs/start/deploy-owner-access.md +60 -52
  190. package/src/skill/docs/start/deploy.md +4 -4
  191. package/src/skill/docs/start/first-api.md +2 -2
  192. package/src/skill/docs/start/hand-crafted.md +3 -3
  193. package/src/skill/docs/start/index.md +3 -3
  194. package/src/skill/docs/start/patterns.md +17 -2
  195. package/src/skill/docs/start/quickstart.md +3 -3
  196. package/src/skill/docs/start/template-blog.md +2 -2
  197. package/src/skill/docs/start/template-cloudflare.md +3 -3
  198. package/src/skill/docs/start/template-empty.md +1 -1
  199. package/src/skill/docs/start/templates.md +1 -1
  200. package/src/skill/docs/tooling/claude-skill.md +1 -1
  201. package/src/skill/docs/tooling/cli.md +21 -16
  202. package/src/skill/docs/tooling/cloud-compiler/authentication.md +2 -2
  203. package/src/skill/docs/tooling/cloud-compiler/endpoints.md +5 -3
  204. package/src/skill/docs/tooling/cloud-compiler/index.md +1 -1
  205. package/src/skill/docs/tooling/cloud-compiler/local-compiler.md +2 -2
  206. package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +74 -1
  207. package/src/skill/docs/tooling/output.md +23 -2
  208. package/src/skill/docs/tooling/troubleshooting.md +1 -1
  209. package/src/skill/docs/ui/account/customization.md +1 -1
  210. package/src/skill/docs/ui/account/environment-variables.md +2 -2
  211. package/src/skill/docs/ui/account/features/admin.md +1 -1
  212. package/src/skill/docs/ui/account/features/api-keys.md +10 -8
  213. package/src/skill/docs/ui/account/features/avatars.md +24 -8
  214. package/src/skill/docs/ui/account/features/index.md +16 -11
  215. package/src/skill/docs/ui/account/features/organizations.md +3 -2
  216. package/src/skill/docs/ui/account/hooks.md +2 -0
  217. package/src/skill/docs/ui/account/index.md +10 -5
  218. package/src/skill/docs/ui/account/with-quickback.md +2 -2
  219. package/src/skill/docs/ui/admin/actions.md +97 -3
  220. package/src/skill/docs/ui/admin/components.md +4 -6
  221. package/src/skill/docs/ui/admin/connecting.md +15 -3
  222. package/src/skill/docs/ui/admin/index.md +71 -6
  223. package/src/skill/docs/ui/admin/inline-editing.md +38 -4
  224. package/src/skill/docs/ui/admin/record-layouts.md +22 -21
  225. package/src/skill/docs/ui/admin/schema-format.md +39 -2
  226. package/src/skill/docs/ui/admin/schema-registry.md +107 -7
  227. package/src/skill/docs/ui/admin/security.md +19 -4
  228. package/src/skill/docs/ui/admin/table-views.md +59 -12
@@ -157,11 +157,14 @@ Drizzle's relational query API — `db.query.<table>.findFirst()` /
157
157
  relations config and your `where` alone, so the scoped wrapper cannot inject
158
158
  the org/owner/team firewall into it. The scoped `db` therefore exposes the
159
159
  Drizzle select builder—the path where Quickback can guarantee firewall
160
- injection—and refuses `db.query.<table>` rather than returning unscoped rows:
160
+ injection—and refuses `db.query.<table>` rather than returning unscoped rows.
161
+ The compiler rejects authored uses before code generation, including Start's
162
+ definition-validation build; the generated runtime guard remains as a
163
+ fail-closed backstop:
161
164
 
162
165
  ```typescript
163
166
  async execute({ db, input }) {
164
- // ❌ Throws: relational queries aren't org-scoped
167
+ // ❌ Compile error: relational queries aren't org-scoped
165
168
  const item = await db.query.media.findFirst({ where: eq(media.id, input.id) });
166
169
 
167
170
  // ✅ Scoped builder — firewall conditions injected automatically
@@ -303,25 +306,53 @@ export default defineAction({
303
306
 
304
307
  ### Importing Tables
305
308
 
306
- Action files import tables from their own feature or other features. The compiler generates alias files for each table, so you import by the table's file name:
309
+ The action's own generated helper supplies `defineAction` and the tables owned
310
+ by that feature. It does not re-export tables from sibling features. Import a
311
+ cross-feature table from that feature's generated helper or generated table
312
+ module, and import Drizzle query operators through the generated project
313
+ `lib/q`:
307
314
 
315
+ {/* doc-compile: skip — demonstrates generated cross-feature helper and runtime paths; the isolated fence does not declare either feature. */}
308
316
  ```typescript
309
- // features/applications/actions/advance.ts
310
- import { eq, and } from "drizzle-orm";
311
-
312
- // Same feature — import from parent directory using the table's file name
313
- import { applications } from "../applications";
314
- import { interviewScores } from "../interview-scores";
317
+ // features/waitlist/actions/promote.ts
318
+ import {
319
+ defineAction,
320
+ waitlistEntries,
321
+ } from "../.quickback/define-action";
322
+ import { reservations } from "../../reservations/.quickback/define-action";
323
+ import { q } from "../../../lib/q";
315
324
 
316
- // Cross-feature — go up to the features directory, then into the other feature
317
- import { candidates } from "../../candidates/candidates";
318
- import { jobs } from "../../jobs/jobs";
325
+ export default defineAction({
326
+ // ...input, access, and transition...
327
+ async execute({ db, record, whereRecord, now }) {
328
+ const existing = await db
329
+ .select()
330
+ .from(reservations)
331
+ .where(q.eq(reservations.waitlistEntryId, record.id));
332
+
333
+ await db
334
+ .update(waitlistEntries)
335
+ .set({ promotedAt: now })
336
+ .where(whereRecord!(waitlistEntries));
337
+
338
+ return existing;
339
+ },
340
+ });
319
341
  ```
320
342
 
321
343
  **Path pattern from `features/{name}/actions/`:**
322
- - Same feature table: `../{table-file-name}` (e.g., `../applications`)
323
- - Other feature table: `../../{other-feature}/{table-file-name}` (e.g., `../../candidates/candidates`)
324
- - Generated lib files: `../../../lib/{module}` (e.g., `../../../lib/realtime`, `../../../lib/webhooks`)
344
+
345
+ - Own feature helper: `../.quickback/define-action`
346
+ - Other feature helper: `../../{other-feature}/.quickback/define-action`
347
+ - Other generated table module: `../../{other-feature}/{table-file-name}`
348
+ - Generated project query helper: `../../../lib/q`
349
+ - Other generated lib files: `../../../lib/{module}` (for example,
350
+ `../../../lib/realtime` or `../../../lib/webhooks`)
351
+
352
+ Keep `defineAction` from the action's own feature: that helper binds `record`,
353
+ `whereRecord`, and `whereTransition`. Import only the external table from a
354
+ sibling feature. The waitlist/reservations names above are just the common
355
+ pattern; the rule applies to every cross-feature action.
325
356
 
326
357
  ### Executor Parameters
327
358
 
@@ -448,9 +479,14 @@ with the transition's "from" precondition for transition actions.
448
479
 
449
480
  #### Reaching Better Auth tables (`authDb`)
450
481
 
451
- The scoped `db` only sees your feature tables. To read Better Auth tables —
452
- users, organizations, members — use the auth database connection from the
453
- Hono context plus the generated `lib/org-access.ts` helper:
482
+ The scoped `db` is the **features** database. Better Auth tables never appear
483
+ on it — that is by design. `AUTH_DB` is a separate Drizzle client.
484
+
485
+ **Caller identity — use `ctx`, do not query `AUTH_DB`.** `ctx.userId`,
486
+ `ctx.activeOrgId`, `ctx.roles`, and `ctx.userRole` are already on the request.
487
+
488
+ To check that a *submitted* user id is an org member (assignee-style
489
+ features), use `c.get("authDb")` plus the generated `getOrgMemberRole` helper:
454
490
 
455
491
  ```typescript
456
492
  // features/projects/actions/assign.ts — validate a userId is an org member
@@ -481,6 +517,17 @@ export default defineAction({
481
517
  ```
482
518
 
483
519
  `c.get("authDb")` is the Drizzle connection to the auth database (in dual-DB
484
- mode it's a separate D1 from your features). For richer queries, import the
485
- auth schema tables from `../../../auth/schema` and query `authDb` directly.
486
-
520
+ mode it's a separate D1 from your features). That is the native membership
521
+ check.
522
+
523
+ For a richer query, use the same `authDb` and import tables from
524
+ `../../../auth/schema` — from an **`actions/` file**. On D1 the tables are
525
+ `user`, `organization`, and `member` — not `organization_membership`. (Neon
526
+ exports the Better Auth CLI's plural names: `users`, `organizations`,
527
+ `members`.)
528
+
529
+ | Surface | AUTH_DB handle | Notes |
530
+ |---|---|---|
531
+ | Action `execute` | `c.get("authDb")` | Import schema from `../../../auth/schema` |
532
+ | [Account hooks](/ui/account/hooks) | `{ authDb, authSchema }` injected | Use the injected namespace — do not invent a path to `auth/schema` |
533
+ | Trigger `handler:` | **none** | Args are `{ ctx, db, env }` — `db` is features only. There is no `c`. Prefer `ctx` for the acting user. Do not import `../../auth/schema` from the table file to reach AUTH_DB; that path used to compile and then fail package-mode wrangler. Check another user's membership in an action. |
@@ -553,7 +553,7 @@ Actions that keep their existing `import { defineAction } from '../.quickback/de
553
553
 
554
554
  #### Compile-time advisory
555
555
 
556
- When `quickback compile` sees a namespace-scoped action still importing the generic helper, it emits a one-line advisory pointing at the narrowed path:
556
+ When `quickback build` sees a namespace-scoped action still importing the generic helper, it emits a one-line advisory pointing at the narrowed path:
557
557
 
558
558
  ```text
559
559
  [quickback:typing] action "feedMoments" in feature "feeds" lives under
@@ -58,6 +58,7 @@ compile.
58
58
  | `AUTHZ_UNREACHABLE_ROLE` | warn | A scoped role declared under `authz.scopes` with **no grant profile** — it can authorize no read, action, or channel. Dead config, deny-safe. |
59
59
  | `AUTHZ_UNREACHABLE_VIEW` | warn | A grant's `read` names a `resource:view` whose resource has no firewall — no role can reach that view. (A reachability proxy — heuristic by design.) |
60
60
  | `AUTHZ_NOT_OVER_RESOURCE` | warn | A `not` whose operand resolves to a **resource (SQL) site** — `NOT EXISTS` over a nullable join can silently pass (the null-trap). The site resolution is conservative, so this stays advisory. |
61
+ | `AUTHZ_RECORD_PREDICATE_NOT_ON_LIST` | warn | A **constant** `read.access.record` predicate (`status: { equals: "published" }`, `id: { equals: "never" }`). `access.record` runs against a loaded row on `GET /:id` only — `GET /`, `POST /batch`, and the MCP list tool stop at the role gate, so the rows still list. Omit `read` to hide a resource; use the firewall to filter. `$ctx`-relative predicates are the per-record shape and stay silent. |
61
62
  | `AUTHZ_PUSHDOWN_COST` | info | Per-permission report: how many SQL subqueries the permission lowers to, plus the max recursive-CTE depth. Advisory, never fails a build. |
62
63
 
63
64
  A few codes are reserved in the diagnostic enum for the milestones that emit
@@ -26,7 +26,7 @@ That one modifier changes what a database breach means: a leaked D1 backup, expo
26
26
  - **`org_data_keys`** — one row per organization holding a random 256-bit data key (DEK), stored **wrapped** under the `ENCRYPTION_KEK` worker secret. Created lazily on the org's first encrypted write.
27
27
  - **Write path** — every write (CRUD routes, batch routes, and `db.insert`/`db.update` inside your actions) flows through the same chokepoint, which AES-256-GCM-encrypts the column before anything else sees it. Audit snapshots, webhook payloads, and realtime deltas therefore carry ciphertext by construction.
28
28
  - **Read path** — generated routes decrypt behind the firewall and then apply masking, so authorized callers see plaintext and everyone else sees the redaction — never ciphertext.
29
- - **`ctx.crypto`** — explicit `await ctx.crypto.decrypt(value)` / `ctx.crypto.encrypt(value)` for action code that processes the field server-side (building a manifest, sending an email). Scoped to the caller's active organization.
29
+ - **`ctx.crypto`** — explicit `await ctx.crypto.decrypt(value)` / `ctx.crypto.encrypt(value)` for action code that processes the field server-side (building a manifest, sending an email). Scoped to the caller's active organization. `ctx.crypto` is only hydrated for authenticated requests — inside schedules, queue consumers, email handlers, and `PUBLIC` actions it is undefined. There, import the primitives directly: `import { encryptValue, decryptValue } from '../lib/encryption'` and call `decryptValue(env, db, organizationId, stored)`. Writes through the `withInternalContext` handle still encrypt automatically.
30
30
  - **Boot guard** — a project with encrypted columns refuses to serve without `ENCRYPTION_KEK` (503 `MISSING_ENV`), instead of silently storing plaintext.
31
31
 
32
32
  Values at rest look like `qbenc:1:<keyVersion>:<iv>:<ciphertext>` — the prefix makes accidental plaintext detectable, and the embedded key version supports rotation with lazy re-encryption on write.
@@ -96,7 +96,7 @@ export default feature("episodes", {
96
96
  guards: { updatable: ["title"], protected: { isPublished: ["publish"] } },
97
97
  masking: { submitterEmail: { type: "email", show: { roles: ["admin"] } } },
98
98
  transitions: { publish: { field: "isPublished", from: false, to: true, access: { roles: ["admin+"] } } },
99
- realtime: { enabled: true, onInsert: true, onUpdate: true },
99
+ realtime: { enabled: true, onInsert: true, onUpdate: true, access: { roles: ["member+"] } }, // access is mandatory — the audience of the broadcast
100
100
  embeddings: { fields: ["title", "summary"] },
101
101
  });
102
102
  ```
@@ -104,7 +104,7 @@ export default feature("episodes", {
104
104
  | Key | Gives you | Reference |
105
105
  |---|---|---|
106
106
  | `read.views` | Named column projections, each with its own route and access rule | [Views](/define/views) |
107
- | `transitions` | Guarded state changes generated as real `POST /:id/{name}` actions — guards, stamps, `undo`, cascades | [Transitions](/define/transitions) |
107
+ | `transitions` | Guarded state changes generated as real `POST /:id/{name}` actions — guards, stamps, `undo`, cascades. **Fixed target only**: each entry needs a literal `to` (with `from` or `fromTo`). A variable target read from input (`via: "nextStatus"`) is a hand-written `actions/<name>.ts` with `transition: { via }` — the compiler errors otherwise. | [Transitions](/define/transitions) |
108
108
  | `triggers` | `before`/`after` hooks on write, lowered to a real SQL trigger or an application handler | [Triggers](/define/triggers) |
109
109
  | `realtime` | Per-table broadcasts on insert/update/delete, audience-scoped | [Realtime](/platform/realtime/using-realtime) |
110
110
  | `owns` | The composition boundary that turns on atomic parent-plus-children writes | [Changesets](/define/changesets) |
@@ -124,7 +124,7 @@ one" routing table at the top of [Actions](/define/actions).
124
124
  That means:
125
125
 
126
126
  - **Both forms remain supported indefinitely.** Mix them freely — some files `feature(...)`, some files `q.table() + defineTable()`, some files Drizzle `sqliteTable() + defineTable()`. The compiler dispatches per file.
127
- - **Action files get the table from the generated helper.** Each action lives in its own file under `actions/` and imports both `defineAction` and the feature's table from `../.quickback/define-action` — the helper re-exports the table typed with the generated schema, so `record` and the audit columns are visible without casts.
127
+ - **Action files get their bound context from the generated helper.** Each action lives in its own file under `actions/` and imports `defineAction` plus tables owned by that feature from `../.quickback/define-action`. The helper re-exports every table **in that feature** typed with the generated schema, so `record` and the audit columns are visible without casts. It does not export tables from a sibling feature: import those separately from that feature's generated helper or table module, while keeping `defineAction` local. Query operators come from project `lib/q`.
128
128
  - **Diagnostics are identical.** Missing firewall → same warning. Protected-field wiring → same check. Nothing about `feature()` weakens the secure-by-default posture.
129
129
 
130
130
  ## Aliases
@@ -187,10 +187,13 @@ For everything action-related — record vs standalone, conflict rules, the gene
187
187
  ## Composition vs reference — `owns`
188
188
 
189
189
  A schema-level FK (`references:` / `.references()`) says "this row points at
190
- that row." It does **not** say who owns whom. When a set of child rows has no
190
+ that row." It does **not** say who owns whom. `.references()` may only target
191
+ another **feature table in the same database** — never Better Auth `users` /
192
+ `user` / `organization` / `member` (those live in `AUTH_DB`). When a set of child rows has no
191
193
  lifecycle of its own — junction memberships, normalized phones/emails, line
192
194
  items — declare the composition with `owns` on the root table:
193
195
 
196
+ {/* doc-compile: skip — excerpt: the owned `tasks` / `projectMembers` tables and the `people` ref target live in sibling files the fence cannot carry; the compiler rejects `owns` that names an undefined table. */}
194
197
  ```ts
195
198
  export default feature("projects", {
196
199
  columns: {
@@ -204,6 +207,9 @@ export default feature("projects", {
204
207
  tasks: { table: "tasks", fk: "projectId", inherit: ["organizationId"] },
205
208
  members: { table: "projectMembers", fk: "projectId", refs: { personId: "people" }, inherit: ["organizationId"] },
206
209
  },
210
+ // `owns` only matters on a write path — declare the changeset ops it rides
211
+ create: { access: { roles: ["member+"] } },
212
+ update: { access: { roles: ["member+"] } },
207
213
  });
208
214
  ```
209
215
 
@@ -220,13 +226,16 @@ mounting its raw route.
220
226
 
221
227
  Action bodies need to run queries against the database. Quickback's compiled projects expose the Drizzle query-builder helpers on the same `q` namespace you use for schema authoring, so `execute` stays inside one DSL:
222
228
 
229
+ {/* doc-compile: skip — excerpt: the `mail` feature's `mailboxes` / `messages` / `threads` tables live in sibling files the fence cannot carry, and the generated `define-action` helper only re-exports tables that exist in the feature. */}
223
230
  ```ts title="quickback/features/mail/actions/inbound.ts"
224
231
  import { z } from "zod";
225
- import { defineAction } from "../.quickback/define-action";
232
+ import {
233
+ defineAction,
234
+ mailboxes,
235
+ messages,
236
+ threads,
237
+ } from "../.quickback/define-action";
226
238
  import { q } from "../../../lib/q";
227
- import { mailboxes } from "../mailboxes";
228
- import { messages } from "../messages";
229
- import { threads } from "../threads";
230
239
 
231
240
  export default defineAction({
232
241
  description: "Ingest an inbound email into the right thread.",
@@ -90,6 +90,8 @@ An explicit predicate on a custom-named column is honoured **on that table** via
90
90
 
91
91
  If `userId` is genuinely informational, rename it to something that says so (`linkedUserId`, `assigneeId`, `inviteeId`) and the warning goes away.
92
92
 
93
+ Do **not** turn that column into a SQL FK to Better Auth. `.references(() => users.id)` (or `user`) is illegal across split D1s (`AUTH_DB` vs `DB`) and deploy fails with `Generate features database migrations`. Store it as `q.text().required()`. See [Schema → References](/define/schema).
94
+
93
95
  ## Predicate Shape
94
96
 
95
97
  ```typescript
@@ -55,7 +55,8 @@ guards: {
55
55
  // Fields only modifiable via specific actions
56
56
  protected?: Record<string, string[]>;
57
57
 
58
- // Fields set on CREATE, never modified after
58
+ // Fields set on CREATE, blocked on every generic update.
59
+ // Actions can still write them — see the note below.
59
60
  immutable?: string[];
60
61
  }
61
62
  ```
@@ -66,8 +67,18 @@ guards: {
66
67
  |------|------------------|
67
68
  | `createable` | Fields allowed in create (POST) request body |
68
69
  | `updatable` | Fields allowed in update (PATCH) request body |
69
- | `protected` | Fields blocked from direct writes, only modifiable via named actions |
70
- | `immutable` | Fields allowed on create, blocked on all updates |
70
+ | `protected` | Fields blocked from direct writes; the named actions are documentation, not enforcement (see below) |
71
+ | `immutable` | Fields allowed on create, blocked on all generic updates (actions can still write them) |
72
+
73
+ > **Guards bind the generic CRUD surface, not actions.** `createable`,
74
+ > `updatable`, `immutable`, and `protected` are enforced by the generated
75
+ > `validateCreate` / `validateUpdate`, which only the CRUD, batch, and changeset
76
+ > routes call. An action handler writes through a scoped `db` with no field-level
77
+ > checks, so it can write any column — including an `immutable` one, and including
78
+ > a `protected` one not listed in that field's action names. Treat the names in
79
+ > `protected` as intent you are documenting, and keep the enforcement in the
80
+ > action's own access rules.
81
+
71
82
 
72
83
  **Combining lists:**
73
84
 
@@ -76,6 +87,15 @@ guards: {
76
87
  - `protected` - Don't also list in `createable` or `updatable` (they're mutually exclusive)
77
88
  - `immutable` - Don't also list in `updatable` (contradiction)
78
89
 
90
+ > **Workflow-owned fields have one writer.** If a status or state column is
91
+ > managed by transitions or named actions, put it only in `protected`, mapped to
92
+ > those transition/action names. Never also put it in `createable` or
93
+ > `updatable`: the compiler rejects either contradiction, and a direct POST or
94
+ > PATCH path would bypass the workflow. Give the column its initial value with a
95
+ > schema default. Records then begin in that state, and only the declared
96
+ > transitions/actions may write the field.
97
+
98
+
79
99
  ```typescript
80
100
  guards: {
81
101
  createable: ["candidateId", "jobId", "notes", "source"],
@@ -269,3 +289,7 @@ The Quickback compiler validates your guards configuration and will error if:
269
289
  3. **Field in both `updatable` and `immutable`** - Contradictory: immutable fields cannot be updated
270
290
  4. **Field in `protected` doesn't exist in schema** - Referenced field must exist in the table
271
291
  5. **Field in `createable`/`updatable`/`immutable` doesn't exist in schema** - All referenced fields must exist
292
+
293
+ Transition/action-managed status fields belong only in `protected`, use a
294
+ schema default for their initial value, and may be written only by the named
295
+ transitions/actions.
@@ -17,7 +17,7 @@ Quickback is a **backend compiler**. You write definition files, and Quickback c
17
17
  - **Don't** create a `workspaces` / `teams` / `tenants` table.
18
18
  - **Don't** create a membership or `*_members` table.
19
19
  - **Do** put `organizationId: q.scope("organization")` on every tenant-scoped table — the firewall is auto-derived from it.
20
- - Membership and roles arrive on every request as `ctx.activeOrgId` and `ctx.roles`. You never query for them.
20
+ - Membership and roles arrive on every request as `ctx.activeOrgId` and `ctx.roles`. Do not query AUTH_DB for the **acting** user. To check that a *submitted* user id belongs to the org, query AUTH_DB from an action — see [Scoped DB](/define/actions/scoped-db#reaching-better-auth-tables-authdb).
21
21
  - Create a tenant with `POST /auth/v1/organization/create` and switch with `POST /auth/v1/organization/set-active` — not a custom action.
22
22
 
23
23
  If your product calls it something else, that's a **label, not a schema decision** — the Account UI renames the organization surfaces for you (see [Account → Customization](/ui/account/customization)).
@@ -10,6 +10,8 @@ isn't in your org.
10
10
  > A relationship's `from:` must be one of *your* feature tables — the compiler rejects one
11
11
  > pointing at Better Auth's `organization_memberships`, `organizations`, or `user`. Org
12
12
  > membership is already decided before your handler runs and is available as `ctx.roles`.
13
+ > To validate a *submitted* user id (an assignee), query AUTH_DB from an action —
14
+ > see [Scoped DB](/define/actions/scoped-db#reaching-better-auth-tables-authdb).
13
15
  >
14
16
  > A relationship's `where:` also takes **scalar equality only** (`string | number |
15
17
  > boolean`). `where: { role: ['admin','owner'] }` is not valid — declare one relationship
@@ -53,6 +55,11 @@ export default defineConfig({
53
55
  });
54
56
  ```
55
57
 
58
+ > **userId is not a SQL FK to Better Auth**
59
+ >
60
+ > `subject: { column: 'userId', equals: 'ctx.userId' }` matches a **plain text** column on your join table. Do not write `.references(() => users.id)` (or `user`, `organization`, `member`) on that column. Better Auth tables live in `AUTH_DB`; feature tables live in `DB`. SQLite cannot FK across those databases, and drizzle-kit fails generating features migrations with `Critical command failed: Generate features database migrations`. Store it as `userId: q.text().required()`. See [Schema → References](/define/schema).
61
+
62
+
56
63
  > **The `from:` table needs its own defineTable**
57
64
  >
58
65
  > A relationship resolves through the `from:` table's **generated resource module**
@@ -82,7 +82,27 @@ A few mechanics to know:
82
82
  - **Column names** default to snake_case of the JS key — `organizationId` ↔ `organization_id`, `salaryMin` ↔ `salary_min`. Pass a positional argument to override: `q.text('custom_name')`.
83
83
  - **`q.id()`** emits `text('id').primaryKey()` with a provider-driven app-layer default.
84
84
  - **`.required()` / `.optional()`** control NOT NULL. Chain before or after `.default(x)`.
85
- - **References:** `q.text().required().references(() => other.id, { onDelete: 'cascade' })`. An FK declares a *pointer*, not ownership — when the child rows are a **composition** of one root (junctions, phones/emails, line items), also declare [`owns`](/define/changesets) on the root to generate the atomic aggregate write path.
85
+ - **References:** `q.text().required().references(() => other.id, { onDelete: 'cascade' })`. An FK declares a *pointer*, not ownership — when the child rows are a **composition** of one root (junctions, phones/emails, line items), also declare [`owns`](/define/changesets) on the root to generate the atomic aggregate write path. `other` must be a **feature table in the same database**.
86
+
87
+ > **Never FK Better Auth tables**
88
+ >
89
+ > `.references(() => users.id)` (or `user`, `organization`, `member`, `session`) on a feature column is illegal. Those tables live in `AUTH_DB`; your features live in `DB`. SQLite cannot FK across D1 databases, and drizzle-kit fails generating features migrations:
90
+ >
91
+ > `Critical command failed: Generate features database migrations`
92
+ >
93
+ > A Start chat compile (`complete=false`) still succeeds — it never runs drizzle-kit. The complete compile (`complete=true` — Generated Backend, or `quickback compile`) is the first time that command runs.
94
+ >
95
+ > A junction's `userId` is a **plain text** Better Auth id, not a SQL FK:
96
+ >
97
+ > {/* doc-compile: skip — two-column excerpt, not a host feature */}
98
+ > ```typescript
99
+ > userId: q.text().required(), // ctx.userId — no .references()
100
+ > channelId: q.text().required().references(() => channels.id, { onDelete: 'cascade' }),
101
+ > ```
102
+ >
103
+ > `authz.relationships` `subject: { column: 'userId', equals: 'ctx.userId' }` does not need, and must not create, a SQL FK. See [Relationships](/define/relationships). To query Better Auth tables, use `c.get("authDb")` from an action — see [Scoped DB](/define/actions/scoped-db#reaching-better-auth-tables-authdb).
104
+
105
+
86
106
  - **Indexes:** column-level `.index()` or table-level `indexes` / `unique` as a third arg to `q.table(name, cols, { indexes, unique })`. With `feature()`, pass `indexes` and `unique` as top-level keys alongside `columns` — the sugar forwards them into the same `q.table` opts.
87
107
 
88
108
  ### Column Types
@@ -101,6 +121,8 @@ A few mechanics to know:
101
121
  | `q.scope(kind)` | `text(...).notNull()` | `z.string()` |
102
122
  | `q.stamp({ fromScope, claim })` | `text(...).notNull()` (nullable with `optional: true`) | `z.string().optional()` |
103
123
 
124
+ In request bodies a column that is not `.required()` is `.optional().nullable()` — omit it to leave it untouched, send `null` to clear it. `""` is not a blank: it is validated like any other value. `.required()` columns never accept `null`.
125
+
104
126
  `q.text()` and `q.url()` accept either a SQL-name string or an options object — `q.text({ sqlName: 'org_id', maxLength: 80 })`. `maxLength` adds `z.string().max(n)` at the validation edge; the SQL column stays `text` (D1 ignores `VARCHAR(n)` length anyway).
105
127
 
106
128
  `q.url()` is `q.text()` plus `z.string().url()` at the validation edge, so `javascript:` / `data:` URIs and free-form strings are rejected before they ever land in storage or get rendered in the CMS.
@@ -716,27 +738,35 @@ For LIST endpoints, labels are batch-resolved efficiently — one query per FK c
716
738
 
717
739
  ## References
718
740
 
719
- When your FK columns don't match the target table name by convention (e.g., `vendorId` actually points to the `contact` table), declare explicit references so the CMS and schema registry know the correct target:
741
+ Declare every feature-table foreign key in the schema with `.references()`.
742
+ That one declaration creates the database relationship and gives the API,
743
+ schema registry, and CMS the same target for label resolution and
744
+ selector/typeahead controls:
720
745
 
721
- {/* doc-compile: skip — one-key excerpt: the fence is the `references` map only, with columns/firewall/guards/crud already elided to `// ...`. This page's whole-file examples are the `feature()` and `q.table()`+`defineTable()` forms at the top, which the gate does compile. */}
746
+ {/* doc-compile: skip — cross-table column excerpt; the complete table forms appear at the top of this page. */}
722
747
  ```typescript
723
- export default defineTable(applications, {
724
- references: {
725
- candidateId: "candidate",
726
- jobId: "job",
727
- referredById: "candidate",
728
- },
729
- // ... firewall, guards, crud
748
+ const applications = q.table("applications", {
749
+ id: q.id(),
750
+ candidateId: q.text().required().references(() => candidates.id),
751
+ jobId: q.text().required().references(() => jobs.id),
730
752
  });
731
753
  ```
732
754
 
733
- Each key is a column name ending in `Id`, and the value is the camelCase table name it references. These mappings flow into the schema registry as `fkTarget` on each column, enabling the CMS to render typeahead/lookup inputs that search the correct table.
755
+ Do this even when a column name appears obvious, such as `sessionId` beside a
756
+ `sessions` table. A matching `*Id` name is a useful compiler suggestion when a
757
+ relationship might be missing; it is not enough evidence to silently invent
758
+ one. CMS-ready schemas state the relationship explicitly.
734
759
 
735
- Convention-based matching (strip `Id` suffix, look for a matching table) still works for simple cases like `projectId` → `project`. Use `references` only for columns where the convention doesn't match.
760
+ The legacy resource-level `references: { vendorId: "contact" }` map can override
761
+ schema-registry target metadata for an alias, but it does not create a database
762
+ foreign key. Prefer `.references(() => contacts.id)` whenever the target is a
763
+ feature table in the same database. Do **not** add `.references()` for Better
764
+ Auth ids (`userId`, `organizationId`, `memberId`, or auth `sessionId`): those
765
+ rows live in `AUTH_DB`, outside the feature database.
736
766
 
737
767
  ## Input Hints
738
768
 
739
- Control how the CMS renders form inputs for specific columns. By default the CMS infers input types from the column's SQL type — `inputHints` lets you override that:
769
+ Control how the CMS renders form inputs for specific columns. By default the CMS infers the control from the column itself — `q.timestamp()` → date-time picker, `q.bool()` → checkbox, `q.int()` → number, `q.enum()` → select, `q.url()` → URL input, `q.json()` → textarea, and name patterns for plain text (`*Url`, `*Notes`, `email`). The registry carries the q column `kind`, so this works on SQLite too, where every timestamp is `text` at the SQL layer. `inputHints` overrides the inference:
740
770
 
741
771
  {/* doc-compile: skip — one-key excerpt: the fence is the `inputHints` map only, with firewall/guards/crud already elided to `// ...`. This page's whole-file examples are the `feature()` and `q.table()`+`defineTable()` forms at the top, which the gate does compile. */}
742
772
  ```typescript
@@ -770,7 +800,7 @@ export default defineTable(jobs, {
770
800
  | `time` | Time picker |
771
801
  | `currency` | Currency input with formatting |
772
802
 
773
- Input hints are emitted in the schema registry as `inputHints` on the table metadata, and the CMS reads them to render the appropriate form controls.
803
+ Input hints are emitted in the schema registry as `inputHints` on the table metadata, and the CMS reads them to render the appropriate form controls. The bundled CMS form renders `richtext`, `select`, `checkbox`, `textarea`, `date`, `datetime`, `currency`, `number`, `email`, `url`, and `text` today; any other hint falls back to the inferred control.
774
804
 
775
805
  ### Rich Text Example
776
806
 
@@ -124,7 +124,7 @@ the stored bytes are, the pillars govern who reaches them.
124
124
  ## Where this is enforced
125
125
 
126
126
  Everything on this page is a **compile-time** decision. The pillars are declared in your
127
- feature files, checked for coherence when you run `quickback compile`, and emitted as
127
+ feature files, checked for coherence when you run `quickback build`, and emitted as
128
128
  generated middleware and query builders. There is no runtime policy engine to
129
129
  misconfigure and no rules to keep in sync by hand — if a policy is incoherent, the
130
130
  compile fails.
@@ -31,6 +31,13 @@ export const episodes = q.table('episodes', {
31
31
  });
32
32
 
33
33
  export default defineTable(episodes, {
34
+ guards: {
35
+ createable: ["title"],
36
+ updatable: ["title"],
37
+ protected: {
38
+ isPublished: ["publish", "revertToDraft"],
39
+ },
40
+ },
34
41
  transitions: {
35
42
  publish: { field: "isPublished", from: false, to: true, access: { roles: ["admin+"] } },
36
43
  revertToDraft: { field: "isPublished", from: true, to: false, access: { roles: ["admin+"] } },
@@ -38,6 +45,23 @@ export default defineTable(episodes, {
38
45
  });
39
46
  ```
40
47
 
48
+ `isPublished` has a schema default and is absent from both `createable` and
49
+ `updatable`. The transition names are its only writers. A workflow-owned field
50
+ cannot also be directly updatable; listing it in both `updatable` and
51
+ `protected` is a compile error and would undermine the state machine.
52
+
53
+ > **Table-level transitions need a fixed `to`**
54
+ >
55
+ > Every `transitions.<name>` entry must name a literal target: `to` with either
56
+ > `from` (scalar or array) or a `fromTo` map. A target that varies per call
57
+ > (`via: "nextStatus"` — read from the action's input) is **not** accepted at
58
+ > table level; the compile fails with
59
+ > `[quickback:transitions] <feature>/<table> transitions.<name>: table-level fromTo transitions need a fixed to (via-style input targets require a hand-written action)`.
60
+ > Write that one as `actions/<name>.ts` with `transition: { field, via, fromTo }`
61
+ > (see [Transition (state-machine policy)](#transition-state-machine-policy)) —
62
+ > or split it into one fixed-target entry per step (`toScreening`, `toInterview`, …).
63
+
64
+
41
65
  The generated actions mount exactly where an authored file would
42
66
  (`POST /episodes/:id/publish`, operationId `episodesPublish`, same MCP tool
43
67
  name), ride the same OpenAPI/security-contract pipeline, and delete cleanly:
@@ -164,8 +188,7 @@ current state. Without it, an `advance` action whose input enum allows
164
188
  ```typescript
165
189
  // features/applications/actions/advance.ts
166
190
  import { z } from "zod";
167
- import { defineAction } from "../.quickback/define-action";
168
- import { applications } from "../applications";
191
+ import { defineAction, applications } from "../.quickback/define-action";
169
192
 
170
193
  export default defineAction({
171
194
  description: "Move an application forward in the pipeline.",
@@ -187,8 +210,7 @@ export default defineAction({
187
210
  ```typescript
188
211
  // features/applications/actions/hire.ts
189
212
  import { z } from "zod";
190
- import { defineAction } from "../.quickback/define-action";
191
- import { applications } from "../applications";
213
+ import { defineAction, applications } from "../.quickback/define-action";
192
214
 
193
215
  export default defineAction({
194
216
  description: "Finalize an offer.",
@@ -243,3 +265,12 @@ The same 409 code is used when an `access.record` predicate (without
243
265
  `transition`) fails — for example `record: { status: { equals: "pending" } }`
244
266
  called against a paid invoice now returns 409 `ACCESS_ACTION_NOT_ALLOWED_FOR_STATE`,
245
267
  not a misleading 403.
268
+
269
+ ## In the CMS
270
+
271
+ The schema registry carries each action's `field`, `fromTo`, `to`/`via`,
272
+ literal `guard`, and `idempotent`. The CMS evaluates them against the row and
273
+ **hides** any transition the record's current state cannot take — no
274
+ `fromTo[current]` entry admits the target, the row is already in the `to`
275
+ state, or a literal guard fails. Nothing extra to declare; see
276
+ [CMS Actions → Transition State](/ui/admin/actions#transition-state).
@@ -106,6 +106,15 @@ Live Views, with full application context:
106
106
  handler: ({ table, op, values /* before */, row /* after */, ctx, db, env }) => { ... }
107
107
  ```
108
108
 
109
+ The `db` a handler receives is the **features** database. There is no `c` and
110
+ no `authDb`. Prefer `ctx.userId`, `ctx.activeOrgId`, `ctx.roles`, and
111
+ `ctx.userRole` for the acting user.
112
+
113
+ Do **not** import `../../auth/schema` from the table file to reach AUTH_DB —
114
+ that import used to survive compile and then fail package-mode wrangler with
115
+ `Could not resolve`. Checking that another user is an org member belongs in
116
+ an [action](/define/actions/scoped-db#reaching-better-auth-tables-authdb).
117
+
109
118
  - **`before*` hooks are synchronous.** Return a partial object to merge
110
119
  into the write payload, or throw to reject — the write never executes and
111
120
  the request gets a structured `TRIGGER_REJECTED` (422) error. Audit
@@ -116,9 +125,11 @@ handler: ({ table, op, values /* before */, row /* after */, ctx, db, env }) =>
116
125
  `TRIGGER_AFTER_FAILED` (500) with `details.committed: true` — the row was
117
126
  already persisted (no transactions on D1), so clients must not blind-retry.
118
127
  - Handlers must be **inline arrow/function expressions**. Imports they
119
- reference are hoisted into the generated registry, and each table's
120
- drizzle object is auto-imported under its authored name — so this works
121
- as written:
128
+ reference are hoisted into the generated registry (`src/lib/trigger-hooks.ts`)
129
+ with relative paths rewritten from the table file — including dynamic
130
+ `import("…")` inside the handler. Write them as they resolve next to the
131
+ table. Each table's drizzle object is auto-imported under its authored
132
+ name — so this works as written:
122
133
 
123
134
  ```typescript
124
135
  import { eq } from 'drizzle-orm';
@@ -99,6 +99,39 @@ returns `VIEW_REQUIRED` once views are declared.
99
99
 
100
100
  Views support the same query parameters as the list endpoint:
101
101
 
102
+ Declare a view's query surface explicitly with `query.filterable`,
103
+ `query.searchable`, and `query.sortable`. Those allowlists are authoritative
104
+ for that view: a field listed there does **not** also need `.filterable()` or
105
+ `.searchable()` on its column definition. Column-level modifiers configure
106
+ ordinary CRUD reads and provide helpful defaults when the compiler generates a
107
+ surface; an explicitly configured view does not require the declaration twice.
108
+ On the ordinary CRUD collection endpoint, the column modifiers remain the
109
+ declaration: only columns marked `.filterable(...)` accept filters, and
110
+ `.searchable()` determines the default cross-column search set. Pagination is
111
+ independent of these allowlists and remains available on both CRUD reads and
112
+ named views.
113
+
114
+ ```typescript
115
+ columns: {
116
+ candidateId: q.text().required(), // no column-level query modifier needed
117
+ stage: q.enum(['applied', 'interview', 'offer']).required(),
118
+ },
119
+ read: {
120
+ views: {
121
+ pipeline: {
122
+ fields: ['id', 'candidateId', 'stage'],
123
+ query: {
124
+ filterable: ['stage'],
125
+ searchable: ['candidateId'],
126
+ },
127
+ },
128
+ },
129
+ }
130
+ ```
131
+
132
+ Unknown columns, encrypted columns, and masked-column query restrictions are
133
+ still validated normally.
134
+
102
135
  ### Pagination
103
136
 
104
137
  | Parameter | Description | Default | Max |
@@ -9,7 +9,7 @@ mkdir my-app && cd my-app
9
9
  npx @quickback-dev/cli start
10
10
  ```
11
11
 
12
- `start` is interactive — it asks for a template, scaffolds the project on disk, and only prompts for an account just before compiling. If you cancel at the login prompt the scaffold stays put; you can finish later with `quickback compile`.
12
+ `start` is interactive — it asks for a template, scaffolds the project on disk, and only prompts for an account just before compiling. If you cancel at the login prompt the scaffold stays put; you can finish later with `quickback build`.
13
13
 
14
14
  Prefer scripting?
15
15
 
@@ -17,7 +17,7 @@ Prefer scripting?
17
17
  npm install -g @quickback-dev/cli
18
18
  quickback create cloudflare my-app
19
19
  cd my-app
20
- quickback compile
20
+ quickback build
21
21
  ```
22
22
 
23
23
  ## How it works
@@ -4,12 +4,12 @@ API keys provide programmatic access for CI/CD pipelines, scripts, and server-to
4
4
 
5
5
  ## Creating API Keys
6
6
 
7
- Create API keys from your [Quickback account](https://account.quickback.dev/profile). Each key is scoped to your organization.
7
+ Create API keys from [Account UI](/ui/account/features/api-keys) (`/api-keys`, linked from profile). Each key is owned by you and scoped to an organization.
8
8
 
9
9
  ## Usage
10
10
 
11
11
  ```bash
12
- QUICKBACK_API_KEY=your_api_key quickback compile
12
+ QUICKBACK_API_KEY=your_api_key quickback build
13
13
  ```
14
14
 
15
15
  API keys are validated by the same `/internal/validate` endpoint as session tokens. See [Authentication](/tooling/cloud-compiler/authentication) for details.