void 0.20.2 → 0.21.0

package/skills/void/docs/guide/email.md

@@ -10,7 +10,7 @@ Send transactional email from your app via [Cloudflare's `send_email` binding](h
 import { sendEmail } from 'void/email';
 
 const result = await sendEmail({
-  from: 'Acme <acme+noreply@mail.void.cloud>',
+  from: 'Acme <acme+noreply@mail.example.com>', // use your project's sender address
   to: 'user@example.com',
   subject: 'Welcome',
   text: 'Thanks for signing up!',
@@ -36,16 +36,20 @@ hits first, because a recipient you have not verified yet fails per-recipient.
 
 ## Setup
 
-Zero config on the Void platform (`void deploy`). Every Void project ships with:
+On a platform with email enabled, your app needs no email configuration before
+`void deploy`. Ask your administrator for the platform's shared mail domain. A
+self-hosted administrator [enables email during installation or upgrade](/guide/platform/installation/credentials#runtime-token-permissions); installations without it do not offer platform email. Void Cloud uses `mail.void.cloud`.
 
-- **Sender** — `<your-slug>+noreply@mail.void.cloud`. Used as the default `from` if you omit it. The platform owns the zone with Email Routing + DKIM + SPF + DMARC set up; you do nothing. Project slugs are capped at 56 characters so this local part fits RFC 5321's 64 octets; a project created before the cap with a longer slug must pass `from` explicitly.
+Each project on an email-enabled platform has:
+
+- **Sender** — `<your-slug>+noreply@<mail-domain>`. Used as the default `from` if you omit it. The platform administrator configures the mail zone and its Email Routing, DKIM, SPF, and DMARC records. Project slugs are capped at 56 characters so this local part fits RFC 5321's 64 octets; a project created before the cap with a longer slug must pass `from` explicitly.
 - **No worker binding to add** — outbound mail is sent by the Void proxy, which holds the
   platform `send_email` binding. Your worker never gets one, so there is nothing to configure.
 - **Your own address as a recipient** — the email on your Void account is registered as a recipient when the project is created. It is verified at once when Cloudflare already holds it verified for the platform (you clicked its link for an earlier project of yours); otherwise Cloudflare mails it a verification link, and until you click that link and run `void email destinations` — the listing is what records the click — a send to yourself comes back `ok: false` with a per-recipient `UNVERIFIED_DESTINATION` in `result.deliveries`.
 
 That's it for configuration. Delivery is gated separately: outbound mail only reaches verified recipients, so `sendEmail({ to: '...', subject: '...', text: '...' })` works on first deploy for your own address once it is verified, and for anyone else after `void email allow` — see [Adding recipients](#adding-recipients).
 
-Deploying to your own Cloudflare account instead (`void deploy --platform cloudflare`) takes one line of `void.json` and one Enter on the first deploy — see [Your own Cloudflare account](#your-own-cloudflare-account).
+Deploying to your own Cloudflare account instead (`void deploy --platform cloudflare`) takes one line of `void.config.ts` and one Enter on the first deploy — see [Your own Cloudflare account](#your-own-cloudflare-account).
 
 ## Adding recipients
 
@@ -61,7 +65,7 @@ Cloudflare emails the recipient with a verification link. Once they click it and
 void email destinations
 ```
 
-The project owner's email (the GitHub address you signed up with) is added automatically when the project is created, so it skips `void email allow` — not the verification. See [Setup](#setup) for when it is verified at once and when there is a link to click.
+The project owner's account email is added automatically when the project is created on an email-enabled platform, so it skips `void email allow` — not the verification. See [Setup](#setup) for when it is verified at once and when there is a link to click.
 
 ::: warning When this is the right fit
 The shared sender is great for: ops alerts to the team, notifications to the project owner, reply-by-email flows on top of inbound, internal/app-internal mail.
@@ -71,7 +75,7 @@ For SaaS sending to arbitrary end-users (every signup gets a welcome email), the
 
 ## Your own domain on the platform
 
-The shared sender lives on the platform's `mail.void.cloud` zone. To send — and receive — at a domain you own, register its Cloudflare zone with the project:
+The shared sender uses the platform's configured mail domain. To send — and receive — at a domain you own, register its Cloudflare zone with the project:
 
 ```sh
 void email domain add acme.com
@@ -120,15 +124,14 @@ At most 50 recipients across `to`, `cc` and `bcc` per call. Each address is chec
 
 `Address` accepts either a string (`"hello@acme.dev"` or `"Name <hello@acme.dev>"`) or an object (`{ email, name? }`). Display names with non-ASCII characters are RFC 2047 encoded automatically.
 
-On the platform the sender is pinned to your project. `from` must be your project's own platform address — `<project-slug>@mail.void.cloud` or `<project-slug>+<tag>@mail.void.cloud`, optionally with a display name (`Acme <acme+noreply@mail.void.cloud>`) — or any address on a domain registered with `void email domain add` (see [Your own domain on the platform](#your-own-domain-on-the-platform)). Anything else is rejected with `INVALID_FROM`. Omit `from` and Void fills in `<project-slug>+noreply@mail.void.cloud` for you.
+On the platform the sender is pinned to your project. `from` must be your project's own platform address — `<project-slug>@<mail-domain>` or `<project-slug>+<tag>@<mail-domain>`, optionally with a display name — or any address on a domain registered with `void email domain add` (see [Your own domain on the platform](#your-own-domain-on-the-platform)). For example, if your platform's mail domain is `mail.example.com`, you can use `Acme <acme+noreply@mail.example.com>`. Anything else is rejected with `INVALID_FROM`. Omit `from` and Void fills in `<project-slug>+noreply@<mail-domain>` for you.
 
-On your own Cloudflare account, `from` defaults to `email.from` from `void.json` and must be on a domain your account can send from; Cloudflare rejects any other sender and `sendEmail` reports it as `INVALID_FROM`.
+On your own Cloudflare account, `from` defaults to `email.from` from `void.config.ts` and must be on a domain your account can send from; Cloudflare rejects any other sender and `sendEmail` reports it as `INVALID_FROM`.
 
 ## Attachments
 
 ```ts
 await sendEmail({
-  from: 'Acme <acme+noreply@mail.void.cloud>',
   to: 'user@example.com',
   subject: 'Your receipt',
   text: 'Receipt attached.',
@@ -146,7 +149,6 @@ For inline images (e.g. logos referenced from HTML), set `disposition: 'inline'`
 
 ```ts
 await sendEmail({
-  from: 'Acme <acme+noreply@mail.void.cloud>',
   to: 'user@example.com',
   subject: 'Hello',
   html: '<img src="cid:logo" alt="Acme">',
@@ -237,11 +239,11 @@ Under the hood, your code runs in workerd (a separate process from the Vite dev
 
 The dev inbox is **not** available under a Class B or C framework — SvelteKit, Nuxt, Analog, Astro. Those adapters own their own dev server and worker build, so Void never installs the Cloudflare Vite plugin for them and has nowhere to register the inbox. Declaring an `assets` binding does not help: SvelteKit, Nuxt and Analog do not run your code in a workerd instance fronted by Vite at all, so there is no loopback to bind to. Sends from those apps return `BINDING_MISSING`. Use `createEmailTestHarness` from `void/email/testing` instead, which captures in-process and works everywhere. When the inbox is configured but unreachable, `sendEmail` returns `UPSTREAM_ERROR` — nothing is captured and nothing is sent.
 
-`sendInDev: true` bypasses the dev inbox for a single send. `void dev` binds no send transport at all — the platform's `__VOID_PROXY` service binding is added only on a deployed worker, and the own-account `SEND_EMAIL` binding is stripped under `serve` so miniflare cannot write stray `.eml` files or send real mail (only that entry: a `send_email` binding of your own under another name is left exactly as `wrangler.jsonc` declares it). With the inbox skipped there is nothing left to fall through to, so the call returns `BINDING_MISSING`: it proves the inbox was bypassed, it does not deliver. To verify real delivery, deploy and send from the deployed worker.
+`sendInDev: true` bypasses the dev inbox for a single send. `void dev` binds no send transport at all — the platform's `__VOID_PROXY` service binding is added only on a deployed worker, and the own-account `SEND_EMAIL` binding is stripped under `serve` so miniflare cannot write stray `.eml` files or send real mail (only that entry: a `send_email` binding of your own under another name is left exactly as `cloudflare.send_email` in `void.config.ts` declares it). With the inbox skipped there is nothing left to fall through to, so the call returns `BINDING_MISSING`: it proves the inbox was bypassed, it does not deliver. To verify real delivery, deploy and send from the deployed worker.
 
 ```ts
 const result = await sendEmail({
-  from: 'acme+noreply@mail.void.cloud',
+  from: 'acme+noreply@mail.example.com', // replace with your project sender
   to: 'verified@acme.dev',
   subject: 'Skips the dev inbox',
   text: 'Not captured — and not delivered either.',
@@ -264,7 +266,7 @@ describe('signup flow', () => {
     const inbox = createEmailTestHarness();
 
     await sendEmail({
-      from: 'acme+noreply@mail.void.cloud',
+      from: 'acme+noreply@mail.example.com', // use your project sender
       to: 'user@example.com',
       subject: 'Welcome',
       text: 'Hi!',
@@ -406,7 +408,7 @@ deployed `email/` handlers without per-project DNS setup. A
 handlers once its inbound readiness is `ready`. Use `void email domain status`
 to check current provider routing and any remaining setup steps.
 
-On your own Cloudflare account there is no shared facility: the deploy derives one Email Routing rule per handler and writes it into `wrangler.jsonc` for you — see [Your own Cloudflare account](#your-own-cloudflare-account).
+On your own Cloudflare account there is no shared facility: the deploy derives one Email Routing rule per handler and records it in `void.lock.json` for you — see [Your own Cloudflare account](#your-own-cloudflare-account).
 
 There is no local inbound trigger yet — `void dev` serves the outbound dev inbox only, so test inbound handlers with `createInboundTestHarness` below.
 
@@ -476,7 +478,7 @@ The harness uses the same precedence rules as the production dispatcher. Reserve
 
 ### Two things to type, once
 
-1. **`email.from` in `void.json`** — the default sender, and the domain Void sets up:
+1. **`email.from` in `void.config.ts`** — the default sender, and the domain Void sets up:
 
    ```json
    {
@@ -486,17 +488,17 @@ The harness uses the same precedence rules as the production dispatcher. Reserve
    }
    ```
 
-   The host (`mail.acme.com`) must be a zone in the Cloudflare account your deploy is pinned to, or sit under one. Without `email.from`, a deploy that uses email prints `add "email": { "from": "you@mail.acme.com" } to void.json` and deploys without it. Void does not pick a zone for you — wrangler cannot list them — and it never writes `void.json`.
+   The host (`mail.acme.com`) must be a zone in the Cloudflare account your deploy is pinned to, or sit under one. Without `email.from`, a deploy that uses email asks you to set it in `void.config.ts` and deploys without email. Void does not pick a zone for you or write the setting automatically.
 
 2. **`void cloudflare login`**, or **`CLOUDFLARE_API_TOKEN`** set to a token with **Email Routing Edit** and **Email Sending Edit** (zone and account) alongside the deploy permissions. A browser session created by older Cloudflare tooling lacks the two email scopes; the deploy tells you to run `void cloudflare logout`, then `void cloudflare login` (one browser Allow) and skips the email step. A token's permissions cannot be listed up front, so a token that lacks one shows up as a row Void could not read (`unknown`), with the permission named. A Global API Key pair (`CLOUDFLARE_API_KEY`) is refused: it has no single bearer for the two calls wrangler has no command for.
 
 ### The first deploy
 
-Before any of your project code runs, the deploy **reads** — the session, the zone, public DNS (MX on the mail domain and on the apex, `_dmarc`, `cf-bounce`), Email Routing status, the zone's subaddressing setting, the routing rules on your addresses, Email Sending, and what `wrangler.jsonc` already holds — and prints what it found and what it would change:
+Before any of your project code runs, the deploy **reads** — the session, the zone, public DNS (MX on the mail domain and on the apex, `_dmarc`, `cf-bounce`), Email Routing status, the zone's subaddressing setting, the routing rules on your addresses, Email Sending, and what the resolved Cloudflare config already holds — and prints what it found and what it would change:
 
 ```
   Email in use   email/support+[ticket].ts · email/_default.ts · sendEmail() in 2 files
-    domain    mail.acme.com          (void.json email.from)
+    domain    mail.acme.com          (void.config.ts email.from)
     zone      acme.com               account Acme (f721b8e5…) · session dev@acme.com
     apex MX   aspmx.l.google.com     left alone — mail lives on the subdomain
     routing   mail.acme.com  not enabled · subaddressing off
@@ -509,7 +511,7 @@ Before any of your project code runs, the deploy **reads** — the session, the
     + enable Email Routing on mail.acme.com       Cloudflare writes and locks 3 MX + 1 SPF record there
     + turn on subaddressing for acme.com          support+anything@ reaches support@
     + onboard mail.acme.com for Email Sending     MX/SPF/DKIM on cf-bounce.mail.acme.com, _dmarc.mail.acme.com (p=reject)
-    + wrangler.jsonc                              send_email: [{ name: "SEND_EMAIL" }], addresses: ["support@mail.acme.com"], vars.__VOID_EMAIL_FROM: "noreply@mail.acme.com"
+    + Cloudflare config                              send_email: [{ name: "SEND_EMAIL" }], addresses: ["support@mail.acme.com"], vars.__VOID_EMAIL_FROM: "noreply@mail.acme.com"
     + routing rule (created on deploy)            support@mail.acme.com → acme-support
     ! email/_default.ts                           a catch-all exists only on an apex; other @mail.acme.com mail bounces
 
@@ -528,7 +530,7 @@ On the second deploy every row reads ready: no prompt, no account call, and wran
 
 DNS can take a few minutes to become visible to the resolver running the deploy. If `void email setup` has already written the exact `addresses` plan but that resolver still sees no subdomain MX, Void preserves the plan and stops before the build or upload. Run `void email status --platform cloudflare`, then retry the deploy after it sees Cloudflare's MX records.
 
-Two rows live in `wrangler.jsonc` rather than in your account, and a deploy that finds every account row ready reconciles them with a plain file write, no prompt: the `addresses` array is rewritten whenever it is not the current derivation (an entry pruned since, a worker rename, a new handler), and `vars.__VOID_EMAIL_FROM` follows a changed `email.from`. Routing rules are `wrangler deploy`'s own work, so a committed `addresses` entry whose rule does not exist yet — the state right after `void email setup` — still reads ready; the address map marks it `(rule created by this deploy)`.
+Two rows live in the generated Cloudflare config rather than in your account, and a deploy that finds every account row ready reconciles them with a plain file write, no prompt: the `addresses` array is rewritten whenever it is not the current derivation (an entry pruned since, a worker rename, a new handler), and `vars.__VOID_EMAIL_FROM` follows a changed `email.from`. Routing rules are `wrangler deploy`'s own work, so a committed `addresses` entry whose rule does not exist yet — the state right after `void email setup` — still reads ready; the address map marks it `(rule created by this deploy)`.
 
 A subdomain is added to a zone that already routes. When Email Routing is **off** on the apex (`Enabled: false`), the subdomain step is not attempted at all — Void never enables routing on the apex from the subdomain path, since that would lock MX records over the apex's live mail — and the checklist prints the dashboard step (`Email → Settings → Subdomains → add mail.acme.com`) instead; `addresses` is withheld until routing on the subdomain reads ready.
 
@@ -544,7 +546,7 @@ The apex path (`email.from` on `acme.com` itself) is allowed with the same one E
 
 **Subaddressing** is a per-zone Cloudflare setting, and it is off by default. Until it is on, a rule for `support@mail.acme.com` does not match `support+T-42@mail.acme.com`. The checklist's `turn on subaddressing for acme.com` row flips it for the whole zone — on the apex and every subdomain — so `email/support+[ticket].ts` works the way it does on the platform.
 
-### What Void writes into `wrangler.jsonc`
+### What Void records in `void.lock.json`
 
 ```jsonc
 {
@@ -563,7 +565,7 @@ The apex path (`email.from` on `acme.com` itself) is allowed with the same one E
 - An address already routed to another worker or to a forwarding rule is **pruned** from the array and reported (`! support@mail.acme.com  already routed to …; left alone, not in addresses`). wrangler's plan is never destructive on your account because of something Void derived.
 - If the array holds entries Void did not derive, the deploy prints which ones and **skips the email step for that deploy** — the deploy itself continues and the array is left untouched. Remove them, or manage `addresses` by hand and leave `email.from` unset.
 
-Deleting a handler leaves its address in `addresses`: the next deploy names it in a `✘` row as an entry Void no longer derives, and skips the email step until you remove that entry from `wrangler.jsonc` by hand (the row says which). Once removed, wrangler's plan drops the rule with its own y/n (default No) in a terminal, an error in CI. Removing the last handler and every `sendEmail()` call leaves the whole setup in `wrangler.jsonc`; the deploy warns which addresses are still routed to a worker with no `email()` export and how to detach them, and deploys as-is.
+Deleting a handler leaves its address in `addresses`: the next deploy names it in a `✘` row as an entry Void no longer derives, and skips the email step until you override `cloudflare.addresses` in `void.config.ts` with the desired list (the row says which). Once removed, Cloudflare's plan drops the rule with its own y/n (default No) in a terminal, an error in CI. Removing the last handler and every `sendEmail()` call leaves the whole setup in `void.lock.json`; the deploy warns which addresses are still routed to a worker with no `email()` export and how to detach them, and deploys as-is. To detach fully, remove `addresses`, `send_email`, and `vars.__VOID_EMAIL_FROM` from `resolved` in `void.lock.json` and remove any authored overrides in `void.config.ts`, then delete the routing rules in Cloudflare.
 
 How handlers become addresses, with `email.from` on `mail.acme.com` under the zone `acme.com`:
 
@@ -591,7 +593,7 @@ Workers Paid needed for arbitrary recipients. Inbound works; sendEmail() to veri
 
 Everything else — routing, rules, the binding — still goes through, and the address map ends with `outbound  sendEmail() from support@mail.acme.com   (verified destinations only)`. Verified destinations are the addresses under **Email Routing → Destination addresses** in your Cloudflare dashboard; a handler that `forward()`s to a new address needs the same verification click.
 
-The refusal is remembered by the `send_email` binding that same run writes into `wrangler.jsonc`: Void writes the binding only after it has attempted the onboarding, so a committed binding next to a domain that is still not onboarded means "tried, refused". Later deploys ask nothing about it, `--require-email` passes, `void email status` reads the domain as set up (its sending row says `not onboarded — verified destinations only` and names the retry), and the address map keeps ending with `(verified destinations only)`. The deploy never retries the onboarding on its own. After upgrading to Workers Paid, run `void email setup --platform cloudflare` once: it asks `Onboard mail.acme.com for Email Sending?` and, on Yes, onboards the domain — from then on the map ends without the marker.
+The refusal is remembered by the `send_email` binding that same run records in `void.lock.json`: Void records the binding only after it has attempted the onboarding, so a committed binding next to a domain that is still not onboarded means "tried, refused". Later deploys ask nothing about it, `--require-email` passes, `void email status` reads the domain as set up (its sending row says `not onboarded — verified destinations only` and names the retry), and the address map keeps ending with `(verified destinations only)`. The deploy never retries the onboarding on its own. After upgrading to Workers Paid, run `void email setup --platform cloudflare` once: it asks `Onboard mail.acme.com for Email Sending?` and, on Yes, onboards the domain — from then on the map ends without the marker.
 
 If `_dmarc.mail.acme.com` or `cf-bounce.mail.acme.com` already has a TXT record, sending onboarding is refused — it writes its own `_dmarc` (`p=reject`) and DKIM records and Cloudflare would answer with a conflict. Inbound is unaffected; remove the records or keep sending off.
 
@@ -601,12 +603,12 @@ The email prompt follows wrangler's own interactivity rule: a CI environment as
 
 ```
 deploy: email on mail.acme.com is not set up, and this shell cannot ask.
-Run `void email setup --platform cloudflare` once locally, commit wrangler.jsonc, then redeploy — deploying without email.
+Run `void email setup --platform cloudflare` once locally, commit void.lock.json, then redeploy — deploying without email.
 ```
 
 then deploys **without** email. Pass `--require-email` to fail instead. When setup has already committed the exact subdomain `addresses` plan and only its MX records are not visible yet, every deploy stops and preserves that plan until DNS can be verified. Automatic resource provisioning is not an escape hatch: it creates D1/KV/R2/Queue/Hyperdrive resources, never a mail setup. To read the rows without deploying or being asked anything, run `void email status --platform cloudflare`.
 
-So the CI story is: run `void email setup --platform cloudflare` once on your machine (it runs the same preflight, checklist and prompt as the first deploy, then writes `wrangler.jsonc`, without deploying), commit `wrangler.jsonc`, and let CI run `void deploy --platform cloudflare --require-email`. Once the MX records are visible, the committed binding and `addresses` make every row read ready and nothing is asked — on Workers Free too, where the committed binding is what remembers the refused sending onboarding (see [Sending](#sending)).
+So the CI story is: run `void email setup --platform cloudflare` once on your machine (it runs the same preflight, checklist and prompt as the first deploy, then updates `void.lock.json`, without deploying), commit `void.lock.json`, and let CI run `void deploy --platform cloudflare --require-email`. Once the MX records are visible, the committed binding and `addresses` make every row read ready and nothing is asked — on Workers Free too, where the committed binding is what remembers the refused sending onboarding (see [Sending](#sending)).
 
 ### If the subdomain step is refused
 

package/skills/void/docs/guide/env-migration.md

@@ -80,7 +80,7 @@ void secret list
 
 Remote stores return names only; plaintext values are validated during upload and again at worker startup. If an upload fails or a name is missing, retain the source values and retry before continuing.
 
-For direct Cloudflare deployments, remove the migrated server keys from `vars` in `wrangler.jsonc` after confirming the upload. Void now treats any schema-declared server key in Worker `vars` as an error.
+For direct Cloudflare deployments, remove the migrated server keys from `cloudflare.vars` in `void.config.ts` after confirming the upload. Void now treats any schema-declared server key in Worker `vars` as an error.
 
 ## 4. Supply client values at build time
 

package/skills/void/docs/guide/index.md

@@ -36,7 +36,7 @@ Types follow your data through the app: from a Drizzle schema to a route handler
 
 Void brings these pieces together:
 
-- **Resources from your code:** imports tell Void which supported resources to provision. Use `void.json` or your Cloudflare config when you need to customize them.
+- **Resources from your code:** imports tell Void which supported resources to provision. Use `void.config.ts` and its `cloudflare` field when you need to customize them.
 - **Types from database to frontend:** your Drizzle schema defines DB types, route handlers infer return types, and the [typed fetch client](./typed-fetch.md) checks calls at the usage site. One [Standard Schema](https://standardschema.dev/) validator can drive both runtime validation and compile-time types.
 - **Local Cloudflare development:** native Void apps run server code in `workerd`, with local database, KV, and storage.
 - **Deploy that understands the app:** `void deploy` reads your migrations, provisions the resources you actually use, and ships the result to the edge.

package/skills/void/docs/guide/pages-routing/head.md

@@ -39,7 +39,7 @@ export const head = defineHead<Props>((c, props) => {
 
 ## Config Defaults
 
-Set site-wide head defaults in `void.json`:
+Set site-wide head defaults in `void.config.ts`:
 
 ```json
 {

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

@@ -0,0 +1,171 @@
+---
+outline: deep
+---
+
+# Sign-in and Access
+
+## Signing In
+
+For the browser admin UI, open `<API URL>/admin` and use the administrator login method selected during setup. On a new installation, follow the printed administrator setup instructions to create the first admin user. You do not need to create an app or sign in through the CLI first.
+
+Connect to your platform's API URL, then sign in as an administrator:
+
+```sh
+void connect https://platform.example.com --no-login
+void platform auth login
+```
+
+The first command saves the connection. The second opens your browser to sign in and saves an administrator session in your system keychain. Sessions last for one hour and are stored separately for each platform.
+
+You can check which account is signed in at any time:
+
+```sh
+void platform auth status
+```
+
+This shows your account, the session's expiry, and the features available on the platform. To end the session, run `void platform auth logout`.
+
+If the platform is protected by Cloudflare Access, `void connect <url>` handles
+the company sign-in before Void login. Interactive Access authentication uses a
+locally installed `cloudflared` and saves its short-lived credential in your
+system keychain for that platform origin. You do not need to copy browser cookies.
+
+For CI, Access credentials do not replace Void deployment credentials. A project
+owner creates the latter with `void project token create`; it is independently
+revocable, expires within 90 days, and authorizes only that project's deploy
+workflow. Human and operator tokens cannot be renewed by Access service proof.
+
+Store Access credentials in origin-keyed `VOID_ACCESS_CREDENTIALS`. A deploy
+that uses prerendering or remote bindings needs entries for both the exact API
+and proxy HTTPS origins, even when both entries contain the same admitted
+service-token pair. `VOID_ACCESS_ORIGIN` selects only one recipient and therefore
+cannot cover both calls. Keep the JSON value in your secret manager, not in
+application configuration. See [CI deployment setup](/guide/platform/installation/first-deployment)
+for the required shape.
+
+## Choosing a Platform
+
+If you manage more than one platform, list your connections and choose a default:
+
+```sh
+void platform list
+void platform use <connection-id>
+```
+
+You can also select a platform for a single command with `--connection`:
+
+```sh
+void platform user list --connection <connection-id>
+```
+
+Use an ID or URL from the connection list. Administrative commands use this selection even when you run them inside an app with a different deployment destination.
+
+## Recovering Administrator Login
+
+If no administrator can use the configured identity provider, the installation
+owner can recover an existing administrator with Cloudflare management access,
+direct database access, and the original encrypted recovery credentials:
+
+```sh
+void platform config auth recover company --installation <id> --file recovery.json
+```
+
+The file identifies the existing account, for example
+`{"administratorUserId":"existing-admin-id"}`. Recovery opens a real login test
+and asks you to confirm the exact identity before restoring access. It does not
+create a new administrator. To use a replacement provider, include its nonsecret
+`configuration` with a new connection ID and supply the secret through
+`--client-secret-env <name>`. To rotate an existing provider's secret, keep its
+connection ID and identity configuration.
+
+For `--yes`, also pin `expectedIdentity` with the exact `issuer` and `subject` in
+the file. A successful browser login is still required. Use `--plan` to preview
+the affected administrator and connection before starting recovery.
+
+## Giving People Access
+
+Open **Settings** in the administrator UI, or run `void platform config auth`,
+to add, test, enable, or disable login methods. Access protection and login
+methods are separate settings. A provider test shows the authenticated account
+before you explicitly link it or enable the configuration.
+
+To change the company gate after installation, use the installing workstation
+with its saved recovery credentials:
+
+```sh
+void platform config auth protection show
+void platform config auth protection enable --installation <id>
+void platform config auth protection disable --installation <id>
+```
+
+Enabling offers application creation or connection to an existing application.
+It checks every API, proxy, and configured dashboard origin and requires a company
+user sign-in. Changing protection ends all current human sessions; sign in again
+afterwards. Before removing a gate used for company signup, select another
+verified company rule or restricted signup. Removing protection retains the
+Cloudflare applications for deliberate cleanup. Disabling an Access login method
+does not remove the gate.
+
+Users can add another enabled login to their existing account with
+`void auth link <connection-id>` or **Account** in the optional
+dashboard. Sign in again first if prompted, then authenticate with the additional
+provider and confirm the identity shown. Matching email addresses alone do not
+link accounts.
+
+In the admin dashboard, open **People → Access** to choose who can join, invite
+people, and manage individual signup grants. Choose **Company-approved or
+individually approved users** to create accounts automatically for people who
+meet your configured company rules while still allowing explicit invitations
+and allowlist grants. Company protection at the platform edge still applies
+before anyone reaches a login page.
+
+With invited/allowlisted signup selected, let a teammate join with GitHub by adding their login to the allowlist:
+
+```sh
+void platform signup allow github teammate
+```
+
+Void shows the change and asks you to confirm it. The teammate can then run `void connect` with the platform's URL and sign in.
+
+You can allow an email address or a whole email domain in the same way:
+
+```sh
+void platform signup allow email teammate@example.com
+void platform signup allow email '*@example.com'
+```
+
+Email patterns apply across the platform's sign-in providers. Quote a domain pattern so your shell passes the `*` to Void.
+
+For an OIDC login without a verified email, allow the identity by its login connection and stable provider subject instead:
+
+```sh
+void platform signup allow identity company-sso 'Employee-42'
+```
+
+Use the connection ID shown by `void platform config auth list` and the exact subject reported by your identity provider. The match is case-sensitive and does not infer an email address or link another account. Any domain or group restrictions configured for that login method still apply, and the account joins as an ordinary user. Remove the grant with `void platform signup disallow identity company-sso 'Employee-42'`.
+
+To invite someone else by email, use:
+
+```sh
+void platform invitation send alex@example.org
+```
+
+An invitation grants signup access for that exact email address. The person must
+sign in with a login method that supplies the same verified email address.
+When platform email delivery is configured, Void also sends connection
+instructions. If delivery is unavailable or fails, the grant still works:
+share the platform's `/invite` page or `void connect '<platform URL>'` command
+with the person yourself. The admin dashboard shows the delivery outcome
+separately from the invitation's pending, accepted, or revoked status.
+
+Inspect the current access settings and invitations with:
+
+```sh
+void platform signup show
+void platform invitation list
+```
+
+Invitation history remains available after an involved account is removed. The stored actor ID
+remains visible when that account's login no longer exists.
+
+`void platform signup open` allows anyone to sign up. Use `void platform signup restrict` to require an allowlist match again. Disallowing an entry affects future signup; it does not suspend an existing account.

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

@@ -0,0 +1,121 @@
+---
+outline: deep
+---
+
+# Email
+
+## Managing Email
+
+These commands apply to a platform that enables email. Every project can send from and receive at `<slug>+tag@<mail domain>` on the platform's shared mail domain; the [email guide](/guide/email) describes what applications do with that.
+
+### Deciding who mail may reach
+
+By default, mail from the shared sender reaches only the recipients each project has verified. For a team whose applications mainly mail colleagues, widen that once for the whole installation:
+
+```sh
+void platform email policy
+void platform email policy-set domains --domains example.com,corp.example.net
+void platform email policy-set any
+void platform email policy-set verified
+```
+
+`domains` lets every project mail any address on the listed domains in addition to its verified recipients; `any` lifts the check. Cloudflare still refuses a recipient it has not verified until your mail domain is onboarded for Email Sending, which needs Workers Paid on the platform's account. Until then such sends come back as `UNVERIFIED_DESTINATION` for that recipient, whatever the policy says. Two things the policy never changes: sends from a project's own custom domain, and mail to any address on the platform's own mail domain — those stay verified-recipient-only, so no project reaches another project's inbox without its consent. A tightening applies to new send admissions as soon as it commits; previously admitted attempts may finish. The same setting is on the admin UI's **Email** page.
+
+### Project caps
+
+Each project has 200 recipient submissions per UTC calendar month and 10 in a rolling 60-second window by default. An attempt stays charged once it starts, including a failed or uncertain outcome. Raise or lower a project's caps by id or slug:
+
+```sh
+void platform email limit hr-portal --monthly 2000 --burst 30
+```
+
+The project's page in the admin UI shows the current values and clears an override.
+
+### Recovering an interrupted send
+
+If a sender stops after beginning a provider call, its unresolved attempt blocks
+removal of the project or sender domain. Inspect the attempt ID and start time:
+
+```sh
+void platform email attempts --project hr-portal
+```
+
+First confirm that the original execution has ended through your Worker logs or
+incident records. Once the attempt is at least 24 hours old, resolve it with an
+audit reason that contains no recipient address or message content:
+
+```sh
+void platform email attempt-resolve <attempt-id> --ended --reason "Original Worker execution ended; provider outcome could not be verified" --plan
+void platform email attempt-resolve <attempt-id> --ended --reason "Original Worker execution ended; provider outcome could not be verified"
+```
+
+This records the send as `outcome_unknown` and releases its cleanup fence. The
+attempt remains charged and is never retried. If its 30-day delivery record has
+expired, only its recipient-free fence is removed. Do not resolve an attempt
+while its original execution may still be active.
+
+Inspect a project's retained receipt and recipient outcomes with:
+
+```sh
+void platform email logs hr-portal --page 1 --limit 50 --json
+```
+
+Logs include operation IDs, recorded outcomes, provider references, and error codes.
+After project deletion, use its project ID until the 30-day metadata retention
+period expires. Message bodies, subjects, attachments, and credentials are not logged.
+
+### Registering email domains for projects
+
+Your users may hold no Cloudflare account. Tell the platform that administrators register email domains, so `void email domain add` prints the command to ask you for instead of opening a token-creation page:
+
+```sh
+void platform email settings-set --domains admin
+```
+
+Then register a domain for a project. The zone must be in the platform's Cloudflare account; the platform's own credential does the setup, and no Cloudflare credential is stored per domain:
+
+```sh
+void platform email domain-add mail.example.com --project hr-portal
+void platform email domain-status mail.example.com
+void platform email domain-rotate-secret mail.example.com
+void platform email domains
+```
+
+Name the exact mail domain: a subdomain such as `mail.example.com` when the apex already receives mail, otherwise the apex itself. `domain-status` reports inbound, outbound, and management readiness separately. Follow any required DNS or Cloudflare dashboard step, then use `domain-sync` to reconcile. Use `domain-rotate-secret` when you need to replace the zone ingress credential explicitly. Email Sending onboarding needs Workers Paid; after upgrading, `domain-sync` re-attempts it. For a zone in another Cloudflare account, pipe an API token for that account on standard input:
+
+```sh
+void platform email domain-add mail.other.example --project hr-portal --token-stdin --yes < token.txt
+```
+
+Project owners see administrator-registered domains in `void email domain list` and `status`; `status` names the `void platform email` command for any step they cannot take themselves, and `sync` and `remove` point them at `domain-sync` and `domain-remove`. A domain an owner registered before you switched to `admin` stays theirs to renew, sync and remove. The runtime token needs the email permissions listed in the [self-hosting guide](/guide/platform/installation/credentials#runtime-token-permissions) for this to work.
+
+A permission refusal leaves setup blocked. After correcting it, run `domain-sync`
+to resume that same setup operation; repeat `domain-rotate-secret` to resume a
+blocked rotation without replacing its staged secret. If project deletion leaves
+a blocked domain cleanup, correct the permission and run `domain-remove <domain>`
+to finish the retained cleanup. If its token has expired or been revoked, provide
+a replacement scoped to the same account and zone:
+
+```sh
+void platform email domain-remove mail.other.example --token-stdin --yes < token.txt
+```
+
+This recovery is available only after project deletion has begun and no other
+project uses the connection. For a live project, renew its token through
+`domain-add`. A timed-out Cloudflare
+mutation stays stopped because replay may duplicate a provider write. After
+confirming the original execution ended, wait 24 hours, inspect the exact
+routing, Worker, secret, catch-all, or Sending resource named by the preview,
+and use its recovery fence:
+
+```sh
+void platform email operation-resolve <operation-id> --ended --outcome <applied|not-applied> --reason "Provider state verified" --plan
+void platform email operation-resolve <operation-id> --ended --outcome <applied|not-applied> --reason "Provider state verified"
+```
+
+Run recovery with the same platform version that created the persisted intent.
+`applied` continues without replaying the write; `not-applied` permits that exact
+step to retry. Secret rotation keeps its staged generation, and removal resumes
+from the unresolved cleanup step. Age alone never authorizes a retry.
+
+Register administrator domains only after a platform upgrade has completed, and remove them before rolling the platform back to a version that predates this feature: an earlier runtime cannot use the platform credential for them and does not distinguish administrator-registered domains from owner-registered ones.

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

@@ -0,0 +1,97 @@
+---
+outline: deep
+---
+
+# Operations
+
+## Previewing Changes
+
+Commands that change the platform show the affected objects before asking for confirmation. To inspect a change without applying it, add `--plan`:
+
+```sh
+void platform user suspend <user-id> --reason "Investigating unexpected traffic" --plan
+```
+
+The preview shows which account will be suspended and the effect on its projects. Run the command again without `--plan` to confirm interactively, or use `--yes` when the change is ready to apply:
+
+```sh
+void platform user suspend <user-id> --reason "Investigating unexpected traffic" --yes
+```
+
+Scripts must use `--yes` to apply these changes. The `void platform auth` session commands run directly and do not use `--plan` or `--yes`; changes under `void platform config auth` do use previews and confirmation. After a change, `void platform system events` shows the administrator, affected objects, and recorded outcome.
+
+Changes can take longer when an account owns many resources. Requests that change the platform allow five minutes by default; use `--timeout` to set a different limit in seconds:
+
+```sh
+void platform user delete <user-id> --timeout 600 --plan
+```
+
+If a request times out or loses its connection, some work may already have finished. Check the affected objects and `system events` before retrying. Void reports partial results when it can and does not automatically repeat the change.
+
+## Following Logs
+
+To investigate a deployment, find its ID and follow its runtime logs:
+
+```sh
+void platform deployment list --project <project-id>
+void platform deployment logs <deployment-id> --since 10m --follow
+```
+
+Runtime logs include application messages, exceptions, and HTTP status codes. Without `--follow`, the command reads a page of historical logs. Use `--since` to choose a duration, an ISO date, or a timestamp in milliseconds.
+
+Logs can become available after a request finishes. Following checks a five-minute overlap to pick up delayed records without printing them again. Records delayed longer than that may need a later historical query.
+
+Build logs use the build's ID:
+
+```sh
+void platform build logs <build-id> --follow
+```
+
+Following waits for the final logs before stopping, including diagnostics written after the build's status changes. For a GitHub Actions build, the command gives you the URL of its logs.
+
+## Checking the Platform
+
+Use the overview to see recent activity, or run a health check to test the platform's services and database:
+
+```sh
+void platform system overview
+void platform system health
+```
+
+Health checks use the services configured for the selected platform. An unhealthy result exits with a nonzero status, so the same command can be used in a script.
+
+The browser dashboard's **System Status** checks refresh every 30 seconds. Failed checks show an HTTP status or connection error beside the service name. If the dashboard cannot refresh the checks, it reports that status is unavailable instead of displaying stale results.
+
+Use `void platform upgrade`, `repair`, `disable`, and `enable` to maintain your platform. See [platform maintenance](/guide/platform/installation/maintenance#resume-repair-recover-and-upgrade).
+
+For disaster recovery, keep a matching PostgreSQL backup, provider data backups, installation identity and complete project-encryption keyring, and immutable runtime artifacts. Keep traffic disabled while restoring data, run `discover` to reconstruct verified local metadata, and review `repair --plan` before recreating missing installer-owned infrastructure. Neither command restores backed-up data. See [Prepare for disaster recovery](/guide/platform/installation/maintenance#prepare-for-disaster-recovery) for the full sequence.
+
+## Using Scripts
+
+Add `--json` to read a command's result from another program:
+
+```sh
+void platform user list --page 1 --limit 50 --json
+void platform system health --json
+```
+
+Results go to standard output. Command errors go to standard error as JSON and exit with a nonzero status. With `--follow`, each log response is a separate JSON line.
+
+Operator tokens expire after one hour. For CI, mint a new operator token at the start of each job from a valid full API login session belonging to an active administrator. Choose the platform explicitly, inject the full session as `VOID_TOKEN` from your secret manager, and capture the exchange output directly into the protected job environment:
+
+```sh
+export VOID_API_URL=https://platform.example.com
+VOID_OPERATOR_TOKEN="$(
+  printf '%s' "$VOID_TOKEN" | void platform auth token --token-stdin
+)" || exit 1
+export VOID_OPERATOR_TOKEN
+unset VOID_TOKEN
+void platform system health --json
+unset VOID_OPERATOR_TOKEN
+```
+
+Disable shell tracing for the exchange and do not write either token to logs or plaintext files. A full API login session expires after 30 days and can be revoked sooner; renew it through the normal authenticated login flow and update the protected CI secret. A job that runs longer than one hour must repeat the exchange while its full API session is still valid. An expired operator token cannot refresh itself, and Void does not issue permanent service tokens for administrator automation.
+
+`auth login --token-stdin` performs the same elevation and saves the one-hour operator token in the system keychain for interactive use. See [operator authentication](/reference/cli#operator-authentication) for the full command syntax.
+
+An email zone has one connection and ingress Worker shared by its exact domain assignments. Removing one assignment preserves resources used by the others. The Email administration page can explicitly rotate that connection secret; ordinary synchronization does not rotate it. Setup and cleanup outcomes include operation IDs, and uncertain provider writes remain recorded until reconciled.