Brooooooklyn · Jul 22, 2026 · Jul 15, 2026 · Jul 15, 2026 · Jul 15, 2026 · Jul 15, 2026
diff --git a/docs/guide/auth.md b/docs/guide/auth.md
@@ -249,6 +249,14 @@ Void manages Better Auth migrations as part of the normal Void migration flow:
 - deploy runs auth migrations together with app migrations
 - users do not run a separate Better Auth CLI path
 
+This applies to `void deploy` (the managed platform), which creates the Better Auth
+tables at runtime after dispatch. Deploying to your own Cloudflare account with
+[`--backend cloudflare`](/integrations/cloudflare) does **not** run that step: there,
+your checked-in `db/migrations/*.sql` must already produce the Better Auth schema, and
+deploy fails closed if they do not. Define the tables in `db/schema.ts` and run
+`void db generate` — Drizzle's `.unique()` and `.references()` are opt-in, and the
+constraints are verified too. See [#274](https://github.com/voidzero-dev/void/issues/274).
+
 ## Unsupported Modes
 
 Void-managed Better Auth is supported only for Cloudflare Void apps in v1.

diff --git a/docs/guide/deployment.md b/docs/guide/deployment.md
@@ -106,6 +106,6 @@ Connect the repository to your project once with `void github connect <project>
 
 ## Other Targets
 
-If you prefer to deploy directly to your own Cloudflare account instead of using Void's managed platform, see the [Cloudflare integration guide](../integrations/cloudflare.md).
+If you prefer to deploy directly to your own Cloudflare account instead of using Void's managed platform, run `void deploy --backend cloudflare` (add `--provision` on the first deploy to create the D1/KV/R2/Queues/Hyperdrive resources your app needs). This uses your local wrangler auth and root `wrangler.jsonc` -- pin an account (`account_id` or `CLOUDFLARE_ACCOUNT_ID`) and keep real secrets in `wrangler secret put` rather than `.env`. `wrangler login` is enough to authenticate, with one exception: provisioning a **Hyperdrive** config for the first time needs `CLOUDFLARE_API_TOKEN`, because wrangler exposes no machine-readable Hyperdrive list for Void to check against (an already-provisioned Hyperdrive app deploys fine under `wrangler login`). In v1 it deploys **full Void apps on the Cloudflare Workers target** (D1/KV/R2/Queues/Hyperdrive; auth and ISR on D1/SQLite); framework SSR (TanStack Start, React Router, vinext, SvelteKit, Nuxt, Analog, Astro), static/SPA/SSG apps (including `output: "static"`), WebSocket/Durable Object apps (`*.ws.ts`), a custom `migrations_pattern`, `--skip-build`, `node`/`bun`/`deno` targets, and PostgreSQL apps with auth all fail closed with guidance. Auth apps must ship checked-in migrations that produce the Better Auth schema. Provision is a single-operator, dev-machine step and is disabled in CI. See the [Cloudflare integration guide](../integrations/cloudflare.md#deploy-to-your-own-cloudflare-account) for the full walk-through and scope.
 
 To deploy to Node.js, Bun, or Deno instead of Cloudflare, set [`target`](../reference/config.md) in `void.json`. This builds a standalone server you can run anywhere, including Docker, Railway, and Fly.io. These targets do not have access to Void platform features such as D1, KV, R2, built-in auth, Workers AI, or cron scheduling. See the [Node.js, Bun, and Deno guide](../integrations/nodejs-bun-deno.md).
diff --git a/docs/guide/env-vars.md b/docs/guide/env-vars.md
@@ -109,15 +109,23 @@ In practice `env.ts` should only import schema helpers from `void/env` and — a
 
 Void uses Vite's standard `.env` convention to populate the schema:
 
-| File                    | Loaded in dev | Shipped on deploy  |
-| ----------------------- | ------------- | ------------------ |
-| `.env`                  | yes           | yes (`plain_text`) |
-| `.env.local`            | yes           | no                 |
-| `.env.production`       | yes           | yes (`plain_text`) |
-| `.env.production.local` | yes           | no                 |
+Whether a file's values ship depends on which deploy path you use:
+
+| File                    | Loaded in dev | Shipped by `void deploy` | Shipped by `--backend cloudflare` |
+| ----------------------- | ------------- | ------------------------ | --------------------------------- |
+| `.env`                  | yes           | yes (`plain_text`)       | yes (worker `vars`)               |
+| `.env.local`            | yes           | no                       | **yes** (worker `vars`)           |
+| `.env.production`       | yes           | yes (`plain_text`)       | yes (worker `vars`)               |
+| `.env.production.local` | yes           | no                       | **yes** (worker `vars`)           |
 
 `.local` files are gitignored by convention — use them for secrets you don't want in source control.
 
+::: warning `.local` files are not deploy-excluded on `--backend cloudflare`
+Managed `void deploy` reads only `.env` and `.env.production`, so a `.local` file keeps secrets off the platform. The self-host `void deploy --backend cloudflare` path instead runs Vite's production env loading, which reads all four files and bakes them into the worker's `vars` as plaintext. A value that is also `export`ed in the shell with the same value is stripped back out, so this bites hardest in CI, where the variable usually only exists in the file.
+
+On that path, keep real secrets out of every `.env*` file and use `wrangler secret put <NAME>` instead. See [Cloudflare deploy](/integrations/cloudflare).
+:::
+
 ### Dotenv variable expansion
 
 Values can reference other keys defined in the same (or earlier-precedence) `.env` file using `${VAR}` or `$VAR`:

diff --git a/docs/guide/queues.md b/docs/guide/queues.md
@@ -10,6 +10,10 @@ Void supports Cloudflare Queues for asynchronous message processing from a top-l
 
 Create files in `queues/**/*.ts`; `.mts`, `.js`, and `.mjs` also work. The queue name is inferred from the filename. For example, `queues/emails.ts` creates a queue named `"emails"`, and `queues/order/notifications.ts` creates `"order/notifications"`.
 
+::: warning Nested files produce a name that cannot be deployed
+Cloudflare queue names allow only letters, digits and `-`, so a name containing `/` is rejected when the queue is provisioned — on both the managed platform and a self-hosted `--backend cloudflare` deploy. Nested files work in local development, but keep queue files flat (`queues/order-notifications.ts` → `"order-notifications"`) for any app you intend to deploy.
+:::
+
 Each queue file should export a default handler wrapped with [`defineQueue`](../reference/api.md#definequeuet-handler). The generic `<T>` parameter defines the message body type. That is the type of each `msg.body` in the batch, and it is also used by the typed `queues` proxy for `send()` calls.
 
 ```ts