void 0.25.0 → 0.26.1

package/{skills/void/docs → docs}/guide/ai.md

@@ -34,15 +34,14 @@ import { ai } from 'void/ai';
 export const POST = defineHandler(async (c) => {
   const { prompt } = await c.req.json();
 
-  return ai
-    .run('@cf/meta/llama-3.3-70b-instruct-fp8-fast', {
-      messages: [{ role: 'user', content: prompt }],
-    })
-    .match({ ok: (result) => c.json(result), limited: (limit) => limit.response() });
+  const result = await ai.run('@cf/meta/llama-3.3-70b-instruct-fp8-fast', {
+    messages: [{ role: 'user', content: prompt }],
+  });
+  return c.json(result);
 });
 ```
 
-Every operation runs through `.match({ ok, limited })`. Both handlers are required. Return a fallback from `limited`, or use `limit.response()` to send a structured HTTP 429. Limits include `resource`, `reason`, and an optional `retryAt`; other failures throw. Await `.match()`, rather than the operation itself.
+AI methods return promises. Await them to receive the result, or return the promise directly from a handler. See [Usage Limits](#usage-limits) for limit errors.
 
 You can use any model available through Cloudflare's AI binding, including Workers AI models such as `@cf/meta/llama-3.3-70b-instruct-fp8-fast` and Cloudflare Gateway models such as `google/gemini-2.5-flash` or `openai/gpt-4.1-mini`. The input object must match the selected Cloudflare model's schema. Models that return binary data, such as generated images, are returned as a `Blob` from `ai.run()`.
 
@@ -57,29 +56,23 @@ 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 }],
-    })
-    .match({ ok: (result) => result, limited: (limit) => limit.response() });
+  return ai.stream('@cf/meta/llama-3.3-70b-instruct-fp8-fast', {
+    messages: [{ role: 'user', content: prompt }],
+  });
 });
 ```
 
-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`.
+Streaming responses end with a `void:error` SSE event if generation is interrupted after the response starts, or `void:limit` for a usage limit. `fetchStream()` from `void/client` throws `UsageLimit` for limits before or during streaming and `StreamError` for other terminal errors. Catch the error in your UI to stop its generating state, retain partial output, and offer retry. This also applies to streaming provider responses and `ai.run()` with `stream: true`.
 
 ## Listing Models
 
 Use `ai.models()` to list available models:
 
 ```ts
-const models = await ai
-  .models()
-  .match({ ok: (result) => result, limited: (limit) => limit.response() });
+const models = await ai.models();
 
 // Filter by task
-const textModels = await ai
-  .models({ task: 'Text Generation' })
-  .match({ ok: (result) => result, limited: (limit) => limit.response() });
+const textModels = await ai.models({ task: 'Text Generation' });
 ```
 
 ## Markdown Conversion
@@ -87,9 +80,7 @@ const textModels = await ai
 Use `ai.toMarkdown()` to convert documents to markdown:
 
 ```ts
-const result = await ai
-  .toMarkdown([{ name: 'document.pdf', blob: pdfBytes }])
-  .match({ ok: (result) => result, limited: (limit) => limit.response() });
+const result = await ai.toMarkdown([{ name: 'document.pdf', blob: pdfBytes }]);
 ```
 
 ## Usage Limits
@@ -100,24 +91,49 @@ requests also use your provider credentials and their billing terms.
 
 A team platform uses its own Cloudflare account and may apply per-user limits. Ask your administrator about the available allowance.
 
+Usage limits reject the operation's promise with `UsageLimit` from `void/limits`. It includes `resource`, `reason`, and an optional `retryAt` timestamp. In Void route handlers and Pages actions, an uncaught limit produces a structured HTTP 429 with retry information. In queues, scheduled jobs, and other server code, it remains a rejected promise.
+
+Handling a limit is optional. Use `instanceof UsageLimit` when you want a fallback or a message tailored to your app:
+
+```ts
+import { defineHandler } from 'void';
+import { ai } from 'void/ai';
+import { UsageLimit } from 'void/limits';
+
+export const POST = defineHandler(async (c) => {
+  const { prompt } = await c.req.json();
+  try {
+    const result = await ai.run('@cf/meta/llama-3.3-70b-instruct-fp8-fast', {
+      messages: [{ role: 'user', content: prompt }],
+    });
+    return c.json(result);
+  } catch (error) {
+    if (error instanceof UsageLimit) {
+      return error.response({ message: 'Try again shortly. Your prompt has been kept.' });
+    }
+    throw error;
+  }
+});
+```
+
+`error.response()` creates the structured HTTP 429 and accepts an optional custom `message`. Other failures reject normally. When using `fetchStream()`, the same `instanceof UsageLimit` check gives your client access to the message and retry information.
+
 ## 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.' }],
-      },
-    ],
-  })
-  .match({ ok: (result) => result, limited: (limit) => limit.response() });
+const result = await ai.run('google/gemini-2.5-flash', {
+  contents: [
+    {
+      role: 'user',
+      parts: [{ text: 'Explain Durable Objects in one paragraph.' }],
+    },
+  ],
+});
 ```
 
-Pass AI Gateway options as the third argument: `ai.run(model, inputs, { gateway: { skipCache: true } })`.
+Pass AI Gateway options as the third argument: `ai.run(model, inputs, { gateway: { skipCache: true } })`. On a team platform, the platform chooses the gateway and sets its metadata and logging; options such as `skipCache` and `cacheTtl` still apply.
 
 For provider-native requests on a direct deployment, configure [`ai.gateway`](../integrations/cloudflare.md#ai-self-host).
 
@@ -126,7 +142,9 @@ For provider-native requests on a direct deployment, configure [`ai.gateway`](..
 Use `ai.provider(provider).fetch(path, init)` for a provider-native API with your
 own provider key. The request goes through the configured Cloudflare AI Gateway
 and retains the provider's native HTTP shape. On a team platform, it also passes
-through that installation's proxy.
+through that installation's proxy. AI Gateway cache, timeout and retry headers,
+such as `cf-aig-cache-ttl` and `cf-aig-max-attempts`, still apply there; the
+platform ignores logging, metadata and cost headers.
 
 ### OpenAI
 
@@ -137,16 +155,13 @@ import { ai } from 'void/ai';
 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 }],
-        max_tokens: 512,
-      },
-    })
-    .match({ ok: (result) => result, limited: (limit) => limit.response() });
+  return ai.provider('openai').fetch('/chat/completions', {
+    body: {
+      model: 'gpt-4o',
+      messages: [{ role: 'user', content: prompt }],
+      max_tokens: 512,
+    },
+  });
 });
 ```
 
@@ -164,8 +179,7 @@ const response = await ai
         },
       ],
     },
-  })
-  .match({ ok: (result) => result, limited: (limit) => limit.response() });
+  });
 ```
 
 ### Custom Providers
@@ -181,8 +195,7 @@ const response = await ai
   })
   .fetch('/v1/respond', {
     body: { prompt: 'Hello' },
-  })
-  .match({ ok: (result) => result, limited: (limit) => limit.response() });
+  });
 ```
 
 ### Image Generation
@@ -192,9 +205,7 @@ 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 })
-    .match({ ok: (result) => result, limited: (limit) => limit.response() });
+  return ai.image('@cf/black-forest-labs/flux-1-schnell', { prompt });
 });
 ```
 
@@ -204,16 +215,13 @@ Use `ai.provider().fetch()` for provider-native image APIs. Match the [provider'
 export const POST = defineHandler(async (c) => {
   const { prompt } = await c.req.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() });
+  return ai.provider('openai').fetch('/images/generations', {
+    body: {
+      model: 'gpt-image-2.5-sunburst',
+      prompt,
+      size: '1024x1024',
+    },
+  });
 });
 ```
 
@@ -227,10 +235,7 @@ export const POST = defineHandler(async (c) => {
   form.set('prompt', String(body.prompt));
   form.set('image', body.image as Blob, 'source.png');
 
-  return ai
-    .provider('openai')
-    .fetch('/images/edits', { body: form })
-    .match({ ok: (result) => result, limited: (limit) => limit.response() });
+  return ai.provider('openai').fetch('/images/edits', { body: form });
 });
 ```
 

package/{skills/void/docs → docs}/guide/app-types.md

@@ -45,7 +45,7 @@ Add `voidPlugin()` to the framework's Vite config to get binding inference, type
 
 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.
+**SPAs** (client-side single-page apps) serve `index.html` with a 200 status for paths that match no file, so client-side routing works out of the box. On a Void platform, missing files under the hashed assets folder (`/assets/`) return 404 instead. Detected when `vite` is a dependency and no backend files exist.
 
 **Static sites** (static site generators like VitePress, Docusaurus, or any pre-built directory) produce per-page HTML files. Detected when a known SSG is a dependency, or when using the `--dir` flag.
 

package/{skills/void/docs → docs}/guide/auth.md

@@ -92,7 +92,7 @@ Email/password is enabled by default. To add social providers:
 }
 ```
 
-Use `auth.providers` when you want to enable social providers explicitly. Provider credentials come from `AUTH_<PROVIDER>_CLIENT_ID` and `AUTH_<PROVIDER>_CLIENT_SECRET`.
+Provider credentials come from `AUTH_<PROVIDER>_CLIENT_ID` and `AUTH_<PROVIDER>_CLIENT_SECRET`.
 
 See the full provider list in the [config reference](../reference/config.md#auth).
 
@@ -127,6 +127,42 @@ Auth sessions use the same database as your app. Void creates `BETTER_AUTH_SECRE
 
 Local development needs no secret setup. To preview a production build locally, provide `BETTER_AUTH_SECRET`.
 
+`POST`, `PUT`, `PATCH` and `DELETE` requests and WebSocket connections from another origin don't use the signed-in session unless that origin is in `trustedOrigins`. If a separate frontend calls your app, add its origin there (see [Customization](#customization)). If your routes use their own cookies, check the request `Origin` yourself, for example with Hono's [`csrf()`](https://hono.dev/docs/middleware/builtin/csrf) middleware.
+
+Deployed apps on Cloudflare limit auth requests per client IP with Better Auth's defaults, for example 3 sign-in attempts per 10 seconds. Each Worker instance keeps its own count. Change or turn off the limits with `rateLimit` in `auth.ts`. To share one count across instances, set `rateLimit: { storage: 'database' }`, then run `void db generate` for a direct Cloudflare deploy.
+
+### Proxies and end-to-end tests
+
+All requests from one IP share one count. Two common setups reach the limits:
+
+- A server calls your auth endpoints for your users, such as a backend-for-frontend, a rewrite from Vercel or nginx, or another Worker's `fetch`. All of those users share that server's IP.
+- End-to-end tests sign up or sign in many times against a deployed app.
+
+Don't read the client IP from `x-forwarded-for` instead: any client can send that header. Give the trusted caller a secret header, and skip the limits only for requests that carry it:
+
+```ts
+import { defineAuth } from 'void/auth';
+
+export default defineAuth(({ defaults, env }) => ({
+  ...defaults,
+  rateLimit: {
+    customRules: {
+      '/**': (request, rule) =>
+        env.AUTH_TRUSTED_KEY && request.headers.get('x-auth-trusted-key') === env.AUTH_TRUSTED_KEY
+          ? false
+          : rule,
+    },
+  },
+}));
+```
+
+`'/**'` matches every auth endpoint. Returning `false` skips the limit, and returning `rule` keeps the default limit for everyone else. Declare `AUTH_TRUSTED_KEY: string().optional()` in `env.ts` and set it with `void secret put AUTH_TRUSTED_KEY` (see [Environment variables](./env-vars.md#production-server-values)).
+
+Your app no longer limits requests that carry the key, so:
+
+- A proxy that sends it must limit every auth request it forwards for each of its users, including sign-up, password reset and verification emails.
+- A test runner should send it only to your app. Never put the key in code that runs in your users' browsers.
+
 ## Customization
 
 For advanced configuration, create `auth.ts` at the project root and export `defineAuth(...)`:

package/{skills/void/docs → docs}/guide/database/postgresql.md

@@ -59,7 +59,7 @@ export const users = pgTable('users', {
 });
 ```
 
-`void gen model` generates PostgreSQL-appropriate code when the dialect is set to `postgresql`.
+`void gen model` generates PostgreSQL-appropriate code when `database` is set to `"pg"`.
 
 ## Migrations
 
@@ -88,4 +88,4 @@ To update a linked Void project's connection, for example after moving the datab
 void db set-url
 ```
 
-This prompts for the new connection string and updates the Hyperdrive configuration. The change takes effect on the next deploy.
+This prompts for the new connection string and updates the Hyperdrive configuration.

package/{skills/void/docs → docs}/guide/database.md

@@ -54,9 +54,9 @@ Define your tables in `db/schema.ts` using column helpers from `void/schema-d1`,
 ::: code-group
 
 ```ts [SQLite (D1)]
+import { sql } from 'void/db';
 // db/schema.ts
 import { sqliteTable, text, integer } from 'void/schema-d1';
-import { sql } from 'void/db';
 
 export const users = sqliteTable('users', {
   id: integer('id').primaryKey({ autoIncrement: true }),
@@ -117,8 +117,8 @@ export * from "./schema/posts";
 Void re-exports all common [Drizzle query operators](https://orm.drizzle.team/docs/select) from `void/db` so you don't need to install `drizzle-orm` separately. Import `db` from `void/db` and your tables from `@schema`:
 
 ```ts
-import { db } from 'void/db';
 import { users } from '@schema';
+import { db } from 'void/db';
 ```
 
 ::: info What is `@schema`?
@@ -134,8 +134,8 @@ const allUsers = await db.select().from(users);
 ### Filter with `where`
 
 ```ts
-import { db, eq, and, or } from 'void/db';
 import { users } from '@schema';
+import { db, eq, and, or } from 'void/db';
 
 // Single condition
 const user = await db.select().from(users).where(eq(users.id, 1));
@@ -200,8 +200,8 @@ const names = await db.select({ name: users.name, email: users.email }).from(use
 ### Ordering and pagination
 
 ```ts
-import { db, desc } from 'void/db';
 import { users } from '@schema';
+import { db, desc } from 'void/db';
 
 const page = await db.select().from(users).orderBy(desc(users.createdAt)).limit(10).offset(20);
 ```
@@ -209,8 +209,8 @@ const page = await db.select().from(users).orderBy(desc(users.createdAt)).limit(
 ### Joins
 
 ```ts
-import { db, eq } from 'void/db';
 import { users, posts } from '@schema';
+import { db, eq } from 'void/db';
 
 const results = await db
   .select({
@@ -290,9 +290,9 @@ export const insertUserSchema = createInsertSchema(users, {
 ```
 
 ```ts [Valibot]
+import { pipe, minLength, email } from 'valibot';
 // db/schema.ts
 import { createInsertSchema } from 'void/drizzle-valibot';
-import { pipe, minLength, email } from 'valibot';
 
 export const insertUserSchema = createInsertSchema(users, {
   name: (schema) => pipe(schema, minLength(1)),
@@ -301,9 +301,9 @@ export const insertUserSchema = createInsertSchema(users, {
 ```
 
 ```ts [ArkType]
+import { type } from 'arktype';
 // db/schema.ts
 import { createInsertSchema } from 'void/drizzle-arktype';
-import { type } from 'arktype';
 
 export const insertUserSchema = createInsertSchema(users, {
   name: type('string > 0'),
@@ -318,10 +318,10 @@ export const insertUserSchema = createInsertSchema(users, {
 Use the derived schema in your route handlers with [`withValidator()`](./server-routing.md#validation):
 
 ```ts
+import { users, insertUserSchema } from '@schema';
 // routes/api/users/index.ts
 import { defineHandler } from 'void';
 import { db } from 'void/db';
-import { users, insertUserSchema } from '@schema';
 
 export const POST = defineHandler.withValidator({
   body: insertUserSchema,
@@ -361,6 +361,21 @@ npm install arktype
 
 See the [CLI reference](../reference/cli/database.md#database) for connection setup, SQL execution, Studio, exports, and other commands.
 
+## Hand-written migrations {#hand-written-migrations}
+
+Deploy compares your Drizzle schema with the snapshots in `db/migrations/meta/`. If you have SQL migrations without this metadata, running `void db generate` would create another migration for the same tables.
+
+To keep an existing migration history:
+
+1. Make your Drizzle schema match the tables your SQL migrations create.
+2. In a scratch copy of the project, remove `db/migrations/` and run `void db generate`.
+3. Copy the generated `meta/` folder into your original migration directory. In `_journal.json`, replace `entries` with an entry for each existing SQL file in order. Use consecutive `idx` values starting at `0`, the file name without `.sql` as `tag`, increasing timestamps as `when`, and the generated entry's `version`. Set `breakpoints` to whether the file uses `--> statement-breakpoint` lines.
+4. Rename the generated snapshot to `<prefix>_snapshot.json`, where `<prefix>` is the part of the last migration tag before its first `_`. For `001_create_users.sql`, use `001_snapshot.json`.
+
+Review and commit the metadata, then run `void deploy` again. If no database has applied the SQL yet, you can instead replace it with migrations from `void db generate`.
+
+For D1 migrations containing triggers, add a `--> statement-breakpoint` line after each complete SQL statement, including the trigger's closing `END;`. Keep the trigger body together.
+
 ## Scaffolding
 
 The `void gen model` command generates dialect-appropriate `sqliteTable`, `pgTable`, or `mysqlTable` definitions.

package/{skills/void/docs → docs}/guide/edge/revalidation.md

@@ -108,7 +108,7 @@ Requests with `Cookie`, `Authorization`, or Cloudflare Access's `Cf-Access-Jwt-A
 
 For a dispatch rewrite, the cache key includes both the destination and original pathname. A direct request to `/en/docs/foo` therefore uses a different entry from `/docs/foo` rewritten to that destination.
 
-Query parameters are excluded by default. Add `routing.revalidateQueryAllowlist` when specific parameters should produce separate cached responses. Middleware `c.rewrite()` runs after the ISR lookup, so it doesn't create an additional cache variant.
+Query parameters are excluded by default. Add `routing.revalidateQueryAllowlist` when specific parameters should produce separate cached responses. Requests with other query parameters get the cached page. If nothing is cached yet, they render live and are not stored, so add every parameter a page reads to `routing.revalidateQueryAllowlist`. Middleware `c.rewrite()` runs after the ISR lookup, so it doesn't create an additional cache variant.
 
 Purge the destination pathname with `revalidate({ paths })`. Purging `/en/docs/foo` clears both direct and rewritten variants. Purging only `/docs/foo` won't clear them, because the entries are stored under the destination.
 

package/{skills/void/docs → docs}/guide/edge/rewrites.md

@@ -109,15 +109,13 @@ The file can include [3xx redirects](./redirects) too. Rules in `void.config.ts`
 
 ## Client navigation
 
-Rewrites run on the server. In Pages mode, a client-side `<Link to="/docs">` navigation may fetch loader data for `/docs` rather than the rewritten route `/en/docs`.
+Rewrites run on the server. In Pages mode, a client-side `<Link href="/docs">` navigation may fetch loader data for `/docs` rather than the rewritten route `/en/docs`.
 
 Use `<a href="/docs">` to make a full server request when the destination has a different loader. Use a redirect if the URL should change.
 
 ## ISR cache keys with rewrites
 
-Static rewrites cache the destination separately for each original pathname. Query parameters vary the cache only when included in `routing.revalidateQueryAllowlist`. Middleware rewrites don't create a separate cache variant.
-
-Purge the destination with `revalidate({ paths: ['/en/docs/foo'] })` to clear direct and rewritten requests. Purging only `/docs/foo` does not clear that entry. See [Revalidation](./revalidation).
+Purge the destination path, such as `/en/docs/foo`, to clear rewritten cache entries. See [Cache keys and rewrites](./revalidation#cache-keys-and-rewrites).
 
 ## Debugging with `X-Void-Routing`
 

package/{skills/void/docs → docs}/guide/email/receiving.md

@@ -100,13 +100,13 @@ There is no local inbound trigger yet — `void dev` serves the outbound dev inb
 
 ## Testing inbound handlers {#testing-inbound-handlers}
 
-Use `createInboundTestHarness` to capture replies, forwards, and rejections. For shared platform mail, pass the full address including the project prefix, such as `acme+support+abc-123@acme.dev`. For direct Cloudflare mail, set `slug: null` and use `support+abc-123@mail.acme.com`.
+Use `createInboundTestHarness` to capture replies, forwards, and rejections. For shared platform mail, pass the full address including the project prefix, such as [`acme+support+abc-123@acme.dev`](mailto:acme+support+abc-123@acme.dev). For direct Cloudflare mail, set `slug: null` and use [`support+abc-123@mail.acme.com`](mailto:support+abc-123@mail.acme.com).
 
 ```ts
 import { describe, it, expect } from 'vitest';
 import { createInboundTestHarness } from 'void/email/testing';
-import support from './email/support+[ticket]';
 import defaultHandler from './email/_default';
+import support from './email/support+[ticket]';
 
 describe('email handlers', () => {
   it('routes to support+[ticket] and extracts the tag', async () => {

package/{skills/void/docs → docs}/guide/email/sending.md

@@ -59,8 +59,6 @@ Cloudflare emails the recipient with a verification link. Once they click it and
 void email destinations
 ```
 
-The project owner’s email is added automatically, but still needs verification as described in [Setup](#setup).
-
 ::: warning When this is the right fit
 The shared sender suits team alerts, project notifications, and replies to inbound mail.
 

package/{skills/void/docs → docs}/guide/env-vars.md

@@ -39,8 +39,12 @@ STRIPE_KEY=sk_test_example
 VITE_API_ORIGIN=http://localhost:5173
 ```
 
+An unquoted value ends at `#`, which starts a comment. Quote a value that contains `#`, such as `DATABASE_URL="postgres://user:p#ss@localhost/my-app"`.
+
 Keep `.env` out of Git. Other dotenv files, including `.env.local`, `.env.production`, `.env.example`, and Wrangler’s `.dev.vars*`, are not supported.
 
+Names starting with `__VOID_` are reserved for Void. Void stops with an error if `.env` or `env.ts` defines one.
+
 Run the local check at any time:
 
 ```sh

package/{skills/void/docs → docs}/guide/jobs.md

@@ -70,10 +70,10 @@ curl -X POST http://localhost:5173/__void/scheduled \
   -d '{"cron":"0 * * * *","scheduledTime":'"$(date +%s000)"'}'
 ```
 
-If you set `__VOID_PROXY_TOKEN` in `.env`, that explicit token takes precedence and the printed curl command uses `x-void-internal: <your-token>` instead.
-
 The endpoint works in native Void apps and supported frameworks. Framework jobs run in the adapter's development runtime and use the bindings it provides.
 
 ## Deployment behavior
 
 Native scheduled events do not require a manual HTTP token. For framework deployments, HTTP requests to `/__void/scheduled` require a matching `x-void-internal` token: the managed platform supplies its proxy token, or you can explicitly configure `CRON_SECRET` for manual calls. An absent or mismatched token returns `401` without running a job.
+
+On a Void platform, each project can use up to 100 different cron expressions and 1,000 schedules (each expression a job exports counts as one schedule). Jobs that share an expression count once toward the expression limit. When you deploy to your own Cloudflare account, Cloudflare's [Cron Trigger limits](https://developers.cloudflare.com/workers/platform/limits/) apply instead.

package/{skills/void/docs → docs}/guide/live.md

@@ -22,6 +22,10 @@ export const live = defineLiveStream({
 });
 ```
 
+This example accepts visitors who are not signed in. Without `onSubscribe`, any connection can subscribe to any topic, so read [Authorization](#authorization) before you publish private data.
+
+Void enables live streams when a [scanned file](../reference/resource-inference.md#scanned-directories) imports `void/live`, so keep this module in `src/` or another scanned directory. To keep it in an unscanned directory such as `lib/`, add that directory to [`inference.scanDirs`](../reference/resource-inference.md#custom-scan-directories) and list the default directories you still use, because `scanDirs` replaces them.
+
 Expose it from a normal route:
 
 ```ts
@@ -99,6 +103,8 @@ await live.withEnv(env).publish('post:12', { title: 'Updated title' });
 
 Only a connection's owner can change its subscriptions. The example above allows anonymous connections; authenticated streams use the current Void user by default.
 
+The owner decides who can change a connection's subscriptions, not which topics the connection can read.
+
 For authenticated streams, pass the same owner key to `connect()` and
 `control()`:
 
@@ -125,16 +131,17 @@ current authenticated user and uses `user:${user.id}` when the user has a string
 `id`. If neither path produces an owner and `allowAnonymousControl` is not set,
 the request is rejected with `403`.
 
-For stream-local subscription rules, use `onSubscribe`:
+Without `onSubscribe`, any connection that passes the owner check (any signed-in user, or any visitor when `allowAnonymousControl` is set) can subscribe to any topic and receives everything published to it. Topic names are easy to guess. Use `onSubscribe` to decide who can read each topic: return a `Response` to reject the subscription, or return nothing to allow it.
 
 ```ts
 export const live = defineLiveStream({
   id: 'app',
   async onSubscribe(ctx) {
-    const match = /^post:(.+)$/.exec(ctx.topic);
-    if (match && !(await canReadPost(ctx.env, ctx.user, match[1]))) {
-      return new Response('Forbidden', { status: 403 });
-    }
+    const post = /^post:(.+)$/.exec(ctx.topic);
+    if (post && (await canReadPost(ctx.env, ctx.user, post[1]))) return;
+    const inbox = /^user:(.+):inbox$/.exec(ctx.topic);
+    if (inbox && ctx.owner === `user:${inbox[1]}`) return;
+    return new Response('Forbidden', { status: 403 });
   },
 });
 ```

package/{skills/void/docs → docs}/guide/pages-routing/actions-and-forms.md

@@ -11,10 +11,10 @@ Use an action to change server data from a form or button. Define it in the page
 Export `action` from a `.server.ts` file. Use `withValidator()` with a [schema-derived validator](../database.md#schema-derived-validators) to validate the request body:
 
 ```ts
+import { users, insertUserSchema } from '@schema';
 // pages/users/index.server.ts
 import { defineHandler } from 'void';
 import { db } from 'void/db';
-import { users, insertUserSchema } from '@schema';
 
 export const action = defineHandler.withValidator({
   body: insertUserSchema,
@@ -176,10 +176,10 @@ const form = useForm('/users/:id', { name: '' }, { params: { id: '42' } });
 When a page needs multiple mutations, such as updating and deleting a user on the same page, export `actions` (plural) instead of `action`:
 
 ```ts
+import { users, updateUserSchema } from '@schema';
 // pages/users/[id].server.ts
 import { defineHandler } from 'void';
 import { db, eq } from 'void/db';
-import { users, updateUserSchema } from '@schema';
 
 export const actions = {
   update: defineHandler.withValidator({
@@ -269,7 +269,7 @@ export const action = defineHandler(async (c) => {
 
 ### Usage limits
 
-For [AI](../ai.md) and [Sandbox](../sandboxes.md) actions, return `limit.response({ message: 'Try again shortly. Your draft is still editable.' })` from the operation's `limited` handler. `Form` displays the message and waits until a known retry deadline before allowing resubmission. It keeps the fields editable and never retries automatically.
+For [AI](../ai.md#usage-limits) and [Sandbox](../sandboxes.md#usage-limits) actions, an uncaught `UsageLimit` automatically produces a structured HTTP 429. To customize the message, catch the error with `instanceof UsageLimit` and return `error.response({ message: 'Try again shortly. Your draft is still editable.' })`. `Form` displays the message and waits until a known retry deadline before allowing resubmission. It keeps the fields editable and never retries automatically.
 
 ## Authentication and origin checks
 
@@ -355,20 +355,32 @@ On the server, use `c.req.parseBody()` to access the uploaded file:
 
 ```ts
 // pages/photos.server.ts
-import { defineHandler } from 'void';
+import { defineHandler, ValidationError } from 'void/handler';
 import { storage } from 'void/storage';
 
+// file.name and file.type come from the browser. Don't use them as the key or trust the type.
+const imageTypes = new Map([
+  ['image/jpeg', 'jpg'],
+  ['image/png', 'png'],
+  ['image/webp', 'webp'],
+]);
+
 export const action = defineHandler(async (c) => {
   const body = await c.req.parseBody();
-  const file = body['photo'] as File;
-  if (file && file.size > 0) {
-    await storage.put(file.name, file.stream(), {
-      httpMetadata: { contentType: file.type },
-    });
+  const file = body['photo'];
+  if (!(file instanceof File) || file.size === 0) return;
+  const ext = imageTypes.get(file.type);
+  if (!ext) {
+    throw new ValidationError({ photo: 'Upload a JPEG, PNG, or WebP image.' });
   }
+  await storage.put(`uploads/${crypto.randomUUID()}.${ext}`, file.stream(), {
+    httpMetadata: { contentType: file.type },
+  });
 });
 ```
 
+Pick the storage key on the server and allow only the file types you expect. See [Serving Files](../storage.md#serving-files) to send them back safely.
+
 ## Choosing a Primitive
 
 | Primitive        | Page update | Form state                 | Framework-specific |