void 0.21.9 → 0.23.0

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
@@ -80,3 +82,7 @@ Void shows the proposed access change and asks you to confirm it. Once approved,
 To see who can join, run `void platform signup show`. You can also allow an email address or a domain such as `*@example.com`. For an OIDC user without verified email, use `void platform signup allow identity <connection-id> <subject>`; the subject match is exact and the provider's domain or group restrictions still apply. Remove that grant with `void platform signup disallow identity <connection-id> <subject>`. `void platform signup open` permits public signup; `void platform signup restrict` requires an allowlist match again.
 
 Your administrator session lasts for one hour. Use it to inspect users, projects, logs, and platform health. The [Platform Administration guide](/guide/platform-administration) walks through those workflows, previews, and automation. You can also open `<API origin>/admin/login` to use the browser admin UI.
+
+### Protect Project Hostnames with Zero Trust
+
+After installation, an administrator can require Cloudflare Access on new project hostnames while allowing each project owner or project administrator to opt out. This is independent of Access login and protection for the platform API itself, and it needs its own Cloudflare API token. See [Project Zero Trust](/guide/platform/administration/zero-trust) for the requirements, setup command, and recovery.

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,11 +66,11 @@ 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.
-3. Copy the PostgreSQL connection URL, including the password and SSL settings, into your password manager. Paste only the URL—not a surrounding `psql` command—into Void's `PostgreSQL DATABASE_URL` prompt.
+3. Copy the PostgreSQL connection URL, including the password and SSL settings, into your password manager. Paste only the URL—not a surrounding `psql` command—into Void's `PostgreSQL DATABASE_URL` prompt, as the provider gives it, including SSL settings such as `sslmode=verify-full`. A Hyperdrive that Void creates trusts only public certificate authorities, so if your database uses a private certificate authority, use a separately managed Hyperdrive, as described below.
 
 | Provider                                                                     | Connection setup                                                                                                                                                                                                                                      |
 | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -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/installation/uninstall.md

@@ -31,7 +31,7 @@ void platform uninstall [id] --plan
 void platform uninstall [id]
 ```
 
-Uninstall blocks platform traffic, removes transient Queues, and records the resources left for you to review. By default, Workers, 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 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.
 
 To also remove eligible data resources owned by the installer:
 
@@ -39,10 +39,25 @@ To also remove eligible data resources owned by the installer:
 void platform uninstall [id] --purge-data
 ```
 
-Even with `--purge-data`, Void retains Workers, 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.
+
+### 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:
+
+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.
 
 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.
 
+Uninstall does not remove the applications created for [project Zero Trust](/guide/platform/administration/zero-trust). While Zero Trust is enabled or still has Access applications, uninstall and `--plan` stop before any change and list those applications. Run `void platform zero-trust disable` first. Uninstall reads this from the installation database, so it also stops when the database cannot be reached.
+
 ::: details Why some resources require manual cleanup
 
 Resources that may have been shared or repurposed require manual review before deletion. Void verifies ownership, keeps those resources in place, and blocks platform traffic.

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

@@ -12,5 +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

@@ -4,82 +4,119 @@ outline: deep
 
 # Sandboxes
 
-Use a Cloudflare Sandbox to run commands, work with files, and expose ports from server code. Each session gets an isolated container.
+Use a Cloudflare Sandbox to run commands, work with files, and connect to servers from server code. Each Sandbox ID selects an isolated container.
 
 ```ts
 import { defineHandler } from 'void';
 import { getSandbox } from 'void/sandbox';
 
 export const POST = defineHandler(async (c) => {
-  const { command } = await c.req.json<{ command: string }>();
   const sandbox = await getSandbox('default');
-  const result = await sandbox.exec(command);
-
-  return c.json(result);
+  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.' }),
+  });
 });
 ```
 
-Importing from `void/sandbox` enables the required Sandbox resources. Native Cloudflare deployments add the `SANDBOX` Durable Object and Container metadata to the Worker. Void Platform deployments provide the same runtime API through a managed Sandbox controller.
+Importing from `void/sandbox` enables the required resources. Local development, native Cloudflare deployments, and Void Platform share the same runtime API.
 
 ## Configuration
 
-Most apps do not need config. The default binding is `SANDBOX`, the Durable Object class is `Sandbox`, and local development, native Cloudflare deploys, and Void Platform all use the published image matching the installed `@cloudflare/sandbox` version.
+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:
 
-```json
-{
-  "sandbox": {
-    "image": "./Dockerfile.sandbox",
-    "platformImage": "registry.example.com/acme/sandbox:latest",
-    "instanceType": "lite",
-    "maxInstances": 2
-  }
-}
+```ts
+import { defineConfig } from 'void/config';
+
+export default defineConfig({
+  sandbox: {
+    image: './Dockerfile.sandbox',
+    platformImage: 'registry.cloudflare.com/<account-id>/sandbox@sha256:<digest>',
+    instanceType: 'standard-1',
+  },
+});
 ```
 
-Available fields:
+| Field               | Default                     | Description                                                          |
+| ------------------- | --------------------------- | -------------------------------------------------------------------- |
+| `binding`           | `SANDBOX`                   | Binding name for local and native Cloudflare use                     |
+| `className`         | `SandboxV1`                 | Durable Object class for local and native Cloudflare use             |
+| `containerName`     | `void-sandbox-v1`           | Cloudflare container application name                                |
+| `image`             | Packaged Node.js Dockerfile | Dockerfile or digest-pinned Cloudflare registry image for native use |
+| `imageBuildContext` | Directory of `image`        | Docker build context                                                 |
+| `platformImage`     | `cloudflare/debian-trixie`  | Image used by managed platform deploys                               |
+| `instanceType`      | `lite`                      | `lite`, `standard-1`, `standard-2`, `standard-3`, or `standard-4`    |
+
+Custom images must include the helper matching Void's installed Sandbox SDK version. The SDK image supplies this binary, but is not a runnable environment itself:
+
+```dockerfile
+FROM node:24.21.0-trixie-slim
+COPY --from=docker.io/cloudflare/sandbox:1.0.0 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim
+WORKDIR /workspace
+CMD ["sleep", "infinity"]
+```
 
-| Field               | Default                    | Description                                                           |
-| ------------------- | -------------------------- | --------------------------------------------------------------------- |
-| `binding`           | `SANDBOX`                  | Binding name for local and native Cloudflare use                      |
-| `className`         | `Sandbox`                  | Durable Object class for local and native Cloudflare use              |
-| `containerName`     | `void-sandbox`             | Cloudflare container app name                                         |
-| `image`             | Matching sandbox SDK image | Dockerfile path or registry image for local and native Cloudflare use |
-| `imageBuildContext` | Directory of `image`       | Docker build context for local and native Cloudflare use              |
-| `platformImage`     | Matching sandbox SDK image | Registry image used by `void deploy`                                  |
-| `instanceType`      | `lite` on Void deploy      | Container size, such as `lite`, `basic`, `standard-1`                 |
-| `maxInstances`      | `20` on Void deploy        | Maximum number of container instances                                 |
+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
 
-`getSandbox(id, options)` returns the SDK sandbox stub for a session id. IDs are normalized by default so user-provided session ids can safely map to Durable Object names.
+`getSandbox(id, options)` resolves a Sandbox without starting it. The first command, file operation, or port request starts the container. IDs contain 1–63 characters and are lowercased by default; pass `normalizeId: false` to preserve case.
 
 ```ts
 import { getSandbox } from 'void/sandbox';
 
-// inside an async handler
-const sandbox = await getSandbox(`user-${user.id}`);
-await sandbox.writeFile('/tmp/input.txt', 'hello');
-const result = await sandbox.exec('cat /tmp/input.txt');
+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(),
+  });
 ```
 
-For code that must run on both deployment targets, use `getSandbox()`. Direct access through `c.env.SANDBOX` is available only on local and native Cloudflare deployments; managed platforms intentionally expose the application Sandbox API without the underlying lifecycle namespace.
+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`.
 
-## State persistence
+`run()` collects command output and handles limits throughout execution with one required `.match({ ok, limited })`. Both handlers are required. Other failures still reject.
 
-A sandbox has a Durable Object identity and a container that can restart:
+`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.
 
-`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.
+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.
 
-Files, running processes, exposed ports, and in-memory shell sessions last only as long as the container. It can stop after inactivity (the SDK defaults to `sleepAfter: "10m"`), crash, or restart during platform scheduling. `keepAlive: true` disables the idle timer but doesn't prevent other restarts.
+`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.
 
-Save anything you need to keep in Durable Object storage, your database, KV, or R2. The SDK also provides helpers to back up and restore directories through R2. Deleting the project on a Void platform removes both layers; routine container restarts only lose container state.
+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. Deleting a project on a Void platform removes both its Durable Objects and containers.
 
 ## Deployment
 
-`void deploy` creates a deployment-scoped Sandbox controller and container application in the Void platform account. The controller owns container lifetime, concurrency admission, and runtime accounting; the application receives only the Sandbox operations exposed by `getSandbox()`.
+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 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
 
-Platform deploys require a registry image reference. The default sandbox works without extra config. If `sandbox.image` points at a custom local Dockerfile, also set `sandbox.platformImage` to an image you have already pushed to a registry.
+Update string commands to argument arrays, move file calls under `.files`, and consume process output and file responses as shown above. Replace `sleepAfter` and `keepAlive` with `inactivityTimeoutMs`; remove `maxInstances` from configuration. The old `Sandbox` export, sessions, code interpreter, process-list helpers, and preview-URL helpers are no longer part of this API.
 
-Managed Sandboxes require Workers Paid on the platform's Cloudflare account. The platform runtime token needs Account / Containers: Edit and Account / Cloudchamber: Edit. These are checked only when an application that uses Sandbox is deployed; installing or upgrading a platform and deploying other applications does not probe Containers access.
+Existing native 0.x Sandboxes need a new Worker configuration and namespace. Back up container files and any Durable Object data, choose a fresh `worker.name`, and remove the old Sandbox bindings, containers, and migrations from that new configuration before deploying. The new default class is `SandboxV1`; existing state does not transfer automatically. Retain the old Worker until you have validated the replacement and restored your data, then clean up its resources. See [Cloudflare's scheduling-policy migration guide](https://developers.cloudflare.com/containers/guides/migrate-to-durable-object-scheduling-policy/).