void 0.22.0 → 0.23.0

package/skills/void/docs/reference/cli/github.md

@@ -0,0 +1,189 @@
+---
+outline: deep
+---
+
+# GitHub and Builds {#github}
+
+Deploy-on-GitHub works from **any** Void login — Google, GitHub, or other SSO. The first time you connect GitHub, Void links your GitHub identity to your current account (a one-time step, independent of how you logged in); it never creates a second account.
+
+## `void github link` {#void-github-link}
+
+```
+void github link
+```
+
+Link your signed-in Void account to GitHub through your browser. `void github install` does this automatically when needed.
+
+::: warning Existing GitHub sign-in
+A GitHub identity can belong to only one Void account. If it is already linked elsewhere, sign in to that Void account or authorize a different GitHub identity.
+:::
+
+## `void github install` {#void-github-install}
+
+```
+void github install
+```
+
+Open the GitHub App install page in your browser. If your account has no linked GitHub identity yet, `void github install` first runs the GitHub link automatically (browser authorize), then continues. After installing, run `void github connect` to link a repository to your project.
+
+## `void github installations` {#void-github-installations}
+
+```
+void github installations
+```
+
+List all GitHub App installations linked to your account. Each entry includes the `[id: <installation_id>]` needed for `--installation` in non-interactive use.
+
+## `void github join` {#void-github-join}
+
+```
+void github join
+```
+
+Join an existing organization installation through your browser. `void github connect` can do this automatically in an interactive terminal. Run `join` locally before non-interactive setup when needed.
+
+Requires a signed-in Void account and organization-installation sharing enabled by your platform. Use `void github installations` to find the installation ID.
+
+## `void github connect` {#void-github-connect}
+
+```
+void github connect [project] [options]
+```
+
+Connect a GitHub repository to a Void project for automatic deploys. On every push to the configured branch, Void builds and deploys your project automatically.
+
+The CLI opens your browser when it needs GitHub authorization. If no installation is available, run `void github install`.
+
+**Options**
+
+| Flag                  | Description                                                                       |
+| --------------------- | --------------------------------------------------------------------------------- |
+| `--project <name>`    | Project name (alias for the positional argument)                                  |
+| `--installation <id>` | GitHub App installation ID (required when you have multiple installations)        |
+| `--repo <owner/repo>` | Repository full name — required unless the installation grants exactly one repo   |
+| `--branch <name>`     | Branch to deploy from — **required in non-interactive mode**                      |
+| `--executor <type>`   | Build executor: `container` (default) or `github_actions`                         |
+| `--workflow <path>`   | Authorized deploy workflow file — defaults to `.github/workflows/void-deploy.yml` |
+
+Choose `container` for platform builds or `github_actions` for a deployment workflow. The CLI prompts for the executor and, for GitHub Actions, the workflow file. Pass the corresponding flags to skip those prompts.
+
+The workflow must be a `.yml` or `.yaml` file under `.github/workflows/`. Only that workflow can obtain the project's OIDC deployment token. Prefer a dedicated deployment workflow.
+
+For CI, supply the project and branch, plus the installation and repository when they cannot be selected automatically. Organization connections require repository authorization in a local browser first.
+
+```
+void github connect my-app \
+  --installation 42 \
+  --repo owner/my-app \
+  --branch main
+```
+
+**Project resolution** follows the same order as deploy: positional / `--project`, `VOID_PROJECT`, linked project (`.void/project.json`).
+
+You can connect only repositories your GitHub account can access.
+
+A project has one GitHub connection. Running `void github connect` on a project that is already connected fails. To connect a different repository, run `void github disconnect` first.
+
+## `void github update` {#void-github-update}
+
+```
+void github update [project] [options]
+```
+
+Change the branch, executor, or workflow for an existing connection. To change the repository, disconnect and reconnect.
+
+**Options**
+
+| Flag                | Description                                                      |
+| ------------------- | ---------------------------------------------------------------- |
+| `--project <name>`  | Project name (alias for the positional argument)                 |
+| `--branch <name>`   | New branch to deploy from                                        |
+| `--executor <type>` | New build executor: `container` or `github_actions`              |
+| `--workflow <path>` | New authorized deploy workflow file (under `.github/workflows/`) |
+
+The CLI prompts for new settings using the current values as defaults. In CI, pass at least one of `--branch`, `--executor`, or `--workflow`.
+
+```
+void github update my-app --executor github_actions
+```
+
+**Project resolution** follows the same order as deploy: positional / `--project`, `VOID_PROJECT`, linked project (`.void/project.json`).
+
+## `void github status` {#void-github-status}
+
+```
+void github status [project]
+```
+
+Show the connected repository, branch, executor, and workflow. Container builds do not use the workflow file.
+
+**Options**
+
+| Flag               | Description                                      |
+| ------------------ | ------------------------------------------------ |
+| `--project <name>` | Project name (alias for the positional argument) |
+
+```
+void github status my-app
+```
+
+**Project resolution** follows the same order as deploy: positional / `--project`, `VOID_PROJECT`, linked project (`.void/project.json`).
+
+## `void github disconnect` {#void-github-disconnect}
+
+```
+void github disconnect [project]
+```
+
+Disconnect a project from its GitHub repository, stopping automatic deploys. Any in-flight builds for the project are cancelled (their deploy tokens are revoked) before the connection is removed. If the project has no connection, it reports that and exits successfully. To point a project at a different repository, disconnect first, then run `void github connect`.
+
+You are asked to confirm before anything is removed. Pass `--yes` to skip the prompt; `--yes` is **required** in a non-interactive shell (CI), where there is no prompt to answer.
+
+**Options**
+
+| Flag               | Description                                                       |
+| ------------------ | ----------------------------------------------------------------- |
+| `--project <name>` | Project name (alias for the positional argument)                  |
+| `--yes`            | Skip the confirmation prompt (required in non-interactive shells) |
+
+```
+void github disconnect my-app --yes
+```
+
+**Project resolution** follows the same order as deploy: positional / `--project`, `VOID_PROJECT`, linked project (`.void/project.json`).
+
+## Build {#build}
+
+Inspect Deploy-on-GitHub builds.
+
+### `void build logs` {#void-build-logs}
+
+```
+void build logs [build] [--follow] [--output <file>] [--project <slug>]
+```
+
+Stream, tail, or download the build logs for a **container** build. With no
+`[build]` argument, targets the project's most recent build.
+
+| Flag                     | Purpose                                                                   | Default |
+| ------------------------ | ------------------------------------------------------------------------- | ------- |
+| `--follow`, `-f`         | Live-tail: poll until the build finishes and its final logs are captured. | off     |
+| `--output <file>`, `-o`  | Write logs to a file instead of stdout (appends while following).         | stdout  |
+| `--project <slug>`, `-p` | Target project.                                                           | linked  |
+
+**Project resolution** follows the same order as deploy: positional / `--project`,
+`VOID_PROJECT`, linked project (`.void/project.json`).
+
+Builds run on **GitHub Actions** keep their logs on GitHub — the command prints
+the Actions run URL instead of streaming. Only the last 10,000 log lines of a
+container build are retained.
+
+Following waits for the platform to confirm the final log tail. If the platform cannot confirm it, upgrade the platform runtime or read the retained logs without `--follow`. An unfinished final tail reports an error after two minutes; retry to recover it.
+
+Examples:
+
+```
+void build logs                     # print the latest build's logs
+void build logs -f                  # follow the latest build until it finishes
+void build logs bld_123 -o build.log  # download a specific build's logs
+```

package/skills/void/docs/reference/cli/platform-config.md

@@ -0,0 +1,92 @@
+---
+outline: deep
+---
+
+# Platform Configuration {#plan-configuration}
+
+Use your administrator session for these commands. See [Platform Management](./platform.md#operator-commands) for platform selection, previews, and confirmation.
+
+`void platform config plans` opens an interactive plan menu using your administrator session. Plans have stable IDs and editable display names. Copy an existing plan to add one, edit limits without redeploying, archive it to stop new assignments, or remove it with an explicit replacement for its accounts.
+
+```sh
+void platform config plans show [plan-id]
+void platform config plans add <plan-id> --copy <existing-id> --name "Team"
+void platform config plans set <plan-id> [--name "Team"] [--file plan.json]
+void platform config plans reset <builtin-plan-id>
+void platform config plans archive <plan-id>
+void platform config plans restore <plan-id>
+void platform config plans remove <plan-id> [--replacement <plan-id>]
+void platform config plans default <plan-id>
+void platform config plans sync
+```
+
+Use `--plan` to preview changes and affected accounts; scripted mutations require `--yes`. Every command supports `--connection <registered-id-or-url>` and `--json`. `show` reports the effective limits, default, assignments, and pending account updates. `reset` restores a built-in plan's original limits and build instance size. Archived plans keep their existing accounts but cannot receive new assignments; change the default before archiving it. `remove` requires a replacement for a plan that has accounts or is the default. Changing the default affects only new accounts.
+
+For `add` and `set`, `--file` reads a JSON object with optional `name`, `limits`, `buildInstanceType`, and boolean `allowShortSlugs`. `limits` is a partial object of nonnegative whole numbers; `0` means unlimited by the plan. Build timeouts remain capped at the platform maximum of 60 minutes; `0` uses that maximum. Omitted settings keep their current values or the copied plan's values. `buildInstanceType` is `standard-3` or `standard-4`. `allowShortSlugs` permits future assignments of project slugs of five characters or fewer; existing URLs remain available. Storage quotas are not editable. See [Plans and Limits](../../guide/platform/administration/plans.md) for supported limits and examples.
+
+An apply checks the preview's revision and rejects concurrent changes. Lower quotas can restrict accounts already above them; usage history and billing periods are preserved. The CLI continues account updates until complete. If an update fails or stops making progress, the configuration remains saved and the command exits unsuccessfully. Run `sync --yes` to continue before editing plans again. Inspect `show` and operator events after an uncertain request outcome.
+
+## Authentication configuration {#authentication-configuration}
+
+`void platform config auth` opens interactive configuration. These commands use
+your administrator session from `void platform auth login`:
+
+```sh
+void platform config auth list
+void platform config auth show company
+void platform config auth add google
+void platform config auth add oidc --id company
+void platform config auth add cloudflare-access --id access
+void platform config auth configure company
+void platform config auth test company
+void platform config auth link company
+void platform config auth enable company
+void platform config auth disable github
+void platform config auth admission
+void platform config auth protection show
+void platform config auth protection enable --installation <id>
+void platform config auth protection disable --installation <id>
+void platform config auth recover company --installation <id> --file recovery.json
+```
+
+When configuring an existing installation for the first time, run
+`void platform config auth initialize`, then sign in again. Its current login
+methods and signup policy are preserved.
+
+Adding or editing a method saves a pending configuration. Enabling it verifies the
+login in your browser before applying it. Linking the verified identity to your
+account is a separate, explicit action. Before disabling a method, verify a linked
+alternative; the last method cannot be disabled. Disabling revokes human sessions
+created through that method, including operator sessions. Scoped deployment tokens
+remain valid; a human login token used as `VOID_TOKEN` is still revoked.
+
+Commands accept `--connection <registered-id-or-url>` and `--json`. Changes accept
+`--plan` or `--yes`. For scripted configuration, use `--file <path>` for the
+nonsecret fields and `--client-secret-env <name>` for the environment variable
+containing the secret. Omit the secret when editing to retain its saved value.
+For `enable` or `link` in scripts, supply `--test-id <id>` from a completed test.
+`test --json` returns a browser URL, test ID, and expiry without waiting for completion.
+
+`admission` chooses invited/allowlisted, company-approved, or public signup.
+Company-approved signup creates ordinary accounts automatically when a user
+passes a configured company rule. Select an enabled, company-restricted OIDC or
+Google Workspace method, or an enabled Cloudflare Access gate. In scripts,
+`admission --file <path> --yes` reads a policy such as
+`{"mode":"company","connections":["company"],"access":false}`.
+
+`protection enable` creates or connects Cloudflare Access applications independently
+of login methods. Its `--file` accepts the `cloudflareAccess` object described in
+[installation setup](../../guide/platform/installation/setup.md#choose-login-methods).
+Protection changes require installation ownership, the saved recovery credentials,
+and a human administrator session. They revoke current human sessions. Before
+removing protection, change any signup rule that depends on that gate. Cloudflare
+applications are retained for deliberate cleanup.
+
+`recover <connection-id>` restores an existing administrator when normal login is
+unavailable. Its file contains `administratorUserId`, optional nonsecret provider
+`configuration`, and an `expectedIdentity` object with exact `issuer` and `subject`
+when using `--yes`. Recovery requires Cloudflare management/database authority,
+original recovery keys, and a successful browser provider test. Use
+`--client-secret-env <name>` for new or rotated credentials.
+
+For automation, supply `VOID_OPERATOR_TOKEN` with an explicit `VOID_API_URL` or `--connection`. Operator tokens are stored separately from application deployment credentials. The API checks your current administrator access on every request. See [Using Scripts](../../guide/platform/administration/operations.md#using-scripts) for an example.

package/skills/void/docs/reference/cli/platform-email.md

@@ -0,0 +1,81 @@
+---
+outline: deep
+---
+
+# Platform Email {#operator-email}
+
+Use your administrator session for these commands. See [Platform Management](./platform.md#operator-commands) for platform selection, previews, and confirmation.
+
+Decide who mail from the shared sender may reach, who registers email domains, and a project's outbound caps:
+
+```sh
+void platform email policy
+void platform email policy-set <verified|domains|any> [--domains <domain[,domain...]>]
+void platform email settings
+void platform email settings-set --domains <self-serve|admin>
+void platform email limit <project-id|slug> [--monthly <n>] [--burst <n>]
+void platform email logs <project-id|slug> [--page <n>] [--limit <n>] [--json]
+void platform email attempts [--project <id|slug>] [--page <n>] [--limit <n>]
+void platform email attempt-resolve <attempt-id> --ended --reason <text>
+void platform email operation-resolve <operation-id> --ended --outcome <applied|not-applied> --reason <text>
+void platform email shared-recipients [--project <id|slug>] [--page <n>] [--limit <n>]
+void platform email shared-recipient-resolve <recipient-id> --ended --outcome <applied|not-applied> --reason <text>
+```
+
+`policy` decides which recipients a project's `<slug>+tag@<mail domain>` sender reaches: `verified` (the default) means only that project's verified destinations; `domains` adds every address on the listed domains; `any` lifts the check. Neither widens delivery to addresses on the platform's own mail domain: those stay verified-destination-only, so no project reaches another project's inbox without its consent. Cloudflare still refuses a destination it has not verified until the platform mail domain is onboarded for Email Sending, so under `domains` or `any` such refusals arrive as per-recipient `UNVERIFIED_DESTINATION` results. Custom-domain sends are not affected.
+
+`settings-set --domains admin` tells `void email domain add` to print the administrator's command instead of starting token setup. `limit` overrides the project's monthly and rolling 60-second caps (defaults 200 and 10); a project page in the admin UI shows and clears them.
+
+`logs` inspects retained receipt and recipient outcomes, including operation IDs, provider references, error codes, and policy versions. Pages contain at most 100 records, newest first; use `--json` for all fields. After project deletion, use its project ID to inspect metadata until the 30-day retention period expires. Message content and credentials are never included.
+
+`attempts` lists interrupted provider calls and their earliest resolution time. Once
+the original Worker execution has ended and the attempt is at least 24 hours old,
+`attempt-resolve` records `outcome_unknown`, retains its quota charge, and releases
+the project/domain cleanup fence. `--ended` is your attestation that the call is no
+longer active; `--reason` is stored in the operator audit log. Keep recipient
+addresses and message content out of the reason. The send is never retried. Use
+`--plan` to preview and `--yes` to apply without a prompt.
+
+`operation-resolve` recovers a Cloudflare routing, Worker, secret, catch-all, or
+Sending mutation whose outcome remains unknown. After the original execution
+has ended and the operation is at least 24 hours old, inspect the exact resource
+named by the preview and attest whether its write was `applied` or `not-applied`.
+Applied writes continue at the next step; not-applied writes retry the same
+persisted intent. The running platform version must match that intent, so restore
+the matching version before recovering an operation created by older code. The
+preview pins the step, attempt, connection and route generations, resource
+identity, and digest used by the apply request. Time alone never retries a write.
+
+`shared-recipients` discovers shared inbound addresses, provider rule names and
+IDs, and interrupted creation intents, including projects awaiting deletion.
+If creation has an unknown outcome, use `shared-recipient-resolve` after the
+original execution has ended and its creation intent is at least 24 hours old.
+Inspect the exact account, zone, recipient and rule named by `--plan`, and use
+Cloudflare's provider audit to establish whether creation was `applied` or
+`not-applied`. A missing rule alone is insufficient evidence for `not-applied`.
+Supply that finding in `--reason`; it is recorded in platform events.
+
+Applied recovery requires the exact owned rule to be present and records its
+ID. Not-applied recovery releases the creation intent only after repeated
+provider inspection and your attestation. Both outcomes leave delivery unready
+until normal reconciliation verifies it. Recovery itself creates or deletes no
+provider rule and never reopens a deleting project; retry deletion afterward
+when recovering cleanup. Use `--yes` to apply the preview without a prompt.
+If the intent or provider ownership changes, inspect a new plan.
+
+Register and maintain email domains for projects whose owners hold no Cloudflare credential:
+
+```sh
+void platform email domains [--project <id|slug>]
+void platform email domain-add <domain> --project <id|slug> [--token-stdin]
+void platform email domain-status <domain>
+void platform email domain-sync <domain>
+void platform email domain-rotate-secret <domain>
+void platform email domain-remove <domain> [--token-stdin]
+```
+
+`domain-add` uses the platform's Cloudflare credential for zones in its account. For another account, pipe a scoped Cloudflare API token on standard input with `--token-stdin --yes`. Managed custom inbound email requires the Cloudflare zone apex (`example.com`). If its MX records already belong to another mail provider, use the project's shared email address or choose another unused zone. Native Cloudflare deployments also support literal recipient addresses on subdomains; see [Your own Cloudflare account](../../guide/email/domains.md#your-own-cloudflare-account).
+
+`domain-status` shows inbound, outbound, and credential-management readiness with the latest operation. A blocked operation resumes through `domain-sync`; a blocked rotation resumes through `domain-rotate-secret`, preserving already confirmed steps and its staged credential. An uncertain operation remains stopped until read-back proves the result or an administrator uses `operation-resolve`. Domains an administrator adds show `managed_by: admin`; their owners can list and inspect them but use these commands for `sync`, `domain-rotate-secret`, and `remove`.
+
+If project deletion leaves cleanup blocked by an expired or revoked Cloudflare token, use `domain-remove <domain> --token-stdin --yes` with a replacement scoped to the same account and zone. This resumes the retained cleanup only when no other project uses the connection. For a live project, renew its token through `domain-add` instead.

package/skills/void/docs/reference/cli/platform-installation.md

@@ -0,0 +1,127 @@
+---
+outline: deep
+---
+
+# Platform Installation {#void-platform-install}
+
+```sh
+void platform install [options] [--yes]
+```
+
+| Option                            | Purpose                                                                              |
+| --------------------------------- | ------------------------------------------------------------------------------------ |
+| `--name <slug>`                   | Installation name used in `void-<name>-<role>` resource names; choose an unused name |
+| `--display-name <name>`           | Human-readable platform name                                                         |
+| `--account <id>`                  | Cloudflare account id                                                                |
+| `--auth-config <path>`            | Login methods, signup policy, and environment references for provider secrets        |
+| `--login-methods <methods>`       | Comma-separated `github`, `google`, `oidc`, or `cloudflare-access` login methods     |
+| `--access-protection`             | Protect the platform UI and APIs with Cloudflare Access                              |
+| `--no-access-protection`          | Skip Cloudflare Access protection                                                    |
+| `--hyperdrive <create\|id>`       | Create Hyperdrive or use the specified existing configuration                        |
+| `--application-domain <domain>`   | Base domain for deployed apps                                                        |
+| `--workers-dev`                   | Explicit testing mode; add an application domain later                               |
+| `--zone <domain>`                 | Cloudflare zone containing the application domain                                    |
+| `--dedicated-zone`                | Add zone-wide catch-all routes; valid only when the app domain is the whole zone     |
+| `--no-dedicated-zone`             | Skip zone-wide application catch-all routes                                          |
+| `--control-plane-domain <domain>` | Optional API custom hostname; defaults to `workers.dev`                              |
+| `--no-control-plane-domain`       | Use the default `workers.dev` API hostname                                           |
+| `--dashboard-url <origin>`        | HTTPS origin of an optional dashboard deployed separately                            |
+| `--plan`                          | Resolve and print a read-only plan                                                   |
+| `--resume`                        | Continue the matching checkpointed installation                                      |
+| `--runtime <path>`                | Deploy a locally built, integrity-checked runtime directory                          |
+| `--yes`                           | Acknowledge Cloudflare changes in non-interactive use                                |
+
+For a first installation, follow [Install a Void Platform](../../guide/self-hosted-platform.md). The interactive installer recommends using a domain and offers **Use workers.dev for testing** as a visible alternative. Void creates the platform infrastructure and tables. External PostgreSQL and a configured login method are required in either mode; GitHub OAuth is the default login choice, not a requirement. `--workers-dev` skips zone/DNS/certificate operations and cannot be combined with `--application-domain`, `--zone`, or `--dedicated-zone`.
+
+Read-only plans, workers.dev installations with the default API hostname, and supported lifecycle operations can use Cloudflare browser login and the system keychain. Installation that writes DNS or creates a zone needs an explicit management token through `CLOUDFLARE_API_TOKEN` or `CF_API_TOKEN`.
+
+The installed platform needs a separate runtime token to provision resources for apps. The interactive installer prompts for it and the other setup values. For non-interactive installs, inject the variables listed in [Install from CI](../../guide/platform/installation/ci.md).
+
+To enable email during install or upgrade, set both `VOID_EMAIL_SENDER_DOMAIN` and `VOID_EMAIL_SHARED_ZONE_ID`. Void records the pair for later upgrades; supplying only one is an error.
+
+Use `--dashboard-url https://dash.example.com` when deploying the optional user
+dashboard separately. The URL must be an HTTPS origin without credentials, a
+path, query, or fragment. Void permits that origin's login callbacks and saves
+it for later maintenance; it does not deploy a dashboard Worker. Omission keeps
+an existing installation's saved dashboard origin.
+
+`--plan` previews resource names, login methods, callback URLs, and credential requirements. Run the install or resume command printed at the end to continue. For login configuration, use either `--auth-config` or `--login-methods` with the Access protection flags.
+
+New resources use `void-<name>-<role>` names; choose an unused installation name. The installer opens setup pages for missing credentials and reuses values already supplied.
+
+Installation progress and partial credentials are saved encrypted locally. Rerun the installer to continue unfinished setup, or pass `--resume --name <id>`. Use lifecycle commands for completed installations.
+
+Use an empty PostgreSQL database dedicated to the installation. You can correct a failed initial connection, but after the database is claimed or Hyperdrive is provisioned, commands reject a different URL.
+
+Choose whether Void creates Hyperdrive or uses an existing configuration. An existing Hyperdrive must point to the platform database with SQL result caching disabled. Supply a database owner URL for migrations. See [Use an existing Hyperdrive](../../guide/platform/installation/prerequisites.md#use-an-existing-hyperdrive) for setup and [Install from CI](../../guide/platform/installation/ci.md) for unattended inputs.
+
+Recovery secrets are encrypted using your system keychain. Without one, supply a base64-encoded 32-byte `VOID_PLATFORM_RECOVERY_KEY`. Keep the original credentials in protected CI secrets for recovery.
+
+If a newly created zone is waiting for registrar delegation, resume after it becomes active:
+
+```sh
+void platform install --resume --name <installation-id>
+```
+
+See [Self-host a Void platform](../../guide/self-hosted-platform.md) for prerequisites, token scope, exact footprint, domain behavior, and an end-to-end walkthrough.
+
+## `void platform domain set` {#void-platform-domain-set}
+
+```sh
+void platform domain set <domain> [--installation <id>] [--zone <domain>] [--dedicated-zone] [--plan] [--yes]
+```
+
+Add an application domain to a workers.dev test platform. Domain-based installations remain the recommended default. The command detects the zone when possible, creates missing DNS and routes after confirmation, and checks HTTPS and project Zero Trust protection before making the domain canonical. If DNS, certificates, or protection are pending, rerun the same command to resume. `--plan` is read-only; non-interactive mutations require `--yes`.
+
+Existing workers.dev URLs remain available, and the platform API origin, OAuth callback, projects, and deployments stay unchanged. The command verifies the running runtime token's Cache Purge permission for the new zone. A disabled platform stays disabled. Use the database URL from the original installation when administering from another machine. Replacing an already configured application domain is not supported. See [Adding a Domain](../../guide/platform/installation/domains.md#adding-a-domain).
+
+## Lifecycle commands {#lifecycle-commands}
+
+Use these commands to recover, update, pause, or remove an installation:
+
+```sh
+void platform discover [--account <id>] [--installation <id-or-name>]
+void platform upgrade [id] [--runtime <path>] [--dashboard-url <origin>] [--plan] [--yes]
+void platform rollback [id] --runtime <earlier-path> [--from-runtime <current-path>] [--plan] [--yes]
+void platform repair [id] [--runtime <path>] [--dashboard-url <origin>] [--plan] [--yes]
+void platform disable [id] [--plan] [--yes]
+void platform enable [id] [--runtime <path>] [--plan] [--yes]
+void platform uninstall [id] [--plan] [--purge-data] [--keep-zone] [--yes]
+```
+
+`discover --installation` limits recovery and endpoint verification to one installation in a shared Cloudflare account.
+
+Omit `id` when only one installation is configured, or choose from the interactive picker. Non-interactive commands need an ID when several installations exist. Commands that make changes also require `--yes`; `--plan` only previews changes.
+
+To add or explicitly change a separately deployed dashboard after installation,
+use `repair --dashboard-url <origin>` or `upgrade --dashboard-url <origin>`.
+Preview with `--plan` first. Existing Access protection must cover the configured
+dashboard origin before maintenance can proceed. See [Optional Dashboard](../../guide/platform/installation/domains.md#optional-dashboard).
+
+After discovery on another machine, set `VOID_PLATFORM_DATABASE_URL`. An upgrade that preserves every deployed Worker also preserves its secrets. For an email-enabled installation without its encrypted recovery file, restore `VOID_PLATFORM_EMAIL_SIGNING_SECRET`; recreating only the email gateway needs that key and does not need the Cloudflare runtime token or JWT signing key. Recreating the API or proxy also requires the email key when email is enabled, in addition to their normal secrets. Recreating the API requires its original runtime-token, GitHub, R2, JWT, and project-encryption values; recreating the proxy requires the runtime token and JWT signing key.
+
+| Command     | Behavior                                                                                      |
+| ----------- | --------------------------------------------------------------------------------------------- |
+| `discover`  | Verifies remote ownership and restores local installation records without downloading secrets |
+| `repair`    | Recreates missing resources owned by the installer                                            |
+| `upgrade`   | Deploys the selected runtime and supported pending migrations                                 |
+| `rollback`  | Restores a declared-compatible earlier runtime without reversing PostgreSQL migrations        |
+| `disable`   | Blocks platform traffic through routing storage without removing data                         |
+| `enable`    | Restores traffic after checking the platform                                                  |
+| `uninstall` | Blocks traffic and removes eligible resources, retaining data by default                      |
+
+Repair and upgrade preserve disabled state. New, resumed, and previously disabled installations block user traffic until all target Workers pass verification; the installer's health probes can still run. Routes and custom domains remain attached.
+
+`--runtime` selects a custom platform build. Relative paths resolve from your current directory. Void verifies the build before making changes; see [Platform Development](../../guide/platform/development/runtime.md#deploying-your-runtime) for creating one.
+
+Without `--runtime`, the CLI uses its packaged platform version.
+
+Platform migrations only move forward. Void checks compatibility before updating the database and tells you if an intermediate release is needed.
+
+An upgrade completes after the new Workers pass health checks. If rollout fails, Void attempts to restore the previous Workers. Retrying does not repeat completed migrations.
+
+`platform rollback` restores a compatible earlier runtime without reversing database migrations. Pass its files with `--runtime`; if the installed version is custom, also supply that version with `--from-runtime`. Void refuses incompatible targets.
+
+Uninstall verifies remote ownership before removing anything. Data resources are retained unless you pass `--purge-data`. Workers, the Queues they use, R2, AI Gateway, DNS records, routes, custom domains, adopted resources, external PostgreSQL, and zones are always retained for manual review.
+
+See [Disable and Uninstall](../../guide/platform/installation/uninstall.md#remove-retained-resources) for the full removal policy and the cleanup order.

package/skills/void/docs/reference/cli/platform-operations.md

@@ -0,0 +1,90 @@
+---
+outline: deep
+---
+
+# Platform Operations {#operator-deployments}
+
+Use your administrator session for these commands. See [Platform Management](./platform.md#operator-commands) for platform selection, previews, and confirmation.
+
+Find a deployment, inspect its manifest, or request cancellation:
+
+```sh
+void platform deployment list [--project <id-or-slug>] [--status <status>] [--search <text>] [--page <n>] [--limit <n>]
+void platform deployment show <id>
+void platform deployment cancel <id>
+void platform deployment migrate-assets <id> [--cursor <cursor>] [--plan|--yes]
+```
+
+Cancellation applies while a deployment is pending, uploading, migrating, or prerendering, and can be requested again while it is canceling. A deployment that has begun switching traffic, is compensating for a failure, or has finished cannot be canceled through this command.
+
+`migrate-assets` copies legacy assets to scoped R2 storage, verifies their contents, and updates each batch only after all its assets are verified. Original assets remain in place, and application traffic stays on the same deployment. Upgrade the platform runtime before using this command. Migrate both active deployments and retained rollback deployments before removing support for older asset storage.
+
+Use `--plan` to preview the first batch. Applying authorizes all remaining batches for that deployment; the CLI previews each batch and prints its result, including `nextCursor`. With `--json`, results are JSON Lines. If a later batch fails or the command is interrupted, resume with the cursor from the last successful result. An ambiguous request is never retried automatically; inspect the deployment before resuming. A completed migration reports `complete: true` and `nextCursor: null`.
+
+Use [`void platform system asset-migrations`](#operator-system) to find deployments requiring migration. Inspect every inventory page, migrate each deployment with `needsMigration` greater than zero, then inspect every page again. Include retained rollback deployments and stored bundles. Investigate rows marked `invalid` before considering migration complete. Keep the older asset readers until the full inventory is valid and no protected deployment needs migration.
+
+Read its runtime logs with:
+
+```sh
+void platform deployment logs <id> [--since <time>] [--cursor <cursor>] [--limit <n>] [--follow]
+```
+
+The default is the last hour, oldest first, with up to 100 records. `--since` accepts a duration such as `10m`, `2h`, or `1d`, an ISO date, or epoch milliseconds. Set `--limit` from 1 to 500 and pass the response's `nextCursor` as `--cursor` to read another page.
+
+`--follow` reads the remaining pages and checks for new logs every two seconds until you press Ctrl+C. It checks a five-minute overlap for delayed records and suppresses replayed rows. Records that arrive later may need a subsequent historical query. Following stops with an error if a window exceeds 10,000 records; use a narrower historical query in that case.
+
+## Builds {#operator-builds}
+
+Inspect a build or read its output:
+
+```sh
+void platform build show <id>
+void platform build logs <id> [--since <sequence>] [--limit <n>] [--follow]
+```
+
+Build logs start at sequence `0` and return up to 500 lines. Use the returned `lastSeq` as `--since` to continue; `--limit` accepts 1 to 500. Container log retrieval requires managed builds to be enabled. GitHub Actions builds return an external log URL.
+
+Following waits for the final logs after the build becomes terminal. If completion cannot be confirmed within two minutes, the command exits with an error. Older builds without a completion signal may wait for 30 seconds without new lines before following stops.
+
+## System {#operator-system}
+
+Inspect activity, check service health, or review administrative changes:
+
+```sh
+void platform system overview
+void platform system health
+void platform system cli-versions
+void platform system asset-migrations [--page <n>] [--limit <n>]
+void platform system events [--page <n>] [--limit <n>]
+void platform system backfill-queue-tokens
+void platform system sandbox-drain [--cursor <opaque-cursor>]
+```
+
+`overview` shows platform totals and recent activity. `health` checks the configured services and database, and exits with a nonzero status if a check fails. `cli-versions` reports the CLI versions used by deployments.
+
+`asset-migrations` inventories active deployments, retained rollback deployments, and deployments with stored bundles. It reports their asset counts, `needsMigration`, and an `invalid` flag for unreadable metadata. Read all pages using the response's pagination fields. Migrate each deployment with `needsMigration` greater than zero through [`deployment migrate-assets`](#operator-deployments), then rerun the full inventory. Migration keeps the original assets; removing those assets or their older readers requires separate verification.
+
+`events` shows the administrator, target, and outcome of changes. A pending event means the outcome has not been recorded. Previews and session login/logout do not create these events. `backfill-queue-tokens` repairs older queue entries that are missing authentication tokens and supports `--plan` before applying the repair.
+
+Use `sandbox-drain` when an upgrade from the legacy tenant-owned Sandbox runtime asks you to finish cleanup. Preview with `--plan`; pass the returned `nextCursor` as `--cursor` to inspect later pages. Apply with `--yes` and rerun until it reports `complete: true`, then rerun the interrupted upgrade. Application traffic stays paused during cleanup, while administrator login remains available. The completed upgrade enables the current managed Sandbox controller automatically.
+
+Use the [platform lifecycle commands](./platform-installation.md#lifecycle-commands) to maintain your installation's Workers.
+
+## Hosted Workers {#operator-workers}
+
+The following commands manage the Workers of the hosted Void Cloud platform.
+They are unavailable on a self-hosted installation; use the
+[lifecycle commands](./platform-installation.md#lifecycle-commands) there instead.
+
+```sh
+void platform worker list [--environment <production|staging>]
+void platform worker show <worker-name> [--environment <production|staging>]
+void platform worker rollback <worker-name> <version-id> [--environment <production|staging>]
+void platform worker rollback-all [--environment <production|staging>]
+void platform worker events [batch-id] [--environment <production|staging>]
+```
+
+Use a name from `worker list`, such as `api` or `proxy`. `show` lists its
+versions and current deployment. Preview either rollback with `--plan`, then
+apply it interactively or with `--yes` in a script. `events` lists worker
+operation events or inspects one batch by ID.