@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
@@ -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.
@@ -33,6 +33,43 @@ app.get('/api/me', async (c) => {
33
33
 
34
34
  `ctx` also carries `authMethod` (`'session' | 'jwt' | 'api-key' | 'oauth' | 'principal'`), `userRole` (the global user-table role), `activeTeamId`, and `scope`. In action and CRUD handlers this same object arrives as the `ctx` argument — you rarely call `c.get('ctx')` directly.
35
35
 
36
+ ## Application Profiles
37
+
38
+ Treat the Better Auth user row as login identity, not automatically as the
39
+ application's complete client or customer model. Before defining feature
40
+ tables, decide whether signed-in people need domain data beyond the identity
41
+ already available on `ctx.user`—for example a customer number, onboarding
42
+ state, preferences, billing metadata, clinical details, or relationships that
43
+ other feature records must reference.
44
+
45
+ If the auth identity fields are enough, use `ctx.userId` / `ctx.user` directly
46
+ and do not create an empty duplicate profile. If the product needs domain data
47
+ or relationships, create a first-class feature resource such as `customers`,
48
+ `clientProfiles`, or `patientProfiles`. Give it its own feature-table primary
49
+ key and normal access, firewall, masking, and guard rules.
50
+
51
+ Use `userId: q.text().required().index()` for the basic link to the Better Auth
52
+ identity. Quickback emits the physical `user_id` column. Treat it as a plain
53
+ text **logical foreign key**: a self-create/bootstrap action derives it from
54
+ `ctx.userId`, and generic clients must not supply or update it through
55
+ `guards.createable` / `guards.updatable`. If the model permits one profile per
56
+ identity globally, add `unique: [{ columns: ["userId"] }]`; if it permits one
57
+ per organization, use `unique: [{ columns: ["organizationId", "userId"] }]`
58
+ instead. Declare explicitly when `userId` is also the row-ownership firewall
59
+ column rather than relying on its name.
60
+
61
+ Do not write `.references(() => user.id)` or `.references(() => users.id)` on
62
+ that link. With the default split-D1 provider, Better Auth lives in `AUTH_DB`
63
+ and feature resources live in `DB`, so SQLite cannot enforce a cross-database
64
+ foreign key. A provider may place both stores in one physical database, but the
65
+ auth schema remains compiler-owned rather than an authored feature-table
66
+ import; keeping this link logical makes the definition portable. Other feature
67
+ tables should use a real feature-database FK such as
68
+ `profileId: q.text().required().references(() => profiles.id)` so the CMS can
69
+ resolve the profile label. See [Schema → References](/define/schema#references),
70
+ [Firewall → ownerId vs userId](/define/firewall#ownerid-vs-userid), and
71
+ [Start patterns → Referencing users](/start/patterns).
72
+
36
73
  ## Organization Context
37
74
 
38
75
  When organizations are enabled, the active organization is on the auth context as `activeOrgId`:
@@ -22,7 +22,7 @@ Quickback generates separate D1 databases for different concerns:
22
22
 
23
23
  | Database | Binding | Purpose |
24
24
  |----------|---------|---------|
25
- | `AUTH_DB` | `AUTH_DB` | Better Auth tables (user, session, account) |
25
+ | `AUTH_DB` | `AUTH_DB` | Better Auth tables (`user`, `session`, `account`, `organization`, `member`) |
26
26
  | `DB` | `DB` | Your application data |
27
27
  | `FILES_DB` | `FILES_DB` | File metadata for R2 uploads |
28
28
  | `WEBHOOKS_DB` | `WEBHOOKS_DB` | Webhook delivery tracking |
@@ -32,6 +32,18 @@ This separation provides:
32
32
  - **Isolation** - Auth schema changes don't touch your data
33
33
  - **Clarity** - Clear ownership of each database
34
34
 
35
+ SQLite foreign keys cannot cross those databases. Feature columns must never
36
+ `.references()` Better Auth tables (`user` / `users` / `organization` /
37
+ `member`). Store a Better Auth id as plain text (`userId: q.text().required()`).
38
+ A `.references(() => users.id)` on a feature table makes deploy fail with
39
+ `Critical command failed: Generate features database migrations`. See
40
+ [Schema → References](/define/schema).
41
+
42
+ The scoped feature `db` never includes those tables — query them from an
43
+ action with `c.get("authDb")`, not from a trigger. On D1 the membership table
44
+ is `member`, not `organization_membership`. See
45
+ [Scoped DB](/define/actions/scoped-db#reaching-better-auth-tables-authdb).
46
+
35
47
  ## Drizzle ORM Integration
36
48
 
37
49
  Quickback uses [Drizzle ORM](https://orm.drizzle.team/) for type-safe database access:
@@ -81,7 +93,7 @@ Quickback generates migrations automatically at compile time based on your schem
81
93
 
82
94
  ```bash
83
95
  # Compile your project (generates migrations)
84
- quickback compile
96
+ quickback build
85
97
 
86
98
  # Apply migrations locally
87
99
  wrangler d1 migrations apply DB --local
@@ -92,7 +104,7 @@ wrangler d1 migrations apply DB --remote
92
104
 
93
105
  Migration files are generated in `quickback/drizzle/` and version-controlled with your code. You never need to manually generate migrations—just define your schema and compile.
94
106
 
95
- Generation runs locally: `quickback compile` invokes your project's own
107
+ Generation runs locally: `quickback build` invokes your project's own
96
108
  `drizzle-kit` against migration state that never leaves your machine. Note that
97
109
  generating a migration is not the same as applying one — `_journal.json` records
98
110
  which migration files *exist*, while D1's own `d1_migrations` table records which
@@ -359,11 +359,11 @@ connection string from the Hyperdrive configuration identified by `id`.
359
359
  ## Better Auth schema generation
360
360
 
361
361
  `src/auth/schema.ts` is a compiler-owned artifact derived with the Better Auth
362
- CLI during `quickback compile`. The generated `build` script is deliberately
362
+ CLI during `quickback build`. The generated `build` script is deliberately
363
363
  read-only with respect to generated source:
364
364
 
365
365
  ```bash
366
- quickback compile # regenerates src/auth/schema.ts and the project output
366
+ quickback build # regenerates src/auth/schema.ts and the project output
367
367
  npm run build # runs tsc only; does not rewrite generated files
368
368
  ```
369
369
 
@@ -382,7 +382,7 @@ generated `package.json` — that's the Better Auth CLI package (the
382
382
  The qualifier script adjusts the CLI output for Postgres schema placement.
383
383
  `auth:schema` produces the intermediate Better Auth output and may remove
384
384
  Quickback's generated-file envelope. Do not commit that intermediate file;
385
- rerun `quickback compile` to restore the canonical project bytes. Don't
385
+ rerun `quickback build` to restore the canonical project bytes. Don't
386
386
  hand-edit `src/auth/schema.ts`.
387
387
 
388
388
  Recompiling also replaces previously generated `package.json` lifecycle
@@ -397,7 +397,7 @@ Drizzle journal covers auth tables, feature tables, indexes, FK/cascade
397
397
  semantics, and the RLS layer:
398
398
 
399
399
  ```bash
400
- quickback compile # generates migrations under quickback/drizzle/
400
+ quickback build # generates migrations under quickback/drizzle/
401
401
  npm run db:migrate # applies schema AND the RLS layer, in order
402
402
  ```
403
403
 
@@ -59,7 +59,7 @@ Two `../` — up from `services/email/` to `quickback/`, then down into `feature
59
59
  ## What the compiler emits
60
60
 
61
61
  1. **`deliverInboundEmail(message, env)`** in `src/lib/email.ts` — the shared dispatcher.
62
- 2. **`email(cfMessage, env, ctx)`** on the Worker default export — Cloudflare adapter. Regenerated on every `quickback compile`.
62
+ 2. **`email(cfMessage, env, ctx)`** on the Worker default export — Cloudflare adapter. Regenerated on every `quickback build`.
63
63
  3. **No wrangler inbound binding.** Cloudflare: configure Email Routing in the dashboard. SES: Receipt rule + S3 + SNS; call `deliverInboundEmail` with the fetched `.eml`.
64
64
  4. The existing outbound `[[send_email]]` binding (Cloudflare) / SES plugin (aws-ses) is unchanged.
65
65
 
@@ -290,7 +290,7 @@ After defining queue handlers:
290
290
 
291
291
  2. **Compile:**
292
292
  ```bash
293
- quickback compile
293
+ quickback build
294
294
  ```
295
295
 
296
296
  3. **Deploy:**
@@ -148,7 +148,7 @@ wrangler queues create my-app-processing-queue
148
148
  ### 2. Compile and Deploy
149
149
 
150
150
  ```bash
151
- quickback compile
151
+ quickback build
152
152
  wrangler deploy
153
153
  ```
154
154
 
@@ -278,10 +278,12 @@ as a normal `postgres_changes` frame on the table's room.
278
278
  "data": { "eventId": "…", "documentId": "…" } }
279
279
  ```
280
280
 
281
- The bundled CMS unwraps envelopes automatically. The full channel/message
282
- catalog ships as `GET /asyncapi.json` (AsyncAPI 3.0), served under the same
283
- auth gating as `/openapi.json`. Any project with realtime or webhooks serves
284
- it, and it documents the CloudEvents envelopes above.
281
+ The bundled CMS and Account SPAs consume these envelopes as-is:
282
+ match on `qbframe`, read the row from `data`, and (for live views) the
283
+ monotonic seq from `qbseq`. The full channel/message catalog ships as
284
+ `GET /asyncapi.json` (AsyncAPI 3.0), served under the same auth gating as
285
+ `/openapi.json`. Any project with realtime or webhooks serves it, and it
286
+ documents the CloudEvents envelopes above.
285
287
 
286
288
  ## Cloudflare Only
287
289
 
@@ -41,7 +41,7 @@ Two `../` — up from `services/schedules/` to `quickback/`, then down into `fea
41
41
 
42
42
  1. **`scheduled(event, env, ctx)`** in the Worker's default export, dispatching to every schedule whose cron matches `event.cron`. Multiple schedules can share a cron; a failure in one is isolated from the others.
43
43
  2. **`[triggers] crons = [...]`** in `wrangler.toml` — one deduped, sorted list across all schedules.
44
- 3. **`src/lib/schedules.ts`** — the generated runner. Regenerated on every `quickback compile`, so there's nothing to hand-maintain.
44
+ 3. **`src/lib/schedules.ts`** — the generated runner. Regenerated on every `quickback build`, so there's nothing to hand-maintain.
45
45
 
46
46
  ## Execute context
47
47
 
@@ -7,11 +7,11 @@ The Quickback Stack uses Cloudflare's storage primitives for different use cases
7
7
  | Service | Use Case | Pages |
8
8
  |---------|----------|-------|
9
9
  | **KV** | Sessions, caching, rate limiting | [Setup](/platform/storage/kv) · [Usage](/platform/storage/using-kv) |
10
- | **R2** | File uploads, avatars, attachments | [Setup](/platform/storage/r2) · [Usage](/platform/storage/using-r2) |
10
+ | **R2** | Hosted file bytes (listing photos, avatars, attachments) | [Setup](/platform/storage/r2) · [Usage](/platform/storage/using-r2) |
11
11
 
12
12
  ## Getting Started
13
13
 
14
14
  - **[KV Setup](/platform/storage/kv)** — Namespace and bindings configuration
15
15
  - **[Using KV](/platform/storage/using-kv)** — Sessions, caching, rate limiting
16
- - **[R2 Setup](/platform/storage/r2)** — Bucket, bindings, CORS configuration
17
- - **[Using R2](/platform/storage/using-r2)** — Uploads, downloads, role-based access
16
+ - **[R2 Setup](/platform/storage/r2)** — Public vs signed reads, buckets, bindings
17
+ - **[Using R2](/platform/storage/using-r2)** — URL fields, public buckets, signed uploads