@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
@@ -4,7 +4,7 @@ The schema registry is a static JSON file generated by the Quickback compiler. I
4
4
 
5
5
  ## Generation
6
6
 
7
- Schema registry generation is **enabled by default**. Run `quickback compile` and the compiler outputs `schema-registry.json` alongside your compiled API files.
7
+ Schema registry generation is **enabled by default**. Run `quickback build` and the compiler outputs `schema-registry.json` alongside your compiled API files.
8
8
 
9
9
  To disable generation:
10
10
 
@@ -67,10 +67,12 @@ interface TableMeta {
67
67
  createable: string[]; // Fields allowed on create
68
68
  updatable: string[]; // Fields allowed on update
69
69
  immutable: string[]; // Fields locked after creation
70
- protected: Record<string, string[]>; // Fields only updatable via actions
70
+ protected: Record<string, string[]>; // Fields writable only via named actions/transitions
71
71
  };
72
72
  masking: Record<string, MaskingRule>; // Per-field masking rules
73
73
  views: Record<string, ViewConfig>; // Named column projections
74
+ defaultView?: string; // Authored read.defaultView
75
+ requiresExplicitView?: true; // Named views exist with no default
74
76
  validation: Record<string, ValidationRule>; // Per-field validation
75
77
  actions: ActionMeta[]; // Table-scoped actions for this table
76
78
  displayColumn?: string; // Human-readable label column
@@ -78,8 +80,72 @@ interface TableMeta {
78
80
  }
79
81
  ```
80
82
 
83
+ Each named view carries the effective read contract the CMS consumes:
84
+
85
+ ```typescript
86
+ interface ViewConfig {
87
+ fields: string[];
88
+ access: AccessRule;
89
+ query?: {
90
+ filterable?: string[] | null;
91
+ searchable?: string[];
92
+ sortable?: string[];
93
+ defaultSort?: string;
94
+ };
95
+ }
96
+ ```
97
+
98
+ For current registries, `access` is the view's explicit access rule or the
99
+ inherited table `read.access` when the view omits an override.
100
+ `query.searchable` is likewise the effective search allowlist: the explicit
101
+ view list when present, otherwise the compiler's eligible table search fields
102
+ after masked fields are removed. An empty array means the named view does not
103
+ support `?search`; it does not mean the table has no rows. `query.filterable`
104
+ contains the explicit named-view allowlist when authored, otherwise a q table's
105
+ column-level `.filterable()` defaults. Raw Drizzle tables emit `null` when no
106
+ closed filter allowlist can be derived, preserving their compatibility mode.
107
+
81
108
  `create`, `update`, `delete`, and `upsert` mirror the preferred flat DSL from `defineTable(...)`. The legacy `crud` block is still emitted for backwards compatibility with older consumers.
82
109
 
110
+ The registry is a projection of authored definitions, not a source of missing
111
+ intent. In particular:
112
+
113
+ - `views` lists the named projections available to the CMS. `defaultView`
114
+ carries the authored `read.defaultView`. When named views exist without one,
115
+ the registry emits `requiresExplicitView: true`; the CMS must show **Choose a
116
+ view** without making a collection request. It must not silently choose the
117
+ first accessible projection, because that would invent an access/shape
118
+ contract. **All Fields** is absent whenever `views` is nonempty. A bare API
119
+ collection request in this state returns `VIEW_REQUIRED`. `defaultSort` is
120
+ unrelated; it controls ordering only.
121
+ - `displayColumn` supplies the human-readable label used for records and
122
+ referenced values. Set it explicitly when the table is a user-facing FK
123
+ target.
124
+ - `crud`, the flat write-operation metadata, and `guards` determine whether
125
+ **New** and edit controls can exist and which inputs they expose.
126
+ - `actions` and `featureActions`, together with action access and `cms`
127
+ metadata, determine whether a control is record-bound, toolbar-placed,
128
+ disabled by state, or intentionally hidden.
129
+
130
+ ### Named-view targets and FK lookups
131
+
132
+ An FK lookup targeting a table with no named views uses the ordinary collection
133
+ route. Once the target declares named views, the CMS may automatically use only
134
+ its authored, role-accessible `defaultView`. It calls
135
+ `GET /api/v1/<target>/views/<defaultView>` and never retries a bare collection
136
+ or silently chooses another view.
137
+
138
+ That default view is lookup-safe when its `fields` include both the target's
139
+ primary key and `displayColumn`. If the default is missing, inaccessible to the
140
+ current role, or omits either identity/label field, the CMS disables the lookup
141
+ and displays an actionable explanation without making a data request.
142
+
143
+ For label typeahead, include the `displayColumn` in the effective
144
+ `query.searchable` allowlist. An explicit named-view allowlist is authoritative,
145
+ so the column does not also need `.searchable()`. When the effective searchable
146
+ list is empty, the selector remains usable as a first-50 chooser; its search
147
+ box is read-only and the CMS sends no `?search` parameter.
148
+
83
149
  ## Feature Actions
84
150
 
85
151
  Standalone actions do not always belong to a single table. When an action is attached to a multi-table feature root, the compiler emits it under `featureActions[featureName]` instead of duplicating it across every table.
@@ -92,6 +158,14 @@ interface SchemaRegistry {
92
158
 
93
159
  The CMS uses `featureActions` for toolbar-style actions that apply to the feature as a whole. Use `cms.placement` on standalone actions to control whether they show for the whole feature or only selected tables.
94
160
 
161
+ Action dialogs derive labels and controls from `ActionMeta.inputFields` plus the
162
+ table registry. An input named `sessionId` is labeled **Session**. When a
163
+ corresponding column has `fkTarget: "sessions"`, the CMS renders a typeahead
164
+ using the target table's `displayColumn` and the lookup read contract above;
165
+ otherwise it renders a plain text input. This is another reason to author the
166
+ schema-level `.references()` even when the action, rather than generic create
167
+ CRUD, is the visible create flow.
168
+
95
169
  > **Internal Tables**
96
170
  >
97
171
  > Tables without a `defineTable()` resource config are marked `internal: true` and hidden from the CMS sidebar. These are typically join tables or system tables.
@@ -118,11 +192,26 @@ The compiler automatically includes the system columns (`id`, `organizationId`),
118
192
 
119
193
  ### fkTarget — FK Resolution
120
194
 
121
- Columns ending in `Id` may have a `fkTarget` property indicating which table they reference. This is resolved in priority order:
195
+ Columns with an authored feature-table relationship have an `fkTarget`
196
+ property indicating which table they reference. In the Quickback schema DSL,
197
+ declare that relationship on the column:
122
198
 
123
- 1. **Explicit `references`** — from your `defineTable()` config (highest priority)
124
- 2. **Drizzle `.references()`** — parsed from schema source code
125
- 3. **Convention** — strip `Id` suffix, match table name directly
199
+ {/* doc-compile: skip — cross-table column excerpt; complete table forms live in /define/schema. */}
200
+ ```typescript
201
+ sessionId: q.text().required().references(() => sessions.id)
202
+ ```
203
+
204
+ The compiler also understands Drizzle's equivalent `.references()` form. A
205
+ legacy `defineTable({ references: { ... } })` map can override registry target
206
+ metadata, but it does not create the database foreign key; prefer the
207
+ schema-level relationship.
208
+
209
+ Do not rely on a column merely ending in `Id`. A same-named sibling table is a
210
+ useful warning/suggestion when the explicit relationship is missing, but the
211
+ name alone cannot establish author intent. CMS-ready definitions make every
212
+ feature-table relationship explicit. Better Auth identifiers such as `userId`
213
+ and `organizationId` are intentionally different: their tables live in
214
+ `AUTH_DB`, so feature columns must not add cross-database `.references()` calls.
126
215
 
127
216
  ```json
128
217
  {
@@ -177,6 +266,11 @@ If you don't explicitly set `displayColumn` in your resource config, the compile
177
266
 
178
267
  The first match wins. If no candidate matches, the table has no display column and the CMS falls back to showing IDs.
179
268
 
269
+ For a table used in CMS selectors or record titles, prefer explicit config even
270
+ when auto-detection currently finds the same column. It records which label is
271
+ part of the UI contract and prevents a later schema change from silently
272
+ changing that label.
273
+
180
274
  ### Explicit Config
181
275
 
182
276
  Set it explicitly in your table definition:
@@ -201,7 +295,13 @@ roomTypeId: "rt_abc123" → displayed as "Master Bedroom"
201
295
  accountCodeId: "ac_xyz789" → displayed as "4100 - Revenue"
202
296
  ```
203
297
 
204
- The FK target table is resolved from the `fkTarget` property on each column. For simple cases like `roomTypeId` → `roomType`, the compiler auto-detects it. For non-obvious mappings (e.g., `vendorId` → `contact`), use explicit [`references`](/define/schema#references) in your `defineTable()` config.
298
+ The FK target table is resolved from the `fkTarget` property on each column.
299
+ Declare a schema-level [`.references()` relationship](/define/schema#references)
300
+ for feature-table ids, including apparently obvious cases such as
301
+ `roomTypeId` → `roomTypes`. Do not make selector behavior depend on a naming
302
+ heuristic. For a legacy metadata-only alias such as `vendorId` → `contact`, the
303
+ resource `references` map can override `fkTarget`, but it is not a substitute
304
+ for a database FK when the two feature tables genuinely have one.
205
305
 
206
306
  ## Pages
207
307
 
@@ -12,10 +12,10 @@ cms: { access: "member" }
12
12
 
13
13
  The shell is served to any signed-in caller so the SPA can explain who is and isn't admitted; the gates that carry data are:
14
14
 
15
- 1. **Account UI** — the "Go to CMS" button is hidden for callers who wouldn't get in.
15
+ 1. **Account UI** — the profile CMS action is hidden for callers who wouldn't get in; admitted members select and activate an organization before navigation.
16
16
  2. **`/api/v1/schema`** — the metadata endpoint returns `403` with `CMS_ACCESS_DENIED` and a hint naming the requirement. Without the registry there is no CMS.
17
- 4. **`custom_view` routes** — the CMS-internal saved-views table uses `userRole: ["appmanager"]` (and, when `cms.sysadmin: true`, also admits `sysadmin`), so saved views can't be read or modified from outside the CMS by non-operator accounts.
18
- 5. **In-SPA gate** — if any earlier layer is bypassed, the SPA still redirects the user to `/account/profile`.
17
+ 3. **`custom_view` routes** — saved views follow whoever is admitted: the `sysadmin` tier in `"sysadmin"` mode, or organization membership plus sysadmin in `"member"` mode.
18
+ 4. **In-SPA gate** — the SPA renders the matching blocked, membership-picker, or sysadmin-scope screen before loading CMS data.
19
19
 
20
20
  Your resource API endpoints keep whatever `read`, `create`, `update`, `delete`, or `upsert` access rules you defined — they're the app's data API and unaffected by the CMS gate.
21
21
 
@@ -55,6 +55,13 @@ With the config above:
55
55
  - **Admins** see Create and Edit buttons but no Delete
56
56
  - **Owners** see all buttons
57
57
 
58
+ When an operation admits a pseudo-role (`PUBLIC`, `AUTHENTICATED`, or
59
+ `SESSION`) instead of an org membership role, the CMS still shows the
60
+ button to anyone who is in the CMS with a membership. A public contact
61
+ form (`create: { access: { roles: ["PUBLIC"] } }`) can be filled by
62
+ anonymous callers *and* by staff in the admin UI — hiding **New** from
63
+ the owner would be stricter than the API.
64
+
58
65
  The row action menu also adapts — Edit and Delete entries only appear when the role has the corresponding permission.
59
66
 
60
67
  ## Guards
@@ -104,6 +111,11 @@ guards: {
104
111
  }
105
112
  ```
106
113
 
114
+ A protected field belongs in neither `guards.createable` nor
115
+ `guards.updatable`. For transition-managed status/state, declare a schema
116
+ default for the initial value and allow only the named transitions/actions to
117
+ write it.
118
+
107
119
  ## Masking
108
120
 
109
121
  Masking rules redact sensitive data based on the user's role. The CMS applies masking client-side for display and the API enforces it server-side in responses.
@@ -161,7 +173,10 @@ read: {
161
173
  }
162
174
  ```
163
175
 
164
- Members only see the "summary" view option. Admins and owners see both "summary" and "financial". The "All Fields" option is always available.
176
+ Members only see the `summary` view option. Admins and owners see `summary` and
177
+ `financial`. **All Fields** is absent because named views define the available
178
+ projections. Since this excerpt does not declare `read.defaultView`, the CMS
179
+ shows **Choose a view** and makes no data request until the user selects one.
165
180
 
166
181
  ## Firewall
167
182
 
@@ -9,7 +9,7 @@ Table mode is the default browse experience:
9
9
  - **Click rows** to navigate to the record detail view
10
10
  - **Row action menus** (three-dot icon) with view, edit, delete, and custom actions
11
11
  - **Column headers** are sortable — click to toggle ascending/descending
12
- - **Search bar** for full-text search across all fields
12
+ - **Search bar** for full-text search across fields allowed by the active collection or named-view query contract
13
13
  - **Responsive columns** that adapt to available space
14
14
 
15
15
  Each row shows the most relevant columns for the table. Foreign key columns display human-readable labels (resolved via `_label` fields) instead of raw UUIDs. Boolean columns render as colored Yes/No badges. Enum columns use color-coded pills.
@@ -74,10 +74,22 @@ Views are named column projections defined in your table's resource config. They
74
74
 
75
75
  ### Toolbar
76
76
 
77
- The toolbar shows a view dropdown when the table has views defined. Options include:
77
+ The toolbar shows a view dropdown when the table has named views. Its options
78
+ are the named views the current role may access.
78
79
 
79
- - **All Fields** — Shows all columns (default)
80
- - Custom views — Only show the columns specified in the view config
80
+ For a table with no named views, the toolbar renders no view control and the
81
+ table uses its ordinary collection projection. Declaring any `read.views`
82
+ replaces that projection with the named-view contract; **All Fields** is not an
83
+ extra option alongside the named views. Set `read.defaultView` to choose which
84
+ named projection opens first in the CMS. The schema registry carries that
85
+ selection as `defaultView`, and the CMS calls the named-view route from its
86
+ first request.
87
+
88
+ If named views exist without `read.defaultView`, the registry emits
89
+ `requiresExplicitView: true`. The CMS shows **Choose a view** and makes no data
90
+ request until the user selects an accessible named view. It never silently
91
+ chooses the first accessible projection, because projection choice is part of
92
+ the table's data/access contract.
81
93
 
82
94
  Views are filtered by role access. If a view's access rules require `admin` and the current user is a `member`, that view won't appear in the dropdown.
83
95
 
@@ -87,24 +99,49 @@ Given this definition:
87
99
 
88
100
  ```typescript
89
101
  read: {
102
+ defaultView: 'summary',
90
103
  views: {
91
104
  summary: {
92
105
  fields: ['id', 'name', 'status'],
93
- access: { roles: ['member', 'admin'] },
106
+ access: { roles: ['member+'] },
94
107
  },
95
108
  full: {
96
109
  fields: ['id', 'name', 'status', 'ssn', 'internalNotes'],
97
- access: { roles: ['admin'] },
110
+ access: { roles: ['admin+'] },
98
111
  },
99
112
  },
100
113
  }
101
114
  ```
102
115
 
103
- - Members see: "All Fields" and "summary"
104
- - Admins see: "All Fields", "summary", and "full"
105
- - Owners see: "All Fields", "summary", and "full"
116
+ - Members see `summary`, which opens by default.
117
+ - Admins and owners see `summary` and `full`; `summary` still opens by default.
118
+
119
+ When a view is selected, the CMS calls
120
+ `GET /api/v1/<table>/views/<name>`, fetching only the projected columns. With
121
+ named views but no `read.defaultView`, bare `GET /api/v1/<table>` returns
122
+ `400 VIEW_REQUIRED`. That can be intentional for API callers that must choose a
123
+ projection, but a CMS table intended to open directly should declare an
124
+ accessible default view.
125
+
126
+ ### Views Used by FK Lookups
106
127
 
107
- When a view is selected, the CMS calls the `listView` API endpoint instead of the standard `list`, fetching only the projected columns.
128
+ When this table is the target of an FK selector, a table with no named views
129
+ uses its ordinary collection route. A table with named views is different: the
130
+ CMS lookup uses only the authored `read.defaultView`, verifies that the current
131
+ role may access it, and calls its named-view route. It never retries the bare
132
+ collection endpoint and never chooses another named view automatically.
133
+
134
+ Make that default view lookup-safe by including the table's primary key and
135
+ `displayColumn` in `fields`. For searchable label typeahead, include the
136
+ `displayColumn` in the view's effective `query.searchable` allowlist. An
137
+ explicit named-view allowlist is authoritative, so the column does not also
138
+ need `.searchable()`. The schema registry emits the effective inherited view
139
+ access and searchability so the CMS can decide before requesting data.
140
+
141
+ If the default is missing, inaccessible, or omits the primary key/label, the
142
+ selector is disabled with an actionable message. If the default is otherwise
143
+ valid but its effective searchable list is empty, the selector shows the first
144
+ 50 options as a chooser, keeps search read-only, and sends no `?search`.
108
145
 
109
146
  ## Default Sort
110
147
 
@@ -121,6 +158,10 @@ export default defineTable(podcastEpisodes, {
121
158
 
122
159
  When the CMS loads the table, it applies this sort automatically. Users can still click column headers to change the sort — `defaultSort` only sets the initial state.
123
160
 
161
+ `defaultSort` does not select a named view. Adding or changing it cannot resolve
162
+ `VIEW_REQUIRED`; use `read.defaultView` (or call the explicit named-view route)
163
+ for that.
164
+
124
165
  ## Pagination
125
166
 
126
167
  The bottom of every table view shows pagination controls:
@@ -133,9 +174,15 @@ The default page size is 25 records. The CMS resets to page 1 when you change th
133
174
 
134
175
  ## Search
135
176
 
136
- The search bar performs full-text search across all columns. Type a query and the CMS debounces the request, then fetches matching records from the API.
177
+ The search bar performs full-text search across the fields allowed by the
178
+ active collection or named-view query contract. Type a query and the CMS
179
+ debounces the request, then fetches matching records from the API. For named
180
+ views, the registry's effective `query.searchable` list tells the CMS whether
181
+ the route accepts `?search` and which projected fields participate.
137
182
 
138
- Search works in both Table and Data Table modes, and works with views (searching within the projected columns).
183
+ Search works in both Table and Data Table modes when the active route supports
184
+ it. For FK selectors, an empty named-default-view search allowlist activates
185
+ the first-50 chooser behavior above, which sends no `?search`.
139
186
 
140
187
  ## Next Steps
141
188