void 0.24.0 → 0.26.0

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

@@ -11,9 +11,7 @@ void platform auth login
 void platform config plans
 ```
 
-Choose a plan to inspect or edit it, copy one into a new plan, or choose the default for new accounts. Existing installations keep their plans, limits, and default until you change them. After upgrading the platform to support plan configuration, these changes require no app or platform redeploy.
-
-Inspection and previews are available immediately after a platform upgrade. Allow 15 minutes before applying changes.
+Choose a plan to inspect or edit it, copy one into a new plan, or choose the default for new accounts. Changes require no app or platform redeploy.
 
 ## Use the Dashboard
 
@@ -90,8 +88,6 @@ Storage figures shown for D1, R2, and KV are informational and cannot be edited
 
 The preview shows the affected account count and checks a sample for accounts already above a proposed quota. Lowering a quota can restrict existing apps, including accounts outside that sample. Usage history and billing periods are preserved, so a plan change does not reset usage. Manual administrator suspensions remain in effect.
 
-After the initial platform upgrade, request quota accounting includes unlimited plans too. For an account that was unlimited before that upgrade, its quota counter may not include earlier requests in the current billing period. Historical analytics remain available. When introducing its first cap, allow for the remaining period or wait until its next billing period.
-
 ## Archive or Remove a Plan
 
 Archive a plan to stop assigning it to new accounts while preserving its current accounts:

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

@@ -8,10 +8,7 @@ Project Zero Trust puts Cloudflare Access in front of the hostnames of projects
 
 This is separate from the Access login and protection for the platform API. Projects deployed directly to Cloudflare are not affected.
 
-New installations choose app access during `void platform install`. The installer
-reuses the platform policy or helps you select separate company rules, and finishes
-setup before opening traffic. Existing installations keep their settings when
-upgraded; use this page to configure app access if it has not been set up yet.
+Choose app access during `void platform install`, or configure it later using this page. The installer reuses the platform policy or helps you select separate company rules, and finishes setup before opening traffic.
 
 If you choose public apps in an account with Default-Deny, Void manages scoped
 public rules instead. New projects and custom domains remain public automatically.

package/skills/void/docs/guide/platform/development/schema-ci.md

@@ -14,7 +14,13 @@ vp run --filter @voidcloud/api db:generate
 
 Review the generated SQL and migration journal before committing them. Released migrations are append-only. An upgrade applies new migrations while the previous Workers may still serve requests, so schema changes must remain compatible with that code.
 
-`platform/packages/api/drizzle/compatibility.json` records which earlier runtimes have been verified against the new schema. Add an edge only after testing that compatibility. The runtime build checks that the migration files and recorded schema history agree. See `packages/platform/README.md` for the manifest contract.
+`platform/packages/api/drizzle/compatibility.json` records which earlier runtimes have been verified against the new schema. Add an edge only after testing that compatibility. The runtime build checks that the migration files and recorded schema history agree.
+
+## Runtime artifact contract
+
+`@void/platform` contains installation manifests, resource naming, discovery contracts, Worker configuration, and deployable bundles under the `./installer` export. Platform source lives in `platform/packages/`.
+
+Runtime artifacts include migration SQL, its journal, and a rollback compatibility manifest. Drizzle authoring snapshots remain in the source tree. Migrations are forward-only; compatibility edges in `platform/packages/api/drizzle/compatibility.json` must be tested against the earlier runtime before publication. The build verifies schema lineage and hashes the journal and SQL files.
 
 ## CI in a Fork
 

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
 
@@ -42,11 +42,6 @@ secret manager to an object keyed by each exact API/proxy origin, with
 and stops if the gate still rejects its checks. Account-wide Default-Deny and
 deployed-application policies remain your responsibility.
 
-If **System Status** reports `proxy HTTP 302 (redirect)` on an older Access-protected
-installation, upgrade with `void platform upgrade <id>`. Current installations use
-a private connection for the dashboard's proxy health check. Keep the proxy's
-Access protection enabled.
-
 ### Expired administrator setup code
 
 Resume an unfinished installation with `void platform install --resume --name <id>`.
@@ -68,7 +63,7 @@ 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.
+Keep the platform runtime current when updating the Void CLI.
 
 Use the installed CLI's packaged runtime to upgrade:
 
@@ -79,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.
@@ -92,10 +89,6 @@ manager so they can also restore a missing Worker during repair.
 
 Database migrations only move forward. Void checks compatibility before upgrading and tells you if an intermediate release is needed. If deployment fails, it attempts to restore the previous Workers against the compatible database schema. Retrying does not repeat completed migrations.
 
-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/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:
 
 ```sh
@@ -107,6 +100,35 @@ Keep the earlier runtime files if you need rollback. If the installed version is
 
 :::
 
+### Follow upgrade and rollback progress
+
+Watching progress is optional: a running upgrade or rollback proceeds through
+the CLI without action on the status page. During maintenance, navigating the
+admin UI automatically redirects to `/admin/status`. You can also open it
+directly on your platform API origin and sign in as an administrator.
+
+The read-only page shows the saved operation, source and target versions, and
+the traffic state reported by the API. It refreshes automatically every five
+seconds while visible. If updates fail, it keeps the last confirmed snapshot
+and marks it as out of date. Normal administrator changes remain paused.
+
+Sign-in and status remain available while the API and authentication database
+are reachable. An operation completing
+does not confirm every project's health. A disabled installation keeps traffic
+paused after an upgrade or rollback.
+
+If an operation fails or waits for DNS or Sandbox drain work, the CLI prints
+the recovery instructions and command needed to resume. Resolve the reported
+problem, then resume with the same runtime files. For a custom rollback, retain
+the source runtime files too. `void platform status <id>` also prints locally saved progress
+before checking the live API; this local checkpoint can be out of date if another
+administrator changed the installation.
+
+When application traffic is paused, visitors receive a temporary-unavailability
+page with a **Try again** link. API requests and form submissions still receive
+HTTP 503 responses. Void does not automatically replay requests; visitors who
+submitted a form should check its result before submitting it again.
+
 ### Manage an installation from another machine
 
 Use `discover` to restore the administrator's local installation records:

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

@@ -73,16 +73,88 @@ Use any PostgreSQL provider that accepts connections from your computer and Clou
 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, 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                                                                                                                                                                                                                                      |
-| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [PlanetScale Postgres](https://planetscale.com/docs/postgres/connecting)     | Choose **Postgres**, not Vitess/MySQL. Open **Connect**, create role credentials, and use the direct primary connection on port `5432`, not PgBouncer on `6432`.                                                                                      |
-| [Neon](https://neon.com/docs/get-started-with-neon/connect-neon)             | Open **Connect**, select the database and owner role, and turn **connection pooling off**.                                                                                                                                                            |
-| [Supabase](https://supabase.com/docs/guides/database/connecting-to-postgres) | Open **Connect** and use the direct connection where IPv6 is available, or the **Session pooler** on port `5432` for IPv4 connectivity. Do not select the transaction pooler on `6543`. Replace the password placeholder with your database password. |
-
-For a dedicated Supabase project, [disable the Data API](https://supabase.com/docs/guides/api/securing-your-api#disable-the-data-api) so the platform's tables are not exposed through Supabase's auto-generated endpoints. Void uses the PostgreSQL connection, not Supabase API keys.
+| Provider                                                                 | Connection setup                                                                                                                                                 |
+| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [PlanetScale Postgres](https://planetscale.com/docs/postgres/connecting) | Choose **Postgres**, not Vitess/MySQL. Open **Connect**, create role credentials, and use the direct primary connection on port `5432`, not PgBouncer on `6432`. |
+| [Neon](https://neon.com/docs/get-started-with-neon/connect-neon)         | Open **Connect**, select the database and owner role, and turn **connection pooling off**.                                                                       |
 
 Once installation claims the database, continue using that same database for resume and maintenance commands. Uninstall never deletes external PostgreSQL.
 
+### Use a provider CLI
+
+You can create the database and retrieve its connection URL from either provider's CLI instead of its dashboard.
+
+::: details PlanetScale Postgres
+
+Install the latest [PlanetScale CLI](https://planetscale.com/docs/cli/planetscale-environment-setup). On macOS, use `brew install pscale`; the installation guide also covers Linux and Windows.
+
+Sign in and list your organizations and regions:
+
+```sh
+pscale auth login
+pscale org list
+pscale region list --org <organization>
+```
+
+Replace `<organization>` with your organization slug and choose a region. List the available Postgres cluster sizes and their prices for that region:
+
+```sh
+pscale size cluster list --org <organization> --engine postgresql --region <region>
+```
+
+Create a dedicated Postgres database with your chosen cluster size, then create a role with permission to create and migrate Void's tables:
+
+```sh
+pscale database create void-platform \
+  --org <organization> \
+  --engine postgresql \
+  --region <region> \
+  --cluster-size <cluster-size> \
+  --wait
+
+pscale role create void-platform main void_owner \
+  --org <organization> \
+  --inherited-roles postgres
+```
+
+Save the **DATABASE URL** printed by the role-creation command in your password manager and paste it into Void's `PostgreSQL DATABASE_URL` prompt. Use the direct primary connection on port `5432` with `sslmode=verify-full`. The role's password is shown when it is created, so save it before closing the terminal.
+
+See PlanetScale's [database commands](https://planetscale.com/docs/cli/database) and [role commands](https://planetscale.com/docs/cli/role) for more options.
+
+:::
+
+::: details Neon
+
+Install the latest [Neon CLI](https://neon.com/docs/cli/install) and sign in:
+
+```sh
+pnpm add --global neon@latest
+neon login
+```
+
+Create a dedicated project, database, and owner role. Replace `<region-id>` with one of Neon's [supported regions](https://neon.com/docs/cli/projects#create), such as `aws-us-east-2`:
+
+```sh
+neon projects create --name void-platform \
+  --database void_platform \
+  --role void_owner \
+  --region-id <region-id>
+```
+
+Use the project ID from the output to retrieve a direct primary connection URL with TLS certificate verification:
+
+```sh
+neon connection-string --project-id <project-id> \
+  --database-name void_platform \
+  --role-name void_owner \
+  --endpoint-type read_write \
+  --ssl verify-full
+```
+
+Save the printed URL in your password manager and paste it into Void's `PostgreSQL DATABASE_URL` prompt. Keep this connection unpooled. See Neon's [connection-string command](https://neon.com/docs/cli/connection-string) for more options.
+
+:::
+
 ### Use an existing Hyperdrive
 
 The installer can create Hyperdrive for you or use one you manage separately. For an existing configuration:

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/quickstart.md

@@ -4,65 +4,51 @@ outline: deep
 
 # Quickstart
 
-Create a Void app, run it locally, and deploy it. You can also [add Void to an existing Vite app](#adding-to-an-existing-vite-app). Use Node.js 24.21.0 or later.
+Create a Void app, run it locally, and deploy it. You can also [add Void to an existing Vite app](#adding-to-an-existing-vite-app).
 
-## Start in an Empty Directory
+## Create an app
 
-Install Void in an empty project directory:
+In an empty directory, install Void and run setup:
 
 ::: code-group
 
 ```sh [npm]
 npm install -D void
+npx void init
 ```
 
 ```sh [pnpm]
 pnpm add -D void
+pnpm void init
 ```
 
 ```sh [yarn]
 yarn add -D void
+yarn void init
 ```
 
 ```sh [bun]
 bun add -D void
+bunx void init
 ```
 
 :::
 
-Run setup:
-
-::: code-group
-
-```sh [npm]
-npx void init
-```
+Choose your UI framework, a starter, and a deployment target. Vite+ is the default build tool. D1 is a good first database: it runs locally without a separate database server. Choose Cloudflare to deploy to your own account, or skip deployment setup for now.
 
-```sh [pnpm]
-pnpm void init
-```
+With pnpm, `pnpm create void my-app` also creates the project directory and configures native build permissions for you.
 
-```sh [yarn]
-yarn void init
-```
+## Run locally
 
-```sh [bun]
-bunx void init
+```sh
+npm run dev
 ```
 
-:::
-
-Void asks you to choose Vite+ or Vite, a UI framework, a starter, and a deployment target. Vite+ is the default. D1 needs no local database server; choose PostgreSQL or MySQL if you use an external database. You can skip deployment setup and decide later.
-
-With pnpm, you can start with `pnpm create void my-app`. It configures native build permissions before installing Void.
-
-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.
+Open `http://localhost:5173`. In a Pages starter, `pages/` contains your UI and companion `.server.ts` files contain its server loaders and actions. Loaders return data to page components as typed props.
 
-## Run and deploy
+## Call a server route
 
-### 1. Edit the generated API route
-
-Database-backed starters include `routes/api/hello.ts`. You can edit its `GET` handler, or create this file if you started with Static Pages:
+Edit `routes/api/hello.ts`, or create it if your starter doesn't include it:
 
 ```ts
 import { defineHandler } from 'void';
@@ -72,75 +58,46 @@ export const GET = defineHandler(() => {
 });
 ```
 
-### 2. Run locally
-
-```sh
-npm run dev
-```
+Visit `http://localhost:5173/api/hello` to see the response. From your client code, call it with Void's typed fetch:
 
-Then visit:
+```ts
+import { fetch } from 'void/client';
 
-- App: `http://localhost:5173`
-- API route: `http://localhost:5173/api/hello`
+const { message } = await fetch('/api/hello');
+```
 
-### 3. Deploy
+The file path defines the URL, and the handler defines the response type. Change `message` in the handler and TypeScript checks the client against the new shape.
 
-If you chose a deployment target during setup, run:
+Database starters also include `db/schema.ts`. Its Drizzle schema defines your tables and query types; Void runs a local database and provisions one when you deploy.
 
-```sh
-void deploy
-```
+## Deploy
 
-If you skipped deployment setup, select your Cloudflare account for the first deploy:
+If you chose a target during setup:
 
 ```sh
-void deploy --platform cloudflare
+npx void deploy
 ```
 
-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:
+If you skipped setup, select your Cloudflare account:
 
 ```sh
-void connect https://platform.example.com
-void project link
-void deploy
+npx void deploy --platform cloudflare
 ```
 
-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.
-
-See [Deployment](./deployment.md) for CI setup and rollback.
-
-## 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.
+Void opens your browser to sign in when needed, builds the app, provisions resources, applies migrations, and prints the deployed URL. Later deploys use the saved target. See [Deployment](./deployment.md) for team platforms, CI, and rollback.
 
-## Meta Frameworks
+## Adding to an existing Vite app
 
-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.
+Install Void and run `void init` with your package manager as shown [above](#create-an-app). Setup adds `voidPlugin()` to your Vite config and creates the remaining project files. If the config needs a manual edit, the CLI shows the change to make.
 
-## Adding to an Existing Vite App
+For a meta framework such as TanStack Start, React Router, or SvelteKit, follow its [integration guide](../integrations/frameworks/overview.md).
 
-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.
+## Next steps
 
-## Troubleshooting pnpm installs
+- [Pages Routing](./pages-routing/overview.md): loaders, layouts, and forms
+- [Server Routing](./server-routing.md): params, middleware, and validation
+- [Database](./database.md): queries and migrations
+- [Environment Variables](./env-vars.md): local values and production secrets
+- [Coding Agents](../integrations/agents.md): use Void's bundled docs and skills
 
 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
-
-- To understand what kind of apps are supported: [Supported App Types](./app-types)
-- [Server Routing](./server-routing): dynamic params, middleware, and validation
-- [Database](./database): queries, migrations, and generated types
-- [Type Safety](./type-safety): end-to-end typed fetch client