@quickback-dev/cli 0.72.9 → 0.72.11

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 (212) hide show
  1. package/dist/commands/build.d.ts.map +1 -1
  2. package/dist/commands/build.js +8 -1
  3. package/dist/commands/build.js.map +1 -1
  4. package/dist/commands/db-explain.d.ts +67 -0
  5. package/dist/commands/db-explain.d.ts.map +1 -0
  6. package/dist/commands/db-explain.js +141 -0
  7. package/dist/commands/db-explain.js.map +1 -0
  8. package/dist/commands/db-export.d.ts +34 -0
  9. package/dist/commands/db-export.d.ts.map +1 -0
  10. package/dist/commands/db-export.js +250 -0
  11. package/dist/commands/db-export.js.map +1 -0
  12. package/dist/commands/db-insights.d.ts +60 -0
  13. package/dist/commands/db-insights.d.ts.map +1 -0
  14. package/dist/commands/db-insights.js +106 -0
  15. package/dist/commands/db-insights.js.map +1 -0
  16. package/dist/commands/db-recovery.d.ts +98 -0
  17. package/dist/commands/db-recovery.d.ts.map +1 -0
  18. package/dist/commands/db-recovery.js +558 -0
  19. package/dist/commands/db-recovery.js.map +1 -0
  20. package/dist/commands/db-target.d.ts +27 -0
  21. package/dist/commands/db-target.d.ts.map +1 -0
  22. package/dist/commands/db-target.js +83 -0
  23. package/dist/commands/db-target.js.map +1 -0
  24. package/dist/commands/db.d.ts +3 -0
  25. package/dist/commands/db.d.ts.map +1 -0
  26. package/dist/commands/db.js +43 -0
  27. package/dist/commands/db.js.map +1 -0
  28. package/dist/commands/effects.d.ts +8 -0
  29. package/dist/commands/effects.d.ts.map +1 -0
  30. package/dist/commands/effects.js +48 -0
  31. package/dist/commands/effects.js.map +1 -0
  32. package/dist/commands/platform-budget.d.ts +143 -0
  33. package/dist/commands/platform-budget.d.ts.map +1 -0
  34. package/dist/commands/platform-budget.js +619 -0
  35. package/dist/commands/platform-budget.js.map +1 -0
  36. package/dist/commands/preview.d.ts +57 -0
  37. package/dist/commands/preview.d.ts.map +1 -0
  38. package/dist/commands/preview.js +268 -0
  39. package/dist/commands/preview.js.map +1 -0
  40. package/dist/commands/search.d.ts +20 -0
  41. package/dist/commands/search.d.ts.map +1 -0
  42. package/dist/commands/search.js +133 -0
  43. package/dist/commands/search.js.map +1 -0
  44. package/dist/index.js +35 -1
  45. package/dist/index.js.map +1 -1
  46. package/dist/lib/api-client.d.ts +4 -0
  47. package/dist/lib/api-client.d.ts.map +1 -1
  48. package/dist/lib/api-client.js.map +1 -1
  49. package/dist/lib/cloudflare-spend-policies.d.ts +92 -0
  50. package/dist/lib/cloudflare-spend-policies.d.ts.map +1 -0
  51. package/dist/lib/cloudflare-spend-policies.js +289 -0
  52. package/dist/lib/cloudflare-spend-policies.js.map +1 -0
  53. package/dist/lib/compiler-stubs.d.ts +2 -0
  54. package/dist/lib/compiler-stubs.d.ts.map +1 -1
  55. package/dist/lib/compiler-stubs.js +2 -0
  56. package/dist/lib/compiler-stubs.js.map +1 -1
  57. package/dist/lib/d1-fingerprint.d.ts +8 -0
  58. package/dist/lib/d1-fingerprint.d.ts.map +1 -0
  59. package/dist/lib/d1-fingerprint.js +113 -0
  60. package/dist/lib/d1-fingerprint.js.map +1 -0
  61. package/dist/lib/file-loader.d.ts +12 -0
  62. package/dist/lib/file-loader.d.ts.map +1 -1
  63. package/dist/lib/file-loader.js +27 -1
  64. package/dist/lib/file-loader.js.map +1 -1
  65. package/dist/lib/migrations/plan.js +3 -0
  66. package/dist/lib/migrations/plan.js.map +1 -1
  67. package/dist/lib/migrations/postprocessors/index.d.ts +6 -5
  68. package/dist/lib/migrations/postprocessors/index.d.ts.map +1 -1
  69. package/dist/lib/migrations/postprocessors/index.js +24 -12
  70. package/dist/lib/migrations/postprocessors/index.js.map +1 -1
  71. package/dist/lib/migrations/postprocessors/search.d.ts +49 -0
  72. package/dist/lib/migrations/postprocessors/search.d.ts.map +1 -0
  73. package/dist/lib/migrations/postprocessors/search.js +160 -0
  74. package/dist/lib/migrations/postprocessors/search.js.map +1 -0
  75. package/dist/lib/migrations/prior-state.d.ts +7 -0
  76. package/dist/lib/migrations/prior-state.d.ts.map +1 -1
  77. package/dist/lib/migrations/prior-state.js +3 -0
  78. package/dist/lib/migrations/prior-state.js.map +1 -1
  79. package/dist/lib/migrations/types.d.ts +1 -1
  80. package/dist/lib/migrations/types.d.ts.map +1 -1
  81. package/dist/lib/migrations/types.js +1 -0
  82. package/dist/lib/migrations/types.js.map +1 -1
  83. package/dist/lib/preview-lifecycle.d.ts +139 -0
  84. package/dist/lib/preview-lifecycle.d.ts.map +1 -0
  85. package/dist/lib/preview-lifecycle.js +429 -0
  86. package/dist/lib/preview-lifecycle.js.map +1 -0
  87. package/dist/lib/preview.d.ts +146 -0
  88. package/dist/lib/preview.d.ts.map +1 -0
  89. package/dist/lib/preview.js +417 -0
  90. package/dist/lib/preview.js.map +1 -0
  91. package/dist/lib/wrangler-resources.d.ts.map +1 -1
  92. package/dist/lib/wrangler-resources.js +4 -2
  93. package/dist/lib/wrangler-resources.js.map +1 -1
  94. package/dist/skill/SKILL.md +9 -3
  95. package/dist/skill/agents/quickback-specialist/AGENT.md +9 -11
  96. package/dist/skill/docs/api/batch-operations.md +19 -0
  97. package/dist/skill/docs/api/caching.md +17 -0
  98. package/dist/skill/docs/api/crud.md +9 -0
  99. package/dist/skill/docs/api/errors.md +31 -2
  100. package/dist/skill/docs/api/query-params.md +6 -0
  101. package/dist/skill/docs/changelog/index.md +1 -0
  102. package/dist/skill/docs/configure/agents.md +1 -1
  103. package/dist/skill/docs/configure/bindings.md +177 -1
  104. package/dist/skill/docs/configure/cloudflare-access.md +43 -0
  105. package/dist/skill/docs/configure/domains.md +1 -1
  106. package/dist/skill/docs/configure/providers.md +5 -0
  107. package/dist/skill/docs/configure/tenant-databases.md +627 -14
  108. package/dist/skill/docs/define/access.md +26 -0
  109. package/dist/skill/docs/define/actions/defining.md +7 -1
  110. package/dist/skill/docs/define/actions/index.md +5 -0
  111. package/dist/skill/docs/define/actions/scoped-db.md +127 -1
  112. package/dist/skill/docs/define/authoring-basics.md +92 -0
  113. package/dist/skill/docs/define/changesets.md +8 -0
  114. package/dist/skill/docs/define/encryption.md +48 -2
  115. package/dist/skill/docs/define/feature.md +17 -2
  116. package/dist/skill/docs/define/guards.md +11 -3
  117. package/dist/skill/docs/define/index.md +1 -1
  118. package/dist/skill/docs/define/invariants.md +321 -0
  119. package/dist/skill/docs/define/issue-tracker-example.md +225 -0
  120. package/dist/skill/docs/define/masking.md +3 -3
  121. package/dist/skill/docs/define/rate-limit.md +78 -30
  122. package/dist/skill/docs/define/read.md +332 -5
  123. package/dist/skill/docs/define/relationships.md +10 -0
  124. package/dist/skill/docs/define/schema.md +137 -10
  125. package/dist/skill/docs/define/scopes.md +1 -0
  126. package/dist/skill/docs/define/transitions.md +9 -0
  127. package/dist/skill/docs/define/triggers.md +127 -1
  128. package/dist/skill/docs/platform/api-contract/index.md +35 -4
  129. package/dist/skill/docs/platform/auth/api-keys.md +26 -3
  130. package/dist/skill/docs/platform/auth/index.md +5 -2
  131. package/dist/skill/docs/platform/auth/plugins/index.md +1 -1
  132. package/dist/skill/docs/platform/database/d1.md +73 -1
  133. package/dist/skill/docs/platform/database/durable-effects.md +224 -0
  134. package/dist/skill/docs/platform/database/neon.md +8 -5
  135. package/dist/skill/docs/platform/database/read-replication.md +9 -0
  136. package/dist/skill/docs/platform/database/recovery.md +292 -0
  137. package/dist/skill/docs/platform/database/using-d1.md +152 -2
  138. package/dist/skill/docs/platform/index.md +1 -0
  139. package/dist/skill/docs/platform/operations/budgets.md +224 -0
  140. package/dist/skill/docs/platform/queues/handlers.md +1 -0
  141. package/dist/skill/docs/platform/queues/index.md +18 -0
  142. package/dist/skill/docs/platform/realtime/table-changes.md +1 -0
  143. package/dist/skill/docs/platform/storage/using-r2.md +13 -0
  144. package/dist/skill/docs/platform/vector/embeddings.md +28 -4
  145. package/dist/skill/docs/platform/vector/using-embeddings.md +17 -0
  146. package/dist/skill/docs/platform/workflows/index.md +385 -0
  147. package/dist/skill/docs/start/deploy-browser.md +51 -0
  148. package/dist/skill/docs/start/deploy.md +97 -1
  149. package/dist/skill/docs/tooling/cli.md +117 -0
  150. package/dist/skill/docs/tooling/cloud-compiler/index.md +15 -0
  151. package/dist/skill/docs/ui/account/customization.md +4 -0
  152. package/dist/skill/docs/ui/admin/record-layouts.md +3 -3
  153. package/package.json +1 -1
  154. package/src/skill/SKILL.md +9 -3
  155. package/src/skill/agents/quickback-specialist/AGENT.md +9 -11
  156. package/src/skill/docs/api/batch-operations.md +19 -0
  157. package/src/skill/docs/api/caching.md +17 -0
  158. package/src/skill/docs/api/crud.md +9 -0
  159. package/src/skill/docs/api/errors.md +31 -2
  160. package/src/skill/docs/api/query-params.md +6 -0
  161. package/src/skill/docs/changelog/index.md +1 -0
  162. package/src/skill/docs/configure/agents.md +1 -1
  163. package/src/skill/docs/configure/bindings.md +177 -1
  164. package/src/skill/docs/configure/cloudflare-access.md +43 -0
  165. package/src/skill/docs/configure/domains.md +1 -1
  166. package/src/skill/docs/configure/providers.md +5 -0
  167. package/src/skill/docs/configure/tenant-databases.md +627 -14
  168. package/src/skill/docs/define/access.md +26 -0
  169. package/src/skill/docs/define/actions/defining.md +7 -1
  170. package/src/skill/docs/define/actions/index.md +5 -0
  171. package/src/skill/docs/define/actions/scoped-db.md +127 -1
  172. package/src/skill/docs/define/authoring-basics.md +92 -0
  173. package/src/skill/docs/define/changesets.md +8 -0
  174. package/src/skill/docs/define/encryption.md +48 -2
  175. package/src/skill/docs/define/feature.md +17 -2
  176. package/src/skill/docs/define/guards.md +11 -3
  177. package/src/skill/docs/define/index.md +1 -1
  178. package/src/skill/docs/define/invariants.md +321 -0
  179. package/src/skill/docs/define/issue-tracker-example.md +225 -0
  180. package/src/skill/docs/define/masking.md +3 -3
  181. package/src/skill/docs/define/rate-limit.md +78 -30
  182. package/src/skill/docs/define/read.md +332 -5
  183. package/src/skill/docs/define/relationships.md +10 -0
  184. package/src/skill/docs/define/schema.md +137 -10
  185. package/src/skill/docs/define/scopes.md +1 -0
  186. package/src/skill/docs/define/transitions.md +9 -0
  187. package/src/skill/docs/define/triggers.md +127 -1
  188. package/src/skill/docs/platform/api-contract/index.md +35 -4
  189. package/src/skill/docs/platform/auth/api-keys.md +26 -3
  190. package/src/skill/docs/platform/auth/index.md +5 -2
  191. package/src/skill/docs/platform/auth/plugins/index.md +1 -1
  192. package/src/skill/docs/platform/database/d1.md +73 -1
  193. package/src/skill/docs/platform/database/durable-effects.md +224 -0
  194. package/src/skill/docs/platform/database/neon.md +8 -5
  195. package/src/skill/docs/platform/database/read-replication.md +9 -0
  196. package/src/skill/docs/platform/database/recovery.md +292 -0
  197. package/src/skill/docs/platform/database/using-d1.md +152 -2
  198. package/src/skill/docs/platform/index.md +1 -0
  199. package/src/skill/docs/platform/operations/budgets.md +224 -0
  200. package/src/skill/docs/platform/queues/handlers.md +1 -0
  201. package/src/skill/docs/platform/queues/index.md +18 -0
  202. package/src/skill/docs/platform/realtime/table-changes.md +1 -0
  203. package/src/skill/docs/platform/storage/using-r2.md +13 -0
  204. package/src/skill/docs/platform/vector/embeddings.md +28 -4
  205. package/src/skill/docs/platform/vector/using-embeddings.md +17 -0
  206. package/src/skill/docs/platform/workflows/index.md +385 -0
  207. package/src/skill/docs/start/deploy-browser.md +51 -0
  208. package/src/skill/docs/start/deploy.md +97 -1
  209. package/src/skill/docs/tooling/cli.md +117 -0
  210. package/src/skill/docs/tooling/cloud-compiler/index.md +15 -0
  211. package/src/skill/docs/ui/account/customization.md +4 -0
  212. package/src/skill/docs/ui/admin/record-layouts.md +3 -3
@@ -355,6 +355,27 @@ also writes `.dev.vars.example` with every declared secret, for local
355
355
  `wrangler dev`. Neon and PlanetScale keep their own template, and any declared
356
356
  secret it lacks is appended to it.
357
357
 
358
+ ### Manage Account Spend Policies
359
+
360
+ ```bash
361
+ quickback platform budget status --account <account-id>
362
+ quickback platform budget plan budget.json --out budget-plan.json --account <account-id>
363
+ quickback platform budget apply budget-plan.json --confirm <digest> --account <account-id>
364
+ quickback platform budget history --account <account-id> [--policy <id>]
365
+ quickback platform budget rollback-plan budget-plan.json --out rollback.json --account <account-id>
366
+ ```
367
+
368
+ These commands manage Cloudflare spending alerts and spending limits for
369
+ Workers and Durable Objects across a whole account, using the official `cf`
370
+ CLI. They are account-level platform controls. They are not per-tenant quotas
371
+ and they do not cap an invoice. Every command needs `--account <id>` or
372
+ `--env <target>`, where the target's `accountId` comes from
373
+ `quickback.config.ts`. The account is printed first, and each `cf` call is
374
+ pinned to it. `plan`, `status`, `history` and `rollback-plan` are read-only.
375
+ `apply` runs only a reviewed plan file and requires its `--confirm` digest.
376
+ `quickback build` and `quickback deploy` never change account policies. See
377
+ [Account spend policies](/platform/operations/budgets).
378
+
358
379
  ### Compact D1 Schema Migrations
359
380
 
360
381
  ```bash
@@ -393,6 +414,26 @@ The route path and each target's API hostname come from
393
414
  `reports/ops.manifest.json`. The command needs no database credentials. The
394
415
  first failure stops the run and exits `1`.
395
416
 
417
+ ### Check and Rebuild Search Indexes
418
+
419
+ ```bash
420
+ quickback search status --env production
421
+ quickback search rebuild --env production # prints the plan
422
+ quickback search rebuild --env production --apply --generation __qb_fts_articles_1a2b3c4d
423
+ ```
424
+
425
+ Operates on the [`read.search`](/define/read#full-text-search-readsearch)
426
+ FTS5 indexes in the target's features D1, as owned by the newest
427
+ `*_quickback_search_*.sql` migration. `status` runs FTS5 `'integrity-check'`
428
+ per index and exits 1 when an index is missing (search migration not applied)
429
+ or out of sync with its table. `rebuild` re-derives the index from the table
430
+ and verifies it; it is a dry run unless `--apply --generation <name>` names the
431
+ generation shown in the plan. No query text is accepted — the statements are
432
+ fixed — and it runs through `wrangler d1 execute` with your Cloudflare
433
+ credentials (`--database` defaults to `DB`, `--local` targets local D1).
434
+ Tenant-object indexes are rebuilt automatically on wake after a migration or
435
+ dump restore.
436
+
396
437
  ### View Documentation
397
438
 
398
439
  ```bash
@@ -666,6 +707,24 @@ not overwrite global IDs for named targets. Postgres migrations and remote
666
707
  Hyperdrive cache/target verification remain operator-owned. See
667
708
  [Deploying](/start/deploy#named-deployment-targets).
668
709
 
710
+ ### Preview environments
711
+
712
+ ```bash
713
+ quickback preview plan --name pr-123 [--env <target>] [--json]
714
+ quickback preview up --name pr-123 [--env <target>] [--ttl <hours>] [--seed <file>]
715
+ quickback preview status [--name pr-123] [--json]
716
+ quickback preview down --name pr-123 [--apply]
717
+ quickback preview gc [--apply] [--limit <n>]
718
+ ```
719
+
720
+ Creates a temporary preview with its own Worker, D1, KV and R2 resources. It
721
+ uses the selected target as a template, applies a synthetic seed and expires.
722
+ `plan` is read-only. `down` and `gc` only review until you pass `--apply`.
723
+ Teardown deletes only resources recorded in
724
+ `.quickback/previews/<name>/ledger.json`, re-verifying each before deleting it.
725
+ Unsupported resource graphs are refused before any account call. See
726
+ [Ephemeral previews](/start/deploy#ephemeral-previews).
727
+
669
728
  ### Verify Neon migrations
670
729
 
671
730
  ```bash
@@ -681,3 +740,61 @@ role. Local migration inventory changes abort parent apply. See
681
740
  [Neon canaries](/platform/database/neon#required-migration-canaries) for role
682
741
  selection, inventory-check limits and cleanup behavior. `quickback migrate`
683
742
  continues to mean authored-source codemods, not database migration execution.
743
+
744
+
745
+ ## D1 diagnostics
746
+
747
+ Read-only D1 tools. Both need `reports/d1-query-catalog.json`, which a build emits when
748
+ [`diagnostics`](/platform/database/using-d1#sampled-query-diagnostics) is set
749
+ (`sampleRate: 0` keeps runtime sampling off).
750
+
751
+ ```bash
752
+ quickback db explain --fingerprint '<fingerprint>' [--input params.json] --binding DB [--local | --remote [--env <target>]] [--json]
753
+ quickback db insights --binding DB --env <target> [--window 24h] [--sort reads|writes|time|count] [--aggregate sum|avg] [--limit 20] [--json]
754
+ quickback db insights --env <target> --account <id> --all-databases [--json]
755
+ ```
756
+
757
+ - **`db explain`** runs one `EXPLAIN QUERY PLAN` for a fingerprint copied from a
758
+ `D1_QUERY` event or `db insights`. It is local by default, and remote only with
759
+ `--remote`. A project with named environments must also pass `--env <target>`. It accepts only canonical read-only `SELECT` fingerprints over
760
+ catalog names. `--input` is a JSON array of synthetic primitive parameters,
761
+ encoded as SQLite literals. The output shows indexes used, full scans and
762
+ temp-B-tree sorts as advice. Nothing is applied.
763
+ - **`db insights`** reads remote Query Insights through your installed
764
+ Wrangler 4.x, with the query strings redacted to fingerprints. Unknown
765
+ bindings never widen to account-wide analytics. Output is top-N adaptive
766
+ analytics, not a billing total.
767
+
768
+ Neither command runs business SQL, changes indexes or installs dependencies.
769
+ Unsupported Wrangler output and failed commands report an error code without
770
+ echoing raw output. See [Explain and Query Insights](/platform/database/using-d1#explain-and-query-insights).
771
+
772
+ ## D1 recovery and exports
773
+
774
+ Fenced restores need [`recovery`](/platform/database/recovery) compiled in and
775
+ deployed. The operator key comes from the environment variable named by
776
+ `recovery.operatorKey.env` (default `QB_RECOVERY_OPERATOR_KEY`), never from a
777
+ plan file. Each database is an independent restore point.
778
+
779
+ ```bash
780
+ quickback db checkpoint --env <target> --binding DB [--binding AUTH_DB] [--out checkpoint.json]
781
+ quickback db restore-plan --env <target> --url <origin> --binding DB (--timestamp <RFC3339> | --checkpoint checkpoint.json) --out restore.json [--writers-stopped <name,...>] [--reissue-pending]
782
+ quickback db restore-apply restore.json --confirm <plan-digest> [--retry-unknown] [--drain-timeout 120] [--acknowledge-failures]
783
+ quickback db restore-status --operation <id> --url <origin>
784
+ quickback db restore-verify restore.json
785
+ quickback db restore-resume --operation <id> --plan restore.json --confirm <resume-digest>
786
+ quickback db restore-undo-plan --operation <id> --plan restore.json --out undo.json
787
+ quickback db export-plan --env <target> --binding DB --format d1|sqlite3_cli_only --directory <absolute path outside git> --out export.json [--table <name>]
788
+ quickback db export-apply export.json --confirm <digest> [--restart]
789
+ quickback db export-status export.json
790
+ quickback db export-verify <receipt.json>
791
+ quickback effects state|list|replay|resolve|reconcile --url <origin> …
792
+ ```
793
+
794
+ - **Planning is read-only.** A plan records target identity, bookmarks, the migration manifest, the control generations, the recovery hooks and the declared stopped writers. Plan files are never overwritten.
795
+ - **Destructive steps need the exact digest.** `restore-apply` reruns resume from the recorded stage. The fence stays held on every failure.
796
+ - **Reopening needs a fresh verification digest.** Only `restore-resume` reopens, and only with that digest.
797
+ - **Exports are protected.** They land only in a real directory outside every Git worktree. Their receipts carry hashes, never data.
798
+
799
+ Wrangler output, SQL and signed URLs are never echoed. See
800
+ [D1 recovery](/platform/database/recovery).
@@ -51,6 +51,21 @@ without changing their definitions or generated output.
51
51
 
52
52
  ## Processing, analytics, and AI use
53
53
 
54
+ Validation requests (`/compile?complete=false`), including Start's definition
55
+ feedback loop, run in a private edge Worker behind the hosted compiler's normal
56
+ authentication and admission checks. The edge Worker has no public workers.dev
57
+ or preview URL. Compiler implementation code stays server-side; callers receive
58
+ generated application files and diagnostics.
59
+
60
+ Complete backend builds continue to use the container pool. If the edge validator
61
+ fails or does not respond within 60 seconds, the proxy falls back to a container.
62
+ The edge Worker has a 60-second CPU limit;
63
+ edge and fallback share a 110-second response budget so Start can return a
64
+ retryable error before its two-minute client timeout.
65
+ Normal validation errors are returned directly so the caller can correct the
66
+ definitions. Moving validation to the edge does not make complete builds
67
+ unlimited or change their authentication requirements.
68
+
54
69
  - Compile payloads are processed for the request. Full compiles use a
55
70
  per-request temporary work directory that is deleted in a `finally` cleanup
56
71
  on success or failure; validation compiles run in memory.
@@ -364,3 +364,7 @@ import './custom-styles.css'; // Your overrides
364
364
  - **[With Quickback](/ui/account/with-quickback)** - How the compiler builds and bundles your customized UI
365
365
  - **[Environment Variables](/ui/account/environment-variables)** - Complete configuration reference
366
366
  - **[Feature Flags](/ui/account/features)** - Enable/disable features
367
+
368
+ ### Compiler-managed logo and favicon
369
+
370
+ For generated applications, set `account.logoUrl` and `account.faviconUrl` in `quickback.config.ts`. These reach the generic Account bundle through runtime configuration, so no edits to generated JavaScript or per-customer SPA rebuild are required. Use same-origin public asset paths or trusted HTTPS image URLs. `account.logoUrl: ''` hides the logo. The source-level `setAppConfig` customization above remains available for a separately maintained Account app.
@@ -38,9 +38,9 @@ export default feature("contacts", {
38
38
  // Contact details are detected as sensitive; on a CRM contact record they
39
39
  // are the point of the record, so this one is reviewed and left visible.
40
40
  masking: { email: false, phone: false, mobile: false },
41
- create: { /* ... */ },
42
- update: { /* ... */ },
43
- delete: { /* ... */ },
41
+ create: { access: { roles: ["owner", "admin", "member"] } },
42
+ update: { access: { roles: ["owner", "admin", "member"] } },
43
+ delete: { access: { roles: ["owner", "admin"] } },
44
44
  layouts: {
45
45
  default: {
46
46
  sections: [
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quickback-dev/cli",
3
- "version": "0.72.9",
3
+ "version": "0.72.11",
4
4
  "description": "CLI for Quickback — define your backend in TypeScript, compile to a fully wired Cloudflare Worker (or Bun / Node) with auth, database, migrations, security, CMS, and Account UI.",
5
5
  "author": "Kardoe Incorporated <paul@kardoe.com>",
6
6
  "license": "MIT",
@@ -8,6 +8,12 @@ allowed-tools: Read, Grep, Glob, Edit, Write
8
8
 
9
9
  Quickback is a **backend compiler**. Define your database schema and security rules in TypeScript; compile them into a Hono API running on Cloudflare Workers. Pair the output with the Quickback Stack for a complete Supabase alternative on Cloudflare.
10
10
 
11
+ ## Authoring workflow
12
+
13
+ Read `docs/define/authoring-basics.md` first (CLI: `quickback docs define/authoring-basics`), then the current firewall/access pages. Treat canonical docs as authoritative over examples or remembered behavior in this file. Map the requested capabilities and permissions, retrieve their focused references, and validate a connected skeleton before adding actions and presentation details. After a compiler error, read the relevant contract before guessing a replacement. Before completion, compare final files against the original requirements; never drop an access branch to obtain a green compile.
14
+
15
+ For project/issue/assignment builds use `docs/define/issue-tracker-example.md`. It includes sibling helper imports, same-org FKs, submitted-user membership checks, and a persisted reporter-or-assignee update. Relationship roles compare the same resource-column name on both rows; they do not automatically map a junction's `issueId` to an issue's `id`. Returned table rows use `output: row(table)`; a green validation alone does not prove generated TypeScript or runtime permissions.
16
+
11
17
  It's two products:
12
18
 
13
19
  ## 1. Quickback Compiler — the build tool
@@ -252,13 +258,13 @@ For Drizzle interop (existing `sqliteTable` schemas): `quickback docs define/esc
252
258
 
253
259
  Before flagging "missing X", check whether a default already covers it:
254
260
 
255
- - **Soft-delete is the default.** `deletedAt` / `deletedBy` are auto-injected at the SQL layer; firewall auto-AND-merges `deletedAt IS NULL`. Opt out with `crud.delete.mode: 'hard'`.
256
- - **Audit fields auto-injected.** `createdAt`, `createdBy`, `modifiedAt`, `modifiedBy` — never declare them in user code. The audit-wrapper auto-populates `createdBy` / `modifiedBy` from `ctx.userId`.
261
+ - **Soft-delete is the default.** Declare `...q.softDelete()` visibly; firewall auto-AND-merges `deletedAt IS NULL`. Opt out with `crud.delete.mode: 'hard'`.
262
+ - **Audit columns must be visible.** Declare `...q.audit()` and, for soft-delete tables, `...q.softDelete()` in `columns`. The compiler validates their canonical shape. Runtime writes populate the values from verified context; do not supply managed fields in scoped inserts. See `define/schema` for the distinction between schema declaration and write-time population.
257
263
  - **Sensitive columns auto-masked.** `email`, `phone`, `ssn`, `password`, `creditCard`, etc. get `show: { or: 'owner', roles: ['admin'] }` by default; falls back to `roles: ['admin']` only when there's no `ownerId` column. Absence of a `masking:` block does NOT mean plain-text — it means the compiler-default is in effect. Declare `masking:` only to override.
258
264
  - **Firewall auto-derived** for tables with a single isolation column (e.g., `organizationId` only).
259
265
  - **Soft-delete cascade** reaches cross-feature children with each child's own firewall AND-merged.
260
266
  - **Reserved keys in `access.record`.** `and`, `or`, `roles`, `userRole` are rejected inside `record:` at compile time — those go on the parent access node.
261
- - **Soft-delete × `unique()` footgun.** A soft-deleted row still occupies its unique index — deleting a unique junction row (e.g. a membership pair) then re-creating it fails the constraint, because the old row is only flagged `deletedAt`, not removed. For re-creatable unique rows, either use `delete.mode: 'hard'` (needs the audit DB on D1) or drop the unique constraint and enforce uniqueness in an action.
267
+ - **Soft-delete and uniqueness.** A full unique index still includes soft-deleted rows. Prefer the documented `unique: [{ columns: [...], whereNotDeleted: true }]` form for re-creatable soft-delete junction rows; see `define/schema`. Do not remove database uniqueness or change deletion semantics merely to avoid a compile error.
262
268
 
263
269
  ---
264
270
 
@@ -138,12 +138,16 @@ For state-machine fields (status, lifecycle), add `transition: { field, via|to,
138
138
 
139
139
  **Retired** (rejected at load time): bundled `actions.ts`, `_feature.ts`, `handlers/` directory, `defineActions()`, `*-actions.ts` filenames.
140
140
 
141
+ ## Grounding and acceptance
142
+
143
+ Start with the compact `docs/define/authoring-basics.md`, then retrieve the current references for the requested capabilities. Current canonical docs override this distillation. Keep a requirement inventory and test the final behavior, not only successful compilation. For assignment-style editing use the connected issue-tracker example: a relationship role requires matching resource-column names, and a reporter-only outer action gate would deny assignees before the join check. Preserve admin bypass, reporter success, and assignee lookup; validate submitted-user org membership separately from scope stamping. Use table-specific `defineAction` helpers for sibling actions, and `row(table)` for table-row output contracts.
144
+
141
145
  ## Defaults the compiler applies (audit before flagging "missing")
142
146
 
143
147
  Before recommending a fix for "missing X", check whether the compiler has already applied X as a default. Common cases that trip up audits:
144
148
 
145
- - **Soft-delete is the default.** Any table without explicit `crud.delete.mode: 'hard'` is soft-deleted; `deletedAt` and `deletedBy` are auto-injected at the SQL layer, and the firewall auto-AND-merges `{ field: 'deletedAt', isNull: true }`. Junction tables, including ones added via Drizzle interop, follow the same default.
146
- - **Audit fields are auto-injected.** `createdAt`, `createdBy`, `modifiedAt`, `modifiedBy` are added by the compiler — never declare them in user code. The audit-wrapper populates `createdBy` / `modifiedBy` from `ctx.userId` on insert/update. **`deletedBy` is auto-populated by the cascade machinery on soft-delete cascades, but standalone `unsafeDb` writes that bypass the wrapper need to set it explicitly.**
149
+ - **Soft-delete is the default.** Any table without explicit `crud.delete.mode: 'hard'` is soft-deleted; declare the soft-delete pair visibly, and the firewall auto-AND-merges `{ field: 'deletedAt', isNull: true }`. Junction tables, including ones added via Drizzle interop, follow the same default.
150
+ - **Audit columns must be visible.** Declare `...q.audit()` and `...q.softDelete()` on soft-delete feature tables; raw Drizzle tables need canonical literal declarations. The compiler validates these shapes. Scoped runtime writes populate managed values from verified context; do not supply them in insert values. Consult `define/schema` before recommending a migration or raw write.
147
151
  - **Sensitive columns are auto-masked.** Column names matching `email`, `phone`, `ssn`, `password`, `creditCard`, etc. get default masking with `show: { or: 'owner', roles: ['admin'] }` (or `roles: ['admin']` only when there's no `ownerId` column). A compile warning announces it. Absence of a `masking:` block does NOT mean the column is plain-text — it means the compiler-default is in effect. Only flag a "PII gap" if the user explicitly overrode the default with a weaker rule.
148
152
  - **Firewall is auto-derived for single-isolation tables.** A table with exactly one isolation column (e.g., `organizationId`) gets `firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }, { field: 'deletedAt', isNull: true }]` derived automatically. Two isolation columns → user must declare explicitly.
149
153
  - **Soft-delete cascade reaches cross-feature children.** When a parent is soft-deleted, every child table FK'd to it (same-feature AND cross-feature) is soft-deleted in the same transaction. The cascade UPDATE AND-merges the child's own firewall, so a parent delete in one tenant never touches another tenant's child. Fixed comprehensively for batch DELETE in v0.10.10 — older "cascade workarounds" in user code can be removed once the project is on v0.10.10+.
@@ -155,19 +159,13 @@ The scoped `db` (the action context's `db`) is a wrapper around Drizzle that:
155
159
 
156
160
  - **Does** auto-AND the resource's firewall WHERE clause into every `select` / `update` / `delete` query.
157
161
  - **Does** route soft-delete `delete()` calls to a `deletedAt`/`deletedBy` UPDATE.
158
- - **Does NOT** auto-populate insert values. A bare `db.insert(table).values({...})` writes whatever object you pass — `organizationId`, `ownerId`, etc. must be explicit. Audit fields (`createdBy`, etc.) ARE auto-populated by the audit-wrapper layer, but tenant-scope columns are not.
162
+ - **Does** populate declared tenant/owner scope columns from verified context on scoped inserts. Audit fields are populated at runtime too. Supply domain fields, not scope or managed audit values; use current `define/actions/scoped-db` guidance.
159
163
 
160
- When auditing an action that does `db.insert(...)`, verify that `organizationId` (and any other isolation columns) are passed explicitly. Don't assume the scoped client fills them in.
164
+ When auditing an action, distinguish caller scope stamping from submitted-pointer validation. Scope stamping does not prove that a submitted assignee belongs to the organization: validate that user through `authDb` and `getOrgMemberRole`. Declare feature-table FKs and same-org matches; consult canonical docs before recommending raw writes.
161
165
 
162
166
  ## Drizzle interop traps
163
167
 
164
- When a feature uses `sqliteTable(...)` (or `pgTable`) directly instead of the recommended `feature()` + `q.scope()` form, the user must own the column declarations. The compiler will inject `organizationId` / `deletedAt` at the SQL and runtime layers if a firewall predicate references them, but the user's TypeScript table type does NOT include those columns. Symptoms:
165
-
166
- - `eq(table.organizationId, ...)` won't typecheck.
167
- - `scopeTo({ organizationId })` falls back to string-keyed lookup.
168
- - The interop pattern works at runtime but is fragile.
169
-
170
- Fix: either declare the auto-injected columns explicitly in the `sqliteTable` body (so types align), OR migrate the table to `feature()` + `q.scope("organization")` which owns both sides.
168
+ Raw `sqliteTable(...)` / `pgTable` declarations must include their actual isolation columns and the canonical literal audit/soft-delete columns. Unknown spreads cannot substitute for those declarations. Read `define/schema` for the managed-column contract and migration command; do not rely on invisible injection to repair missing types or use casts to bypass it. Prefer `feature()` with `q.scope()`, `q.audit()`, and `q.softDelete()` for new tables.
171
169
 
172
170
  ## Security Principles
173
171
 
@@ -349,6 +349,25 @@ if (res.ok) {
349
349
  }
350
350
  ```
351
351
 
352
+ ### Authored atomic D1 actions
353
+
354
+ The matrix above describes generated HTTP batch/changeset handlers. An action's
355
+ [`db.batch(builders, options)`](/define/actions/scoped-db#atomic-d1-batches-and-concurrency)
356
+ is one native D1 transaction; it does not make an ordinary D1 `failFast` loop
357
+ transactional. SQL conditions and the action's idempotency commit marker join
358
+ that same transaction.
359
+
360
+ `DB_BATCH_ROLLED_BACK`, failed SQL batch conditions and a statement refused
361
+ by a `QB_TRIGGER_REJECTED` trigger or an [invariant](/define/invariants)
362
+ (`422 TRIGGER_REJECTED`, its code in `details.code`) report
363
+ `details.committed: false`. `DB_BATCH_POST_COMMIT_FAILED` reports
364
+ `details.committed: true`: the action's writes succeeded even though hooks failed.
365
+ `DB_BATCH_OUTCOME_UNKNOWN` reports `details.committed: null`: a timeout or lost
366
+ acknowledgement leaves the outcome unresolved. Reconcile committed/unknown
367
+ operations before taking further action; do not automatically resend with a new
368
+ key. Receipt retries return the saved response, `IDEMPOTENCY_COMMITTED`, or
369
+ `IDEMPOTENCY_OUTCOME_UNKNOWN` without repeating mutation code.
370
+
352
371
  ### Embeddings and Realtime
353
372
 
354
373
  When a resource has `embeddings` or `realtime` configured, queue messages
@@ -54,6 +54,23 @@ Vary: Authorization, Cookie, Cf-Access-Jwt-Assertion
54
54
 
55
55
  Every other JSON response produced under a cookie, bearer token, or [Cloudflare Access](/configure/cloudflare-access) assertion (writes, actions, auth, admin) is sent with `Cache-Control: private, no-store` unless the route sets its own policy, and always carries `Vary: Authorization, Cookie, Cf-Access-Jwt-Assertion`, so a proxy can never serve one user's body to another.
56
56
 
57
+ ## Server-side caching
58
+
59
+ ETags save transfer. The read still runs. To skip the query and render on
60
+ repeat reads, opt a resource into the user-scoped
61
+ [Workers Cache](/define/read#workers-cache) with
62
+ `read.cache: { engine: "workers", scope: "user", ttlSeconds }`. Every hit is
63
+ authenticated and authorized first. The ETag, `304` and `Cache-Control`
64
+ behavior on this page does not change.
65
+
66
+ Freshness comes from a [data epoch](/define/read#the-data-epoch). It is one
67
+ row in the features database holding a random token, replaced in the same D1
68
+ batch as every write the Worker commits there. A token is never reused, so a
69
+ D1 restore cannot make an old entry serve the wrong data. The trade-off is one
70
+ extra single-row write per write batch, plus one primary read of the token per
71
+ cached request. Writes made outside the Worker, such as `wrangler d1 execute`,
72
+ must mint a new token themselves.
73
+
57
74
  ## Client usage
58
75
 
59
76
  ### fetch API
@@ -55,6 +55,13 @@ For a resource named `jobs`, Quickback generates:
55
55
  | `PUT` | `/jobs/:id` | Upsert a record (requires config) |
56
56
  | `PUT` | `/jobs/batch` | Batch upsert multiple records (requires config) |
57
57
 
58
+ Each route is generated only for a verb the table declares, and only with the
59
+ `access` that verb declares: a verb that mounts a route without `access` is a
60
+ compile error (`ACCESS_REQUIRED`), never an endpoint open to every signed-in
61
+ caller. To keep a verb's settings without its route (a soft-delete mode used
62
+ by cascades), set `routes: false`. See
63
+ [Operations without access](/define/access#operations-without-access).
64
+
58
65
  A table a namespace claims mounts these under the namespace prefix
59
66
  (`/event/:eventId/jobs`), and every row they read or write is confined to the instance in the URL
60
67
  (see [Claimed tables are pinned to the URL instance](/define/areas#claimed-tables-are-pinned-to-the-url-instance)). With [`legacy`](/define/areas#keeping-the-old-url-legacy) it also keeps
@@ -438,6 +445,8 @@ DELETE /jobs/:id
438
445
  ```
439
446
 
440
447
  Deletes a record. Behavior depends on the `delete.mode` configuration.
448
+ The route needs `delete.access`; `delete: { mode: "soft", routes: false }`
449
+ keeps the mode (for cascades and actions) with no `DELETE` route.
441
450
 
442
451
  ### Soft Delete (default)
443
452
 
@@ -19,7 +19,7 @@ The generated API returns structured error responses with consistent fields acro
19
19
  | `422` | Unprocessable | `Idempotency-Key` reused with a different request or principal, or a stored encrypted value will not decrypt (`ENCRYPTION_UNREADABLE`), or a write carried a platform-managed JSON key (`JSON_KEY_RESTRICTED`) |
20
20
  | `428` | Precondition Required | `If-Match` sent where it can't anchor: no revision column, a batch endpoint (single-resource precondition), or the POST changeset variant |
21
21
  | `429` | Too Many Requests | Rate limit exceeded |
22
- | `500` | Internal Error | Uncaught throw — generic body, full error server-side. Also `DB_WRITE_OUTCOME_UNKNOWN`: a write passed the configured [`queryTimeoutMs`](/configure/providers#database-options) and may still have committed |
22
+ | `500` | Internal Error | Uncaught throw — generic body, diagnostics server-side. Also `DB_WRITE_OUTCOME_UNKNOWN`: a write passed the configured [`queryTimeoutMs`](/configure/providers#database-options) and may still have committed |
23
23
  | `503` | Service Unavailable | **Retryable.** `AUTH_REVOCATION_UNAVAILABLE`, or `DB_TIMEOUT` — a read passed the configured D1 deadline |
24
24
 
25
25
  ## Error Response Format — RFC 9457 Problem Details
@@ -352,7 +352,7 @@ form can show the conflict inline. `details.column` is the first of them.
352
352
  | `DB_TIMEOUT` | 503 | **Retryable.** A read passed [`queryTimeoutMs`](/configure/providers#database-options) (D1 only). The read had no side effects; retry. `details: { binding }` |
353
353
  | `DB_WRITE_OUTCOME_UNKNOWN` | 500 | A write passed `queryTimeoutMs`. D1 does not cancel the statement, so it may still commit after the response. **Re-read the record before retrying** — a blind retry can double-apply. `details: { binding, outcome: 'unknown' }` |
354
354
  | `ENCRYPTION_UNREADABLE` | 422 | A stored [`.encrypted()`](/define/encryption) value will not decrypt |
355
- | `TRIGGER_REJECTED` | 422 / 403 | A [before-trigger](/define/triggers#rejection-status) refused the write; nothing was persisted. `layer: "trigger"`, `details.code` for a prefixed `sql:` rejection |
355
+ | `TRIGGER_REJECTED` | 422 / 403 | A [before-trigger](/define/triggers#rejection-status) refused the write; nothing was persisted. `layer: "trigger"`, `details.code` for a prefixed `sql:` rejection or an [invariant](/define/invariants) |
356
356
 
357
357
  The `details.column` field is only present when the driver's error message identified the offending column (SQLite/D1 do; some PG variants don't).
358
358
 
@@ -468,6 +468,9 @@ With `tenancy.isolation: 'durable-object'`, responses about an organization's ow
468
468
  | `TENANT_RPC_VERSION_MISMATCH` | The edge and tenant Workers disagree on the RPC contract; deploy the tenant Worker first |
469
469
  | `TENANT_AUTHORIZATION_EPOCH_CHANGED` | A restore advanced the tenant's authorization epoch; credentials issued before it are refused |
470
470
  | `TENANT_RESTORE_PENDING` | A restore is pending or unreconciled; sync or cancel it first |
471
+ | `STORAGE_FILE_NOT_READY` | A tenant upload is not verified (or is unavailable after a restore); `details.status` says which (409) |
472
+ | `STORAGE_FILE_BRIDGE_EDGE_OUTDATED` / `STORAGE_FILE_BRIDGE_UNAVAILABLE` | The tenant file bridge cannot sign here: the edge Worker is older than the object, or the call is not a forwarded request (a job or alarm) (503) |
473
+ | `TENANT_FILE_GRANT_FAILED` / `TENANT_FILES_PURGING` / `TENANT_BRIDGE_*` / `TENANT_FILE_*` | The edge refused (or could not sign) a tenant file grant: a forged or malformed envelope, a reused key, a stale generation, or a purge cleanup in progress |
471
474
  | `TENANT_RESTORE_TOO_LARGE` | Operator restore: the dump exceeds the restore limit (413) |
472
475
  | `TENANT_OPERATION_FAILED` | Operator route refused or failed (409); `detail` says why |
473
476
  | `TENANT_COMMAND_INVALID` | A tenant command request failed its schema |
@@ -475,6 +478,8 @@ With `tenancy.isolation: 'durable-object'`, responses about an organization's ow
475
478
  | `TENANT_COMMAND_REPLY_INVALID` | The tenant object answered a command with a malformed reply |
476
479
  | `TENANT_JOB_INVALID` | A tenant job message is invalid |
477
480
  | `TENANT_JOB_CALL_ONLY` | A result job was delivered instead of called (callTenantJob) |
481
+ | `TENANT_JOB_PLACEMENT` | A tenant job was sent to an object of the wrong placement (a partition job outside its partition, an organization job in a partition), or its message names another partition |
482
+ | `TENANT_JOB_STALE_GENERATION` | A queued tenant job was delivered under a restore generation the object no longer has; it is dropped, never run |
478
483
  | `TENANT_JOB_FAILED` | A called tenant job failed |
479
484
  | `TENANT_JOB_REPLY_INVALID` | The tenant object answered a job call with a malformed reply |
480
485
  | `TENANT_JOB_RESULT_INVALID` | A tenant job result is not serializable |
@@ -634,3 +639,27 @@ error. With it, they still never carry a bound value — the message, cause and
634
639
  stack go through the same [redaction](#bound-values-never-leave-the-database)
635
640
  as the server log. `1` and `true` turn it on; any other value leaves it off. Leave it
636
641
  unset in production.
642
+
643
+ ## Tenant request diagnostics
644
+
645
+ With Durable Object tenancy, `tenant.request.failed`,
646
+ `tenant.data_keys.unavailable`, and `tenant.rpc.failed` emit structured logs.
647
+ Generated action execution failures emit `action.execute.failed`. Each includes
648
+ a UUID `requestId`, the registered route template, HTTP method, operation
649
+ `stage`, and up to four entries in `causes`. A cause contains an allowlisted
650
+ error name/code, a fixed category (such as `missing_table`, `query_failed`, or
651
+ `network_connection_lost`), and up to eight bundle locations. Unknown errors
652
+ retain the category `unknown`; arbitrary messages are never copied.
653
+
654
+ The edge forwards the correlation ID to the tenant and returns it in
655
+ `x-request-id`. Non-UUID inbound IDs are replaced for these diagnostics. Search
656
+ both Workers by that ID, then use the Worker event's deployed version to map
657
+ `index.js` / `worker.js` (or `.mjs`) line and column locations to source. Edge
658
+ forwarding routes may be wildcard templates; the tenant/action log identifies
659
+ the matched handler.
660
+
661
+ These diagnostics omit SQL, bound values, raw paths, queries, error messages,
662
+ function names, arbitrary filenames, and credential/key material. They do not
663
+ change HTTP status codes, encryption's fail-closed behavior, or retry policy.
664
+ They diagnose a failure without assuming that a data-key warning necessarily
665
+ caused the request to fail.
@@ -219,6 +219,12 @@ WHERE (title LIKE '%engineer%' OR department LIKE '%engineer%')
219
219
 
220
220
  Only columns defined with `text()` in your Drizzle schema are searchable. Non-text columns (integers, timestamps, UUIDs, blobs) are automatically excluded.
221
221
 
222
+ A resource that declares [`read.search`](/define/read#full-text-search-readsearch)
223
+ (D1) uses SQLite FTS5 instead: whitespace-separated literal terms that must
224
+ all match whole tokens in the indexed fields, ordered by field-match relevance
225
+ with offset pagination unless `?sort=` is given. Its OpenAPI operations
226
+ describe the exact semantics under `x-search`.
227
+
222
228
  ## Complete Example
223
229
 
224
230
  Combine all query parameters together:
@@ -5,6 +5,7 @@ listed separately; detailed setup instructions live in the product guides.
5
5
 
6
6
  ## Coming next
7
7
 
8
+ - **One sign-in for dedicated apps.** Enter through Cloudflare Access while keeping your workspace permissions in place. [Learn more](/configure/cloudflare-access#native-browser-applications-opt-in).
8
9
  - **A lighter migration history.** Consolidate D1 migrations into a clean starting point, with checks that protect existing databases. [Learn more](/platform/database/schema-baselines).
9
10
 
10
11
  ## November 2026
@@ -420,7 +420,7 @@ Projects without an attendee server compile byte-identically.
420
420
  - **Its hostname is bound as a custom domain on the same Worker automatically** — no `providers.runtime.config.routes` entry needed. A host the target already routes (its API host, say) adds no second route. See [Multi-Domain Architecture](/configure/domains#named-mcp-server-hosts).
421
421
  - The URL needs a path (`https://mcp.attend.vip/guest`, or `…/mcp` on a dedicated host): the host root's `/.well-known/oauth-protected-resource` is the default server's document. `https://` only, no port, query or fragment, and the host can't be a CMS, Account, admin, app, auth or webhook host — their hostname middleware would serve or block the MCP path. On a host the target already serves (its API or `BETTER_AUTH_URL` host, a `routes` entry), the path can't be `/mcp` or any named server's `path` either: the public URL is matched first and would shadow that server there.
422
422
 
423
- With [named environments](/configure/domains#named-environments), key `publicUrl` by environment name. Every environment runs the same bundle, so the compiler stamps `QUICKBACK_ENVIRONMENT = "<name>"` into each target's vars whenever a `publicUrl` is keyed by environment; the Worker reads it to know which public URL is its own. Only that URL is routed and accepted as an audience on that target — `mcp-dev.attend.vip` is never a resource of production. An environment without an entry serves the server at `BETTER_AUTH_URL + path` only. Keys must be plain environment names (a letter, then letters, digits, `-` or `_`), and never an `Object.prototype` member such as `constructor`. A host owned by another target, or a `domains: 'none'` target with an entry, fails the compile.
423
+ With [named environments](/configure/domains#named-environments), key `publicUrl` by environment name. Every environment runs the same bundle, so the compiler stamps `QUICKBACK_ENVIRONMENT = "<name>"` into each target's vars whenever a `publicUrl` is keyed by environment (or the `apiKey` plugin is on); the Worker reads it to know which public URL is its own. Only that URL is routed and accepted as an audience on that target — `mcp-dev.attend.vip` is never a resource of production. An environment without an entry serves the server at `BETTER_AUTH_URL + path` only. Keys must be plain environment names (a letter, then letters, digits, `-` or `_`), and never an `Object.prototype` member such as `constructor`. A host owned by another target, or a `domains: 'none'` target with an entry, fails the compile.
424
424
 
425
425
  ### Login and consent pages
426
426