void 0.21.9 → 0.23.0

package/skills/void/docs/guide/ai.md

@@ -10,6 +10,14 @@ Void provides a typed AI client for Workers AI and Cloudflare's [AI Gateway](htt
 import { ai } from 'void/ai';
 ```
 
+## Handling usage limits
+
+Every AI operation is lazy and must be executed with `.match({ ok, limited })`. Both handlers are required, including for provider-native requests, model listing and document conversion. Return a useful fallback from `limited`, or use `limit.response({ message: 'AI is temporarily unavailable.' })` to send a structured HTTP 429. Limits expose `resource`, `reason`, and an optional `retryAt`. Other failures still reject.
+
+Do not await the operation itself; await its `.match()` call. TypeScript checks your handlers and the resulting success/fallback union.
+
+Streaming responses end with a `void:error` SSE event if generation is interrupted after the response starts. A recognized quota interruption calls your `limited` handler and emits `void:limit`, preserving the message from `limit.response()`. `fetchStream()` throws on either terminal event so your UI can exit its generating state. This also applies to streaming provider responses and `ai.run()` with `stream: true`.
+
 ## Basic Usage
 
 Call `ai.run()` with a model name and inputs. Model names and input types are fully typed from `@cloudflare/workers-types`.
@@ -21,9 +29,11 @@ import { ai } from 'void/ai';
 export const POST = defineHandler(async (c) => {
   const { prompt } = await c.req.json();
 
-  const result = await ai.run('@cf/meta/llama-3.3-70b-instruct-fp8-fast', {
-    messages: [{ role: 'user', content: prompt }],
-  });
+  const result = await ai
+    .run('@cf/meta/llama-3.3-70b-instruct-fp8-fast', {
+      messages: [{ role: 'user', content: prompt }],
+    })
+    .match({ ok: (result) => result, limited: (limit) => limit.response() });
 
   return c.json(result);
 });
@@ -42,23 +52,27 @@ import { ai } from 'void/ai';
 export const POST = defineHandler(async (c) => {
   const { prompt } = await c.req.json();
 
-  return ai.stream('@cf/meta/llama-3.3-70b-instruct-fp8-fast', {
-    messages: [{ role: 'user', content: prompt }],
-  });
+  return ai
+    .stream('@cf/meta/llama-3.3-70b-instruct-fp8-fast', {
+      messages: [{ role: 'user', content: prompt }],
+    })
+    .match({ ok: (result) => result, limited: (limit) => limit.response() });
 });
 ```
 
-`ai.stream()` calls `ai.run()` with `stream: true` and wraps the result in a `Response` with `content-type: text/event-stream` and `cache-control: no-cache` headers.
-
 ## Listing Models
 
 Use `ai.models()` to list available models:
 
 ```ts
-const models = await ai.models();
+const models = await ai
+  .models()
+  .match({ ok: (result) => result, limited: (limit) => limit.response() });
 
 // Filter by task
-const textModels = await ai.models({ task: 'Text Generation' });
+const textModels = await ai
+  .models({ task: 'Text Generation' })
+  .match({ ok: (result) => result, limited: (limit) => limit.response() });
 ```
 
 ## Markdown Conversion
@@ -66,7 +80,9 @@ const textModels = await ai.models({ task: 'Text Generation' });
 Use `ai.toMarkdown()` to convert documents to markdown:
 
 ```ts
-const result = await ai.toMarkdown([{ name: 'document.pdf', blob: pdfBytes }]);
+const result = await ai
+  .toMarkdown([{ name: 'document.pdf', blob: pdfBytes }])
+  .match({ ok: (result) => result, limited: (limit) => limit.response() });
 ```
 
 ## Local Development
@@ -80,12 +96,11 @@ npm run dev
 
 When the app imports `void/ai`, Void enables a remote Workers AI binding during
 development and preview. Requests use your Cloudflare account and its allowance;
-Workers AI has no local simulator. The session uses the same keychain-backed
-Cloudflare login as the CLI, or `CLOUDFLARE_API_TOKEN` in an automated environment.
+Workers AI has no local simulator. Use your Cloudflare login or
+`CLOUDFLARE_API_TOKEN` in an automated environment.
 
 For a team platform, use `void connect <platform-url>` and link your project.
-Development requests use that platform's HTTPS proxy and usage controls.
-Credentials are injected into server bindings automatically.
+Development requests use that platform's account and usage limits.
 
 ## Usage Limits
 
@@ -93,55 +108,54 @@ Workers AI usage is measured in [neurons](https://developers.cloudflare.com/work
 On a direct deployment, usage belongs to your Cloudflare account. Provider-native
 requests also use your provider credentials and their billing terms.
 
-A team platform tracks usage in its own account and can apply per-user limits.
-Fresh self-hosted installations assign the `custom` profile, which has no
-platform-imposed AI allowance. Administrators can select a quota profile through
-[Platform Administration](./platform-administration.md). These profiles do not
-subscribe users to a commercial plan or charge them automatically; the operator
-remains responsible for its infrastructure and provider accounts.
+A team platform uses its own Cloudflare account and may apply per-user limits. Ask your administrator about the available allowance.
 
 ## Cloudflare Gateway Models
 
 `ai.run()` mirrors Cloudflare's `env.AI.run()` model naming and input schemas. Third-party models use Cloudflare model IDs and Cloudflare-managed credentials.
 
 ```ts
-const result = await ai.run('google/gemini-2.5-flash', {
-  contents: [
-    {
-      role: 'user',
-      parts: [{ text: 'Explain Durable Objects in one paragraph.' }],
-    },
-  ],
-});
+const result = await ai
+  .run('google/gemini-2.5-flash', {
+    contents: [
+      {
+        role: 'user',
+        parts: [{ text: 'Explain Durable Objects in one paragraph.' }],
+      },
+    ],
+  })
+  .match({ ok: (result) => result, limited: (limit) => limit.response() });
 ```
 
 OpenAI-compatible models use OpenAI-style `messages`:
 
 ```ts
-const result = await ai.run('openai/gpt-4.1-mini', {
-  messages: [{ role: 'user', content: 'Summarize this deploy.' }],
-});
+const result = await ai
+  .run('openai/gpt-4.1-mini', {
+    messages: [{ role: 'user', content: 'Summarize this deploy.' }],
+  })
+  .match({ ok: (result) => result, limited: (limit) => limit.response() });
 ```
 
 Pass Cloudflare AI Gateway options as the third argument:
 
 ```ts
-const result = await ai.run(
-  'openai/gpt-4.1-mini',
-  {
-    messages: [{ role: 'user', content: 'Summarize this deploy.' }],
-  },
-  {
-    gateway: {
-      skipCache: true,
+const result = await ai
+  .run(
+    'openai/gpt-4.1-mini',
+    {
+      messages: [{ role: 'user', content: 'Summarize this deploy.' }],
+    },
+    {
+      gateway: {
+        skipCache: true,
+      },
     },
-  },
-);
+  )
+  .match({ ok: (result) => result, limited: (limit) => limit.response() });
 ```
 
-Managed requests use the installation's gateway and project metadata. Direct
-requests use your Workers AI binding; provider-native requests require your own
-`ai.gateway` configuration.
+For provider-native requests on a direct deployment, configure [`ai.gateway`](../integrations/cloudflare.md#ai-self-host).
 
 ## Provider-Native Requests
 
@@ -159,13 +173,16 @@ import { ai } from 'void/ai';
 export const POST = defineHandler(async (c) => {
   const { prompt } = await c.req.json();
 
-  const response = await ai.provider('openai').fetch('/chat/completions', {
-    body: {
-      model: 'gpt-4o',
-      messages: [{ role: 'user', content: prompt }],
-      max_tokens: 512,
-    },
-  });
+  const response = await ai
+    .provider('openai')
+    .fetch('/chat/completions', {
+      body: {
+        model: 'gpt-4o',
+        messages: [{ role: 'user', content: prompt }],
+        max_tokens: 512,
+      },
+    })
+    .match({ ok: (result) => result, limited: (limit) => limit.response() });
 
   const result = await response.json();
   return c.json(result);
@@ -186,7 +203,8 @@ const response = await ai
         },
       ],
     },
-  });
+  })
+  .match({ ok: (result) => result, limited: (limit) => limit.response() });
 
 const result = await response.json();
 ```
@@ -204,7 +222,8 @@ const response = await ai
   })
   .fetch('/v1/respond', {
     body: { prompt: 'Hello' },
-  });
+  })
+  .match({ ok: (result) => result, limited: (limit) => limit.response() });
 ```
 
 ### Image Generation
@@ -214,38 +233,45 @@ Use `ai.run()` or `ai.image()` for Cloudflare-native image models:
 ```ts
 export const POST = defineHandler(async (c) => {
   const { prompt } = await c.req.json();
-  return ai.image('@cf/black-forest-labs/flux-1-schnell', { prompt });
+  return ai
+    .image('@cf/black-forest-labs/flux-1-schnell', { prompt })
+    .match({ ok: (result) => result, limited: (limit) => limit.response() });
 });
 ```
 
-Use `ai.provider().fetch()` for provider-native image APIs:
+Use `ai.provider().fetch()` for provider-native image APIs. Match the [provider's request schema](https://developers.openai.com/api/reference/resources/images/methods/generate):
 
 ```ts
 export const POST = defineHandler(async (c) => {
   const { prompt } = await c.req.json();
 
-  return ai.provider('openai').fetch('/images/generations', {
-    body: {
-      model: 'gpt-image-1.5',
-      prompt,
-      size: '1024x1024',
-      response_format: 'b64_json',
-    },
-  });
+  return ai
+    .provider('openai')
+    .fetch('/images/generations', {
+      body: {
+        model: 'gpt-image-2.5-sunburst',
+        prompt,
+        size: '1024x1024',
+      },
+    })
+    .match({ ok: (result) => result, limited: (limit) => limit.response() });
 });
 ```
 
-For multipart provider APIs, pass a `FormData` body. Void serializes the body through the proxy and reconstructs it before forwarding to AI Gateway:
+For multipart provider APIs, pass `FormData`:
 
 ```ts
 export const POST = defineHandler(async (c) => {
   const body = await c.req.parseBody();
   const form = new FormData();
-  form.set('model', 'gpt-image-1.5');
+  form.set('model', 'gpt-image-2.5-sunburst');
   form.set('prompt', String(body.prompt));
   form.set('image', body.image as Blob, 'source.png');
 
-  return ai.provider('openai').fetch('/images/edits', { body: form });
+  return ai
+    .provider('openai')
+    .fetch('/images/edits', { body: form })
+    .match({ ok: (result) => result, limited: (limit) => limit.response() });
 });
 ```
 
@@ -290,22 +316,6 @@ For local development, add it to `.env` in your project root:
 OPENAI_API_KEY=sk-...
 ```
 
-If the key is missing at runtime, `ai.provider().fetch()` throws a descriptive error telling you which env var to set.
-
 ### Streaming with Provider-Native APIs
 
-Provider-native streaming APIs return the provider response directly:
-
-```ts
-export const POST = defineHandler(async (c) => {
-  const { prompt } = await c.req.json();
-
-  return ai.provider('openai').fetch('/chat/completions', {
-    body: {
-      model: 'gpt-4o',
-      messages: [{ role: 'user', content: prompt }],
-      stream: true,
-    },
-  });
-});
-```
+Return the provider response directly. For example, add `stream: true` to the OpenAI request body shown above.

package/skills/void/docs/guide/app-types.md

@@ -16,27 +16,16 @@ The type is auto-detected from your project structure, or you can set it explici
 
 In a Void app, Void handles server routing and deployment. Use React, Vue, Svelte, or Solid for server-rendered pages, or build a frontend with any library that works with Vite.
 
-All Void features that involve backend logic are available in this mode, including [server routing](./server-routing.md), [pages mode](./pages-routing/overview.md), [authentication](./auth.md), [typed fetch](./typed-fetch.md), [cron jobs](./jobs.md), and [queues](./queues.md).
-
 A Void app can be **API-only** (just `routes/`), a **SPA + API** (frontend in `src/` with API routes), or **full-stack with pages mode** (server-rendered pages in `pages/` with co-located data loading):
 
 <VoidAppFileTree annotations />
 
-Your worker handles API routes, page rendering, and (optionally) [custom SSR](./ssr.md). Static assets are served from the edge via per-worker assets. Cloudflare bindings (D1, KV, R2) are [inferred from your source code](../reference/resource-inference.md) and provisioned automatically.
+Void serves API routes, page rendering, and optional [custom SSR](./ssr.md) alongside static assets. Resources such as D1, KV, and R2 are [inferred from your code](../reference/resource-inference.md) and provisioned when you deploy.
 
 Void apps can also use [`output: 'static'`](./ssg.md) to pre-render all pages at build time. That gives you a fully static site that can be deployed anywhere, with no Cloudflare Worker required.
 
 **Deploy:** `void deploy` builds the app, provisions resources, applies migrations, and uploads it to your saved Cloudflare or Void target. See [Deployment](./deployment.md) for setup.
 
-**Detected when any of these exist:**
-
-- `routes/` directory
-- `pages/` directory
-- `middleware/` directory
-- `crons/` directory
-- `queues/` directory
-- Custom SSR entry (`src/main.ssr.ts` or `src/main.ssr.tsx`)
-
 ## Meta Frameworks
 
 Void supports deploying Vite-based meta-framework apps with `void deploy`. The framework owns routing and SSR. Void handles [binding inference](../reference/resource-inference.md), [typed DB queries](./database.md), migrations, and deployment.
@@ -50,15 +39,11 @@ Void supports deploying Vite-based meta-framework apps with `void deploy`. The f
 | [Analog](https://analogjs.org/)                     | `@analogjs/platform`    | [Guide](../integrations/frameworks/analog.md)         |
 | [Astro](https://astro.build/)                       | `astro`                 | [Guide](../integrations/frameworks/astro.md)          |
 
-Add `voidPlugin()` to the framework's Vite config to get binding inference, typed DB generation, migration management, cron jobs, queues, and caching. Void-managed auth is not supported in framework mode; use Better Auth's official integration for your framework. See the [Meta Frameworks Integration](../integrations/frameworks/overview.md) for the full feature matrix, deploy pipeline, and per-framework setup guides.
-
-**Deploy:** `void deploy` runs your framework's build, provisions resources, applies migrations, and deploys to the selected target. Your framework continues to handle routing and rendering.
-
-**Detected when** any of the above packages is in your dependencies.
+Add `voidPlugin()` to the framework's Vite config to get binding inference, typed DB generation, migration management, cron jobs, queues, and caching. Void-managed auth is not supported in framework mode; use Better Auth's official integration for your framework. See the [Meta Frameworks Integration](../integrations/frameworks/overview.md) for supported features and setup guides.
 
 ## Pre-built Static Sites
 
-Any project that produces static files, whether that is an SPA, a static site, or a plain directory. Assets are served directly from the edge, and a minimal passthrough worker is generated automatically. You do not need to write worker code yourself.
+Any project that produces static files, whether that is an SPA, a static site, or a plain directory. Void serves the assets without requiring application code.
 
 **SPAs** (client-side single-page apps) fall back all non-file paths to `index.html` with a 200 status, so client-side routing works out of the box. Detected when `vite` is a dependency and no backend files exist.
 
@@ -116,20 +101,6 @@ To deploy only the static output, set:
 { "inference": { "appType": "static" } }
 ```
 
-## Auto-Detection
-
-When running `void deploy` and no `inference.appType` is set in `void.config.ts`, the detection logic runs in this order:
-
-| Priority | Condition                                                                                                       | Type                                        |
-| -------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
-| 1        | `--dir` flag                                                                                                    | Static (or SPA with `--spa`)                |
-| 2        | Known SSG in dependencies (`vitepress`, `@docusaurus/core`)                                                     | Static, builds with SSG CLI                 |
-| 2a       | ...and backend files also exist                                                                                 | Refused — set `inference.appType` yourself  |
-| 3        | `@tanstack/react-start`, `@react-router/dev`, `@sveltejs/kit`, `nuxt`, `@analogjs/platform`, or `astro` in deps | Framework                                   |
-| 4        | Backend files exist (`routes/`, `pages/`, `middleware/`, `crons/`, `queues/`, SSR entry)                        | Void app                                    |
-| 5        | `vite` or `vite-plus` in dependencies, no backend files                                                         | SPA, builds with `vite build` or `vp build` |
-| 6        | `dist/index.html` or `./index.html` exists                                                                      | Static (no build step)                      |
-
 ## Explicit Configuration
 
 To lock the app type and skip auto-detection, set `inference.appType` in [`void.config.ts`](../reference/config.md):

package/skills/void/docs/guide/auth.md

@@ -5,7 +5,7 @@ outline: deep
 # Authentication
 
 ::: warning ⚠️ Void Apps Only
-Void-managed auth currently works only for Void apps. Meta-framework mode is not supported yet.
+Void-managed auth requires a native Void app on Cloudflare. For meta-frameworks or Node.js, Bun, and Deno, use Better Auth directly.
 :::
 
 Void configures [Better Auth](https://www.better-auth.com/) for your app, including its database connection, API routes, and client. Start with email and password, or add a social login provider.
@@ -14,17 +14,7 @@ Void configures [Better Auth](https://www.better-auth.com/) for your app, includ
 
 ### 1. Enable auth
 
-Add a provider to `void.config.ts`. Email/password is the default, so the simplest config is:
-
-```json
-{
-  "auth": {
-    "providers": ["email"]
-  }
-}
-```
-
-You can also skip this step entirely. Auth activates automatically when you import from `void/auth` or `void/client`.
+Import `auth` from `void/client` to enable email/password auth automatically. Use [configuration](#config) to add social providers.
 
 ### 2. Sign up and sign in
 
@@ -36,14 +26,14 @@ import { auth } from 'void/client';
 // sign up
 await auth.signUp.email({
   email: 'alice@example.com',
-  password: 's3cret',
+  password: 'example-password-123',
   name: 'Alice',
 });
 
 // sign in
 await auth.signIn.email({
   email: 'alice@example.com',
-  password: 's3cret',
+  password: 'example-password-123',
 });
 ```
 
@@ -83,8 +73,6 @@ export const loader = defineHandler(() => {
 await auth.signOut();
 ```
 
-The rest of this page covers configuration, server helpers, and advanced customization in detail.
-
 ## Config
 
 Auth turns on automatically when you:
@@ -94,9 +82,7 @@ Auth turns on automatically when you:
 - add `auth` to `void.config.ts`
 - add a root-level `auth.ts` file
 
-The simplest setup is no config at all. Email/password auth is enabled by default.
-
-Example:
+Email/password is enabled by default. To add social providers:
 
 ```json
 {
@@ -117,38 +103,9 @@ For example, `github` uses:
 
 ## Client Usage
 
-`void/client` exports a preconfigured Better Auth client:
-
-```ts
-import { auth } from 'void/client';
-
-await auth.signUp.email({
-  email: 'alice@example.com',
-  password: 's3cret',
-  name: 'Alice',
-});
-
-await auth.signIn.email({
-  email: 'alice@example.com',
-  password: 's3cret',
-});
-
-await auth.signOut();
-```
-
-The client uses Better Auth's API, configured at `/api/auth`.
-
-See the official [Better Auth client docs](https://www.better-auth.com/docs/concepts/client) for the full client API.
-
-Framework-specific clients are selected automatically:
-
-- React pages apps use `better-auth/react`
-- Vue pages apps use `better-auth/vue`
-- Svelte pages apps use `better-auth/svelte`
-- Solid pages apps use `better-auth/solid`
-- other Void apps use `better-auth/client`
+The `auth` client uses [Better Auth's client API](https://www.better-auth.com/docs/concepts/client) at `/api/auth`. Void selects the client for your framework automatically.
 
-For advanced usage, `void/client` also exports `createAuthClient`.
+For a custom client, import `createAuthClient` from `void/client`.
 
 ## Server Usage
 
@@ -162,67 +119,13 @@ import { getSession, getUser, requireAuth } from 'void/auth';
 - `getSession()` returns `{ user, session } | null`
 - `requireAuth(c)` returns the authenticated user or throws `401`
 
-Example:
-
-```ts
-import { defineHandler } from 'void';
-import { requireAuth } from 'void/auth';
-
-export const GET = defineHandler((c) => {
-  const user = requireAuth(c);
-  return { email: user.email };
-});
-```
-
-### `AuthUser`
-
-`AuthUser` maps to Better Auth's core user type:
-
-```ts
-interface AuthUser {
-  id: string;
-  email: string;
-  emailVerified: boolean;
-  name: string;
-  image?: string | null;
-  createdAt: Date;
-  updatedAt: Date;
-}
-```
-
-### `AuthSession`
-
-`AuthSession` maps to Better Auth's core session type:
-
-```ts
-interface AuthSession {
-  id: string;
-  token: string;
-  userId: string;
-  expiresAt: Date;
-  createdAt: Date;
-  updatedAt: Date;
-  ipAddress?: string | null;
-  userAgent?: string | null;
-}
-```
+Import `AuthUser` and `AuthSession` from `void/auth` for type annotations. See their fields in the [API reference](../reference/api/auth.md#authuser).
 
 ## Behavior
 
-When auth is active, Void configures Better Auth with these conventions:
-
-- mount path: `/api/auth/*`
-- email/password enabled by default unless `auth.providers` is set without `"email"`
-- `auth.providers` can enable any built-in Better Auth social provider
-- deployed apps need an auth secret via `BETTER_AUTH_SECRET`
-- D1/SQLite uses the app `DB` binding
-- PostgreSQL apps (`"database": "pg"`) use the app `HYPERDRIVE` binding
-
-Auth sessions live in the same database system as the rest of the app.
-
-On both deployment targets, Void keeps an existing `BETTER_AUTH_SECRET` or generates one when it's missing. The value is stored as an encrypted Worker secret and reused by later versions.
+Auth sessions use the same database as your app. Void creates `BETTER_AUTH_SECRET` on deploy if it is missing and reuses it on later deploys.
 
-The Vite development server uses a built-in fallback secret automatically. A local preview of a production build needs `BETTER_AUTH_SECRET`; production deployment through Void manages the secret lifecycle for you.
+Local development needs no secret setup. To preview a production build locally, provide `BETTER_AUTH_SECRET`.
 
 ## Customization
 
@@ -245,19 +148,12 @@ For the full set of available options, see the official [Better Auth options ref
 
 Auth tables live alongside your app's tables. During local development, Void creates them automatically.
 
-A Void platform deploy creates the Better Auth tables at runtime after dispatch. A direct Cloudflare deploy requires those tables in your checked-in migrations. Generate them with:
+Void platforms create auth tables automatically. For a direct Cloudflare deploy, include them in your checked-in migrations:
 
 ```sh
 void db generate
 ```
 
-Void adds the production Better Auth schema, including configured model names and plugin tables, to Drizzle's migration input. Review and commit the SQL before deploying. You don't need to duplicate the auth tables in `db/schema.ts` or run a separate Better Auth CLI.
+Review and commit the SQL before deploying. Void includes your auth configuration and plugin tables; you don't need to duplicate them in `db/schema.ts` or run the Better Auth CLI.
 
 MySQL stores OAuth access, refresh, and ID tokens as unbounded text. Existing direct-deploy MySQL apps should run `void db generate` once after upgrading to widen earlier `varchar(255)` token columns. Void platform deployments apply the same safe widening automatically.
-
-## Unsupported Modes
-
-Void-managed Better Auth is supported only for Cloudflare Void apps in v1.
-
-- meta-framework mode should use Better Auth's official framework integrations directly
-- `target: "node" | "bun" | "deno"` should use Better Auth directly

package/skills/void/docs/guide/database/d1.md

@@ -4,26 +4,11 @@ outline: deep
 
 # D1 (SQLite)
 
-[Cloudflare D1](https://developers.cloudflare.com/d1/) is a serverless SQLite database distributed across Cloudflare's network. Void manages it for you, so there is no setup, no connection string, and no separate local database configuration during development.
-
-## When to Use D1
-
-D1 is the default database for Void apps and a great choice when you want zero-config database access:
-
-- **Prototyping:** start building immediately with no external database to provision
-- **Read-heavy apps:** optimized for read workloads at the edge
-- **Small to medium scale:** a good fit for apps that do not need advanced SQL features such as stored procedures or complex joins
-- **Simplicity:** Void creates, migrates, and manages the D1 instance for you
-
-For write-heavy workloads, complex queries, or connecting to existing infrastructure, see [PostgreSQL](./postgresql).
-
-## Configuration
-
-None. D1 is the default dialect, so you can start by defining your schema and querying.
+[Cloudflare D1](https://developers.cloudflare.com/d1/) is Void's default SQLite database. Start with a [schema](../database.md#schema-definition); Void manages the database locally and when you deploy.
 
 ## Read replication
 
-Void enables [D1 read replication](https://developers.cloudflare.com/d1/best-practices/read-replication/) when it provisions a database. For a database that was already configured before this feature, run `void deploy --platform cloudflare --provision` once to enable it. Queries through `db` from `void/db` use a D1 session for each Void request, so reads can run near the request and later queries in that request see at least the same data. Framework handlers without Void's request scope start each database operation on the primary. `createDb` starts a replica-capable session for the binding you pass it.
+Void enables [D1 read replication](https://developers.cloudflare.com/d1/best-practices/read-replication/) when it provisions a database. To enable it on an existing database, run `void deploy --platform cloudflare --provision`. Queries through `db` from `void/db` use a D1 session for each Void request, so reads can run near the request and later queries in that request see at least the same data. Framework handlers without Void's request scope start each database operation on the primary. `createDb` starts a replica-capable session for the binding you pass it.
 
 Replicas can lag between requests. Authentication session checks start on the primary so a revoked session is not accepted because of replica lag. If another read must start with the latest primary data, use `env.DB.withSession('first-primary')` from `cloudflare:workers`. Other query libraries and raw D1 calls need their own `withSession()` to use replicas; a bare D1 binding reads from the primary.
 
@@ -35,45 +20,15 @@ To store local data outside `.void`, set `voidPlugin({ persistTo: 'local-state'
 
 ## Migrations & Prototyping
 
-Void offers two workflows for applying schema changes.
-
-### Prototyping with `push`
-
-During development, use `void db push` to apply your schema directly to the local D1 database. It does not create migration files.
-
-```bash
-void db push
-```
-
-This diffs your Drizzle schema against the local database and applies the changes immediately. It's fast and ideal for iterating on your schema before committing to a migration.
-
-### Production migrations
-
-When you're ready to ship, generate SQL migration files from your schema:
+Use `void db push` to apply schema changes locally without creating migration files. Before deploying, generate and commit migrations:
 
-```bash
+```sh
 void db generate
+void db migrate # apply locally
+void deploy     # apply remotely and deploy
 ```
 
-This creates timestamped SQL files in `db/migrations/` that capture the diff between your schema and the last generated migration.
-
-To apply pending migrations locally:
-
-```bash
-void db migrate
-```
-
-## Deploy Workflow
-
-When you run `void deploy`:
-
-1. The app is built
-2. Migration files are collected from `db/migrations/`
-3. If the schema has drifted ahead of the migrations, you're prompted to generate and commit the new migrations
-4. Pending migrations run against the remote D1 database
-5. The new worker goes live
-
-Deploys always go through migration files. `push` is only for local development.
+See [Database commands](../../reference/cli/database.md#database) for the full workflow.
 
 ## Batch Operations
 
@@ -91,7 +46,7 @@ await db.batch([
 
 ## Alternative Query Layers
 
-While Void's Drizzle integration is the recommended approach, you can use any library that accepts a D1 binding. Import `env.DB` from `cloudflare:workers` and pass it to your library:
+Use `env.DB` from `cloudflare:workers` with another query library or the raw D1 API:
 
 ### Kysely
 
@@ -114,5 +69,5 @@ const { results } = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bin
 Void still handles binding inference and deployment regardless of which query layer you use.
 
 ::: warning ⚠️ Meta framework limitation
-Some frameworks, like Nuxt and SvelteKit, do not run in workerd during dev and therefore do not support directly importing from `cloudflare:workers`.
+Nuxt and SvelteKit do not support `cloudflare:workers` imports during local development. Use `void/db` or your framework's binding access API.
 :::