void 0.23.0 → 0.25.0

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

@@ -8,6 +8,14 @@ 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.
 
+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.
+Keep these rules enabled while Default-Deny is on; removing them can block traffic.
+Public-only installations need no identity providers or company policies until you
+choose to protect apps. To renew their token in Admin, leave the policy fields blank.
+
 ## Requirements
 
 - A Cloudflare Zero Trust organization in the account that hosts the platform, with the identity providers and reusable Access policies you want to use. Select at least one Allow policy that matches people by identity. Void rejects Bypass and Service Auth policies, and rules that allow Everyone or any service token.
@@ -116,22 +124,29 @@ If a project must accept such requests:
 
 Void creates and owns these self-hosted applications in your Zero Trust organization:
 
-| Application                | Covers                                                                    | Policy                                                           | Exists                                                             |
-| -------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------ |
-| Shared project application | `*.<your domain>` and this installation's `workers.dev` testing URLs      | Your selected policies and identity providers                    | Once, while Zero Trust is enabled                                  |
-| Public exception           | One public project's `<slug>.<your domain>` and `workers.dev` testing URL | A Bypass policy for Everyone, named `Void project is public`     | One for each public project                                        |
-| Custom domain application  | All custom domains of one protected project                               | Your selected policies and identity providers                    | One for each protected project that has custom domains             |
-| Health check exception     | `void-platform-health.<your domain>/health`                               | A Bypass policy for Everyone, named `Void platform health check` | Once, while Zero Trust is enabled on an installation with a domain |
+| Application                 | Covers                                                                    | Policy                                                                   | Exists                                                             |
+| --------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------ |
+| Shared project application  | `*.<your domain>` and this installation's `workers.dev` testing URLs      | Your selected policies and identity providers                            | Once for protected-app configurations                              |
+| Public app management check | A reserved, unused dispatch check path                                    | Deny Everyone; verifies management permissions without opening hostnames | Once, instead of the shared wildcard in public-only mode           |
+| Public exception            | One public project's `<slug>.<your domain>` and `workers.dev` testing URL | A Bypass policy for Everyone, named `Void project is public`             | One for each public project                                        |
+| Custom domain application   | All managed custom domains of one project                                 | Company policies for protected projects; Bypass for public ones          | One for each project with managed custom domains                   |
+| Health check exception      | `void-platform-health.<your domain>/health`                               | A Bypass policy for Everyone, named `Void platform health check`         | Once, while Zero Trust is enabled on an installation with a domain |
+
+Installations configured through the installer also manage public custom-domain
+rules. Their custom-domain application changes policy when a project switches
+between public and protected access.
 
-Custom domains of a public project need no Access application.
+If the installer already configured the same health-check exception, Zero Trust
+reuses it. Disabling project Zero Trust leaves that existing exception in place
+so platform health checks continue to work.
 
 The number of applications Void needs is:
 
 ```text
-2 + public projects + protected projects that have custom domains
+1 + health-check applications + public projects + projects with managed custom domains
 ```
 
-Use 1 instead of 2 on an installation without a domain. For example, 40 projects with 10 public and 5 protected projects that have custom domains need 2 + 10 + 5 = 17 applications. Void stops with an error when the account has more than 500 Access applications.
+The first application is the shared company policy or the public-app management check. Count a health exception once, including when it is shared with the installer. For example, 40 projects with one health exception, 10 public projects, and 5 projects with managed custom domains need 1 + 1 + 10 + 5 = 17 applications. Void stops with an error when the account has more than 500 Access applications.
 
 #### Recognizing Void's Applications
 

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

@@ -49,7 +49,7 @@ void platform install \
   --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.
+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 `<platform-api-url>/auth/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.
 
 :::
 

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

@@ -8,15 +8,20 @@ Keep one password-manager entry for this platform. Paste the saved values into t
 
 ## 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 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 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.
+For workers.dev testing with the default API hostname, browser login can authorize
+infrastructure setup. Void also checks account-wide Access requirements; if the
+current credential cannot read them, the installer asks for a scoped Access token.
+Protected apps and public apps under Default-Deny need an ongoing app-management
+token, stored encrypted. Access setup requires a management token even on
+workers.dev. Skip zone permissions until you add a domain.
 
 Browser login does not grant AI Gateway access. Include **Account → AI Gateway → Edit** on the runtime token so Void can verify and create that resource.
 
 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 installer’s runtime-token link preselects required account permissions. Compare the form with the checklist shown beside the link, and select the indicated zone for a domain installation.
+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`.
 
 ::: details Permissions to select for each token
 
@@ -39,6 +44,8 @@ Use the following permissions for the core platform. Cloudflare may label write
 | Zone    | Workers Routes     | Edit       | —                                       |
 | Zone    | Cache Purge        | —          | Purge                                   |
 
+When Void configures Access in the installation account, the initial management-token link also selects **Account → Access: Apps and Policies → Edit** and **Account → Access: Organizations, Identity Providers, and Groups → Read**. Protection adds **Account → Access: Service Tokens → Edit**. When the authentication configuration or saved setup selects existing applications, the link requests Read access instead of Edit. These permissions belong to the management token; the runtime token does not need them.
+
 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.

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

@@ -66,9 +66,14 @@ void platform repair <installation-id> --dashboard-url https://dash.example.com
 
 The origin must contain no credentials, path, query, or fragment. Void saves it
 for login callbacks and keeps it across upgrades and repairs. The command does
-not create a dashboard Worker or DNS records; deploy that app separately. Omit
-the option to keep the saved origin. The dashboard provides sign-in, linked
-login methods, and sign-out; use the CLI for user project and team management.
+not create a dashboard Worker or DNS records. Follow the source app’s
+[standalone dashboard preparation](https://github.com/voidzero-dev/void/tree/main/platform/packages/dashboard#standalone-deployment)
+to deploy your own copy with an unused Worker name, your dashboard hostname,
+and the installed API Worker’s service binding. Set its `API_URL` to the public
+API origin, `DASHBOARD_URL` to the dashboard origin, and `SITE_DOMAIN` to the
+installation’s application domain. Omit the option to keep the saved origin.
+The dashboard provides sign-in, linked login methods, and sign-out; use the CLI
+for user project and team management.
 
 If Access protects the platform, its application must cover this dashboard
 origin too. Configure the origin when installing protection. To change it on an

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

@@ -33,8 +33,8 @@ void project token create --name ci --expires-in 30
 ```
 
 Store the printed `VOID_TOKEN` and `VOID_API_URL` in the CI secret manager, then
-use `void connect <url> --no-login` in a fresh checkout if connection metadata
-is not committed. Rotate with `void project token renew <id>` and revoke with
+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
 `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

@@ -28,6 +28,13 @@ existing gate, verify that its service policy admits the installation token and
 that the application covers the printed API and proxy origins. A Cloudflare
 management API token does not authenticate an Access-protected HTTP request.
 
+For automatic setup, resuming also creates or verifies an Access exception
+limited to `/health` on the reserved dispatch health hostname. Void still requires
+its private probe token on that endpoint; requests without it cannot reach an
+application. This lets installation check routing while employee protection and
+account-wide Default-Deny remain enabled. It does not bypass Access for an entire
+Worker or for deployed apps.
+
 For externally supplied credentials, set `VOID_ACCESS_CREDENTIALS` from your
 secret manager to an object keyed by each exact API/proxy origin, with
 `CF_ACCESS_CLIENT_ID` and `CF_ACCESS_CLIENT_SECRET` in each entry. Then rerun
@@ -56,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:
 
@@ -80,10 +87,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
@@ -95,6 +98,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

@@ -8,7 +8,7 @@ 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.
+- An account with your chosen login provider: GitHub, Google, OIDC, or Cloudflare Access.
 - 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.
@@ -19,9 +19,10 @@ Workers for Platforms requires a paid plan. Your database and Cloudflare usage a
 
 In the [Cloudflare dashboard](https://dash.cloudflare.com/), select the account where you want the platform to live:
 
-1. Open **Workers for Platforms** and enable its plan. Review [Workers for Platforms pricing](https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/platform/pricing/) before confirming.
-2. Open **R2 Object Storage** and complete its activation. Void creates the bucket later.
-3. For a domain installation, choose a domain you own, such as `example.app`. If you need one, register it with your preferred registrar. Use a spare domain's root: apps will be served at `my-app.example.app`. For workers.dev testing, skip this step and the DNS setup below.
+1. Open **Workers & Pages** once to let Cloudflare provision Workers for the account.
+2. Open **Workers for Platforms** and enable its plan. Review [Workers for Platforms pricing](https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/platform/pricing/) before confirming.
+3. Open **R2 Object Storage** and complete its activation. Void creates the bucket later.
+4. For a domain installation, choose a domain you own, such as `example.app`. If you need one, register it with your preferred registrar. Use a spare domain's root: apps will be served at `my-app.example.app`. For workers.dev testing, skip this step and the DNS setup below.
 
 If that domain is already in this Cloudflare account, use its existing zone. Otherwise, [add the domain to Cloudflare](https://developers.cloudflare.com/dns/zone-setups/full-setup/setup/) and follow the nameserver instructions until the zone is active. A zone is Cloudflare's DNS configuration for a domain; creating one does not buy the domain.
 
@@ -36,7 +37,7 @@ pnpm add --global void
 void platform install --plan
 ```
 
-Sign in to Cloudflare when prompted, then choose an installation name and account. `--plan` previews the resources without changing them or requiring runtime secrets.
+Sign in to Cloudflare when prompted, then choose an installation name and account. `--plan` previews the resources without changing them or requiring runtime secrets. Completed plans save your choices locally. Run `void platform install` again to select a saved plan; Void checks the current Cloudflare state before asking you to apply it.
 
 For a domain installation, use these answers. Testing mode skips the application domain, zone, and catch-all questions:
 
@@ -51,7 +52,7 @@ For a domain installation, use these answers. Testing mode skips the application
 
 Choose an unused installation name in your account. For example, `team` creates resources such as `void-team-api` and `void-team-proxy`.
 
-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.
+The preview lists the credentials you will need. Review [Credentials](/guide/platform/installation/credentials), then run the install command printed at the end. The guided installation provides setup links and the login callback when needed.
 
 You can select either path directly:
 
@@ -72,22 +73,94 @@ 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:
 
 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.
+2. Select it in the installer and review 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

@@ -4,13 +4,19 @@ outline: deep
 
 # Install and Configure Login
 
+Press Enter to accept a suggested zone or display name, or type to replace it. Enter your own installation name and application domain; examples such as `company` and `example.com` are placeholders.
+
 For workers.dev testing, start the interactive install and choose your login method below:
 
 ```sh
 void platform install --workers-dev
 ```
 
-For a domain installation, the management token is the one value the interactive installer needs in the shell. Browser login cannot create the application's DNS record. In Bash or zsh, read the token without displaying it or putting its value in command history:
+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.
+
+::: details Use an existing management token from the shell
+
+Set `CLOUDFLARE_API_TOKEN` to use an existing token instead of the prompt. In Bash or zsh, read it without displaying it or putting its value in command history:
 
 ```sh
 printf 'Cloudflare management API token: '
@@ -20,7 +26,7 @@ export CLOUDFLARE_API_TOKEN
 void platform install
 ```
 
-::: details PowerShell equivalent
+In PowerShell:
 
 ```powershell
 $env:CLOUDFLARE_API_TOKEN = [System.Net.NetworkCredential]::new('', (Read-Host 'Cloudflare management API token' -AsSecureString)).Password
@@ -29,14 +35,66 @@ void platform install
 
 :::
 
-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.
+After reviewing `--plan`, run `void platform install` and select your saved plan, or run the command printed under **Next, run this command to install the platform**. Both carry your choices into installation and check the current Cloudflare state. Review the refreshed plan. At **Apply this plan?**, **Yes** is selected; press Enter to continue to the credential prompts, or choose **No** to stop. Void opens the relevant setup pages and provides fallback links in the terminal. It reuses values you have already supplied.
+
+Saved plans contain your installation choices, including paths to any authentication configuration or custom runtime. They contain no secrets or approval to install. Declining the plan or cancelling management-token setup keeps those choices for your next attempt.
 
 ## Choose login methods
 
-The installer offers GitHub, Google, generic OIDC, and Cloudflare Access login.
+The installer offers GitHub, Google, generic OIDC, and Cloudflare Access login. Select all methods you want to enable; none are selected initially.
 Cloudflare Access protection is a separate choice from Access login. The
 GitHub OAuth steps below apply when you select GitHub login.
 
+## Choose who can access apps
+
+The installer asks **Who should be able to access deployed apps?**
+
+- **Same people allowed by the platform’s Access policy** reuses your selected company identities and policies. This is recommended when platform Access protection is enabled.
+- **Anyone — public apps** allows public visits.
+- **Choose a different Access policy** selects separate company rules for apps. Without platform protection, this option is **Set up Cloudflare Access protection**.
+
+The plan shows the default app access. Void finishes and verifies app access before
+opening application traffic; new projects inherit the selected default automatically.
+If setup stops, use the printed resume command. Existing installations retain their
+administrator settings during upgrades.
+
+App protection uses the account hosting your platform. If platform login or
+protection uses another account, select equivalent identity providers and policies
+in the hosting account when prompted. Use the app domain’s apex or a workers.dev
+hostname for the API so it stays outside the app wildcard.
+
+Void checks account-wide Default-Deny during setup. For public apps in an account
+that requires Access rules, it creates rules for each app and its verified custom
+domains. Other subdomains keep their existing access rules. It leaves account-wide
+Default-Deny enabled and does not bypass the platform API or proxy.
+
+App rules need **Access: Apps and Policies Edit** and **Organizations, Identity
+Providers, and Groups Read**. Void stores this management token encrypted for future
+apps and domain changes. The installer asks before retaining a setup-only token for
+that purpose, or guides you to create a dedicated token. Public apps without
+Default-Deny need no ongoing Access-management credential.
+
+For scripts, use `--app-access public|platform|custom`. Supply
+`VOID_PLATFORM_APP_ACCESS_TOKEN` when app rules are needed, or add an `appAccess`
+section to your `--auth-config` file:
+
+```json
+{
+  "appAccess": {
+    "mode": "custom",
+    "identityProviderIds": ["hosting-account-identity-provider-id"],
+    "policyIds": ["hosting-account-company-policy-id"],
+    "tokenEnv": "APP_ACCESS_API_TOKEN"
+  }
+}
+```
+
+Keep the file’s existing `connections` configuration. For `mode: "platform"`,
+same-account identity and policy selections are reused. Headless setup requires an
+explicit app-management token; it never silently retains an installer-only token.
+
+## Finish login configuration
+
 For Google, create an OAuth client and register the printed callback URL. You
 can restrict it to named Google Workspace domains. For OIDC or Access login,
 provide the issuer URL, client ID, and client secret. Select **Company-approved
@@ -86,6 +144,10 @@ with GitHub or another login method. With company-approved signup, a colleague
 who passes the company gate can create an ordinary account using GitHub even
 when their GitHub email differs from their company email.
 
+Your identity provider determines how employees sign in, such as through Okta or
+Google Workspace. Your Access policies determine who can reach the platform and
+which MFA or device requirements apply.
+
 Automatic setup uses an existing Zero Trust organization, selected identity
 providers, and existing company policies. Void creates dedicated applications
 and a scoped service token for protected installation checks. It preserves your
@@ -94,9 +156,13 @@ company policies, including device and MFA requirements.
 The setup credential needs **Access: Apps and Policies Write** and
 **Access: Organizations, Identity Providers, and Groups Read** in the identity
 account. Creating protection also needs **Access: Service Tokens Write**.
-Provide a separate setup token through `VOID_PLATFORM_ACCESS_SETUP_TOKEN` if
-your Cloudflare management credential lacks these permissions. These permissions
-are not required by the platform's runtime token. See Cloudflare's
+For setup in the installation account, the initial management-token link includes
+these permissions. Void checks Access reads before provisioning and reuses that
+management token during Access setup, so you do not need a second API token.
+For applications in another account, provide a token scoped to that identity
+account when asked. Scripts can supply an explicit override through
+`VOID_PLATFORM_ACCESS_SETUP_TOKEN`. The platform's runtime token does not need
+Access management permissions. See Cloudflare's
 [Access API](https://developers.cloudflare.com/api/resources/zero_trust/subresources/access/subresources/applications/)
 and [service-token permissions](https://developers.cloudflare.com/api/resources/zero_trust/subresources/access/subresources/service_tokens/methods/create/).
 
@@ -117,7 +183,9 @@ Keep the file's `connections` list from the example above, or use a connection
 with `{"id":"access","kind":"cloudflare-access","label":"Company Access"}`
 to create Access login as well. Omit `protection` for login-only setup.
 
-To connect applications managed elsewhere, select **Connect existing applications**.
+To connect applications managed elsewhere, select **Use Access applications your company already manages**.
+Enter the account that owns the Access applications; it can differ from the
+account hosting Void.
 Scripts use `mode: "existing"`, optional `accountId`, and `loginApplicationId`
 and/or `protectionApplicationId`. For login, set `loginClientSecretEnv`. For
 protection, supply `serviceToken` with `id`, `clientIdEnv`, and `clientSecretEnv`
@@ -148,7 +216,7 @@ The installer collects your runtime token, PostgreSQL URL, login-provider creden
 
 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:
+If you supplied a management token through the shell, remove it when finished:
 
 ```sh
 unset CLOUDFLARE_API_TOKEN
@@ -164,10 +232,12 @@ If Void created a zone, it stops in `waiting-for-dns` and prints nameservers. Se
 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.
+Resume reuses the saved management token and asks for one if it is missing or rejected by Cloudflare. You can override it through `CLOUDFLARE_API_TOKEN`. 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 stopped before a checkpoint was saved, rerun `void platform install` and select your saved plan, or rerun the original command.
 
 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`.
 
+Resume restores your selected Hyperdrive. If that selection is missing from the saved checkpoint, add `--hyperdrive <existing-id>` when resuming, using the same configuration you originally selected.
+
 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.
 
 :::