void 0.25.0 → 0.26.0

package/dist/{subcommand-prompt-Dhom39bd.mjs → subcommand-prompt-B6WS9Aoz.mjs}

@@ -1,5 +1,5 @@
 import { $ as wrapTextWithPrefix, G as promptTitle, M as getGuide, V as optionText, b as S_RADIO_ACTIVE, d as S_CHECKBOX_SELECTED, i as S_BAR_END, it as wrapAnsi, j as formatInstructionFooter, n as SELECT_INSTRUCTIONS, r as S_BAR, t as MULTISELECT_INSTRUCTIONS, u as S_CHECKBOX_INACTIVE, w as S_STEP_SUBMIT } from "./prompts-6OSVA7DJ.mjs";
-import { c as import_picocolors } from "./output-BBsUwdyT.mjs";
+import { c as import_picocolors } from "./output-BvdaehtE.mjs";
 //#region src/cli/subcommand-prompt.ts
 function promptSubcommand(command, subcommands) {
 	return new Promise((resolve) => {

package/dist/validate-pna7R3Pv.mjs

@@ -0,0 +1,2 @@
+import { i as validateMigrations } from "./validate-ymhap6M_.mjs";
+export { validateMigrations };

package/dist/{validate-ctOrgiS3.mjs → validate-ymhap6M_.mjs}

@@ -1,6 +1,6 @@
 import { a as join } from "./dist-BVqXeR_h.mjs";
 import { n as readJournal, r as stripSqlExt } from "./collect-DiTn9yr6.mjs";
-import { t as DESTRUCTIVE_PRAGMA } from "./plan-NPpwZ_kc.mjs";
+import { t as DESTRUCTIVE_PRAGMA } from "./plan-CJGEeTEI.mjs";
 import { existsSync, readdirSync } from "node:fs";
 import { tokenizeSql } from "@void/deploy-core";
 //#region src/migrations/validate.ts

package/dist/{ws-CL1w7GXU.d.mts → ws-C79j4aED.d.mts}

@@ -1,6 +1,6 @@
 import { t as StandardSchemaV1 } from "./standard-schema-Fo_vCAZh.mjs";
 import { r as AuthUser } from "./auth-DkcFflXV.mjs";
-import { a as CloudEnv } from "./handler-CZ4nAylQ.mjs";
+import { a as CloudEnv } from "./handler-BeK3weD4.mjs";
 import { WebSocketRouteMap } from "void/routes";
 //#region src/runtime/ws.d.ts
 type MaybePromise<T> = T | Promise<T>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "void",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/voidzero-dev/void.git",
@@ -339,11 +339,11 @@
     "@cloudflare/workers-auth": "0.12.0",
     "@cloudflare/workers-types": "^4.20260702.1",
     "@napi-rs/keyring": "2.1.0",
-    "@void/deploy-cloudflare": "0.25.0",
-    "@void/deploy-core": "0.25.0",
-    "@void/edge": "0.25.0",
-    "@void/isr": "0.25.0",
-    "@void/platform": "0.25.0",
+    "@void/deploy-cloudflare": "0.26.0",
+    "@void/deploy-core": "0.26.0",
+    "@void/edge": "0.26.0",
+    "@void/isr": "0.26.0",
+    "@void/platform": "0.26.0",
     "acorn": "^8.18.0",
     "better-auth": "^1.7.7",
     "better-sqlite3": "^13.0.3",
@@ -393,7 +393,7 @@
     "zod": "^4.6.5"
   },
   "peerDependencies": {
-    "@void/md": "0.25.0",
+    "@void/md": "0.26.0",
     "arktype": ">=2.0.0",
     "valibot": ">=1.0.0-beta.7",
     "vite": "^8.0.0",

package/skills/void/SKILL.md

@@ -19,6 +19,8 @@ Use `void` and `@void/*` in imports, examples, and package manifests. Follow the
 project's existing framework and deployment destination. Deploying to a Void
 platform requires an explicit `void connect <url>` first; never infer a platform
 from old examples, tokens, or project IDs.
+Platform hostnames passed to `void connect` default to HTTPS; include `http://`
+explicitly when connecting to a local HTTP platform.
 For a one-time deployment elsewhere, connect to that platform, then set
 `VOID_API_URL` for the deploy command and pass `--project <slug>`. This preserves
 the app's existing saved destination, including when the target project is new.
@@ -78,7 +80,8 @@ the app's existing saved destination, including when the target project is new.
 - Declare application environment keys in `env.ts` and access them through
   `void/env`; follow `docs/guide/env-vars.md` for local and production values.
 - For platform setup, follow the pages linked from
-  `docs/guide/self-hosted-platform.md`. For recovery, use its documented resume
+  `docs/guide/self-hosted-platform.md`. Use `void platform list` to find the
+  installation slug for maintenance. For recovery, use its documented resume
   or repair workflow and preserve the installation's credentials and resources.
 - Use `--plan` to review platform changes. If an operation has an uncertain
   outcome, inspect its status and events before retrying.
@@ -87,4 +90,4 @@ If the user invokes this skill without a task, inspect the app's local structure
 configuration, and saved deployment destination, give a brief status, and ask
 what they want to work on.
 
-For AI and Sandbox operations, use `.match({ ok, limited })` and choose a useful quota fallback. In Pages, prefer the adapter’s `Form` with `useForm()` so action failures remain visible and entered data is preserved. See `docs/guide/ai.md`, `docs/guide/sandboxes.md`, and `docs/guide/pages-routing/actions-and-forms.md`.
+Await AI and Sandbox operations normally. Usage limits reject with `UsageLimit` from `void/limits`; Void routes and Pages actions automatically return HTTP 429. Optionally catch with `instanceof UsageLimit` for a fallback or custom response. In Pages, prefer the adapter’s `Form` with `useForm()` so action failures remain visible and entered data is preserved. See `docs/guide/ai.md`, `docs/guide/sandboxes.md`, and `docs/guide/pages-routing/actions-and-forms.md`.

package/skills/void/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. Usage limits reject with [`UsageLimit`](#usage-limits); Void route handlers and Pages actions automatically send a structured HTTP 429 when it is left uncaught.
 
 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,21 +91,46 @@ 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 } })`.
@@ -137,16 +153,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 +177,7 @@ const response = await ai
         },
       ],
     },
-  })
-  .match({ ok: (result) => result, limited: (limit) => limit.response() });
+  });
 ```
 
 ### Custom Providers
@@ -181,8 +193,7 @@ const response = await ai
   })
   .fetch('/v1/respond', {
     body: { prompt: 'Hello' },
-  })
-  .match({ ok: (result) => result, limited: (limit) => limit.response() });
+  });
 ```
 
 ### Image Generation
@@ -192,9 +203,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 +213,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 +233,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/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/guide/database.md

@@ -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/guide/live.md

@@ -22,6 +22,8 @@ export const live = defineLiveStream({
 });
 ```
 
+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

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

@@ -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
 

package/skills/void/docs/guide/platform/installation/credentials.md

@@ -8,7 +8,7 @@ Keep one password-manager entry for this platform. Paste the saved values into t
 
 ## Cloudflare API Tokens {#runtime-token-permissions}
 
-For a domain installation or Cloudflare Access setup, the installer guides you through creating separate management and runtime tokens using Cloudflare's [API token setup](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/). Its links preselect the permissions and suggest names based on your platform's display name. Scope the tokens to your selected account and, when using a domain, its zone, save them in your password manager, and paste them into the masked CLI prompts.
+For a domain installation or Cloudflare Access setup, the installer guides you through creating separate management and runtime tokens using Cloudflare's [API token setup](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/). Its links preselect the permissions and suggest names based on your platform's display name, but Cloudflare's form cannot preselect a zone: for a domain installation, change the zone policy from **All Domains** to **Specified Domains** and select your zone. If Void will create the zone, keep **All Domains** on both tokens: the zone does not exist yet, and the runtime token needs it to purge cache. Save the tokens in your password manager and paste them into the masked CLI prompts.
 
 For workers.dev testing with the default API hostname, browser login can authorize
 infrastructure setup. Void also checks account-wide Access requirements; if the
@@ -21,7 +21,7 @@ Browser login does not grant AI Gateway access. Include **Account → AI Gateway
 
 The management token lets your CLI install and maintain the platform. The runtime token is stored as a Worker secret so the platform can deploy apps after you close your terminal. They are separate credentials.
 
-Compare each token's form with the permission checklist below, and select the indicated account and zone for a domain installation. The installer saves a management token entered at the prompt in this installation’s encrypted local checkpoint and reuses it on resume. Upgrades, repairs, and other lifecycle maintenance also use that saved management token. During installation, a rejected token can be replaced at the prompt. An explicit `CLOUDFLARE_API_TOKEN` or `CF_API_TOKEN` takes precedence. Keep your password-manager copy for maintenance or another machine; scripts supply it through `CLOUDFLARE_API_TOKEN`.
+Compare each token's form with the permission checklist below. The installer saves a management token entered at the prompt in this installation’s encrypted local checkpoint and reuses it on resume. Upgrades, repairs, and other lifecycle maintenance also use that saved management token. During installation, a rejected token can be replaced at the prompt. An explicit `CLOUDFLARE_API_TOKEN` or `CF_API_TOKEN` takes precedence. Keep your password-manager copy for maintenance or another machine; scripts supply it through `CLOUDFLARE_API_TOKEN`.
 
 ::: details Permissions to select for each token
 

package/skills/void/docs/guide/platform/installation/first-deployment.md

@@ -34,7 +34,11 @@ void project token create --name ci --expires-in 30
 
 Store the printed `VOID_TOKEN` and `VOID_API_URL` in the CI secret manager, then
 run `void connect "$VOID_API_URL" --no-login` before deploying in each fresh CI
-environment. Project files do not replace this connection step. Rotate with `void project token renew <id>` and revoke with
+environment. Project files do not replace this connection step. CI cannot answer
+the project prompt, so choose the project before `void deploy`: set `VOID_PROJECT`,
+pass `--project <slug>`, or commit `.void/project.json` from `void project link`.
+New apps ignore `.void` in `.gitignore`; to commit the link, replace that line
+with `.void/*` and `!.void/project.json`. Rotate with `void project token renew <id>` and revoke with
 `void project token revoke <id>`. A human login token is not a CI credential.
 
 If Cloudflare Access protects the platform, Access proof and the project

package/skills/void/docs/guide/platform/installation/maintenance.md

@@ -6,7 +6,7 @@ outline: deep
 
 ## Resume, repair, recover, and upgrade
 
-You can omit an installation ID when only one is configured. With several installations, choose one interactively or pass its ID in CI.
+Run `void platform list` to find the installation slug beside its name. Lifecycle commands accept this slug, an installation ID, or a saved connection ID. You can omit the selector when only one installation is configured. With several installations, choose one interactively or pass its slug or ID in CI.
 
 ### Resume an installation
 
@@ -74,6 +74,8 @@ void platform upgrade [id]
 
 An upgrade validates the runtime, applies supported pending migrations, deploys the Workers, and checks their health. Existing Worker secrets are preserved.
 
+Before starting, Void checks access to the installation's Cloudflare account, Workers, and existing R2 buckets. If credentials are rejected, set `CLOUDFLARE_API_TOKEN` to a management token scoped to that account and retry. This overrides the installation's saved management token.
+
 ::: details Migration safety, credential rotation, and interrupted upgrades
 
 Some upgrades briefly put the platform into maintenance mode. Traffic resumes after the new version passes health checks. If an upgrade is interrupted during maintenance, rerun the same command to complete it.

package/skills/void/docs/guide/platform/installation/setup.md

@@ -12,7 +12,7 @@ For workers.dev testing, start the interactive install and choose your login met
 void platform install --workers-dev
 ```
 
-For a domain installation or Access setup, Void guides you to create a management API token and paste it into a masked prompt. Browser login can preview DNS, but cannot change it or configure Access. The token-creation link preselects the permissions for your choices; scope the token to your account and, when using a domain, its zone. No shell environment variable is needed for interactive installation.
+For a domain installation or Access setup, Void guides you to create a management API token and paste it into a masked prompt. Browser login can preview DNS, but cannot change it or configure Access. The token-creation link preselects the permissions for your choices. When using an existing domain, change the zone policy from **All Domains** to **Specified Domains** and select your zone, as the CLI prompt describes. No shell environment variable is needed for interactive installation.
 
 ::: details Use an existing management token from the shell
 

package/skills/void/docs/guide/platform/installation/uninstall.md

@@ -11,7 +11,9 @@ void platform disable [id] --plan
 void platform disable [id]
 ```
 
-Disabled platforms reject application traffic while retaining domains and routes. Repair and upgrade preserve that state. Restore traffic with:
+Disabled platforms reject application traffic while retaining domains and routes. The platform API also rejects requests, so CLI commands that use it, including login and deploy, fail until you enable the platform again. Only the administrator status page at `<api-url>/admin/status` and administrator sign-in stay available. Repair and upgrade preserve that state.
+
+Enabling redeploys the platform Workers from the selected runtime, verifies them, and then restores traffic. Pass `--runtime <path>` to enable with a custom platform build:
 
 ```sh
 void platform enable [id] --plan
@@ -31,7 +33,9 @@ void platform uninstall [id] --plan
 void platform uninstall [id]
 ```
 
-Uninstall blocks platform traffic, removes Queues that no remaining platform Worker uses, and records the resources left for you to review. By default, Workers, the Queues they use, KV, R2, Hyperdrive, the dispatch namespace, and AI Gateway remain in your account. Adopted resources, external PostgreSQL, zones, DNS records, routes, custom domains, and Cloudflare Access resources are always retained.
+Uninstall blocks platform traffic, removes Queues that no remaining platform Worker uses, and lists the resources left for you to review. Use `--plan` to review deletions and retained resources before making changes. By default, Workers, the Queues they use, KV, R2, Hyperdrive, the dispatch namespace, and AI Gateway remain in your account. Adopted resources, external PostgreSQL, and zones are always retained. Email Routing settings are retained; `--purge-resources` removes only the rules that send mail to the platform. DNS records, routes, custom domains, and Cloudflare Access resources are retained unless you use `--purge-resources`.
+
+When uninstall finishes, the record of what was kept stays at `~/.void/platforms/<account-id>/<installation-id>.json`. Without `--purge-data`, the encrypted credentials file `<installation-id>.recovery.enc` next to it is kept too. Delete both once you have finished the manual cleanup below.
 
 To also remove eligible data resources owned by the installer:
 
@@ -39,20 +43,49 @@ To also remove eligible data resources owned by the installer:
 void platform uninstall [id] --purge-data
 ```
 
-Even with `--purge-data`, Void retains Workers, the Queues they use, R2, AI Gateway, DNS records, routes, custom domains, Access resources, adopted resources, external PostgreSQL, and zones. Review those in the Cloudflare dashboard if you want to remove them.
+Even with `--purge-data`, Void retains Workers, the Queues they use, R2, AI Gateway, DNS records, routes, custom domains, Access resources, adopted resources, external PostgreSQL, and zones. Review those in the Cloudflare dashboard if you want to remove them, or use `--purge-resources`.
+
+### Remove everything Void created
+
+To delete every Cloudflare resource the installation created:
+
+```sh
+void platform uninstall [id] --purge-resources --plan
+void platform uninstall [id] --purge-resources
+```
+
+`--purge-resources` includes `--purge-data`. It also deletes the platform Workers, Queues, the application Workers left in the dispatch namespace, the R2 bucket and its objects, the AI Gateway, the platform DNS record, Worker routes and custom domains, and the Access applications and service tokens the installer created. The plan lists each resource in deletion order, and everything that stays. If Cloudflare shows that the AI Gateway was created after installation, for example because it was deleted and created again under the same name, it is kept and listed.
+
+If the platform sends email, it first deletes the Email Routing rules in the sender domain's zone that send mail to the platform email gateway Worker, and resets such a catch-all rule to drop mail. It leaves Email Routing enabled and keeps the sender domain's MX, SPF, and DKIM records.
+
+It never removes zones, adopted resources, external PostgreSQL, other Email Routing settings, Analytics Engine datasets, Access policies or identity providers you chose, or API tokens. Revoke the API tokens you created for the platform afterward.
+
+Before making changes, `--purge-resources` checks that no projects remain and that it can read the resources it plans to delete. Delete any projects with `void project delete <name>` first.
+
+Set `CLOUDFLARE_API_TOKEN` to a token with the Edit permissions listed by `--plan`. Browser login cannot delete DNS records or Access resources. Access resources in a separate identity account need permissions in that account; email-enabled platforms also need **Zone → Email Routing Rules → Edit** for the sender domain's zone.
+
+The read checks cannot verify Edit permissions. If a deletion is denied, uninstall may have already disabled traffic or removed resources. Update the token permissions and rerun the command to resume.
+
+If a route, custom domain, DNS record, or Access resource no longer matches what the installation recorded, for example a route that now sends traffic to another Worker, it is kept and listed with the reason, and uninstall continues. Do not run `--purge-resources` while someone else is changing the platform's Workers, routes, or custom domains: a change made after Void checks a resource and before it deletes it is not detected.
+
+If Cloudflare refuses a deletion, for example because a Worker you created yourself still sends logs to the platform tail Worker, uninstall stops and names the resource. Fix it, then rerun the same command to continue.
+
+If a plain or `--purge-data` uninstall stopped before it finished, rerun it with `--purge-resources` to also delete what it kept. Once an uninstall finishes, use the manual steps below instead.
 
 ### Remove retained resources
 
-Cloudflare refuses to delete a resource while a platform Worker still uses it. In the Cloudflare dashboard, remove what is left in this order, skipping anything already gone:
+After an uninstall without `--purge-resources`, Cloudflare refuses to delete a resource while a platform Worker still uses it. In the Cloudflare dashboard, remove what is left in this order, skipping anything already gone:
 
 1. Delete the platform DNS record, Worker routes, and custom domains.
-2. Open each platform Queue and remove the platform API Worker from its consumers.
-3. Delete the platform Workers.
-4. Delete the platform Queues.
-5. Delete the application Workers in the dispatch namespace, then delete the namespace.
-6. Delete the platform KV namespaces and Hyperdrive configuration.
-7. Empty the R2 bucket, then delete it.
-8. Delete the AI Gateway.
+2. If the platform sends email, open **Email Routing** for the sender domain's zone. Delete the routing rules and any catch-all rule that send mail to the platform email gateway Worker. Then remove the sender subdomain from Email Routing, or disable Email Routing if you enabled it only for the platform.
+3. Open each platform Queue and remove the platform API Worker from its consumers.
+4. Delete the platform Workers, except the tail Worker (its name ends in `-tail`).
+5. Delete the platform Queues.
+6. Delete the application Workers in the dispatch namespace, then delete the namespace.
+7. Delete the tail Worker. Cloudflare refuses while other Workers still send logs to it.
+8. Delete the platform KV namespaces and Hyperdrive configuration.
+9. Empty the R2 bucket, then delete it.
+10. Delete the AI Gateway.
 
 If installation configured Cloudflare Access, the uninstall plan lists its recorded applications and service tokens with their ownership and IDs. Review them in Zero Trust after uninstall. Remove installer-created resources only when nothing else uses them; resources connected from an existing company setup remain under their owner's control.
 

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

@@ -18,13 +18,10 @@ import { getSandbox } from 'void/sandbox';
 
 export const POST = defineHandler(async (c) => {
   const sandbox = await getSandbox('default');
-  return sandbox.run(['node', '--version']).match({
-    ok: (result) =>
-      c.json({
-        exitCode: result.exitCode,
-        stdout: new TextDecoder().decode(result.stdout),
-      }),
-    limited: (limit) => limit.response({ message: 'Execution is temporarily unavailable.' }),
+  const result = await sandbox.run(['node', '--version']);
+  return c.json({
+    exitCode: result.exitCode,
+    stdout: new TextDecoder().decode(result.stdout),
   });
 });
 ```
@@ -42,33 +39,55 @@ const sandbox = await getSandbox(`user-${user.id}`, {
   inactivityTimeoutMs: 10 * 60 * 1000,
   enableInternet: false,
 });
-const response = await sandbox
-  .run(['node', '--version'], {
-    signal: AbortSignal.timeout(5_000),
-  })
-  .match({
-    ok: (result) => Response.json({ exitCode: result.exitCode }),
-    limited: (limit) => limit.response(),
-  });
+const result = await sandbox.run(['node', '--version'], {
+  signal: AbortSignal.timeout(5_000),
+});
 ```
 
 Commands take an executable and arguments as an array. For shell syntax, explicitly run `['sh', '-c', command]`. Execution options include `cwd` (default `/workspace`), `env`, `user`, `signal`, `pty`, `stdin`, `stdout`, and `stderr`.
 
-`run()` collects command output and handles limits throughout execution with one required `.match({ ok, limited })`. Both handlers are required. Other failures still reject.
+Sandbox operations return promises. `run()` resolves with `stdout` and `stderr` as `ArrayBuffer`s and the command's exit code. Usage limits reject with [`UsageLimit`](#usage-limits); other failures reject normally.
 
-`exec()` returns a lazy operation yielding a process through its `ok` handler. Use `output()` to collect `stdout` and `stderr` as `ArrayBuffer`s with the exit code, or read the streams and match `exitCode`. Both `output()` and `exitCode` require their own `.match({ ok, limited })`. Matching `exitCode` keeps a long command active during pauses in its output; unattended background commands can stop when the Sandbox becomes idle.
+`exec()` resolves with a process. Await `process.output()` to collect its output and exit code, or read the streams and await `process.exitCode`. Waiting for completion keeps a long command active during pauses in its output; unattended background commands can stop when the Sandbox becomes idle. A runtime limit can reject completion after a command has successfully started.
 
 Use `stdin: 'pipe'` for a writable input stream. `kill(signal?)` stops a process, and `resize(cols, rows)` resizes its terminal.
 
-File operations live under `sandbox.files`: `readFile`, `writeFile`, `stat`, `lstat`, `readDirectory`, `mkdir`, `rename`, and `remove`. Each file operation requires `.match({ ok, limited })`. `readFile()` yields a streaming `Response` to `ok`; use `.text()`, `.arrayBuffer()`, or `.body`. `writeFile()` accepts text, binary data, or a byte stream. Relative file paths require an explicit `cwd` option.
+File operations live under `sandbox.files`: `readFile`, `writeFile`, `stat`, `lstat`, `readDirectory`, `mkdir`, `rename`, and `remove`. Await `readFile()` to receive a streaming `Response`, then use `.text()`, `.arrayBuffer()`, or `.body`. `writeFile()` accepts text, binary data, or a byte stream. Relative file paths require an explicit `cwd` option.
 
-To reach a server inside the container, call `sandbox.fetch(port, new Request(url)).match({ ok, limited })`. `sandbox.running()` checks whether the container is running; `sandbox.destroy()` stops it.
+To reach a server inside the container, await `sandbox.fetch(port, new Request(url))`. `sandbox.running()` checks whether the container is running; `sandbox.destroy()` stops it.
 
 `getSandbox()` options include `inactivityTimeoutMs` (default ten minutes, maximum six hours), `enableInternet` (default `false`), and string `labels`. Internet access and labels take effect on the next container start. `binding` selects a custom native binding; managed platforms use the configured binding.
 
 For code that runs on both deployment targets, use `getSandbox()`. Direct access through `c.env.SANDBOX` is available only on local and native Cloudflare deployments.
 
-The `limited` handler receives `resource: 'sandbox'`, a `reason` of `concurrency` or `runtime_budget`, and `response({ message })` for a structured HTTP 429. Keep user input available so it can be retried. Resolving a Sandbox, checking `running()`, stopping a process, and `destroy()` do not need a quota handler; cleanup remains available after a limit.
+## Usage limits
+
+Sandbox limits reject with `SandboxLimitError`, which extends `UsageLimit` from `void/limits`. The error includes `resource: 'sandbox'` and a `reason` of `concurrency` or `runtime_budget`. Void route handlers and Pages actions automatically send a structured HTTP 429 when the error is left uncaught.
+
+Use `instanceof UsageLimit` to optionally handle both AI and Sandbox limits, or `instanceof SandboxLimitError` for Sandbox-specific handling:
+
+```ts
+import { defineHandler } from 'void';
+import { UsageLimit } from 'void/limits';
+import { getSandbox } from 'void/sandbox';
+
+export const POST = defineHandler(async (c) => {
+  const sandbox = await getSandbox('default');
+  try {
+    const result = await sandbox.run(['node', 'task.mjs']);
+    return c.json({ exitCode: result.exitCode });
+  } catch (error) {
+    if (error instanceof UsageLimit) {
+      return error.response({
+        message: 'Execution is temporarily unavailable. Try again shortly.',
+      });
+    }
+    throw error;
+  }
+});
+```
+
+Keep user input available so it can be retried. Checking `running()`, stopping a process, and `destroy()` remain available after a usage limit.
 
 ## State persistence