void 0.20.2 → 0.21.0

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

@@ -0,0 +1,56 @@
+---
+outline: deep
+---
+
+# Users and Projects
+
+## Managing Users and Projects
+
+Start by finding the user you want to inspect:
+
+```sh
+void platform user list --search teammate
+void platform user show <user-id>
+```
+
+Use the ID from the list in the second command. The detail view shows the user's projects and usage. You can change their plan or list just their projects:
+
+```sh
+void platform user plan <user-id> pro
+void platform project list --user <user-id>
+void platform project show <project-id>
+```
+
+Project details include resources, domains, and recent builds and deployments. The [command reference](/reference/cli#operator-commands) also covers suspending and restoring users, deleting projects, and removing accounts.
+
+In the admin dashboard, open a project to view its team. Search for a platform user and choose a role to add them immediately; an email address is not required. You can also change or remove existing members. Pending invitations created through other project workflows remain visible until accepted or revoked. If email is unavailable for a pending invitation, share its ID so the user can accept it with `void project team accept <invitation-id>`. The owner cannot be removed from the team; transfer ownership first.
+
+### Transferring Project Ownership
+
+Only an installation administrator can change a project's owner. The new owner must already have an account on this platform. In the dashboard, search for the new owner on the project page and preview the transfer before applying it. The CLI accepts a user ID:
+
+```sh
+void platform project owner <project-id> <new-owner-user-id> --plan
+void platform project owner <project-id> <new-owner-user-id> --yes
+```
+
+The preview shows both owners, their plans and suspension state, blockers, and the changes to routing and usage counters. Wait for active rollbacks and builds to finish. For an ordinary active deployment, wait or use `void platform deployment cancel <id>`; rollback deployments cannot be canceled. A managed Sandbox controller also blocks transfer until its cleanup completes, even if no Sandbox container is running; the preview identifies the deployment that owns it.
+
+After the transfer, the former owner becomes a project administrator. Existing project-scoped CI deploy credentials are revoked; create replacements as the new owner. The new owner's plan and limits apply immediately. Usage before the transfer remains charged to the former owner; later usage is charged to the new owner. If an apply reports partial convergence, inspect the project and operator event log before repeating it.
+
+New users on a self-hosted installation start with the `custom` profile, which
+does not cap application requests, AI usage, deployment frequency, or retained
+Worker deployments. Named profiles such as `pro` apply the platform's quota and
+retention policies; they do not purchase Cloudflare services or bill your users.
+Storage figures are not a hard storage-quota boundary. Set an operating budget
+and retention policy before opening signup beyond your invited team.
+
+The last active administrator cannot be deleted or suspended, including through
+the browser admin UI. Another administrator must still have access. Automatic
+usage limits do not remove administrator access and do not count as a manual
+suspension.
+
+When removing another administrator, Void revokes their administrator access
+before changing application traffic or deleting resources. If cleanup fails,
+access stays revoked and the error describes the partial result. A remaining
+administrator can inspect it and retry cleanup.

package/skills/void/docs/guide/platform/development/local.md

@@ -0,0 +1,119 @@
+---
+outline: deep
+---
+
+# Local Development
+
+## Setting Up the Repository
+
+Clone your fork and install the workspace dependencies with Vite+:
+
+```sh
+git clone https://github.com/your-org/void.git
+cd void
+vp install
+vpr install:void-dev
+void-dev --help
+```
+
+Use the Node.js version recorded in `.node-version`. The workspace uses public npm packages; a GitHub Packages token is not required.
+
+`install:void-dev` builds the CLI, shared packages, and platform runtime, then makes this checkout's built CLI globally available as `void-dev`. Public packages export their built files, so run `vp run build:core` after later source changes to refresh the alias. The installer refuses to replace an unrelated global command. Remove only this checkout's alias with `vpr uninstall:void-dev`. The commands on these development pages run from the repository root.
+
+## Finding the Implementation
+
+| Directory                                            | Purpose                                                              |
+| ---------------------------------------------------- | -------------------------------------------------------------------- |
+| `packages/void`                                      | Framework, application runtime, and CLI                              |
+| `packages/platform`                                  | Installer contracts, packaged Workers, and platform migrations       |
+| `packages/deploy-core`, `packages/deploy-cloudflare` | Shared deployment contracts and Cloudflare upload code               |
+| `platform/packages/api`                              | Users, projects, deployments, provisioning, and administrator API/UI |
+| `platform/packages/dispatch`                         | Application routing and static assets                                |
+| `platform/packages/proxy`                            | AI, remote bindings, and revalidation                                |
+| `platform/packages/email-gateway`                    | Inbound mail routing and tenant delivery                             |
+| `platform/packages/tail`                             | Runtime log ingestion                                                |
+| `platform/packages/dashboard`                        | Dashboard source and local UI components in `ui/`                    |
+
+The `@voidcloud/*` names identify workspace implementation packages. Their `private: true` flags prevent publishing those packages to npm. Deployable core Workers are bundled into the public `@void/platform` package.
+
+The core installer creates the API, dispatch, proxy, and tail Workers. The dashboard and managed GitHub build services are available in the source tree but are not included in that installation. Adding an optional service requires its infrastructure, bindings, authentication, and capability configuration together.
+
+## Running the API Locally
+
+Start a local PostgreSQL server and make `psql` and `pg_isready` available on your path. Then create the development database, apply its migrations, and seed an administrator:
+
+```sh
+vp run --filter @voidcloud/api setup --admin-email dev@example.com
+vp run --filter @voidcloud/api dev --local --enable-containers=false --host localhost --port 8787
+```
+
+The command disables the optional build containers, so basic API and admin work
+does not require Docker. To develop managed builds, install Docker and run the
+API with containers enabled.
+
+Open `http://localhost:8787/admin/`. Setup writes local development values to the API and dashboard `.dev.vars` files, including the development authentication bypass and local database connection. Those files are ignored by Git. Production installations get separate credentials through the installer.
+
+The API's development bypass lets you work on the browser admin UI without setting up OAuth. Operator CLI sessions still require administrator authentication; they do not use the browser bypass.
+
+## Running the Dashboard Locally
+
+The dashboard is a separate source app. After API setup, start it in another terminal:
+
+```sh
+vp run --filter @voidcloud/dashboard dev
+```
+
+Its local `.dev.vars` should point to the API you started:
+
+```dotenv
+API_URL=http://localhost:8787
+SITE_DOMAIN=apps.example.com
+```
+
+Open the Vite URL and choose **Dev login (local API)**. That button appears for a localhost API and uses the local development sign-in endpoint.
+
+You can also point the dashboard at an API that you operate. If Cloudflare Access protects that API, install `cloudflared` and opt into the dashboard's local token helper with matching origins:
+
+```dotenv
+API_URL=https://platform.example.com
+CF_ACCESS_APP_URL=https://platform.example.com
+SITE_DOMAIN=apps.example.com
+```
+
+The helper refreshes an Access session before the dev server starts. Human
+dashboard requests require the user's Access session as well as their Void login;
+a service token does not represent that user. Service-token pairs are for scoped
+machine operations. This is dashboard development configuration; Access
+credentials are separate from platform login credentials.
+
+For a deployed dashboard, bind its `API` service to your platform API, configure
+`DASHBOARD_URL` on both the dashboard and API, and include that exact dashboard origin in the
+platform's Access protection application. The dashboard passes the browser's
+company identity to the API using that service binding. Its login page shows
+the platform's currently enabled methods, and **Account** supports adding an
+additional login identity.
+
+## Testing Changes
+
+Run tests for the area you changed while developing:
+
+```sh
+vp test run platform/packages/api/test/integration/operator-auth.test.ts
+vp run check
+```
+
+Before preparing a release, build the packages and run the complete checks:
+
+```sh
+vp run build:all
+vp run check
+vp lint
+vp run lint:platform
+vp fmt --check
+vp test run
+vp run build:docs
+```
+
+Platform integration tests use their local test database by default. To test against PostgreSQL, set `VOID_TEST_DATABASE_URL` to a disposable database: these tests clear tables between cases.
+
+To exercise a deployed application, deploy a disposable copy of `playground/kitchen-sink` and pass its URL as `SMOKE_URL` to the smoke test described in `platform/scripts/kitchen-sink-smoke-test.md`. That test creates and removes application data.

package/skills/void/docs/guide/platform/development/runtime.md

@@ -0,0 +1,124 @@
+---
+outline: deep
+---
+
+# Runtime and Source Builds
+
+## Deploying Your Runtime
+
+Build the runtime. From a Git checkout, the build automatically records the current commit in the runtime manifest. An uncommitted checkout is recorded with a `-dirty` suffix:
+
+```sh
+vp run build:core
+```
+
+Build systems may set `VOID_PLATFORM_SOURCE_REVISION` when they need to override automatic detection with another immutable revision. A source archive without Git metadata builds normally but leaves the revision unrecorded.
+
+The runtime is written to `packages/platform/dist/runtime`. Use the built CLI to preview a new installation from those files:
+
+```sh
+void-dev platform install \
+  --name my-team \
+  --application-domain example.app \
+  --zone example.app \
+  --runtime packages/platform/dist/runtime \
+  --plan
+```
+
+Before applying the plan, complete the [installation guides](/guide/self-hosted-platform). Run the command without `--plan` to install. For testing before your domain is ready, replace `--application-domain` and `--zone` with `--workers-dev`; PostgreSQL and the runtime/GitHub/R2 credentials are still needed. Use `void-dev` in place of `void` and keep `--runtime packages/platform/dist/runtime` on install and resume commands. For an interrupted installation, keep that runtime build available until it completes.
+
+Later, run `void-dev platform domain set example.app`. Domain setup uses the existing installed runtime and needs no `--runtime`, rebuild, or app redeploy. It keeps the platform API URL and original workers.dev app URLs available.
+
+For an existing installation, preview an upgrade using its connection ID:
+
+```sh
+void-dev platform upgrade <installation-id> \
+  --runtime packages/platform/dist/runtime --plan
+```
+
+Then run it without `--plan` to apply the upgrade. Source-built runtimes go through the same artifact, database, ownership, and health checks as released runtimes. The CLI preserves a disabled installation's state and records the source revision in its installation checkpoint.
+
+## Optional GitHub Webhook Ingress for Access-Protected APIs
+
+The core installer does not deploy the dashboard, GitHub App, build Containers,
+or webhook ingress. Passing a source build with `--runtime` does not provision
+their infrastructure, bindings, credentials, or platform capabilities. The
+repository's hosted deployment scripts target Void Cloud; they are not a
+general setup procedure for adding these services to a self-hosted platform.
+Use the core CLI deployment workflow unless your fork supplies and maintains
+that optional integration.
+
+If your fork has added managed GitHub builds and Cloudflare Access protects its API hostname, GitHub cannot deliver directly
+to `/webhooks/github`: GitHub does not present your Access credentials. Do not add
+an Everyone or bypass policy to the API application.
+
+The API source package includes an optional, path-isolated Worker for this case.
+It accepts only `POST /github`, validates GitHub's signature over the raw body,
+and forwards one authenticated internal operation over an API service binding.
+The API independently verifies both that internal proof and GitHub's signature
+before running the normal webhook handler. Installations without perimeter
+protection can continue using the API's direct `/webhooks/github` endpoint.
+
+To deploy the optional ingress:
+
+1. Provision the GitHub App, build executors, API bindings, credentials, and
+   managed-build capability in your fork, then deploy its source API runtime
+   with the internal operation. A core install or upgrade alone does not add
+   managed builds.
+2. Edit `platform/packages/api/wrangler.github-webhook-ingress.jsonc`. Give the
+   ingress a name unique to the installation and set its `API` service binding to
+   the exact installed API Worker name. Keep its public hostname separate from
+   every human/API hostname covered by Access.
+3. Deploy it from the repository root:
+
+   ```sh
+   vp run --filter @voidcloud/api deploy:github-webhook-ingress --env production
+   ```
+
+   Use `--env staging` for the staging entries in the same config.
+
+4. In the Cloudflare dashboard, add encrypted Worker secrets. Set the GitHub
+   App's existing `GITHUB_WEBHOOK_SECRET` on both the API and ingress Workers.
+   Generate a separate high-entropy value, such as `openssl rand -base64 32`,
+   and set it as `GITHUB_WEBHOOK_INGRESS_SECRET` on both Workers. Do not reuse a
+   platform management, JWT, Access, or GitHub webhook credential for that value.
+5. In the GitHub App settings, keep **Content type** set to `application/json`,
+   keep the same webhook secret, and change **Webhook URL** to the isolated
+   ingress URL ending in `/github`. Use GitHub's test delivery and confirm a 2xx
+   response before relying on push builds.
+
+The ingress has no login, dashboard, project, operator, proxy, or arbitrary
+forwarding route. It does not make the GitHub integration part of the core
+installer, provision build executors, create a GitHub App, configure Cloudflare
+Access, or manage either Worker's secrets. Its body limit is 25 MiB, based on
+GitHub's [documented 25 MB webhook payload cap](https://docs.github.com/en/webhooks/webhook-events-and-payloads#payload-cap);
+malformed or larger deliveries are rejected before event processing.
+
+## Deploying Source Builds from CI
+
+Build `@void/platform` from your checkout and pass its runtime directory to `install`, `upgrade`, `repair`, `enable`, or `rollback` with `--runtime`. Custom runtimes get the same integrity, migration, health, and rollback checks as packaged releases.
+
+Void records the runtime's manifest digest, whether it was packaged or custom, and its source revision. A build from a Git checkout automatically records `HEAD`, or `<HEAD>-dirty` when the checkout has uncommitted files. Build systems can set `VOID_PLATFORM_SOURCE_REVISION` to override automatic detection.
+
+A fresh CI runner can discover the installation each time. Set `CLOUDFLARE_API_TOKEN` and `VOID_PLATFORM_DATABASE_URL` through its protected environment, then:
+
+::: details CI commands and recovery inputs
+
+```sh
+vp run build:core
+
+export VOID_PLATFORM_REGISTRY_DIR="$RUNNER_TEMP/void-platform-registry"
+export VOID_PLATFORM_RECOVERY_KEY="$(openssl rand -base64 32)"
+node packages/void/dist/cli/cli.mjs platform discover --account "$CLOUDFLARE_ACCOUNT_ID" \
+  --installation "$VOID_PLATFORM_INSTALLATION"
+node packages/void/dist/cli/cli.mjs platform upgrade "$VOID_PLATFORM_INSTALLATION" \
+  --runtime packages/platform/dist/runtime --plan
+node packages/void/dist/cli/cli.mjs platform upgrade "$VOID_PLATFORM_INSTALLATION" \
+  --runtime packages/platform/dist/runtime --yes
+```
+
+Omit the installation selector only if the account has one discoverable installation. Run one deployment per installation at a time, and let it finish before starting the next. Cancelling during migrations or Worker rollout can leave an installation waiting for recovery.
+
+Keep the management token, database URL, JWT signing secret, email signing secret for email-enabled installations, and complete project-encryption keyring in a protected CI environment. Upgrades inherit deployed Worker secrets. The original values are needed when recreating a missing Worker; configuration credentials are also needed when explicitly rotating them.
+
+:::

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

@@ -0,0 +1,95 @@
+---
+outline: deep
+---
+
+# Schema and CI
+
+## Changing the Platform Schema
+
+The schema lives in `platform/packages/api/src/schema.ts`. Generate a migration after changing it:
+
+```sh
+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.
+
+## CI in a Fork
+
+The uncredentialed test workflows use GitHub-hosted runners in forks. They build and test the workspace without requiring Void Cloud accounts, tokens, or deployment access.
+
+If your fork has a released platform version, set the repository variable
+`VOID_PLATFORM_PRODUCTION_REF` to its immutable 40-character commit SHA. Platform
+pull requests then create that version's database, seed representative user,
+project, and encrypted-secret records, and apply the proposed migrations. The
+check verifies existing data and runs the previous runtime against the upgraded
+schema. Mutable branch or tag names are rejected.
+
+Without an explicit SHA, required compatibility checks use the latest successful
+GitHub deployment to `Prod` (or `VOID_PLATFORM_PRODUCTION_ENV`). They require
+read access to deployment history and stop if no completed deployment is found.
+Advancing the production branch does not change the selected baseline. Fork
+workflows that call platform CI must grant `deployments: read` alongside
+`contents: read`.
+
+The upstream repository also contains workflows for deploying Void Cloud and publishing the official npm packages. Forks should configure their own release workflow around the built CLI and `platform upgrade --runtime`; the [source-build CI example](/guide/platform/development/runtime#deploying-source-builds-from-ci) shows the required inputs. Keep production credentials in protected environments restricted to the appropriate release refs.
+
+Public releases use matching versions for the CLI, scaffolder, adapters, and
+packaged platform. The publish workflow rejects mismatched versions and previously
+unpublished `void` versions that npm cannot reuse. Stable versions use `latest`;
+prereleases use their named channel, such as `beta` or `rc`. Numeric prereleases
+use `next`. The scaffolder installs its exact matching CLI version, so
+`create-void@beta` cannot silently select the stable CLI. Packaged platform
+runtimes record the release commit as their source revision.
+
+The npm release job uses [trusted publishing](https://docs.npmjs.com/trusted-publishers/)
+from GitHub-hosted runners, with `id-token: write` and no stored npm publishing
+token. Configure a trusted publisher for each public package using this
+repository, `publish.yml`, and the `Release` environment, allowing direct
+`npm publish`. A brand-new package
+needs an initial authenticated publication before its trusted publisher can be
+configured; subsequent releases use OIDC.
+
+The managed build fallback CLI also derives its version from
+`packages/void/package.json`; there are no separate version pins to update.
+Build its image from the repository root with
+`docker build --file platform/packages/api/container/Dockerfile .`.
+The root `.dockerignore` limits that build context to the agent, Dockerfile,
+and public SDK manifest.
+
+Publishing requires both SDK CI and platform CI, including the platform unit and
+API integration suites. Release tags also run the Windows SDK checks; a passing
+SDK-only build cannot publish a changed control plane.
+
+### Retrying a Release
+
+To retry a failed release without moving an existing tag, add `+retry.N` to a
+new Git tag, with `N` starting at `1`. Keep the package versions unchanged:
+
+| Git tag                  | Package version | npm channel |
+| ------------------------ | --------------- | ----------- |
+| `v0.21.0`                | `0.21.0`        | `latest`    |
+| `v0.21.0+retry.1`        | `0.21.0`        | `latest`    |
+| `v0.21.0-beta.1+retry.2` | `0.21.0-beta.1` | `beta`      |
+
+For example, when the packages are at `0.21.0`, commit the release fix and tag
+that commit:
+
+```sh
+git tag -a 'v0.21.0+retry.1' -m 'Retry 0.21.0 publication.'
+git push origin 'refs/tags/v0.21.0+retry.1'
+```
+
+The retry suffix belongs only in the Git tag, not in `package.json`. A `-1`
+suffix is a distinct prerelease version, not a retry. Tag and package versions
+are checked before dependency installation and the full CI jobs; retries still
+run the normal release checks.
+
+Retries publish only package versions that are still missing from npm. They
+cannot replace an already-published version. If an earlier attempt partially
+published the release and you changed its package contents, bump the version
+instead of combining different contents under the same version.
+
+For implementation history, use the design archive at `platform/meta/design-docs/README.md`. Its proposals explain earlier decisions; the source and current guides define the supported behavior.

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

@@ -0,0 +1,58 @@
+---
+outline: deep
+---
+
+# Install from CI
+
+For your first installation, follow the [interactive setup](/guide/platform/installation/setup). Use this page when automating a configured installation.
+
+::: details Non-interactive inputs
+
+Inject the following values from protected CI secrets. Do not commit them in a workflow or a plaintext secrets file.
+
+| Environment variable                         | Value from the interactive setup                                                            |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `CLOUDFLARE_API_TOKEN`                       | Management API token                                                                        |
+| `VOID_PLATFORM_RUNTIME_CLOUDFLARE_API_TOKEN` | Runtime API token                                                                           |
+| `VOID_PLATFORM_DATABASE_URL`                 | Dedicated PostgreSQL URL                                                                    |
+| `VOID_PLATFORM_HYPERDRIVE_ID`                | Existing externally managed Hyperdrive ID, when applicable                                  |
+| `VOID_PLATFORM_HYPERDRIVE_ORIGIN_HOST`       | Origin host of that Hyperdrive; set with its ID and user                                    |
+| `VOID_PLATFORM_HYPERDRIVE_ORIGIN_USER`       | Runtime database user of that Hyperdrive; set with its ID and host                          |
+| `VOID_PLATFORM_R2_ACCESS_KEY_ID`             | R2 Access Key ID                                                                            |
+| `VOID_PLATFORM_R2_SECRET_ACCESS_KEY`         | R2 Secret Access Key                                                                        |
+| `VOID_PLATFORM_JWT_SECRET`                   | Original JWT signing secret                                                                 |
+| `VOID_PLATFORM_EMAIL_SIGNING_SECRET`         | Dedicated email signing secret when email is enabled                                        |
+| `VOID_PLATFORM_PROJECT_SECRET_KEY`           | Original base64-encoded project-encryption key                                              |
+| `VOID_PLATFORM_RECOVERY_KEY`                 | Base64-encoded 32-byte key for local encrypted recovery state when no keychain is available |
+| `VOID_EMAIL_SENDER_DOMAIN`                   | Optional shared mail domain; requires `VOID_EMAIL_SHARED_ZONE_ID`                           |
+| `VOID_EMAIL_SHARED_ZONE_ID`                  | Cloudflare zone ID for that mail domain; requires `VOID_EMAIL_SENDER_DOMAIN`                |
+
+For the default GitHub-only login, also set `VOID_PLATFORM_GITHUB_CLIENT_ID`,
+`VOID_PLATFORM_GITHUB_CLIENT_SECRET`, and `VOID_PLATFORM_ADMIN_GITHUB_LOGIN`.
+For Google, OIDC, or Access login, pass `--auth-config <path>` using the
+[configuration format](/guide/platform/installation/setup#choose-login-methods).
+Inject each `clientSecretEnv` named in that file from your CI secret manager.
+Automatic Access protection may also need `VOID_PLATFORM_ACCESS_SETUP_TOKEN`
+with the [setup permissions](/guide/platform/installation/setup#cloudflare-access).
+
+Use that installation's saved signing and encryption keys on every resume or repair that needs them. After a keyring rotation, use the [complete keyring recovery inputs](/guide/platform/installation/maintenance#manage-an-installation-from-another-machine). The database claim and tables remain after uninstall; use a fresh database for a different installation.
+
+Set both email values to enable email during install or upgrade. Later upgrades reuse the recorded values. If an email-enabled installation has no recorded values, supply both before upgrading.
+
+```sh
+void platform install \
+  --name team \
+  --display-name "Team Void" \
+  --account <account-id> \
+  --application-domain example.app \
+  --zone example.app \
+  --yes
+```
+
+Mutations require `--yes` in CI; a read-only `--plan` does not. Custom runtimes also require `--runtime <directory>`. For a new installation, run `--plan` with the same account, name, and domain options as the unattended install. If you use `--auth-config`, pass the same file to both commands. Register the printed callback when creating a login provider's OAuth or OIDC client manually; automatic Access setup manages its own application. A custom API hostname is optional.
+
+:::
+
+## Customize the Platform
+
+To change the platform's implementation or deploy your own build, follow [Platform Development](/guide/platform-development). It covers local development, source builds, and CI for a fork.

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

@@ -0,0 +1,90 @@
+---
+outline: deep
+---
+
+# Credentials
+
+Keep one password-manager entry for this platform. Paste the saved values into the installer when asked; most do not need shell environment variables.
+
+## Cloudflare API Tokens {#runtime-token-permissions}
+
+For a domain installation, create two custom tokens using Cloudflare's [API token setup](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/). Name them **Void Platform Management** and **Void Platform Runtime**. Scope them to your selected account and application zone.
+
+For workers.dev testing with the default API hostname, browser login can authorize installation: you only need to create the runtime token and R2 credentials below. Skip the zone permissions until you add a domain.
+
+Browser login does not grant AI Gateway access. A preview can therefore show **inspect ai-gateway**: Void verifies that resource with the runtime token after you confirm installation, before creating any resources. Include **Account → AI Gateway → Edit** on that token. Other infrastructure continues using your browser login, and a normal API-token installation keeps using its management token when that token already has access.
+
+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.
+
+The runtime-token link preselects all required account permissions, including Workers Tail, Hyperdrive, and AI Gateway when needed. Review them against the short summary beside the link before creating the token. If the form differs, use that summary to correct it. For a domain installation, also select the indicated zone. See [Cloudflare's token template documentation](https://developers.cloudflare.com/fundamentals/api/how-to/account-owned-token-template/).
+
+::: details Permissions to select for each token
+
+Use the following permissions for the core platform. Cloudflare may label write access as **Edit** or **Write**, depending on the token screen; see its [permission reference](https://developers.cloudflare.com/fundamentals/api/reference/permissions/).
+
+| Scope   | Permission         | Management | Runtime                                 |
+| ------- | ------------------ | ---------- | --------------------------------------- |
+| Account | Account Settings   | Read       | Read                                    |
+| Account | Workers Scripts    | Edit       | Edit                                    |
+| Account | Workers Tail       | Read       | Read                                    |
+| Account | D1                 | Edit       | Edit                                    |
+| Account | Workers KV Storage | Edit       | Edit                                    |
+| Account | Workers R2 Storage | Edit       | Edit                                    |
+| Account | Queues             | Edit       | Edit                                    |
+| Account | Hyperdrive         | Write      | Write                                   |
+| Account | Account Analytics  | Read       | Read                                    |
+| Account | AI Gateway         | Edit       | Edit when installing with browser login |
+| Zone    | Zone               | Read       | —                                       |
+| Zone    | DNS                | Edit       | —                                       |
+| Zone    | Workers Routes     | Edit       | —                                       |
+| Zone    | Cache Purge        | —          | Purge                                   |
+
+The management token also needs **Zone Edit** with authority to create zones if you ask Void to create the zone. If it already exists, use the selected zone with Zone Read and DNS Edit. Nested application domains additionally need **SSL and Certificates: Read** on the management token. A custom runtime that enables custom project domains needs **SSL and Certificates: Edit** on the runtime token; the core runtime does not enable that feature.
+
+Void checks access before provisioning. If it reports a missing permission, update the token's permissions for the selected account or zone and retry.
+
+:::
+
+## Enable Email {#enable-email}
+
+Choose a shared sender domain and its Cloudflare zone ID. The mail zone may differ from the application zone, but it must belong to the platform's Cloudflare account. To enable email on an existing installation, run:
+
+```sh
+VOID_EMAIL_SENDER_DOMAIN=mail.example.com \
+VOID_EMAIL_SHARED_ZONE_ID=your-zone-id \
+void platform upgrade your-installation-id
+```
+
+Set the same two variables before `void platform install` to enable email during a new installation. Void records the pair for later upgrades; an ordinary upgrade cannot replace it.
+
+Enabling email lets administrators [register email domains for projects](/guide/platform/administration/email#registering-email-domains-for-projects) and lets projects register destination addresses through the runtime token. That needs **Email Routing Addresses: Edit** and **Email Sending: Edit** on the account, plus **Zone: Read**, **Zone Settings: Edit** and **Email Routing Rules: Edit** on the zones that will carry mail. The runtime-token link preselects them when email is enabled. Email Sending onboarding for arbitrary recipients needs Workers Paid.
+
+The installer deploys the email gateway, prepares the shared mail route, and verifies inbound readiness before opening platform traffic. If setup fails, correct the reported permission, mail-zone configuration, or routing conflict, then rerun the same install or upgrade command. A fresh install resumes with `void platform install --resume --name <installation-id>`.
+
+## R2 Upload Credentials
+
+The installer opens the **R2 token creation** form directly, requesting an account token (or a user token if your role cannot create account tokens). Select **Object Read & Write**—the form starts with read-only access—and keep **Apply to all buckets in this account (including newly created buckets)** selected. This lets the token access the buckets Void creates afterward. Create the token and save its **Access Key ID** and **Secret Access Key**. These are different from the management/runtime tokens above. See [R2's token instructions](https://developers.cloudflare.com/r2/api/tokens/).
+
+## Signing and Encryption Keys {#signing-and-encryption-keys}
+
+The **JWT signing key** signs platform login tokens. The **Project encryption key** encrypts app secrets stored by your platform. Generate a separate key for each by running this command twice:
+
+```sh
+openssl rand -base64 32
+```
+
+Save each result in your password manager, then paste it into the corresponding installer prompt. The command generates 32 random bytes encoded as base64, suitable for either field. Keep the two original keys for recovery; do not regenerate them when resuming or upgrading.
+
+::: details Generate the keys without printing them to your terminal
+
+On macOS, this copies a suitable random value to the clipboard:
+
+```sh
+openssl rand -base64 32 | pbcopy
+```
+
+Paste it into your password manager as **JWT signing key**. Run the command again and save the second value as **Project encryption key**. On PowerShell, use `Set-Clipboard` instead of `pbcopy`. If OpenSSL is unavailable, use your secret manager's secure generator for 32 random bytes in base64, or `node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("base64"))'`.
+
+:::
+
+When email is enabled, Void also creates an independent **Email signing key** for confirmation links and service-to-service email requests. The installer keeps it in encrypted recovery state. Set `VOID_PLATFORM_EMAIL_SIGNING_SECRET` to a separate value of at least 32 random bytes when you need an externally custodied copy, including a headless installation whose local recovery files will not persist.

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

@@ -0,0 +1,68 @@
+---
+outline: deep
+---
+
+# Domains and Resources
+
+## Adding a Domain
+
+When your domain is ready, run:
+
+```sh
+void platform domain set example.app --plan
+void platform domain set example.app
+```
+
+The command selects your installed platform (or offers a picker), finds or creates its zone, sets up DNS and routing, and verifies HTTPS before publishing the new application URLs. Set the management token as described in [installation setup](/guide/platform/installation/setup) when creating DNS or a zone. Grant the existing runtime token **Cache Purge: Purge** on the new zone; Void checks that permission through the running platform without asking you to paste its token again.
+
+If nameservers or certificates are pending, follow the printed guidance and rerun the same command. Your workers.dev app URLs continue working during and after setup. Projects, deployments, secrets, and the platform API URL stay the same, so developers do not reconnect and configured login callbacks do not change. DNS and configuration changes may take time to propagate.
+
+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.
+
+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.
+
+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.
+
+## Other Domain Options
+
+::: details Custom API hostname
+
+Pass `--control-plane-domain platform.example.net` during installation. The hostname must belong to a zone the selected account and management token can manage. Omitting it keeps the API on `workers.dev`.
+
+:::
+
+### Using a Nested Application Domain
+
+::: details Use apps.example.com within an existing company zone
+
+An app at `my-app.apps.example.com` needs a certificate for `*.apps.example.com`. Universal SSL for `example.com` only covers first-level hostnames. Configure an active wildcard certificate with [Advanced Certificate Manager](https://developers.cloudflare.com/ssl/edge-certificates/advanced-certificate-manager/), a paid add-on, or use an existing custom wildcard certificate before installation:
+
+```sh
+void platform install --application-domain apps.example.com --zone example.com --plan
+```
+
+The management token needs **SSL and Certificates: Read** (or Edit) on that zone for the certificate check. Void does not order certificates or enable paid products automatically. Leave `--dedicated-zone` off: that flag is only for installations whose application domain is the entire zone and adds catch-all routes for otherwise unmatched traffic.
+
+:::
+
+## 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.
+
+| Resource                                  |                                 Count | Purpose                                                                                       |
+| ----------------------------------------- | ------------------------------------: | --------------------------------------------------------------------------------------------- |
+| Workers                                   | 5, plus one per app using workers.dev | API/control plane, proxy, tail ingestion, dispatch, email gateway, and test-origin forwarders |
+| KV namespaces                             |                                     3 | Routing, ISR cache, and static asset storage                                                  |
+| R2 buckets                                |                                     1 | Static and deployment assets                                                                  |
+| Queues                                    |                                     2 | Usage events and cron firing                                                                  |
+| Workers for Platforms dispatch namespaces |                                     1 | User application Workers                                                                      |
+| Hyperdrive configurations                 |                                     1 | External platform PostgreSQL                                                                  |
+| AI Gateways                               |                                     1 | Installation-isolated AI routing and metering                                                 |
+| Proxied wildcard DNS records              |                                0 or 1 | Created only when an application domain is configured                                         |
+| Zones                                     |                                0 or 1 | Created only when the requested application zone is absent                                    |
+
+The API Worker uses four Durable Object classes for usage, cron scheduling, error monitoring, and concurrency. Worker bindings create the request and log datasets in Analytics Engine. The core installation doesn't create Container applications, a GitHub App, a dashboard Worker, or build Workers.