@quickback-dev/cli 0.66.1 → 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 (199) 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/skill/SKILL.md +6 -6
  55. package/dist/skill/docs/api/crud.md +7 -0
  56. package/dist/skill/docs/api/index.md +1 -1
  57. package/dist/skill/docs/api/openapi.md +1 -1
  58. package/dist/skill/docs/changelog/index.md +19 -1
  59. package/dist/skill/docs/configure/agents.md +1 -1
  60. package/dist/skill/docs/configure/index.md +8 -3
  61. package/dist/skill/docs/configure/providers.md +1 -0
  62. package/dist/skill/docs/configure/variables.md +3 -3
  63. package/dist/skill/docs/define/access.md +7 -0
  64. package/dist/skill/docs/define/actions/defining.md +35 -7
  65. package/dist/skill/docs/define/actions/record-and-standalone.md +7 -4
  66. package/dist/skill/docs/define/actions/scoped-db.md +46 -16
  67. package/dist/skill/docs/define/areas.md +1 -1
  68. package/dist/skill/docs/define/diagnostics.md +1 -0
  69. package/dist/skill/docs/define/encryption.md +1 -1
  70. package/dist/skill/docs/define/feature.md +14 -7
  71. package/dist/skill/docs/define/guards.md +27 -3
  72. package/dist/skill/docs/define/schema.md +24 -14
  73. package/dist/skill/docs/define/security.md +1 -1
  74. package/dist/skill/docs/define/transitions.md +35 -4
  75. package/dist/skill/docs/define/views.md +33 -0
  76. package/dist/skill/docs/index.md +2 -2
  77. package/dist/skill/docs/platform/auth/api-keys.md +1 -1
  78. package/dist/skill/docs/platform/auth/using-auth.md +37 -0
  79. package/dist/skill/docs/platform/database/d1.md +2 -2
  80. package/dist/skill/docs/platform/database/neon.md +4 -4
  81. package/dist/skill/docs/platform/email/index.md +1 -1
  82. package/dist/skill/docs/platform/queues/handlers.md +1 -1
  83. package/dist/skill/docs/platform/queues/using-queues.md +1 -1
  84. package/dist/skill/docs/platform/schedules/index.md +1 -1
  85. package/dist/skill/docs/platform/storage/index.md +3 -3
  86. package/dist/skill/docs/platform/storage/r2.md +87 -37
  87. package/dist/skill/docs/platform/storage/using-r2.md +99 -19
  88. package/dist/skill/docs/platform/webhooks/inbound.md +40 -0
  89. package/dist/skill/docs/start/deploy-browser.md +39 -44
  90. package/dist/skill/docs/start/deploy-owner-access.md +28 -19
  91. package/dist/skill/docs/start/deploy.md +2 -2
  92. package/dist/skill/docs/start/first-api.md +1 -1
  93. package/dist/skill/docs/start/hand-crafted.md +3 -3
  94. package/dist/skill/docs/start/index.md +3 -3
  95. package/dist/skill/docs/start/quickstart.md +3 -3
  96. package/dist/skill/docs/start/template-blog.md +2 -2
  97. package/dist/skill/docs/start/template-cloudflare.md +2 -2
  98. package/dist/skill/docs/start/template-empty.md +1 -1
  99. package/dist/skill/docs/start/templates.md +1 -1
  100. package/dist/skill/docs/tooling/claude-skill.md +1 -1
  101. package/dist/skill/docs/tooling/cli.md +20 -15
  102. package/dist/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
  103. package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +5 -3
  104. package/dist/skill/docs/tooling/cloud-compiler/index.md +1 -1
  105. package/dist/skill/docs/tooling/cloud-compiler/local-compiler.md +2 -2
  106. package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +47 -2
  107. package/dist/skill/docs/tooling/output.md +23 -2
  108. package/dist/skill/docs/tooling/troubleshooting.md +1 -1
  109. package/dist/skill/docs/ui/account/environment-variables.md +2 -2
  110. package/dist/skill/docs/ui/account/features/admin.md +1 -1
  111. package/dist/skill/docs/ui/account/features/avatars.md +24 -8
  112. package/dist/skill/docs/ui/account/features/index.md +9 -5
  113. package/dist/skill/docs/ui/account/features/organizations.md +3 -2
  114. package/dist/skill/docs/ui/account/index.md +3 -1
  115. package/dist/skill/docs/ui/account/with-quickback.md +1 -1
  116. package/dist/skill/docs/ui/admin/actions.md +97 -3
  117. package/dist/skill/docs/ui/admin/components.md +4 -6
  118. package/dist/skill/docs/ui/admin/connecting.md +15 -3
  119. package/dist/skill/docs/ui/admin/index.md +71 -6
  120. package/dist/skill/docs/ui/admin/inline-editing.md +38 -4
  121. package/dist/skill/docs/ui/admin/record-layouts.md +22 -21
  122. package/dist/skill/docs/ui/admin/schema-format.md +39 -2
  123. package/dist/skill/docs/ui/admin/schema-registry.md +107 -7
  124. package/dist/skill/docs/ui/admin/security.md +19 -4
  125. package/dist/skill/docs/ui/admin/table-views.md +59 -12
  126. package/package.json +1 -1
  127. package/src/cursor/quickback.mdc +1 -1
  128. package/src/skill/SKILL.md +6 -6
  129. package/src/skill/docs/api/crud.md +7 -0
  130. package/src/skill/docs/api/index.md +1 -1
  131. package/src/skill/docs/api/openapi.md +1 -1
  132. package/src/skill/docs/changelog/index.md +19 -1
  133. package/src/skill/docs/configure/agents.md +1 -1
  134. package/src/skill/docs/configure/index.md +8 -3
  135. package/src/skill/docs/configure/providers.md +1 -0
  136. package/src/skill/docs/configure/variables.md +3 -3
  137. package/src/skill/docs/define/access.md +7 -0
  138. package/src/skill/docs/define/actions/defining.md +35 -7
  139. package/src/skill/docs/define/actions/record-and-standalone.md +7 -4
  140. package/src/skill/docs/define/actions/scoped-db.md +46 -16
  141. package/src/skill/docs/define/areas.md +1 -1
  142. package/src/skill/docs/define/diagnostics.md +1 -0
  143. package/src/skill/docs/define/encryption.md +1 -1
  144. package/src/skill/docs/define/feature.md +14 -7
  145. package/src/skill/docs/define/guards.md +27 -3
  146. package/src/skill/docs/define/schema.md +24 -14
  147. package/src/skill/docs/define/security.md +1 -1
  148. package/src/skill/docs/define/transitions.md +35 -4
  149. package/src/skill/docs/define/views.md +33 -0
  150. package/src/skill/docs/index.md +2 -2
  151. package/src/skill/docs/platform/auth/api-keys.md +1 -1
  152. package/src/skill/docs/platform/auth/using-auth.md +37 -0
  153. package/src/skill/docs/platform/database/d1.md +2 -2
  154. package/src/skill/docs/platform/database/neon.md +4 -4
  155. package/src/skill/docs/platform/email/index.md +1 -1
  156. package/src/skill/docs/platform/queues/handlers.md +1 -1
  157. package/src/skill/docs/platform/queues/using-queues.md +1 -1
  158. package/src/skill/docs/platform/schedules/index.md +1 -1
  159. package/src/skill/docs/platform/storage/index.md +3 -3
  160. package/src/skill/docs/platform/storage/r2.md +87 -37
  161. package/src/skill/docs/platform/storage/using-r2.md +99 -19
  162. package/src/skill/docs/platform/webhooks/inbound.md +40 -0
  163. package/src/skill/docs/start/deploy-browser.md +39 -44
  164. package/src/skill/docs/start/deploy-owner-access.md +28 -19
  165. package/src/skill/docs/start/deploy.md +2 -2
  166. package/src/skill/docs/start/first-api.md +1 -1
  167. package/src/skill/docs/start/hand-crafted.md +3 -3
  168. package/src/skill/docs/start/index.md +3 -3
  169. package/src/skill/docs/start/quickstart.md +3 -3
  170. package/src/skill/docs/start/template-blog.md +2 -2
  171. package/src/skill/docs/start/template-cloudflare.md +2 -2
  172. package/src/skill/docs/start/template-empty.md +1 -1
  173. package/src/skill/docs/start/templates.md +1 -1
  174. package/src/skill/docs/tooling/claude-skill.md +1 -1
  175. package/src/skill/docs/tooling/cli.md +20 -15
  176. package/src/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
  177. package/src/skill/docs/tooling/cloud-compiler/endpoints.md +5 -3
  178. package/src/skill/docs/tooling/cloud-compiler/index.md +1 -1
  179. package/src/skill/docs/tooling/cloud-compiler/local-compiler.md +2 -2
  180. package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +47 -2
  181. package/src/skill/docs/tooling/output.md +23 -2
  182. package/src/skill/docs/tooling/troubleshooting.md +1 -1
  183. package/src/skill/docs/ui/account/environment-variables.md +2 -2
  184. package/src/skill/docs/ui/account/features/admin.md +1 -1
  185. package/src/skill/docs/ui/account/features/avatars.md +24 -8
  186. package/src/skill/docs/ui/account/features/index.md +9 -5
  187. package/src/skill/docs/ui/account/features/organizations.md +3 -2
  188. package/src/skill/docs/ui/account/index.md +3 -1
  189. package/src/skill/docs/ui/account/with-quickback.md +1 -1
  190. package/src/skill/docs/ui/admin/actions.md +97 -3
  191. package/src/skill/docs/ui/admin/components.md +4 -6
  192. package/src/skill/docs/ui/admin/connecting.md +15 -3
  193. package/src/skill/docs/ui/admin/index.md +71 -6
  194. package/src/skill/docs/ui/admin/inline-editing.md +38 -4
  195. package/src/skill/docs/ui/admin/record-layouts.md +22 -21
  196. package/src/skill/docs/ui/admin/schema-format.md +39 -2
  197. package/src/skill/docs/ui/admin/schema-registry.md +107 -7
  198. package/src/skill/docs/ui/admin/security.md +19 -4
  199. package/src/skill/docs/ui/admin/table-views.md +59 -12
@@ -35,14 +35,14 @@ bash dev.sh 3001
35
35
  Point the CLI to your local compiler:
36
36
 
37
37
  ```bash
38
- QUICKBACK_API_URL=http://localhost:3000 quickback compile
38
+ QUICKBACK_API_URL=http://localhost:3000 quickback build
39
39
  ```
40
40
 
41
41
  Or export it for the session:
42
42
 
43
43
  ```bash
44
44
  export QUICKBACK_API_URL=http://localhost:3000
45
- quickback compile
45
+ quickback build
46
46
  ```
47
47
 
48
48
  The supported launcher does not require `quickback login`. It opts the compiler
@@ -29,7 +29,7 @@ npx @quickback-dev/cli create cloudflare my-app
29
29
 
30
30
  1. Check your `quickback.config.ts` exists and is valid
31
31
  2. Ensure all tables in `quickback/features/` have valid exports
32
- 3. Run `quickback compile` with `--verbose` for detailed output
32
+ 3. Run `quickback build` with `--verbose` for detailed output
33
33
 
34
34
  ## Drizzle rename prompts in CI/headless compile
35
35
 
@@ -83,7 +83,52 @@ userId: q.text().required().references(() => users.id, { onDelete: 'cascade' })
83
83
  generating features migrations.
84
84
 
85
85
  A Start chat compile (`complete=false`) still succeeds — it never runs
86
- drizzle-kit. Deploy (`complete=true`) is the first time that command runs.
86
+ drizzle-kit. The complete compile (`complete=true` — Generated Backend, or
87
+ `quickback compile`) is the first time that command runs.
88
+
89
+ ## `complete compile: wrangler bundle failed`
90
+
91
+ The complete compile bundles the generated Worker with
92
+ `wrangler deploy --dry-run`. A typical cause is a named import the generated
93
+ `define-action` helper does not re-export:
94
+
95
+ ```
96
+ No matching export in "src/features/tables/.quickback/define-action.ts" for import "reservations"
97
+ ```
98
+
99
+ The helper re-exports every table in **that feature only**. If `reservations`
100
+ is another table inside `tables`, import it from the action's own
101
+ `../.quickback/define-action` helper. If it belongs to a separate
102
+ `reservations` feature, keep `defineAction` from the action's own feature and
103
+ import only the external table from
104
+ `../../reservations/.quickback/define-action` (or the generated
105
+ `../../reservations/reservations` table module). Import query operators as `q`
106
+ from project `../../../lib/q`; neither feature helper owns them. This is the
107
+ same rule for any waitlist/reservations-style cross-feature action: the local
108
+ helper supplies the bound action context, and each external feature supplies
109
+ its own tables.
110
+
111
+ Current compilers validate named imports from generated action helpers before
112
+ code generation. Start's definition-validation build (`complete=false`)
113
+ therefore rejects this source immediately with `Invalid generated
114
+ action-helper import(s)` and names the owning feature, available table exports,
115
+ and corrective import. If an older compiler or an already-generated project
116
+ reaches Wrangler first, apply the same fix above and rebuild Generated Backend
117
+ before Deploy.
118
+
119
+ The compile sandbox has no network and bundles against the compiler image's
120
+ own dependencies, so anything you declare in
121
+ [`build.dependencies`](/configure#custom-dependencies) is not installed there.
122
+ Rather than fail on `Could not resolve "yjs"`, the compiler **skips** the
123
+ bundle check for those projects and says so in the compile warnings:
124
+
125
+ ```
126
+ Skipped the Worker bundle check — build.dependencies not installed in the
127
+ compiler image: yjs, y-prosemirror
128
+ ```
129
+
130
+ The compile still succeeds and the generated output is unchanged; unresolved
131
+ imports and missing named exports surface at `wrangler deploy` instead.
87
132
 
88
133
  Store the Better Auth id as plain text:
89
134
 
@@ -36,6 +36,7 @@ src/
36
36
  │ ├── types.ts # Runtime type definitions
37
37
  │ ├── masks.ts # Field masking utilities
38
38
  │ ├── services.ts # Service layer
39
+ │ ├── q.ts # Generated Drizzle query-operator namespace for actions
39
40
  │ ├── audit-wrapper.ts # Stamps the managed audit columns on write
40
41
  │ └── security-audit.ts # Unsafe cross-tenant audit logger (when needed)
41
42
  └── middleware/
@@ -74,6 +75,13 @@ Not every per-feature file is always emitted:
74
75
  - `schema.ts`, `{feature}.ts`, and `{feature}.resource.ts` are skipped for tableless features.
75
76
  - A multi-table feature gets one alias file per table (`{feature}.ts`, `{other_table}.ts`) alongside the single `schema.ts`.
76
77
 
78
+ Each `.quickback/define-action.ts` helper is scoped to its feature: it exports
79
+ that feature's bound `defineAction` and tables, but no tables from sibling
80
+ features. A cross-feature action imports the external table from the sibling
81
+ feature's generated helper or table module. From a normal
82
+ `src/features/{feature}/actions/` file, import query operators with
83
+ `import { q } from "../../../lib/q"`.
84
+
77
85
  ## Spec Blobs Are Assets, Not Bundle
78
86
 
79
87
  `openapi.json`, `asyncapi.json` and `schema-registry.json` are **not** written
@@ -163,6 +171,19 @@ unrecoverable while a missed one is only untidy:
163
171
 
164
172
  Nothing under `src/` is ever listed: the wipe already covers it.
165
173
 
174
+ ## Root files you own
175
+
176
+ A recompile rewrites `src/` wholesale, but three root files are merged rather
177
+ than replaced:
178
+
179
+ - **`package.json`** — compiler-owned scripts and dependencies converge on every
180
+ compile; scripts and fields the compiler does not emit are kept. Because owned
181
+ scripts converge, a hand-deleted `db:migrate:auth:*` step comes back — declare
182
+ [`authMigrations: 'external'`](/configure/providers#cloudflare-d1) instead.
183
+ - **`.gitignore`** — a union: your entries stay, missing compiler entries are
184
+ appended.
185
+ - **`README.md`** — written once; an existing README is never touched.
186
+
166
187
  ## Generated Package Dependency Security
167
188
 
168
189
  For projects using Better Auth, the generated `package.json` keeps the stable
@@ -210,11 +231,11 @@ records the patched transitive version. Use `npm audit --omit=dev` when
210
231
  evaluating the production dependency tree; development-tool advisories are a
211
232
  separate review surface.
212
233
 
213
- For Better Auth projects, `quickback compile` owns auth-schema generation.
234
+ For Better Auth projects, `quickback build` owns auth-schema generation.
214
235
  The generated `build` script runs TypeScript only and never rewrites
215
236
  `src/auth/schema.ts`, so build and deployment preflight checks preserve a clean
216
237
  generated worktree. `auth:schema` remains an explicit diagnostic command; run
217
- `quickback compile` afterward to restore canonical generated bytes.
238
+ `quickback build` afterward to restore canonical generated bytes.
218
239
 
219
240
  On recompilation, Quickback replaces commands for script names it generates,
220
241
  including `build`, with the current compiler output. Scripts with other names
@@ -102,7 +102,7 @@ Quickback now adds a D1-specific safety pass around Drizzle-generated migrations
102
102
  2. **Drop-only cleanup migrations** are reordered child-first when foreign keys require it.
103
103
  3. **All D1 migration directories** generated by the compiler are replayed against SQLite during compile, so a D1-breaking migration fails before deploy.
104
104
 
105
- If `quickback compile` now fails with a D1 replay error, treat that as a real migration problem instead of a deploy-time surprise. The generated SQL needs manual intervention or a schema change that Drizzle can express more safely.
105
+ If `quickback build` now fails with a D1 replay error, treat that as a real migration problem instead of a deploy-time surprise. The generated SQL needs manual intervention or a schema change that Drizzle can express more safely.
106
106
 
107
107
  ## Runtime Issues
108
108
 
@@ -281,11 +281,11 @@ VITE_DISABLE_EMAIL_STATUS_CHECK=false
281
281
  The Account UI has no standalone deploy path — the compiler ships a generic prebuilt bundle (built once per compiler release) into your Worker. In a compiled project you normally set none of the variables on this page by hand:
282
282
 
283
283
  1. Declare the values in `quickback.config.ts` under `account` (name, branding, URLs, `auth` feature flags).
284
- 2. `quickback compile` stages the prebuilt Account assets and bakes the values into the generated worker.
284
+ 2. `quickback build` stages the prebuilt Account assets and bakes the values into the generated worker.
285
285
  3. The worker injects them into every served Account shell as `window.__QUICKBACK_RUNTIME`, which the SPA prefers over baked `VITE_*` values. This runtime blob is the only per-project configuration channel — no per-project Vite build runs.
286
286
 
287
287
  ```bash
288
- quickback compile
288
+ quickback build
289
289
  npx wrangler deploy
290
290
  ```
291
291
 
@@ -85,7 +85,7 @@ The admin domain serves the same Account SPA at root (`/`). The SPA's client-sid
85
85
 
86
86
  ## CMS Access Control
87
87
 
88
- When both CMS and Account UI are enabled, the admin panel's profile page shows a "Go to CMS" button. You can restrict this to admin users only:
88
+ When both CMS and Account UI are enabled, the Account profile shows a CMS action. It opens the sole organization directly or lets a multi-organization user choose one first. You can restrict this to the sysadmin tier only:
89
89
 
90
90
  ```typescript
91
91
  cms: { domain: "cms.example.com", access: "sysadmin" },
@@ -1,35 +1,51 @@
1
1
  # Avatars
2
2
 
3
- When file uploads are enabled, Account UI provides avatar upload functionality.
3
+ When file uploads are enabled, Account UI provides avatar and organization logo
4
+ upload. Both POST to `/storage/v1/object` and **only work with valid R2
5
+ credentials**.
4
6
 
5
7
  ## Enabling
6
8
 
7
- In `quickback.config.ts`:
9
+ Off by default. Start apps leave it off — a `workers.dev` deploy can create
10
+ the R2 bucket, but it cannot mint the API-token secrets presigning and the
11
+ storage routes need.
8
12
 
9
13
  ```ts
10
14
  account: {
11
15
  fileUploads: true,
12
16
  // ...
13
17
  }
18
+
19
+ providers: {
20
+ fileStorage: defineFileStorage("cloudflare-r2", { managed: true }),
21
+ }
14
22
  ```
15
23
 
16
- The compiler emits `VITE_ENABLE_FILE_UPLOADS=true` into the Account SPA's build env.
24
+ The compiler emits `VITE_ENABLE_FILE_UPLOADS=true` only when **both** are set.
25
+ `account.fileUploads: true` without managed R2 does not turn the UI on — the
26
+ dialogs would 404.
27
+
28
+ Set the Worker secrets `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`, and
29
+ `R2_SECRET_ACCESS_KEY`. See [R2 Setup](/platform/storage/r2).
17
30
 
18
31
  ## Upload Flow
19
32
 
20
- 1. User clicks their profile picture
33
+ 1. User clicks their profile picture (or **Upload Logo** on org settings)
21
34
  2. Image picker opens (supports JPG, PNG, WebP)
22
35
  3. Image is cropped to square
23
- 4. Uploaded to R2/S3 storage
24
- 5. Profile updated with new avatar URL
36
+ 4. Uploaded to R2 via `/storage/v1/object`
37
+ 5. Profile / organization updated with the new URL
25
38
 
26
39
  ## Requirements
27
40
 
28
41
  - `account.fileUploads: true`
29
- - R2 bucket or S3-compatible storage configured
30
- - Upload endpoints available in your API
42
+ - Managed R2 — `defineFileStorage("cloudflare-r2", { managed: true })`
43
+ - Valid R2 credentials on the Worker (`R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`,
44
+ `R2_SECRET_ACCESS_KEY`)
45
+ - Upload endpoints available (`/storage/v1/*`)
31
46
 
32
47
  ## Related
33
48
 
34
49
  - [R2 Storage](/platform/storage/r2) — File storage setup
35
50
  - [Environment Variables](/ui/account/environment-variables)
51
+ - [Admin UI](/ui/admin) — the CMS does not host these uploads
@@ -211,16 +211,20 @@ VITE_ENABLE_FILE_UPLOADS=false # default: false
211
211
 
212
212
  **When enabled:**
213
213
  - Avatar/profile picture upload
214
+ - Organization logo upload
214
215
  - Image cropping and editing
215
- - File upload to R2/S3
216
+ - File upload to R2
216
217
 
217
218
  **When disabled:**
218
- - No file upload functionality
219
- - Users can only use default avatars
219
+ - No file upload UI (default, including Start apps)
220
+ - Users can only use default avatars / initials
220
221
 
221
222
  **Requirements:**
222
- - R2 bucket or S3 configured
223
- - Upload endpoints in your API
223
+ - `account.fileUploads: true`
224
+ - Managed R2 (`defineFileStorage("cloudflare-r2", { managed: true })`)
225
+ - Valid R2 credentials: `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`
226
+
227
+ The compiler will not emit `VITE_ENABLE_FILE_UPLOADS=true` without managed R2 — otherwise the picker 404s. See [Avatars](/ui/account/features/avatars).
224
228
 
225
229
  ### Subscriptions
226
230
 
@@ -1,11 +1,12 @@
1
1
  # Organizations
2
2
 
3
- Account UI provides a complete organization management interface when `VITE_ENABLE_ORGANIZATIONS=true`. `/dashboard` is that surface: the organizations you belong to and pending invitations. **Manage Organizations** on `/profile` (and in the user menu) opens it. Personal account settings live on `/profile`. The profile **Go to…** picker opens the tenant app using `account.appUrl` and `account.tenantPattern` — see [Customization](/ui/account/customization#tenant-url-patterns). Teams are a separate opt-in (`VITE_ENABLE_ORG_TEAMS`), surfaced when the compiler detects `organization({ teams: { enabled: true } })` in the Better Auth config.
3
+ Account UI provides a complete organization management interface when `VITE_ENABLE_ORGANIZATIONS=true`. `/dashboard` is that surface: the organizations you belong to and pending invitations. **Manage Organizations** on `/profile` (and in the user menu) opens it. Personal account settings live on `/profile`. The profile **Go to…** picker opens the tenant app using `account.appUrl` and `account.tenantPattern` — see [Customization](/ui/account/customization#tenant-url-patterns). When CMS is enabled, the profile also offers an access-aware CMS action: one membership opens directly, several memberships produce a picker, and the selected organization is made active before navigation. A pinned project targets only its configured organization; it never labels another membership as the CMS destination. Teams are a separate opt-in (`VITE_ENABLE_ORG_TEAMS`), surfaced when the compiler detects `organization({ teams: { enabled: true } })` in the Better Auth config.
4
4
 
5
5
  ## Organization CRUD
6
6
 
7
7
  - Create new organizations, with `checkSlug` debounce on the slug field
8
- - Update name, **slug** (rename navigates to the new URL), **metadata** (JSON object), and logo
8
+ - Update name, **slug** (rename navigates to the new URL), and **metadata** (JSON object)
9
+ - **Logo upload** only when `account.fileUploads: true` **and** managed R2 is configured with valid credentials (`R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`). Start apps leave this off. See [Avatars](/ui/account/features/avatars).
9
10
  - Delete organizations — gated on the `organization:delete` permission (default: owner)
10
11
 
11
12
  ## Member Management
@@ -12,6 +12,8 @@ Login, signup, profile editing, password management, device sessions, email chan
12
12
 
13
13
  When organizations are enabled, `/profile` has **Manage Organizations** (the `/dashboard` org list and invites) and a **Go to…** control that opens the tenant app. The URL is `account.appUrl` plus `account.tenantPattern` with the org slug substituted (the same `getTenantUrl` used on the org dashboard). One org is a single button; several orgs is a picker. The control is hidden when those config values cannot produce a URL.
14
14
 
15
+ When the project also enables the CMS, the profile has a separate CMS action. One membership opens that organization directly; several memberships produce an organization picker. Account UI makes the selected organization active before navigating, so the CMS cannot inherit a different active organization from an earlier session. The action follows `cms.access`: membership is required in `"member"` mode, while only `user.role === "sysadmin"` sees it in `"sysadmin"` mode. A zero-membership sysadmin opens the tenant picker only when `cms.sysadmin: true` explicitly enables cross-tenant scope. When `features.pinnedOrganizationId` is set, the profile targets only that fixed organization and never offers the caller's other memberships.
16
+
15
17
  Served on its own domain (e.g., `auth.example.com`) or at `/account/` when embedded alongside the CMS.
16
18
 
17
19
  ### Organization Management (multi-tenant)
@@ -46,7 +48,7 @@ export default {
46
48
  ```
47
49
 
48
50
  ```bash
49
- quickback compile
51
+ quickback build
50
52
  npx wrangler deploy
51
53
  ```
52
54
 
@@ -28,7 +28,7 @@ export default {
28
28
  Then compile and deploy:
29
29
 
30
30
  ```bash
31
- quickback compile
31
+ quickback build
32
32
  npx wrangler deploy
33
33
  ```
34
34
 
@@ -1,6 +1,29 @@
1
1
  # Actions
2
2
 
3
- Actions are custom operations defined in your feature files (e.g., `approve`, `void`, `post`, `applyPayment`). The CMS renders them as clickable buttons with auto-generated input forms — no UI code required.
3
+ Actions are custom operations defined in your feature files (e.g., `approve`, `void`, `post`, `applyPayment`). The CMS renders eligible declared or generated actions as clickable buttons with auto-generated input forms — no UI code required. It never invents an action from `cms` metadata alone.
4
+
5
+ ## When an Action Control Exists
6
+
7
+ An action must first exist in the generated schema registry: author it with
8
+ `defineAction`, or declare a table transition so the compiler generates it.
9
+ The CMS then applies the action's access rules for the current membership role,
10
+ omits `cms.hidden` actions, and evaluates record/state conditions. A role that
11
+ is not admitted never sees the control. On a record page, an admitted action
12
+ whose `access.record` condition fails is shown disabled with the reason; an
13
+ action whose `transition` cannot fire from the record's current state (no
14
+ `fromTo` entry admits the target, already in the target state, or a literal
15
+ `guard` fails) is **hidden** — the route would answer `409
16
+ ACCESS_ACTION_NOT_ALLOWED_FOR_STATE`, so the control is never offered.
17
+
18
+ The optional `cms` block changes presentation and placement. It cannot create
19
+ the action, add CRUD, or widen `access`.
20
+
21
+ For a transition-managed `status`, give the column an initial schema default,
22
+ omit it from `guards.createable` and `guards.updatable`, and declare it only in
23
+ `guards.protected` with the allowed transition/action names. The CMS will offer
24
+ those eligible lifecycle controls instead of a direct status editor. A
25
+ protected field cannot also be `createable` or `updatable`: the schema default
26
+ sets the initial status, and only the named transitions/actions may write it.
4
27
 
5
28
  ## Where Actions Appear
6
29
 
@@ -10,6 +33,12 @@ Actions show up in two places:
10
33
 
11
34
  In Table mode, the three-dot menu on each row includes a section for custom actions. Actions are separated from standard operations (view, edit, delete) by a divider.
12
35
 
36
+ A record-bound action has no `path:` and needs an existing record ID. It cannot
37
+ appear as a table-level control, and an empty table has no row menu in which to
38
+ show it. If the operation creates the first row—booking a reservation, joining
39
+ a waitlist, importing records—author it as a standalone action and place it in
40
+ the table toolbar.
41
+
13
42
  ### Action Bar (Detail View)
14
43
 
15
44
  In the record detail view, an "Actions" card displays all available actions as buttons. Each button shows the action name, and hovering reveals the description as a tooltip.
@@ -32,13 +61,32 @@ The dialog generates the appropriate input control for each field:
32
61
 
33
62
  | Zod Type | Input Control | Notes |
34
63
  |----------|--------------|-------|
35
- | `string` | Text input | Free-text entry |
64
+ | `string` | Text input or FK typeahead | Free text unless the field resolves to an emitted `fkTarget` |
36
65
  | `number` | Number input | Step 0.01, supports decimals |
37
66
  | `boolean` | Checkbox | With label text |
38
67
  | `array<string>` | Text input | Comma-separated values, split on save |
39
68
 
40
69
  Required fields are marked with a red asterisk. Default values from the schema are pre-filled.
41
70
 
71
+ Field names are humanized for their labels, so `sessionId` appears as
72
+ **Session** rather than exposing the storage-oriented suffix. When that input
73
+ name corresponds to a parent-table column with an emitted `fkTarget`, the
74
+ dialog resolves the lookup through that column metadata, then renders a
75
+ selector for the FK target table and shows its `displayColumn` labels. Declare
76
+ the feature-table relationship in the schema with
77
+ `.references(() => sessions.id)` so plural or otherwise non-conventional target
78
+ names resolve reliably. Without `fkTarget`, the action input remains a plain
79
+ text field.
80
+
81
+ If the target has named views, the selector uses only a role-accessible authored
82
+ `read.defaultView` and calls its named-view endpoint. It never falls back to a
83
+ bare list or silently chooses another projection. The default view must include
84
+ the target primary key and `displayColumn`; otherwise the dialog disables the
85
+ lookup with an actionable explanation. Put the `displayColumn` in the view's
86
+ effective `query.searchable` allowlist for typeahead search. If that allowlist
87
+ is empty, the dialog instead shows the first 50 options in a non-searching
88
+ chooser and sends no `?search` request.
89
+
42
90
  ### Example
43
91
 
44
92
  Given this action definition:
@@ -92,7 +140,26 @@ The action's `access.record` conditions are evaluated against the current record
92
140
  | `notEquals` | `{ status: { notEquals: 'void' } }` | Field must not equal value |
93
141
  | `in` | `{ status: { in: ['pending', 'draft'] } }` | Field must be one of values |
94
142
 
95
- All conditions must pass for the action to be visible. This means "approve" actions naturally disappear after a record is approved, and "void" actions only appear on voidable records.
143
+ All conditions must pass before the action can execute. In record menus and the
144
+ detail action bar, a role-admitted action whose record condition fails is
145
+ disabled with an explanation. This means an "approve" control cannot run after
146
+ the record is approved, and "void" cannot run on a non-voidable record.
147
+
148
+ ### Transition State
149
+
150
+ A record action with a `transition` policy ([Transitions](/define/transitions))
151
+ is hidden when the record's current state cannot take it. The registry carries
152
+ the policy's `field`, `fromTo`, `to`/`via`, literal `guard`, and `idempotent`;
153
+ the CMS evaluates them against the row exactly as the route does:
154
+
155
+ - `fromTo[current]` must list the target (`to`), or be non-empty when the
156
+ target comes from input (`via`).
157
+ - A record already in the `to` state never sees the control.
158
+ - Literal guards (`{ col: value }`, `{ null: true }`, `{ notNull: true }`) must
159
+ hold. A `custom` function guard is opaque to the CMS and does not hide.
160
+
161
+ So an application in `applied` with `fromTo: { interview: ["offer"] }` shows no
162
+ "To Offer" control; once it reaches `interview`, the control appears.
96
163
 
97
164
  ## CMS Metadata
98
165
 
@@ -179,6 +246,33 @@ This provides a visual cue that the action has permanent consequences.
179
246
 
180
247
  Actions with `path:` set are standalone — not tied to a specific record. They appear in a separate section and don't receive a `recordId` when executed. The CMS passes `null` as the record ID for standalone actions.
181
248
 
249
+ This is the right shape for a business-controlled create flow when generic CRUD
250
+ create would expose too much. For example, a reservation action can enforce
251
+ capacity, uniqueness, and status defaults while still giving an empty
252
+ reservations table a visible **New reservation** toolbar action:
253
+
254
+ {/* doc-compile: skip — abbreviated CMS-placement example. */}
255
+ ```typescript
256
+ export default defineAction({
257
+ path: "/reservations/make-reservation",
258
+ method: "POST",
259
+ input: z.object({ sessionId: z.string().min(1) }),
260
+ access: { roles: ["member+"] },
261
+ cms: {
262
+ label: "New reservation",
263
+ placement: "tables",
264
+ tables: ["reservations"],
265
+ },
266
+ async execute({ db, ctx, input }) {
267
+ // Check capacity/duplicates, then insert the protected default status.
268
+ },
269
+ });
270
+ ```
271
+
272
+ By contrast, define table `create.access` and `guards.createable` when the
273
+ generic **New** form is intentionally safe. Do not add raw create merely to get
274
+ a button if the action is where the business invariants live.
275
+
182
276
  ### Placement in Multi-Table Features
183
277
 
184
278
  When a standalone action belongs to a feature with multiple tables, the CMS needs to know where to render it.
@@ -6,7 +6,7 @@ The CMS is built from composable React components organized by function. Every c
6
6
 
7
7
  ### Sidebar
8
8
 
9
- The main navigation sidebar. Reads the schema registry to build a collapsible feature-grouped table list.
9
+ The main navigation sidebar. Reads the schema registry to build a collapsible feature-grouped table list and renders the active organization and signed-in user in its footer.
10
10
 
11
11
  ```typescript
12
12
  interface SidebarProps {
@@ -20,11 +20,9 @@ interface SidebarProps {
20
20
  | Feature icons | Each feature gets a contextual icon (e.g., Calculator for accounting) |
21
21
  | Active state | Current table highlighted with primary color |
22
22
  | Internal filter | Tables with `internal: true` are hidden |
23
- | Footer stats | Shows total feature and table counts |
24
-
25
- ### Header
26
-
27
- Top bar with tagline, organization switcher, and the signed-in user's role.
23
+ | Organization | One membership is a static name; multiple memberships add a switcher dropdown |
24
+ | Pinned mode | Hides the organization switcher because the scope is fixed |
25
+ | Profile footer | Shows the signed-in user, organization role, and sign-out action |
28
26
 
29
27
  ### Role context
30
28
 
@@ -119,7 +119,7 @@ export default defineConfig({
119
119
  });
120
120
  ```
121
121
 
122
- When you run `quickback compile`, the CLI:
122
+ When you run `quickback build`, the CLI:
123
123
  1. Builds the CMS SPA from source and places assets in `src/apps/cms/`
124
124
  2. Adds `[assets]` config to `wrangler.toml` with `run_worker_first = true`
125
125
  3. Generates Worker routing to serve the CMS SPA
@@ -166,8 +166,9 @@ By default, the CMS gates access behind organization membership:
166
166
 
167
167
  1. User logs in via Better Auth session
168
168
  2. CMS fetches the user's organization memberships
169
- 3. If the user belongs to multiple organizations, an **org selector** is displayed
170
- 4. Once an org is selected, the user's role within that org determines their CMS permissions
169
+ 3. If the user belongs to one organization, its name is shown without a dropdown
170
+ 4. If the user belongs to multiple organizations, the sidebar displays an **org selector**
171
+ 5. Once an org is selected, the user's role within that org determines their CMS permissions
171
172
 
172
173
  This is the default behavior for Quickback projects with no pinned org.
173
174
 
@@ -182,6 +183,17 @@ When your project sets `features.pinnedOrganizationId`, the CMS keeps org-backed
182
183
 
183
184
  Pinned organization mode is useful for internal tools, blogs, and one-customer deployments that still want org-backed roles and schema conventions without runtime org switching.
184
185
 
186
+ > **File uploads need valid R2 credentials**
187
+ >
188
+ > The CMS does not upload profile pictures or organization logos — those are
189
+ > Account UI, gated on `account.fileUploads`. They only work with
190
+ > [managed R2](/platform/storage/r2) and the `R2_ACCOUNT_ID` /
191
+ > `R2_ACCESS_KEY_ID` / `R2_SECRET_ACCESS_KEY` secrets. Start apps leave that
192
+ > flag off: a browser deploy can create the bucket, but it cannot mint those
193
+ > credentials. A `q.url()` field in the CMS stores a string; it does not
194
+ > upload to R2.
195
+
196
+
185
197
  ## Next Steps
186
198
 
187
199
  - **[Table Views](/ui/admin/table-views)** — Browse and Data Table view modes
@@ -29,9 +29,60 @@ The CMS generates its entire UI from your Quickback definitions. Define a table
29
29
  - **FK typeahead** — Server-side search for foreign key fields with debounced queries and keyboard navigation.
30
30
  - **Field masking** — Email, phone, SSN, and redaction patterns applied per role. Masked fields show a lock icon.
31
31
  - **Custom actions** — Action dialogs with auto-generated input forms, access filtering, CMS metadata (icons, categories, confirmations), and side effects warnings.
32
- - **Views** — Named column-level projections per role. "All Fields" plus custom views in the toolbar.
33
- - **Auto-form generation** — Create and edit forms built from guards (createable/updatable fields).
34
- - **Display column auto-detection** — FK labels resolved automatically from `name`, `title`, `label`, `code`, and other common patterns.
32
+ - **Views** — Named column-level projections per role, with an explicit default projection for CMS table entry.
33
+ - **Auto-form generation** — Create and edit forms built from guards (createable/updatable fields). Inputs follow the column's constraints — `q.enum` renders a select, `q.url` a URL input, `q.text({ maxLength })` a length-capped field — required columns are marked and constraints shown as helper text, untouched optional fields are omitted from the request (cleared ones are sent as `null`), and a `VALIDATION_ERROR` from the API is shown inline under the offending fields.
34
+ - **Human-readable relationships** — FK labels and selectors use the target table's `displayColumn` and an authored schema reference.
35
+
36
+ ## CMS Readiness Review
37
+
38
+ Enabling the CMS makes the definitions visible; it does not invent a safe UI
39
+ workflow. Before compiling a CMS-backed project, review every visible table
40
+ against this checklist:
41
+
42
+ 1. **Collection entry** — A table with no named views can use its ordinary
43
+ collection projection. Once `read.views` contains a named view, there is no
44
+ implicit full-row fallback. Set `read.defaultView` to an accessible named
45
+ view when the CMS must open the table directly. Without it, bare
46
+ `GET /api/v1/<table>` correctly returns `400 VIEW_REQUIRED`; callers must use
47
+ `GET /api/v1/<table>/views/<name>`. The registry marks that intentional
48
+ state with `requiresExplicitView: true`, so the CMS shows **Choose a view**
49
+ and makes no data request until one is selected. It never silently chooses
50
+ the first accessible projection. `defaultSort` only chooses ordering and
51
+ cannot satisfy view selection or fix `VIEW_REQUIRED`.
52
+ 2. **Labels** — Set `displayColumn` on tables used as FK targets or record
53
+ titles. Auto-detection is a convenience, but an explicit value makes the
54
+ intended human label stable.
55
+ 3. **Relationships** — For feature-table foreign keys, declare the relationship
56
+ in the schema with `.references(() => target.id)`. The CMS needs the emitted
57
+ `fkTarget` for selector/typeahead controls. Treat a matching `*Id` sibling
58
+ table name as a compiler diagnostic suggestion, not as proof of a
59
+ relationship. Better Auth ids are the exception: they live in `AUTH_DB` and
60
+ remain plain text, not cross-database FKs. When a target has named views,
61
+ its role-accessible `read.defaultView` must include its primary key and
62
+ `displayColumn`; the CMS lookup uses that named route only. Add the label to
63
+ the view's effective `query.searchable` for typeahead, or it becomes a
64
+ first-50 chooser with no search request.
65
+ 4. **CRUD controls** — **New** requires generated `create` CRUD, admitted
66
+ `create.access`, and all required non-default inputs in
67
+ `guards.createable`. Edit controls require generated `update` CRUD,
68
+ admitted `update.access`, and fields in `guards.updatable`. A protected
69
+ workflow field belongs in neither generic write list. Give it a schema
70
+ default for creation; only its named transitions/actions may write it.
71
+ 5. **Business actions** — A record-bound action needs an existing row. A
72
+ workflow that creates the first row should be a standalone action with
73
+ `path:` and explicit table-toolbar placement, such as
74
+ `cms: { placement: "tables", tables: ["reservations"] }`. Check action
75
+ roles and record conditions, and use `cms.hidden` only when the action is
76
+ intentionally API-only. Action input names are humanized (`sessionId`
77
+ becomes **Session**). The CMS resolves a matching `fkTarget` through the
78
+ parent-table column metadata, then reads the FK target through its safe
79
+ collection or named-default-view route. It renders search only when that
80
+ route supports it. Without an explicit schema relationship, the action
81
+ dialog falls back to plain text.
82
+
83
+ Read [Schema Registry](/ui/admin/schema-registry),
84
+ [Table Views](/ui/admin/table-views), and [Actions](/ui/admin/actions) before
85
+ authoring or reviewing a CMS-backed schema.
35
86
 
36
87
  ## Architecture
37
88
 
@@ -91,7 +142,7 @@ export default defineConfig({
91
142
  ### 2. Compile
92
143
 
93
144
  ```bash
94
- quickback compile
145
+ quickback build
95
146
  ```
96
147
 
97
148
  The compiler generates `schema-registry.json` and copies CMS static assets to `src/apps/`. It also adds an `[assets]` section to `wrangler.toml` so Cloudflare serves the CMS SPA automatically.
@@ -125,6 +176,20 @@ This adds a custom domain route to `wrangler.toml`. Both domains serve the same
125
176
  cms: { access: "member" } // let organization members in
126
177
  ```
127
178
 
179
+ Start apps ship that setting. A sysadmin who also holds an organization membership uses the seat (`owner` / `admin` / `member`) rather than the cross-tenant picker — the picker is only for a sysadmin who belongs to nothing.
180
+
181
+ > **File uploads need valid R2 credentials**
182
+ >
183
+ > Profile pictures and organization logos are **Account UI**, not the CMS — they
184
+ > live at `/account/profile` and `/account/<slug>/settings`. They only work with
185
+ > `account.fileUploads: true`, [managed R2](/platform/storage/r2)
186
+ > (`defineFileStorage("cloudflare-r2", { managed: true })`), and the
187
+ > `R2_ACCOUNT_ID` / `R2_ACCESS_KEY_ID` / `R2_SECRET_ACCESS_KEY` secrets. A
188
+ > Start `workers.dev` deploy can create the bucket; it cannot mint those
189
+ > credentials, so Start leaves uploads off. Pasting a URL into a `q.url()`
190
+ > column in the CMS is just a string — it does not upload bytes.
191
+
192
+
128
193
  > **`user.role === "appmanager"` does not open the CMS in either mode.** appmanager is the *control plane* — users, organizations, and subscriptions at [`/account/admin`](/ui/account) — and deliberately holds no tenant-data powers. Keeping those separable is the entire point of the appmanager/sysadmin split. An appmanager who is also a member of an organization gets in as that member, on the membership, not on the platform role.
129
194
 
130
195
 
@@ -138,7 +203,7 @@ The gates that carry real data:
138
203
 
139
204
  1. **`/api/v1/schema`** — the metadata endpoint. Admits `sysadmin`, plus any caller with a membership when `access: "member"`. Otherwise `403` with `CMS_ACCESS_DENIED` and a hint naming the requirement. Without the registry there is no CMS.
140
205
  2. **`custom_view` routes** — saved views follow whoever is admitted: the `sysadmin` tier in `"sysadmin"` mode, org membership *or* sysadmin in `"member"` mode.
141
- 3. **Account UI link** — the "Go to CMS" button is hidden for callers who wouldn't get in.
206
+ 3. **Account UI link** — the profile CMS action is hidden for callers who wouldn't get in. For admitted members it activates the selected organization before opening the CMS.
142
207
 
143
208
  Your resource API endpoints (`/api/v1/<resource>`) are **not** affected — they continue to use the per-resource `read`, `create`, `update`, `delete`, and `upsert` access rules you defined.
144
209
 
@@ -162,7 +227,7 @@ The shell is served to any signed-in caller, and the SPA resolves one of six sta
162
227
 
163
228
  The decision is a pure function (`resolveCmsAccess`), so the table above is tested rather than described.
164
229
 
165
- Sysadmin scope lives in the browser and rides every request as `?organizationId=` — it is not part of the session, because a sysadmin holds no membership row for Better Auth to make active. Change it from the sidebar.
230
+ For a zero-membership sysadmin in explicit cross-tenant mode, scope lives in the browser and rides every request as `?organizationId=` because Better Auth has no membership row to make active. Change it from the sidebar. A sysadmin who also holds memberships follows the ordinary membership flow instead; selecting a membership clears any older cross-tenant override. The sidebar shows the sole organization as static text and becomes a dropdown only when the user belongs to multiple organizations.
166
231
 
167
232
  #### `access: "sysadmin"` without `cms.sysadmin`
168
233