void 0.22.0 → 0.23.0

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

@@ -19,13 +19,15 @@ If nameservers, certificates, or project Zero Trust protection are pending, foll
 
 Use `--installation <id>` to select an installation explicitly, `--zone example.com` for an app domain such as `apps.example.com`, or `--dedicated-zone` for catch-all routing on a dedicated zone. Nested domains still need the wildcard certificate described below. This command adds the first domain; replacing an existing application domain is not currently supported. It uses the installed runtime and does not require `--runtime` or an app redeploy.
 
+Choose an application domain whose wildcard leaves existing Worker Custom Domains reachable. Existing more-specific routes covering all requests can preserve those hostnames. If Void reports a conflict, choose another application domain; for a new installation, you can start with `void platform install --workers-dev` and add a suitable domain later.
+
 Browser login sessions are specific to each origin. Apps using their own OAuth providers may need to register their new callback URLs. Void's built-in auth uses the request origin automatically unless the app overrides that configuration.
 
 ### What Changes in Testing Mode?
 
-Each deployed app gets a small forwarding Worker and its own `workers.dev` origin. It forwards requests, including WebSockets and SSE, through the same platform router. Names include installation and project IDs; a later project with the same slug cannot inherit a deleted project's test URL.
+In testing mode, each app gets a `workers.dev` URL. These URLs continue working after you add a domain; new apps then use the domain.
 
-Testing origins use shared ISR storage but bypass the extra edge response cache because you cannot use your zone's purge API for `workers.dev`. Custom-domain requests use the normal edge cache after activation. Existing test URLs and forwarding Workers are retained when you add a domain; new apps then use the domain without creating more forwarding Workers. Like other platform Workers, forwarders are retained for manual cleanup on uninstall; platform disablement and project suspension still apply to their traffic.
+Testing URLs support WebSockets, SSE, and shared ISR storage, but skip the extra edge response cache. Their forwarding Workers remain for manual cleanup after uninstall. Platform disablement and project suspension still block their traffic.
 
 ## Other Domain Options
 
@@ -49,6 +51,32 @@ The management token needs **SSL and Certificates: Read** (or Edit) on that zone
 
 :::
 
+## Optional Dashboard
+
+The API's `/admin/` pages are included in the core installation. You can deploy
+the optional user dashboard separately and configure its HTTPS origin during
+installation with `--dashboard-url https://dash.example.com`.
+
+For an existing installation, preview and apply the configuration with:
+
+```sh
+void platform repair <installation-id> --dashboard-url https://dash.example.com --plan
+void platform repair <installation-id> --dashboard-url https://dash.example.com --yes
+```
+
+The origin must contain no credentials, path, query, or fragment. Void saves it
+for login callbacks and keeps it across upgrades and repairs. The command does
+not create a dashboard Worker or DNS records; deploy that app separately. Omit
+the option to keep the saved origin. The dashboard provides sign-in, linked
+login methods, and sign-out; use the CLI for user project and team management.
+
+If Access protects the platform, its application must cover this dashboard
+origin too. Configure the origin when installing protection. To change it on an
+already protected platform, deliberately remove protection through authentication
+configuration, apply the origin, then enable protection again. Choose a separate
+admission rule first if signup depends on the Access gate. Maintenance stops if
+the configured origin is outside the active coverage.
+
 ## Cloudflare footprint
 
 New platform resources use deterministic `void-<installation-name>-<role>` names where Cloudflare allows them, such as `void-team-api`. Choose an unused installation name in the account; Void stops on an unowned name conflict instead of replacing that resource. Existing installations keep their recorded names, including older names with suffixes.

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

@@ -21,6 +21,8 @@ void deploy --platform void --project my-first-app
 
 `void connect` validates the platform and signs you in when needed. Confirm project creation when deploy asks. To use a project that already exists, run `void project link` instead. An app already linked to another platform keeps its existing destination; use a fresh app directory for your first test.
 
+Once accepted by the platform, a deployment continues independently of the CLI connection. The CLI reconnects automatically after a connection failure. Use `void project status` to inspect a deployment after closing the CLI, or `void project cancel` to request cancellation.
+
 The CLI stores login credentials in your system keychain, separately for each platform URL. With no URL, `void connect` offers Cloudflare or a Void platform; `void connect --platform void` offers saved platforms and an option to enter another URL.
 
 For CI, create a bounded, project-scoped deploy credential while signed in as

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

@@ -56,6 +56,8 @@ Repair recreates missing infrastructure that the installer owns. It does not res
 
 ### Upgrade the platform
 
+Keep the platform runtime current when updating the Void CLI. If a developer's CLI reports that project lookup requires an upgrade, upgrade the platform before retrying.
+
 Use the installed CLI's packaged runtime to upgrade:
 
 ```sh
@@ -80,7 +82,7 @@ Database migrations only move forward. Void checks compatibility before upgradin
 
 Upgrades automatically enable managed Sandboxes. The platform runtime token needs Account / Containers: Edit and Account / Cloudchamber: Edit, and the Cloudflare account must use Workers Paid before its first Sandbox application deploy. The upgrade itself does not probe Containers access, so platforms that do not deploy Sandbox applications need no additional plan or permissions.
 
-When upgrading from a release that used tenant-owned Sandbox containers, the upgrade may first ask you to finish the legacy cleanup. Follow the [`sandbox-drain` instructions](/reference/cli#operator-system), then rerun the upgrade. Administrator login remains available during that maintenance step.
+When upgrading from a release that used tenant-owned Sandbox containers, the upgrade may first ask you to finish the legacy cleanup. Follow the [`sandbox-drain` instructions](../../../reference/cli/platform-operations.md#operator-system), then rerun the upgrade. Administrator login remains available during that maintenance step.
 
 After a successful upgrade, you can restore a declared-compatible earlier runtime without reversing migrations:
 

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

@@ -4,11 +4,16 @@ outline: deep
 
 # Prerequisites
 
-Start with a Cloudflare account you can administer, an account with your chosen login provider, and an empty hosted PostgreSQL database. GitHub is the default and is optional when another method is selected. A domain is recommended. If yours is not ready, choose **Use workers.dev for testing** during installation and [add a domain later](/guide/platform/installation/domains#adding-a-domain). The steps below explain how to get the credentials the installer asks for.
+To run a Void platform, you need:
+
+- A Cloudflare account with Workers for Platforms and R2 enabled.
+- An empty hosted PostgreSQL database.
+- An account with your chosen login provider. GitHub is the default; Google, OIDC, and Cloudflare Access are also supported.
+- A domain for your apps, or `workers.dev` for testing. You can [add a domain later](/guide/platform/installation/domains#adding-a-domain).
 
 Void creates the Workers, storage, queues, routing, and database tables through the CLI.
 
-This setup has costs: Workers for Platforms requires a paid plan, and your database and Cloudflare usage have their own pricing. External PostgreSQL is required in either mode.
+Workers for Platforms requires a paid plan. Your database and Cloudflare usage are billed separately.
 
 ## Prepare Your Cloudflare Account and Domain
 
@@ -31,15 +36,7 @@ pnpm add --global void
 void platform install --plan
 ```
 
-Void checks your saved Cloudflare login while you enter the installation name. If sign-in is needed, it opens your browser after you submit the name; press Ctrl+C to cancel. The plan command then asks for the account and basic configuration and shows the resources it would create. It does not require the database or runtime secrets and does not change Cloudflare resources.
-
-The installer first offers these choices, with the domain option selected:
-
-```text
-Where should your apps live?
-  Use a domain — recommended
-  Use workers.dev for testing — add a domain later
-```
+Sign in to Cloudflare when prompted, then choose an installation name and account. `--plan` previews the resources without changing them or requiring runtime secrets.
 
 For a domain installation, use these answers. Testing mode skips the application domain, zone, and catch-all questions:
 
@@ -52,9 +49,9 @@ For a domain installation, use these answers. Testing mode skips the application
 | Optional custom API hostname            | Leave empty to use `workers.dev`                    |
 | Dedicate all unmatched traffic to Void? | Yes only if this whole zone belongs to the platform |
 
-Platform resources use your installation name: `team` creates names such as `void-team-api`, `void-team-proxy`, and `void-team-routing`, with no random suffix. Use a different installation name for another platform in the same account. If a required resource already exists and belongs to another installation, Void stops without overwriting it. Existing installations keep their recorded resource names.
+Choose an unused installation name in your account. For example, `team` creates resources such as `void-team-api` and `void-team-proxy`.
 
-The preview shows the actual resource names and login callback URL that installation will use with the same configuration. It also links directly to the runtime-token form and the account's R2 token page. When you select GitHub login, it links to GitHub OAuth registration. It does not open credential setup pages or save an installation draft; Cloudflare browser login still opens when needed.
+The preview includes your login callback URL and links for creating credentials. Keep it open while following [Credentials](/guide/platform/installation/credentials), then run the install command printed at the end.
 
 You can select either path directly:
 
@@ -69,7 +66,7 @@ void platform install --workers-dev --plan
 
 Use an empty PostgreSQL database dedicated to this platform. It stores users, projects, and deployments; individual apps can still use D1. Void creates the tables and the Hyperdrive connection, but does not provision the PostgreSQL server.
 
-Void does not require a particular database provider. Use an existing PostgreSQL host or choose a service such as **PlanetScale Postgres**, **Neon**, **Supabase**, or others.
+Use any PostgreSQL provider that accepts connections from your computer and Cloudflare:
 
 1. Create a fresh database or project dedicated to the platform, with no existing application tables. Use a database role that can create and manage its tables and schemas.
 2. Open the provider's connection details and select the primary database. Use a direct connection or a session-mode pooler, not transaction pooling. The connection must work from both your computer and Cloudflare.
@@ -85,4 +82,12 @@ For a dedicated Supabase project, [disable the Data API](https://supabase.com/do
 
 Once installation claims the database, continue using that same database for resume and maintenance commands. Uninstall never deletes external PostgreSQL.
 
-During interactive installation, choose whether Void creates Hyperdrive or uses an existing configuration in your Cloudflare account. Select an existing configuration by name and confirm its database, host, port, runtime user, and disabled SQL result caching. If you need a new separately managed configuration, choose **Set up a separately managed Hyperdrive**; Void pauses and gives you setup instructions. Create it with any unused name, point it at the dedicated PostgreSQL database using a runtime user, and disable SQL result caching. See [Cloudflare's Hyperdrive setup guide](https://developers.cloudflare.com/hyperdrive/get-started/), or ask your organization's Hyperdrive administrator to create it. Rerun the installer and select it. Paste a database owner connection into the PostgreSQL URL prompt for installation and migrations. Void verifies the selected Hyperdrive against that database, records its identity for later maintenance, and leaves its configuration under your external manager's control. For unattended installation, supply the existing Hyperdrive ID, origin host, and runtime user through the environment variables in [Install from CI](/guide/platform/installation/ci).
+### Use an existing Hyperdrive
+
+The installer can create Hyperdrive for you or use one you manage separately. For an existing configuration:
+
+1. Point it at the dedicated platform database using a runtime user, and disable SQL result caching.
+2. Select it in the installer and confirm the database, host, port, and runtime user.
+3. Supply a database owner connection at the PostgreSQL URL prompt so Void can apply migrations.
+
+To create one first, choose **Set up a separately managed Hyperdrive** and follow the printed instructions or [Cloudflare’s setup guide](https://developers.cloudflare.com/hyperdrive/get-started/). Rerun the installer once it is ready. Void leaves its configuration under your control. For unattended setup, use the Hyperdrive variables in [Install from CI](/guide/platform/installation/ci).

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

@@ -29,7 +29,7 @@ void platform install
 
 :::
 
-After `--plan`, run the install command printed at the end of the preview. Void recalculates the plan and asks you to confirm it; choose the same login methods again if you selected them interactively. Void then saves a local setup draft and opens the runtime-token page when that token is missing. Paste the token into the masked prompt. As you continue, it opens GitHub and R2 at their respective steps. Each page has a short checklist and a clickable fallback link in the terminal. Values already supplied through the environment or saved setup are reused without opening their pages again.
+After reviewing `--plan`, run the command printed under **Next step: run this command to install**. It carries your choices into installation. Confirm the plan, then follow the credential prompts. Void opens the relevant setup pages and provides fallback links in the terminal. It reuses values you have already supplied.
 
 ## Choose login methods
 
@@ -131,7 +131,9 @@ ID, and secret, without a `cloudflareAccess` block or Cloudflare management toke
 Follow Cloudflare's [OIDC application guide](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/saas-apps/generic-oidc-saas/)
 and register the exact callback printed by Void.
 
-For the default GitHub-only setup:
+### GitHub
+
+For GitHub login:
 
 1. The installer opens [GitHub's new OAuth App form](https://github.com/settings/applications/new) when it needs OAuth credentials. Sign in as the account that will own the login integration.
 2. Set **Application name** to your platform's display name and **Homepage URL** to the API URL Void just printed.
@@ -140,9 +142,11 @@ For the default GitHub-only setup:
 
 This OAuth App handles sign-in.
 
-For the default GitHub-only setup, the prompts collect the runtime token, administrator GitHub username, PostgreSQL URL, GitHub client ID and secret, R2 credentials, and signing/encryption keys. Other login methods collect their configured provider credentials and use the one-time administrator setup code described above. Secret values are masked and setup progress is encrypted locally using the system keychain. Keep a password-manager copy for recovery on another machine.
+## Finish installation
+
+The installer collects your runtime token, PostgreSQL URL, login-provider credentials, R2 credentials, and signing and encryption keys. It masks secret values and saves setup progress encrypted through your system keychain. Keep a password-manager copy for recovery on another machine.
 
-Void shows installation progress while it prepares the database, provisions Cloudflare resources, deploys the services, and verifies platform health. Progress is checkpointed for recovery. When installation finishes, follow the printed administrator sign-in instructions and open the admin dashboard link. GitHub-only setup creates the first admin user when the selected GitHub account signs in; configurable setup uses the one-time `/setup` code and selected administrator login method. No app or CLI login is required. Void also prints the API URL to use when you [connect and deploy an app](/guide/platform/installation/first-deployment).
+Once installation finishes, open the printed admin dashboard link. For GitHub-only setup, sign in as the administrator selected during installation. For configurable login, use the one-time `/setup` code to confirm the administrator’s identity. Use the printed API URL to [connect and deploy an app](/guide/platform/installation/first-deployment).
 
 Remove the management token from the shell when finished:
 
@@ -162,7 +166,7 @@ void platform install --resume --name <installation-id>
 
 Keep the management token available for any remaining DNS changes. When using a source build, also pass the same `--runtime` directory. Resume uses the saved checkpoint and original secrets; do not start a second installation or generate replacement keys. If setup failed before a checkpoint was saved, rerun the original command.
 
-If setup stops or fails, rerun `void platform install`. It lists unfinished installations, including those that reached provisioning, and offers **Continue setup** or **Start a new platform install**. Entering an existing unfinished name also asks whether to resume it; declining lets you enter another name. Continuing restores your saved answers and checkpoints. Starting new does not reuse or delete previous credentials or resources. `--resume --name <id>` continues directly and is required for non-interactive recovery. Read-only `--plan` runs do not save drafts. Completed platforms are managed with `platform status`, `repair`, or `upgrade`, not reinstalled.
+You can also rerun `void platform install` and choose **Continue setup** for an unfinished installation. For non-interactive recovery, use `--resume --name <id>`. Manage completed platforms with `platform status`, `repair`, or `upgrade`.
 
 If Cloudflare rejects a saved runtime token during continued credential setup, Void opens the token page and asks for a replacement in the same run. Network or service failures do not discard saved tokens. Tokens supplied through the environment must be corrected there instead.
 

package/skills/void/docs/guide/platform-administration.md

@@ -12,6 +12,7 @@ The operator commands for users, projects, deployments, and system status requir
 
 - [Sign-in and Access](/guide/platform/administration/access)
 - [Users and Projects](/guide/platform/administration/projects)
+- [Plans and Limits](/guide/platform/administration/plans)
 - [Project Zero Trust](/guide/platform/administration/zero-trust)
 - [Email](/guide/platform/administration/email)
 - [Operations](/guide/platform/administration/operations)

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

@@ -8,13 +8,11 @@ Use queues to process work asynchronously, such as sending emails or handling up
 
 ## Defining queues
 
-Create files in `queues/**/*.ts`; `.mts`, `.js`, and `.mjs` also work. The queue name is inferred from its path, with nested path segments joined by `-`. For example, `queues/emails.ts` creates a queue named `"emails"`, and `queues/order/notifications.ts` creates `"order-notifications"`. A nested path must not normalize to the same name as another file: `queues/order/notifications.ts` and `queues/order-notifications.ts` conflict, so Void reports the collision and asks you to rename one.
+Create a consumer in `queues/`. TypeScript and JavaScript files are supported (`.ts`, `.mts`, `.js`, `.mjs`). Its path determines the queue name: `queues/emails.ts` creates `emails`, and `queues/order/notifications.ts` creates `order-notifications`. Each queue must have a unique name.
 
 The resulting name must follow Cloudflare's queue naming rules: 1–63 characters, only letters, digits, and `-`, beginning and ending with a letter or digit.
 
-If you previously used a nested queue locally, update producer calls from `queues['order/notifications']` to `queues['order-notifications']`. The derived binding remains `QUEUE_ORDER_NOTIFICATIONS`.
-
-Each queue file should export a default handler wrapped with [`defineQueue`](../reference/api.md#definequeue-t-handler). The generic `<T>` parameter defines the message body type. That is the type of each `msg.body` in the batch, and it is also used by the typed `queues` proxy for `send()` calls.
+Export a default handler wrapped with [`defineQueue<T>`](../reference/api/handlers.md#definequeue-t-handler). `T` defines the message body for both the consumer and calls to `send()`:
 
 ```ts
 // queues/emails.ts
@@ -56,8 +54,6 @@ export const POST = defineHandler(async (c) => {
 });
 ```
 
-The binding name is derived automatically: `QUEUE_` + queue name uppercased with non-alphanumeric characters replaced by `_`. For example, `queues/emails.ts` creates binding `QUEUE_EMAILS`, while `queues/order/notifications.ts` creates binding `QUEUE_ORDER_NOTIFICATIONS`.
-
 ## Per-message acknowledgment
 
 Each message in the batch has `ack()` and `retry()` methods matching the [Cloudflare Queues API](https://developers.cloudflare.com/queues/configuration/consumer-concurrency/):
@@ -111,12 +107,14 @@ export default defineQueue<Message>(async (batch, env) => {
 
 - `maxBatchSize`: maximum number of messages per batch (default `10`)
 - `maxBatchTimeout`: maximum seconds to wait before delivering an incomplete batch (default `5`)
-- `maxRetries`: maximum number of retries before a message is dead-lettered (default `3`)
+- `maxRetries`: maximum number of retries before delivery is exhausted (default `3`)
 - `retryDelay`: seconds to wait between retries (default `0`)
 
-## Deployment behavior
+Void-managed queues do not configure a dead-letter queue. Cloudflare permanently
+deletes messages that exhaust their retries without one; see
+[Cloudflare's dead-letter queue guide](https://developers.cloudflare.com/queues/configuration/dead-letter-queues/).
 
-On deploy, Void includes all discovered queues in the deploy manifest. The platform provisions Cloudflare Queues, configures producer bindings on the user worker, and registers the dispatch worker as the queue consumer for relay delivery.
+Void provisions queues and connects their producers and consumers when you deploy.
 
 ## Local development
 

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

@@ -56,36 +56,9 @@ Void asks you to choose Vite+ or Vite, a UI framework, a starter, and a deployme
 
 With pnpm, you can start with `pnpm create void my-app`. It configures native build permissions before installing Void.
 
-If a manual pnpm install reports blocked build scripts, run `pnpm approve-builds` for `esbuild`, `sharp`, and `workerd`. Set `better-sqlite3: false` in `pnpm-workspace.yaml`'s `allowBuilds`; Void uses its bundled binaries. Setup updates the pnpm lockfile, including in CI. Later installs can use `pnpm install --frozen-lockfile`.
-
 The examples below use `void` for brevity. Outside package scripts, run the local binary with `npx void`, `pnpm void`, `yarn void`, or `bunx void`. Keep Void installed in the project so the CLI and app use the same version.
 
-## Using with Coding Agents
-
-`void init` detects your coding agent and installs its instructions and skills. If detection fails, choose an agent when prompted. In agents that support it, load the `/void` skill and describe the app you want to build. See [Coding Agents](../integrations/agents) for setup details.
-
-## Meta Frameworks
-
-Use Void's [Pages routing](./pages-routing/overview) or keep a framework such as TanStack Start, React Router, or SvelteKit. Follow the [framework guides](../integrations/frameworks/overview) for setup.
-
-## Adding to an Existing Vite App
-
-Install Void using the package manager command [above](#start-in-an-empty-directory).
-
-Enable the plugin in `vite.config.ts`:
-
-```ts
-import { defineConfig } from 'vite';
-import { voidPlugin } from 'void';
-
-export default defineConfig({
-  plugins: [voidPlugin()],
-});
-```
-
-Then run `void init` with your package manager to configure the remaining project files. Existing compatibility dates are preserved; new projects use Void's tested Workers compatibility date.
-
-## Once You Have a Working App
+## Run and deploy
 
 ### 1. Edit the generated API route
 
@@ -110,32 +83,60 @@ Then visit:
 - App: `http://localhost:5173`
 - API route: `http://localhost:5173/api/hello`
 
-### 3. Choose where to deploy
+### 3. Deploy
 
-If you chose a deployment target during setup, you're ready. If you skipped it, run `void init` again or choose Cloudflare for the first deploy:
+If you chose a deployment target during setup, run:
+
+```sh
+void deploy
+```
+
+If you skipped deployment setup, select your Cloudflare account for the first deploy:
 
 ```sh
 void deploy --platform cloudflare
 ```
 
-Void opens your browser to sign in when needed. To use your team's platform, connect using the API URL from your administrator:
+Void opens your browser to sign in when needed. To use your team's platform, connect using the API URL from your administrator, then link a project and deploy:
 
 ```sh
 void connect https://platform.example.com
 void project link
+void deploy
 ```
 
-### 4. Deploy
+Void builds the app, provisions its resources, applies pending migrations, and prints the deployed URL. If a production secret is missing, [set it](./env-vars.md) and deploy again. Later deploys use the saved target.
 
-With your target configured, run:
+See [Deployment](./deployment.md) for CI setup and rollback.
 
-```sh
-void deploy
+## Using with Coding Agents
+
+`void init` detects your coding agent and installs its instructions and skills. If no agent is detected, use the bundled docs linked in `AGENTS.md`. In agents that support it, load the `/void` skill and describe the app you want to build. See [Coding Agents](../integrations/agents) for setup details.
+
+## Meta Frameworks
+
+Use Void's [Pages routing](./pages-routing/overview) or keep a framework such as TanStack Start, React Router, or SvelteKit. Follow the [framework guides](../integrations/frameworks/overview) for setup.
+
+## Adding to an Existing Vite App
+
+Install Void using the package manager command [above](#start-in-an-empty-directory).
+
+Enable the plugin in `vite.config.ts`:
+
+```ts
+import { defineConfig } from 'vite';
+import { voidPlugin } from 'void';
+
+export default defineConfig({
+  plugins: [voidPlugin()],
+});
 ```
 
-Void builds the app, provisions the resources it uses, applies pending migrations, and prints the deployed URL. If it reports a missing production secret, [configure that secret](./env-vars.md) and deploy again.
+Then run `void init` with your package manager to configure the remaining project files.
+
+## Troubleshooting pnpm installs
 
-Subsequent deploys use the same target. See [Deployment](./deployment.md) for CI setup, migrations, and rollback. To generate a supported push-to-deploy workflow, run `void init --github`.
+If a manual pnpm install reports blocked build scripts, run `pnpm approve-builds` for `esbuild`, `sharp`, and `workerd`. Set `better-sqlite3: false` in `pnpm-workspace.yaml`'s `allowBuilds`; Void uses its bundled binaries.
 
 ## Next steps
 

package/skills/void/docs/guide/remote-dev.md

@@ -42,13 +42,9 @@ VOID_REMOTE=1 vite dev
 | R2      | Local file-backed R2       | Remote R2 bucket    |
 | AI      | Always proxied             | Always proxied      |
 
-AI inference is always routed through the proxy regardless of remote mode. There is no local AI emulation.
+AI requests use your platform’s account and allowance in both local and remote mode. There is no local AI simulator.
 
-## How It Works
-
-In remote mode, binding calls go through your platform's proxy, authenticated with your login token. The proxy uses the linked project's configuration to choose the D1 database, KV namespace, or R2 bucket.
-
-You don't need to change any code. Imports like `import { db } from "void/db"` and direct binding access via `c.env.KV` both work transparently.
+## Checking Remote Mode
 
 When the dev server starts with remote mode active, it prints:
 
@@ -63,7 +59,6 @@ When the dev server starts with remote mode active, it prints:
 
 - **Network latency:** each binding call makes a network request, so responses may be slower than local development.
 - **R2 multipart uploads:** `createMultipartUpload()` and `resumeMultipartUpload()` are not supported in remote mode.
-- **R2 conditional writes:** `put(..., { onlyIf })` requires a current Void platform and an active deployment with the native remote-binding handler. Update the platform and redeploy the project if this operation is unavailable. Failed preconditions return `null`; Void never retries a conditional write as an unconditional REST upload.
+- **R2 conditional writes:** `put(..., { onlyIf })` requires a current Void platform and an active deployment with the native remote-binding handler. Update the platform and redeploy the project if this operation is unavailable. Failed preconditions return `null`.
 - **D1 dump:** `db.dump()` is not supported in remote mode.
-- **D1 batch compatibility:** `db.batch()` requires an active deployment with the native remote-binding handler. Void does not split a batch into REST calls because that would lose D1's atomic all-or-nothing behavior.
-- **Writes affect real data:** remote mode connects to your actual deployed resources. Inserts, updates, and deletes are real, so use it carefully or point it at a staging project.
+- **D1 batches:** `db.batch()` requires an updated platform and project deployment.

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

@@ -12,13 +12,13 @@ import { getSandbox } from 'void/sandbox';
 
 export const POST = defineHandler(async (c) => {
   const sandbox = await getSandbox('default');
-  const process = await sandbox.exec(['node', '--version']);
-  const result = await process.output();
-
-  return c.json({
-    exitCode: result.exitCode,
-    stdout: new TextDecoder().decode(result.stdout),
-    stderr: new TextDecoder().decode(result.stderr),
+  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.' }),
   });
 });
 ```
@@ -27,7 +27,7 @@ Importing from `void/sandbox` enables the required resources. Local development,
 
 ## Configuration
 
-Most apps do not need config. The default binding is `SANDBOX`, the Durable Object class is `SandboxV1`, and the default environment provides Node.js 24 on Debian Trixie. Local development and native deploys build Void's packaged Dockerfile, so Docker must be running. Managed platform deploys use Cloudflare's managed Node.js image.
+The default environment provides Node.js 24 on Debian Trixie. Local development and native deploys need Docker running. Managed platform deploys use Cloudflare's managed Node.js image.
 
 Use `void.config.ts` when you need a custom image or container size:
 
@@ -62,7 +62,7 @@ WORKDIR /workspace
 CMD ["sleep", "infinity"]
 ```
 
-For a managed platform, push your custom image to that platform account's Cloudflare registry and set `platformImage` to its digest-pinned reference. If `image` is already a Cloudflare registry reference, it also becomes the default `platformImage`. External registry references and mutable tags are not supported by the new scheduling policy. See [Cloudflare's image management guide](https://developers.cloudflare.com/containers/guides/image-management/#push-images-to-the-cloudflare-registry).
+For a managed platform, push your custom image to that platform account's Cloudflare registry and set `platformImage` to its digest-pinned reference. If `image` is already a Cloudflare registry reference, it also becomes the default `platformImage`. External registries and mutable tags are not supported. See [Cloudflare's image management guide](https://developers.cloudflare.com/containers/guides/image-management/#push-images-to-the-cloudflare-registry).
 
 ## Runtime API
 
@@ -75,37 +75,45 @@ const sandbox = await getSandbox(`user-${user.id}`, {
   inactivityTimeoutMs: 10 * 60 * 1000,
   enableInternet: false,
 });
-await sandbox.files.writeFile('/workspace/input.txt', 'hello');
-const process = await sandbox.exec(['cat', '/workspace/input.txt'], {
-  signal: AbortSignal.timeout(5_000),
-});
-const { stdout, exitCode } = await process.output();
-const text = new TextDecoder().decode(stdout);
+const response = await sandbox
+  .run(['node', '--version'], {
+    signal: AbortSignal.timeout(5_000),
+  })
+  .match({
+    ok: (result) => Response.json({ exitCode: result.exitCode }),
+    limited: (limit) => limit.response(),
+  });
 ```
 
 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`.
 
-`exec()` returns a process immediately after it starts. Read its `stdout` and `stderr` streams, or call `output()` to collect both as `ArrayBuffer`s together with the exit code. `exitCode` is a promise; `kill(signal?)` and `resize(cols, rows)` are asynchronous. Use `stdin: 'pipe'` to receive a writable `stdin` stream. A process can continue running after a request returns, until it exits or its container stops. When streaming output from a long command, await `process.exitCode` alongside consuming its streams. This keeps an explicit command wait active even while the command produces no output; unattended background commands can stop when the Sandbox becomes idle.
+`run()` collects command output and handles limits throughout execution with one required `.match({ ok, limited })`. Both handlers are required. Other failures still reject.
 
-File operations live under `sandbox.files`: `readFile`, `writeFile`, `stat`, `lstat`, `readDirectory`, `mkdir`, `rename`, and `remove`. `readFile()` returns a streaming `Response`; use `.text()`, `.arrayBuffer()`, or `.body`. `writeFile()` accepts text, binary data, or a byte stream. Relative file paths require an explicit `cwd` option.
+`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.
 
-To reach a server inside the container, call `sandbox.fetch(port, new Request(url))`. `sandbox.running()` checks whether the container is running; `sandbox.destroy()` stops it.
+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.
+
+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.
 
 `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.
+
 ## State persistence
 
 `getSandbox(id)` selects the same Durable Object for that ID within a deployment. Native Cloudflare deployments preserve that namespace across Worker versions. Each managed platform deployment has its own namespace; rolling back to a retained deployment reconnects to that deployment's namespace.
 
-Files, running processes, and listening servers last only as long as the container. It can stop after inactivity, crash, or restart. Save anything you need to keep in your database, KV, or R2. For custom Durable Object implementations, `void/sandbox` also exports the SDK's `Files`, `DirectoryBackup`, `DirectoryBackupGateway`, `S3Mount`, and `S3Gateway` helpers. Deleting a project on a Void platform removes both its Durable Objects and containers.
+Files, running processes, and listening servers last only as long as the container. It can stop after inactivity, crash, or restart. Save anything you need to keep in your database, KV, or R2. Deleting a project on a Void platform removes both its Durable Objects and containers.
 
 ## Deployment
 
-Sandboxes require [Workers Paid](https://dash.cloudflare.com/?to=/:account/workers/plans) and Containers access. Void checks this before provisioning or building. A managed platform's runtime token needs Account / Containers: Edit and Account / Cloudchamber: Edit. Applications without Sandbox do not require Containers or perform this entitlement check.
+Sandboxes require [Workers Paid](https://dash.cloudflare.com/?to=/:account/workers/plans) and Containers access. A managed platform's runtime token needs Account / Containers: Edit and Account / Cloudchamber: Edit.
 
-`void deploy --platform cloudflare` builds native images and deploys the Sandbox alongside the application. `void deploy` on a connected Void Platform creates a deployment-scoped Sandbox controller, which enforces concurrency and runtime limits. Upgrade the platform before deploying an application built with this Sandbox API.
+`void deploy --platform cloudflare` builds native images and deploys the Sandbox alongside the application. `void deploy` on a connected Void Platform applies the platform's Sandbox concurrency and runtime limits. Upgrade the platform before deploying an application built with this Sandbox API.
 
 ## Moving from Sandbox SDK 0.x