void 0.22.0 → 0.23.0

package/skills/void/SKILL.md

@@ -1,129 +1,29 @@
 ---
 name: void
-description: Void skill for app development and CLI operations. Use this skill to route user requests to the appropriate bundled Void docs.
+description: Build Void apps and use the Void CLI by loading the relevant bundled guides and references.
 ---
 
-# Void Skill
+# Void
 
-This skill is a router. Open the minimum relevant docs files under `docs/` and execute.
+Read only the guides needed for the user's task. The bundled documentation lives
+under `docs/` beside this skill; in an installed project it is available at
+`node_modules/void/skills/void/docs/`.
 
-Docs in this skill are bundled from `docs/` during `void` package build and live at:
+Before running a Void command, find its group in `docs/reference/cli.md`, then
+read the matching page under `docs/reference/cli/` for syntax, options, and
+deployment target. Use Void commands for application and platform
+workflows. Mention Wrangler only when the user needs to recognize a literal
+configuration file or environment variable.
 
-- `skills/void/docs/**/*.md`
-
-`void init --agents` always writes brief instructions to `AGENTS.md`, pointing to `node_modules/void/skills/void/docs/`. It preserves content outside its versioned block, leaves other instruction files untouched, and links skills for detected agents without asking which agent is in use.
-
-`void init` offers Git initialization with `--git` / `--no-git` overrides and suggests an optional initial commit command. It preserves existing repositories and never commits automatically; see `docs/reference/cli.md` for CI and workspace behavior.
-
-## Command Naming
-
-For a new platform installation, prefer an app domain at the zone apex. Nested
-app domains need an active wildcard edge certificate and SSL-and-Certificates
-read permission; `void platform install --plan` verifies coverage. Use the
-self-hosted platform guide for certificate setup rather than enabling a paid
-product without an explicit request.
-
-For first-time platform setup, follow the installation pages linked from `docs/guide/self-hosted-platform.md` in order and introduce credentials when the user reaches that step. Recommend a domain; offer explicit `void platform install --workers-dev` for testing before one is ready. PostgreSQL, credentials for the selected login methods, runtime/R2 credentials, and saved signing/encryption keys are required. GitHub is the default and is optional. `--auth-config` accepts nonsecret provider configuration with environment secret references; `--plan` does not read those secrets. Configurable installations finish first-administrator setup using a one-time code and browser identity confirmation. Domain-free installation skips zone/DNS/certificate operations and can use browser login. `void platform domain set <domain>` later performs resumable DNS/HTTPS setup while preserving existing test URLs and the API origin. The command checks the deployed runtime token's cache-purge permission for the new zone; it does not ask users to retrieve that token. Interactive installation asks whether Void should create Hyperdrive or use a separately managed one; if the latter is missing, it gives setup instructions and stops before provisioning. It still prompts for the owner PostgreSQL URL. Prefer interactive prompts for secrets and keep CI variables in the CI workflow. Void creates the platform infrastructure and database tables.
-
-For an existing Cloudflare site, run `void deploy` with its root `wrangler.jsonc` or `wrangler.json`. An unlinked project gets a prompt to link and deploy using the existing Worker and resources. Accepting verifies and saves the destination, migrates the root config to `void.config.ts` and `void.lock.json`, then continues deployment. Keep new application resources, migrations, auth setup, and secret changes separate from this first handoff; ISR has its own explicit cache choice. The active Worker Version must be the latest upload so inherited secrets have an unambiguous source. Failed builds retain the link for retry. Read `docs/integrations/cloudflare.md` for the supported configuration and rollback behavior.
-
-When linking reports missing inferred resources, check the listed bindings and inference reasons against the existing Worker and `void.config.ts`; preserve `.void/cloudflare-link.json` for retries. For prerendered/revalidated sites without a cache, migration saves an explicit `routing.isr` choice in `void.config.ts`. True provisions the cache during this deployment; false keeps ISR disabled on retries and later deployments until changed. Keep page-level exports with either choice. CI must configure the boolean before resuming a migration with no saved choice. An application KV binding explicitly named `ISR_CACHE` is still required. Existing D1 bindings without checked-in migrations retain their local migration settings during handoff.
-
-For Cloudflare upload failures, use the detailed error message printed by the CLI and saved in the deploy log. A numeric error code alone may not identify the cause.
-
-Platform administration uses `void platform auth login` and the nested
-`user`, `project`, `deployment`, `build`, `signup`, `invitation`, `email`, `system`, and
-hosted-only `worker` groups. Open the operator section of `docs/reference/cli.md`
-before running these commands. Use `--json` for structured reads and `--plan`
-to inspect mutations; approved noninteractive mutations require `--yes`.
-The last active administrator cannot be deleted or suspended. If an allowed
-administrator removal reports partial cleanup, access remains revoked; use a
-remaining administrator to inspect the result and retry.
-Use `void platform config auth` to configure login methods; `platform auth`
-manages your administrator session. Test a pending configuration before enabling
-it, explicitly link identities when switching methods, and verify a linked
-alternative before disabling a method. Disabling revokes its human sessions,
-including human tokens used in CI, while scoped deployment tokens remain valid.
-Create CI credentials with `void project token create`; they are bound to one
-project, expire within 90 days, and support explicit renewal and revocation.
-Cloudflare Access service credentials pass only the perimeter and never renew or
-elevate a human or operator token.
-For scripted configuration, use nonsecret JSON with `--file` and read secrets
-with `--client-secret-env`; never put client secrets in command arguments.
-Use `void platform config auth admission` to select company-approved automatic
-signup when the organization's identity policy already determines eligibility;
-individual invitations remain optional. The same controls are available under
-Settings in the administrator UI.
-Access login and platform protection are independent. The installer can create
-dedicated Access applications or connect existing ones, including a separate
-identity account. Protection setup verifies API/proxy coverage and uses scoped
-service credentials for installation and CI. Use `platform config auth protection`
-to show, enable, or disable protection; retain the company gate when probes fail.
-Users link another enabled method with `void account link [connection-id]` after
-recent sign-in and explicit browser identity confirmation. For expired first-admin
-codes, resume installation or repair completed provisioning. Lost-provider recovery
-uses `platform config auth recover` with installation ownership, original recovery
-keys, an existing administrator ID, and a real provider login; never reopen signup.
-Operator credentials are separate from application deployment credentials and
-ignore repository platform selections. `VOID_OPERATOR_TOKEN` requires an
-explicit `VOID_API_URL` or `--connection`; credentials must never be written to
-project files. `signup open` allows public signup and `signup restrict` enforces
-the allowlist. For OIDC identities without verified email, use `signup allow identity
-<connection-id> <subject>` and the exact `signup disallow` counterpart; never infer an
-email or link accounts. Inspect `system events` and the target object after an ambiguous
-mutation failure before retrying.
-
-Use `void connect` for deployment onboarding: no arguments offers Cloudflare or a Void platform, `--platform cloudflare` signs in and selects an account, and a platform URL verifies discovery and signs in with a supported provider. It preserves existing project links when connecting elsewhere. `--no-login` saves only verified Void connection metadata; authenticated headless connection requires a valid origin-scoped keychain session or `VOID_TOKEN` with matching `VOID_API_URL`. Platform installation and administration use `void platform`.
-
-For Void platform project access, use `void project team`: invite only an email already registered on that platform and assign `reader`, `collaborator`, or `admin`. The invited account uses `void connect <url>` followed by pending/accept/decline on that active connection, regardless of the current directory's project link or deploy target. `VOID_API_URL` overrides the connection; an unscoped `VOID_TOKEN` selects Void Cloud. Acceptance preserves directory links; run `void project link` in an unlinked checkout of the invited application. Project-scoped team management does not apply to direct Cloudflare deployments. Installation administrators transfer ownership with `void platform project owner <project-id> <user-id> --plan` and apply the reviewed transfer with `--yes`.
-
-For a self-hosted platform's project Zero Trust policy, installation administrators use `void platform zero-trust`; pass the Access management token only through `--token-stdin`. Project owners and project administrators use `void project zero-trust status|protect|public|reconcile`; these commands do not apply to direct Cloudflare deployments. When a deploy or rollback is refused because protection is not settled, check `void project zero-trust status`; an owner or project administrator can run `void project zero-trust reconcile` before retrying.
-
-Use Void commands for every user-facing workflow. Never ask the user to install, authenticate, or run Wrangler directly. Say Cloudflare or Void instead, except when naming literal `wrangler.jsonc` / `wrangler.json` files or `WRANGLER_*` environment variables the user must inspect.
-
-`void auth login|status|logout` follows the saved deploy destination or asks the user to choose; `void account` explicitly manages a Void platform account.
-
-Use `void` in examples and commands in this skill. For first-time setup, prefer `void init` followed by `void deploy`; in an empty directory, install `void` first and let `void init` add the matching Pages adapter and starter dependencies with Vite+ as the default scaffold toolchain. In an existing app, `void init` configures Void in place by adding missing Vite scripts and creating or patching `vite.config.*` with `voidPlugin()`. For Cloudflare deployment, Void uses bundled tooling and secure browser OAuth; init or the first deploy saves the selected `account_id`, and `void cloudflare login|status|logout` manages the session; Void-managed deployment requires an explicitly connected platform. Use `void connect <url>` for an existing platform or `void platform install --plan` to preview a company control plane in the user's Cloudflare account. The core self-hosted platform excludes the dashboard, GitHub App, and build Containers; lifecycle commands are resumable and verify remote, Worker, and R2 ownership before mutations. `void platform disable` gates traffic through installation-owned routing storage and remains disabled through repair or upgrade; `void platform enable` explicitly restores traffic. Safe uninstall retains name-addressed Workers, R2, AI Gateway, external PostgreSQL, and zones for explicit manual cleanup. Direct Cloudflare deploys support native Void apps, static/SPA/SSG output, and Cloudflare builds from TanStack Start, React Router, vinext, SvelteKit, Nuxt, Analog, and Astro. They provision inferred resources, validate and apply migrations, require schema-declared server values in encrypted remote secret storage, upload and probe an immutable Worker Version, then activate and synchronize triggers. Native Void features are Workers Free-compatible by default; `void/sandbox` is an explicit exception because it uses Cloudflare Containers and therefore requires Workers Paid. A Sandbox deploy checks Containers access before provisioning/building, while apps without Sandbox perform no entitlement probe. Versions without preview URLs are staged at 0% and probed through workers.dev using a version override; the same safe fallback applies when Access blocks a generated preview alias but admits the stable Worker hostname. Set `CLOUDFLARE_WORKERS_SUBDOMAIN` in a fresh CI checkout, while local deploys cache it automatically. When Cloudflare Access protects `workers.dev`, use an admitted `CF_ACCESS_CLIENT_ID` / `CF_ACCESS_CLIENT_SECRET` service-token pair for CI, or a short-lived `CF_ACCESS_TOKEN` from `cloudflared` for an interactive local readiness probe. With Cloudflare saved in `.void/project.json`, secret, domain, project status/log/rollback, and remote database commands operate directly on the pinned Worker/account. Logs are a live tail. Rollback restores the selected version's saved schedules, queues, workflows, routes, and domains but never reverses database migrations; versions without complete trigger snapshots use code-only rollback and keep the current routes and schedules. On either deployment platform, auth-enabled `void deploy` preserves an existing `BETTER_AUTH_SECRET` or creates a persistent encrypted secret when missing; always use Void's deployment flow so it can manage that secret safely.
-
-Use `void` and `@void/*` in code examples and package manifests.
-
-Non-interactive self-hosted platform install, upgrade, repair, disable, enable, and uninstall commands require `--yes`; `--plan` is read-only and needs no acknowledgement.
-
-Platform install plans show actual resource names, the GitHub callback, and credential links without opening credential pages or saving a draft; Cloudflare browser login still opens if needed. New platforms use `void-<name>-<role>` names without random suffixes. Conflicts stop installation; existing installations retain recorded names. Approved interactive installs open the runtime-token, GitHub OAuth, and R2 pages only when those credentials are missing, with fallback instructions. Local credential drafts preserve the callback across retries and encrypt partial inputs. Interactive installs list unfinished installs, including interrupted provisioning, or offer "Start a new platform install". Entering an unfinished name asks to resume it; declining returns to name entry. Completed platforms are excluded, and new installs never inherit or delete old credentials or resources. Use `--resume --name <id>` to continue directly or in CI. Do not generate replacement signing keys or create another installation to recover a cancelled prompt.
-
-Cloudflare browser login does not grant AI Gateway access. A platform installation preview may mark that resource `inspect`; apply must verify it with the existing runtime-token input (Account → AI Gateway → Edit) before any provisioning. Never treat a permission failure as an empty resource inventory or skip ownership verification. The runtime token is used only for AI Gateway provider calls; other operations retain the operator credential.
-
-Use `--runtime <directory>` on platform install, upgrade, repair, enable, or rollback when deploying a locally built `@void/platform` runtime. The directory must contain the generated integrity manifest, Worker artifacts, and migration tree. Build it with `vp run --filter @void/platform build`; Git source revisions are detected automatically, with `-dirty` for uncommitted changes. `VOID_PLATFORM_SOURCE_REVISION` is an optional override. Do not treat this as a safety bypass: custom and packaged runtimes follow the same verification and rollback path.
-
-For self-hosted platform installation, require a dedicated empty PostgreSQL database. Interactive lifecycle commands use Cloudflare browser OAuth with keyring storage. Wrangler OAuth has Zone Read, so a plan that creates a zone or DNS record requires a scoped `CLOUDFLARE_API_TOKEN` with Account → Zone → Edit and/or Zone → DNS → Edit; finish Workers onboarding and choose a workers.dev subdomain for a fresh Cloudflare account. The installed platform uses a separate `VOID_PLATFORM_RUNTIME_CLOUDFLARE_API_TOKEN`. Its core permissions include Hyperdrive: Write at account scope and Cache Purge: Purge on the application zone; SSL and Certificates: Edit is needed only when a custom runtime enables custom project domains. Managed Sandbox apps additionally require Workers Paid plus Account → Containers → Edit and Account → Cloudchamber → Edit on that runtime token; these are checked on the first Sandbox application deploy, not during platform install or upgrade. The installer preflights account and Hyperdrive access and safely verifies Cache Purge for an existing zone with a unique nonexistent URL. Fresh installs require unique per-installation values from the operator's secret manager: `VOID_PLATFORM_JWT_SECRET` with at least 32 random bytes and `VOID_PLATFORM_PROJECT_SECRET_KEY` as canonical base64 for 32 random bytes. Never let a local checkpoint or ephemeral CI runner be their only custodian. Enabling email generates a separate signing key in encrypted recovery state; supply `VOID_PLATFORM_EMAIL_SIGNING_SECRET` from the secret manager for headless installs without persistent recovery files. The installer transactionally claims the database for one installation, pins that URL after a successful claim, never removes the claim during uninstall, and uses it for a cross-host lifecycle lock plus a secret-free authoritative lifecycle manifest. Local recovery checkpoints are AES-256-GCM encrypted with an OS-keychain key; never place platform secrets in plaintext files. After discovery on a new machine, provide `VOID_PLATFORM_DATABASE_URL`. For email-enabled installations without encrypted recovery state, also restore the original `VOID_PLATFORM_EMAIL_SIGNING_SECRET`; recreating only the email gateway needs this key, not JWT or runtime credentials. Normal upgrades preserve other deployed Worker secrets; restore the original runtime, GitHub, R2, JWT, and project-encryption values when recreating the API or proxy as documented. Upgrades enable managed Sandboxes automatically. An upgrade from the tenant-owned legacy may still require `void platform system sandbox-drain`: preview with `--plan`, follow each `nextCursor`, then apply with `--yes` until the DB-backed response reports `complete: true`; never delete an unverified app by name. The installer trusts only DB-backed sandbox-drain probe protocol v1. Before it accepts an empty inventory, the database admission barrier makes older deployment inserts finish and become visible or rejects them after the protocol floor is armed. Lifecycle redeploys preserve unmanaged Worker routes and custom domains in both the new trigger state and rollback snapshot. They stop before migrations or uploads when live Hyperdrive origin metadata differs from the pinned database. Platform upgrade SQL is forward-only: packaged hashes and the live Drizzle prefix must match, pending migrations require an exact source-version/schema rollback edge, and the old version remains authoritative until target health succeeds. Use `void platform rollback --runtime <earlier>` only when the installed runtime declares the exact earlier version/schema compatible; pass `--from-runtime` for the exact current custom artifact. Rollback preserves the forward database schema and cannot lower a database-required safety protocol. Safe uninstall retains Worker routes, custom domains, and R2 for explicit manual cleanup because Cloudflare cannot condition their deletion on an immutable generation.
-
-For an organization-managed Hyperdrive, set `VOID_PLATFORM_HYPERDRIVE_ID`, `VOID_PLATFORM_HYPERDRIVE_ORIGIN_HOST`, and `VOID_PLATFORM_HYPERDRIVE_ORIGIN_USER` together before installation. Use `VOID_PLATFORM_DATABASE_URL` for a separate owner connection that runs migrations; the Hyperdrive must be named `void-<installation-name>-database` and have SQL result caching disabled. See `docs/guide/platform/installation/prerequisites.md`.
-
-For self-hosted recovery, `VOID_PLATFORM_PROJECT_SECRET_KEY` restores an original `v1` project-secret keyring. After rotation, restore every retained version with `VOID_PLATFORM_PROJECT_SECRET_KEYS_JSON` and its active entry with `VOID_PLATFORM_PROJECT_SECRET_ACTIVE_KEY_VERSION`. These inputs restore a missing API Worker and never replace the live keyring of an existing Worker. Inject them from a secret manager without logging them or writing plaintext files.
-
-For Cloudflare user switching, `void cloudflare login` always opens a fresh browser sign-in. `void cloudflare status` distinguishes the authenticated user and credential method from the project's pinned deployment account. Login never retargets a project. Remove API-credential environment overrides from the current shell before browser sign-in, without printing their values; automatic deployment checks continue to reuse valid sessions.
-
-## No-Args Behavior
-
-Published self-hosted platform routes and custom domains are observed and recorded as retained attachments. Lifecycle commands gate traffic through installation-owned routing storage but never delete those attachments unattended.
-
-If invoked without a concrete task, do a brief app status check and report:
-
-1. App type (`void`, `framework`, `spa`, `static`) using `docs/app-types.md` criteria.
-2. Backend feature usage (`routes/`, `pages/`, `middleware/`, `migrations/`, `crons/`, `queues/`, SSR entries).
-3. Runtime signals (`void/db`, `void/kv`, `void/storage`, queue usage).
-4. Auth signals (`void/auth`, `auth` client imports, OAuth env vars).
-5. Deployment platform and optional Void project linkage (`.void/project.json`), plus config readiness (`void.config.ts`, Cloudflare `account_id`, tsconfig extends).
-6. Optional health checks (`void account whoami`, `void db status` when relevant).
-
-Then ask what to do next.
+Use `void` and `@void/*` in imports, examples, and package manifests. Follow the
+project's existing framework and deployment destination.
 
 ## Task Routing
 
 | User intent                                | Docs file(s)                                                                              |
 | ------------------------------------------ | ----------------------------------------------------------------------------------------- |
 | CLI command syntax, flags, env vars        | `docs/reference/cli.md`                                                                   |
-| Initial setup, onboarding, first app       | `docs/guide/quickstart.md`, `docs/reference/cli.md`                                       |
+| Initial setup, onboarding, first app       | `docs/guide/quickstart.md`, `docs/reference/cli/setup.md`                                 |
 | App type detection and mode behavior       | `docs/guide/app-types.md`, `docs/reference/config.md`                                     |
 | Server/API routing and middleware          | `docs/guide/server-routing.md`, `docs/integrations/hono.md`                               |
 | Pages mode, loader/action, forms, layouts  | `docs/guide/pages-routing/*.md`, `docs/guide/type-safety.md`                              |
@@ -132,39 +32,54 @@ Then ask what to do next.
 | Authentication                             | `docs/guide/auth.md`, `docs/guide/env-vars.md`                                            |
 | Cloudflare runtime bindings and config     | `docs/integrations/cloudflare.md`, `docs/reference/config.md`, `docs/guide/env-vars.md`   |
 | AI inference (Workers AI, providers)       | `docs/guide/ai.md`                                                                        |
+| Durable State and WebSockets               | `docs/guide/durable-state.md`, `docs/guide/websockets.md`                                 |
+| Server-sent events and live streams        | `docs/guide/sse.md`, `docs/guide/live.md`                                                 |
+| Sandboxes                                  | `docs/guide/sandboxes.md`                                                                 |
+| Email                                      | `docs/guide/email.md`, then the matching guide under `docs/guide/email/`                  |
 | KV / storage / queues / cron jobs          | `docs/guide/kv.md`, `docs/guide/storage.md`, `docs/guide/queues.md`, `docs/guide/jobs.md` |
 | SSR and caching                            | `docs/guide/ssr.md`, `docs/guide/edge/*.md`                                               |
 | Rewrites, redirects, fallbacks             | `docs/guide/edge/rewrites.md`, `docs/guide/edge/redirects.md`, `docs/reference/config.md` |
 | Static site generation                     | `docs/guide/ssg.md`                                                                       |
-| Deployment and CI                          | `docs/guide/deployment.md`, `docs/reference/cli.md`                                       |
-| Install or maintain a company platform     | `docs/guide/self-hosted-platform.md`, `docs/reference/cli.md`                             |
+| Deployment and CI                          | `docs/guide/deployment.md`, `docs/reference/cli/deploy.md`                                |
+| Install or maintain a company platform     | `docs/guide/self-hosted-platform.md`, `docs/reference/cli/platform-installation.md`       |
 | Develop or deploy a platform fork          | `docs/guide/platform-development.md`, `docs/guide/self-hosted-platform.md`                |
-| Platform administration                    | `docs/guide/platform-administration.md`, `docs/reference/cli.md`                          |
-| Self-host deploy to own Cloudflare account | `docs/integrations/cloudflare.md`, `docs/reference/cli.md`                                |
-| Project status, deployment history         | `docs/reference/cli.md`                                                                   |
-| Cache purging                              | `docs/reference/cli.md`                                                                   |
-| Project logs, runtime errors               | `docs/reference/cli.md`                                                                   |
-| Secrets management (put/sync/delete)       | `docs/reference/cli.md`, `docs/guide/env-vars.md`                                         |
+| Platform administration                    | `docs/guide/platform-administration.md`, `docs/reference/cli/platform.md`                 |
+| Platform plans and account limits          | `docs/guide/platform/administration/plans.md`, `docs/reference/cli/platform-config.md`    |
+| Self-host deploy to own Cloudflare account | `docs/integrations/cloudflare.md`, `docs/reference/cli/deploy.md`                         |
+| Project status, deployment history         | `docs/reference/cli/project.md`                                                           |
+| Cache purging                              | `docs/reference/cli/project.md`                                                           |
+| Project logs, runtime errors               | `docs/reference/cli/project.md`                                                           |
+| Secrets management (put/sync/delete)       | `docs/reference/cli/secrets.md`, `docs/guide/env-vars.md`                                 |
 | Typed env vars (`defineEnv`, `env.ts`)     | `docs/guide/env-vars.md`                                                                  |
-| Custom domain setup                        | `docs/reference/cli.md`                                                                   |
-| Database status, reset, seed, export       | `docs/reference/cli.md`, `docs/guide/database.md`                                         |
-| Auth login/logout/whoami                   | `docs/reference/cli.md`                                                                   |
+| Custom domain setup                        | `docs/reference/cli/domains.md`                                                           |
+| Database status, reset, seed, export       | `docs/reference/cli/database.md`, `docs/guide/database.md`                                |
+| Auth login/logout/whoami                   | `docs/reference/cli/auth.md`                                                              |
 | Overview / introduction                    | `docs/guide/index.md`                                                                     |
 | API surface details                        | `docs/reference/api.md`                                                                   |
 | Meta framework integration                 | `docs/integrations/frameworks/*.md`                                                       |
 | Coding agent setup                         | `docs/integrations/agents.md`                                                             |
 | Node.js / Bun / Deno targets               | `docs/integrations/nodejs-bun-deno.md`                                                    |
-| ORMs and external databases                | `docs/integrations/orms-and-external-dbs.md`                                              |
+| ORMs and external databases                | `docs/guide/database.md`                                                                  |
 | Project structure and conventions          | `docs/reference/structure.md`                                                             |
 | Resource/binding inference                 | `docs/reference/resource-inference.md`                                                    |
 
-## Working Rules
-
-- For any task involving running `void` commands — including checking status, managing secrets, viewing logs, or deploying — open `docs/reference/cli.md` FIRST. Do not guess command syntax.
-- Never guess or infer `void` CLI command names or flags. Always consult `docs/reference/cli.md` for the exact command before running it.
-- For multi-topic tasks, combine only the needed doc files.
-- If docs and memory differ, follow docs.
-- For Void-managed auth, `void db generate` automatically includes the production Better Auth schema in the generated migration, including configured model/field renames and plugin tables. Keep those migrations under `db/migrations/`; do not duplicate generated auth tables in the application Drizzle schema.
-- **Env vars:** When the project has `env.ts`, the canonical access pattern is `import { env } from "void/env"`. Declare every env key in `env.ts` via `defineEnv({...})` so values are typed and validated. Do not introduce ad-hoc `process.env.X` or untyped `c.env.X` access in new code — add the key to `env.ts` first.
-
-For platform email domains, use `void email domain add` with an account- and zone-scoped Cloudflare API token. Read inbound, outbound, and management readiness separately; `domain sync` reconciles without rotating secrets. Use a stable `sendEmail({ idempotencyKey })` for retryable sends and inspect `void email logs` when the result is `OUTCOME_UNKNOWN`; never retry an uncertain send with a new key. Administrators can inspect retained outcomes with `void platform email logs <project-id|slug> --json`; use the project ID after deletion. Native Cloudflare email setup remains `void email setup --platform cloudflare` and does not support platform idempotency keys.
+## Working rules
+
+- Read the relevant guide before changing configuration, persistent resources,
+  authentication, or deployment workflows. The guides define current behavior;
+  avoid copying a second set of instructions into this skill.
+- Before moving deployed Durable State or WebSocket definitions, read their
+  guides and use `void info` to preserve resource names and instance keys.
+- Declare application environment keys in `env.ts` and access them through
+  `void/env`; follow `docs/guide/env-vars.md` for local and production values.
+- For platform setup, follow the pages linked from
+  `docs/guide/self-hosted-platform.md`. For recovery, use its documented resume
+  or repair workflow and preserve the installation's credentials and resources.
+- Use `--plan` to review platform changes. If an operation has an uncertain
+  outcome, inspect its status and events before retrying.
+
+If the user invokes this skill without a task, inspect the app's local structure,
+configuration, and saved deployment destination, give a brief status, and ask
+what they want to work on.
+
+For AI and Sandbox operations, use `.match({ ok, limited })` and choose a useful quota fallback. In Pages, prefer the adapter’s `Form` with `useForm()` so action failures remain visible and entered data is preserved. See `docs/guide/ai.md`, `docs/guide/sandboxes.md`, and `docs/guide/pages-routing/actions-and-forms.md`.

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

@@ -10,6 +10,14 @@ Void provides a typed AI client for Workers AI and Cloudflare's [AI Gateway](htt
 import { ai } from 'void/ai';
 ```
 
+## Handling usage limits
+
+Every AI operation is lazy and must be executed with `.match({ ok, limited })`. Both handlers are required, including for provider-native requests, model listing and document conversion. Return a useful fallback from `limited`, or use `limit.response({ message: 'AI is temporarily unavailable.' })` to send a structured HTTP 429. Limits expose `resource`, `reason`, and an optional `retryAt`. Other failures still reject.
+
+Do not await the operation itself; await its `.match()` call. TypeScript checks your handlers and the resulting success/fallback union.
+
+Streaming responses end with a `void:error` SSE event if generation is interrupted after the response starts. A recognized quota interruption calls your `limited` handler and emits `void:limit`, preserving the message from `limit.response()`. `fetchStream()` throws on either terminal event so your UI can exit its generating state. This also applies to streaming provider responses and `ai.run()` with `stream: true`.
+
 ## Basic Usage
 
 Call `ai.run()` with a model name and inputs. Model names and input types are fully typed from `@cloudflare/workers-types`.
@@ -21,9 +29,11 @@ import { ai } from 'void/ai';
 export const POST = defineHandler(async (c) => {
   const { prompt } = await c.req.json();
 
-  const result = await ai.run('@cf/meta/llama-3.3-70b-instruct-fp8-fast', {
-    messages: [{ role: 'user', content: prompt }],
-  });
+  const result = await ai
+    .run('@cf/meta/llama-3.3-70b-instruct-fp8-fast', {
+      messages: [{ role: 'user', content: prompt }],
+    })
+    .match({ ok: (result) => result, limited: (limit) => limit.response() });
 
   return c.json(result);
 });
@@ -42,23 +52,27 @@ import { ai } from 'void/ai';
 export const POST = defineHandler(async (c) => {
   const { prompt } = await c.req.json();
 
-  return ai.stream('@cf/meta/llama-3.3-70b-instruct-fp8-fast', {
-    messages: [{ role: 'user', content: prompt }],
-  });
+  return ai
+    .stream('@cf/meta/llama-3.3-70b-instruct-fp8-fast', {
+      messages: [{ role: 'user', content: prompt }],
+    })
+    .match({ ok: (result) => result, limited: (limit) => limit.response() });
 });
 ```
 
-`ai.stream()` calls `ai.run()` with `stream: true` and wraps the result in a `Response` with `content-type: text/event-stream` and `cache-control: no-cache` headers.
-
 ## Listing Models
 
 Use `ai.models()` to list available models:
 
 ```ts
-const models = await ai.models();
+const models = await ai
+  .models()
+  .match({ ok: (result) => result, limited: (limit) => limit.response() });
 
 // Filter by task
-const textModels = await ai.models({ task: 'Text Generation' });
+const textModels = await ai
+  .models({ task: 'Text Generation' })
+  .match({ ok: (result) => result, limited: (limit) => limit.response() });
 ```
 
 ## Markdown Conversion
@@ -66,7 +80,9 @@ const textModels = await ai.models({ task: 'Text Generation' });
 Use `ai.toMarkdown()` to convert documents to markdown:
 
 ```ts
-const result = await ai.toMarkdown([{ name: 'document.pdf', blob: pdfBytes }]);
+const result = await ai
+  .toMarkdown([{ name: 'document.pdf', blob: pdfBytes }])
+  .match({ ok: (result) => result, limited: (limit) => limit.response() });
 ```
 
 ## Local Development
@@ -80,12 +96,11 @@ npm run dev
 
 When the app imports `void/ai`, Void enables a remote Workers AI binding during
 development and preview. Requests use your Cloudflare account and its allowance;
-Workers AI has no local simulator. The session uses the same keychain-backed
-Cloudflare login as the CLI, or `CLOUDFLARE_API_TOKEN` in an automated environment.
+Workers AI has no local simulator. Use your Cloudflare login or
+`CLOUDFLARE_API_TOKEN` in an automated environment.
 
 For a team platform, use `void connect <platform-url>` and link your project.
-Development requests use that platform's HTTPS proxy and usage controls.
-Credentials are injected into server bindings automatically.
+Development requests use that platform's account and usage limits.
 
 ## Usage Limits
 
@@ -93,55 +108,54 @@ Workers AI usage is measured in [neurons](https://developers.cloudflare.com/work
 On a direct deployment, usage belongs to your Cloudflare account. Provider-native
 requests also use your provider credentials and their billing terms.
 
-A team platform tracks usage in its own account and can apply per-user limits.
-Fresh self-hosted installations assign the `custom` profile, which has no
-platform-imposed AI allowance. Administrators can select a quota profile through
-[Platform Administration](./platform-administration.md). These profiles do not
-subscribe users to a commercial plan or charge them automatically; the operator
-remains responsible for its infrastructure and provider accounts.
+A team platform uses its own Cloudflare account and may apply per-user limits. Ask your administrator about the available allowance.
 
 ## Cloudflare Gateway Models
 
 `ai.run()` mirrors Cloudflare's `env.AI.run()` model naming and input schemas. Third-party models use Cloudflare model IDs and Cloudflare-managed credentials.
 
 ```ts
-const result = await ai.run('google/gemini-2.5-flash', {
-  contents: [
-    {
-      role: 'user',
-      parts: [{ text: 'Explain Durable Objects in one paragraph.' }],
-    },
-  ],
-});
+const result = await ai
+  .run('google/gemini-2.5-flash', {
+    contents: [
+      {
+        role: 'user',
+        parts: [{ text: 'Explain Durable Objects in one paragraph.' }],
+      },
+    ],
+  })
+  .match({ ok: (result) => result, limited: (limit) => limit.response() });
 ```
 
 OpenAI-compatible models use OpenAI-style `messages`:
 
 ```ts
-const result = await ai.run('openai/gpt-4.1-mini', {
-  messages: [{ role: 'user', content: 'Summarize this deploy.' }],
-});
+const result = await ai
+  .run('openai/gpt-4.1-mini', {
+    messages: [{ role: 'user', content: 'Summarize this deploy.' }],
+  })
+  .match({ ok: (result) => result, limited: (limit) => limit.response() });
 ```
 
 Pass Cloudflare AI Gateway options as the third argument:
 
 ```ts
-const result = await ai.run(
-  'openai/gpt-4.1-mini',
-  {
-    messages: [{ role: 'user', content: 'Summarize this deploy.' }],
-  },
-  {
-    gateway: {
-      skipCache: true,
+const result = await ai
+  .run(
+    'openai/gpt-4.1-mini',
+    {
+      messages: [{ role: 'user', content: 'Summarize this deploy.' }],
+    },
+    {
+      gateway: {
+        skipCache: true,
+      },
     },
-  },
-);
+  )
+  .match({ ok: (result) => result, limited: (limit) => limit.response() });
 ```
 
-Managed requests use the installation's gateway and project metadata. Direct
-requests use your Workers AI binding; provider-native requests require your own
-`ai.gateway` configuration.
+For provider-native requests on a direct deployment, configure [`ai.gateway`](../integrations/cloudflare.md#ai-self-host).
 
 ## Provider-Native Requests
 
@@ -159,13 +173,16 @@ import { ai } from 'void/ai';
 export const POST = defineHandler(async (c) => {
   const { prompt } = await c.req.json();
 
-  const response = await ai.provider('openai').fetch('/chat/completions', {
-    body: {
-      model: 'gpt-4o',
-      messages: [{ role: 'user', content: prompt }],
-      max_tokens: 512,
-    },
-  });
+  const response = await ai
+    .provider('openai')
+    .fetch('/chat/completions', {
+      body: {
+        model: 'gpt-4o',
+        messages: [{ role: 'user', content: prompt }],
+        max_tokens: 512,
+      },
+    })
+    .match({ ok: (result) => result, limited: (limit) => limit.response() });
 
   const result = await response.json();
   return c.json(result);
@@ -186,7 +203,8 @@ const response = await ai
         },
       ],
     },
-  });
+  })
+  .match({ ok: (result) => result, limited: (limit) => limit.response() });
 
 const result = await response.json();
 ```
@@ -204,7 +222,8 @@ const response = await ai
   })
   .fetch('/v1/respond', {
     body: { prompt: 'Hello' },
-  });
+  })
+  .match({ ok: (result) => result, limited: (limit) => limit.response() });
 ```
 
 ### Image Generation
@@ -214,38 +233,45 @@ Use `ai.run()` or `ai.image()` for Cloudflare-native image models:
 ```ts
 export const POST = defineHandler(async (c) => {
   const { prompt } = await c.req.json();
-  return ai.image('@cf/black-forest-labs/flux-1-schnell', { prompt });
+  return ai
+    .image('@cf/black-forest-labs/flux-1-schnell', { prompt })
+    .match({ ok: (result) => result, limited: (limit) => limit.response() });
 });
 ```
 
-Use `ai.provider().fetch()` for provider-native image APIs:
+Use `ai.provider().fetch()` for provider-native image APIs. Match the [provider's request schema](https://developers.openai.com/api/reference/resources/images/methods/generate):
 
 ```ts
 export const POST = defineHandler(async (c) => {
   const { prompt } = await c.req.json();
 
-  return ai.provider('openai').fetch('/images/generations', {
-    body: {
-      model: 'gpt-image-1.5',
-      prompt,
-      size: '1024x1024',
-      response_format: 'b64_json',
-    },
-  });
+  return ai
+    .provider('openai')
+    .fetch('/images/generations', {
+      body: {
+        model: 'gpt-image-2.5-sunburst',
+        prompt,
+        size: '1024x1024',
+      },
+    })
+    .match({ ok: (result) => result, limited: (limit) => limit.response() });
 });
 ```
 
-For multipart provider APIs, pass a `FormData` body. Void serializes the body through the proxy and reconstructs it before forwarding to AI Gateway:
+For multipart provider APIs, pass `FormData`:
 
 ```ts
 export const POST = defineHandler(async (c) => {
   const body = await c.req.parseBody();
   const form = new FormData();
-  form.set('model', 'gpt-image-1.5');
+  form.set('model', 'gpt-image-2.5-sunburst');
   form.set('prompt', String(body.prompt));
   form.set('image', body.image as Blob, 'source.png');
 
-  return ai.provider('openai').fetch('/images/edits', { body: form });
+  return ai
+    .provider('openai')
+    .fetch('/images/edits', { body: form })
+    .match({ ok: (result) => result, limited: (limit) => limit.response() });
 });
 ```
 
@@ -290,22 +316,6 @@ For local development, add it to `.env` in your project root:
 OPENAI_API_KEY=sk-...
 ```
 
-If the key is missing at runtime, `ai.provider().fetch()` throws a descriptive error telling you which env var to set.
-
 ### Streaming with Provider-Native APIs
 
-Provider-native streaming APIs return the provider response directly:
-
-```ts
-export const POST = defineHandler(async (c) => {
-  const { prompt } = await c.req.json();
-
-  return ai.provider('openai').fetch('/chat/completions', {
-    body: {
-      model: 'gpt-4o',
-      messages: [{ role: 'user', content: prompt }],
-      stream: true,
-    },
-  });
-});
-```
+Return the provider response directly. For example, add `stream: true` to the OpenAI request body shown above.

package/skills/void/docs/guide/app-types.md

@@ -16,27 +16,16 @@ The type is auto-detected from your project structure, or you can set it explici
 
 In a Void app, Void handles server routing and deployment. Use React, Vue, Svelte, or Solid for server-rendered pages, or build a frontend with any library that works with Vite.
 
-All Void features that involve backend logic are available in this mode, including [server routing](./server-routing.md), [pages mode](./pages-routing/overview.md), [authentication](./auth.md), [typed fetch](./typed-fetch.md), [cron jobs](./jobs.md), and [queues](./queues.md).
-
 A Void app can be **API-only** (just `routes/`), a **SPA + API** (frontend in `src/` with API routes), or **full-stack with pages mode** (server-rendered pages in `pages/` with co-located data loading):
 
 <VoidAppFileTree annotations />
 
-Your worker handles API routes, page rendering, and (optionally) [custom SSR](./ssr.md). Static assets are served from the edge via per-worker assets. Cloudflare bindings (D1, KV, R2) are [inferred from your source code](../reference/resource-inference.md) and provisioned automatically.
+Void serves API routes, page rendering, and optional [custom SSR](./ssr.md) alongside static assets. Resources such as D1, KV, and R2 are [inferred from your code](../reference/resource-inference.md) and provisioned when you deploy.
 
 Void apps can also use [`output: 'static'`](./ssg.md) to pre-render all pages at build time. That gives you a fully static site that can be deployed anywhere, with no Cloudflare Worker required.
 
 **Deploy:** `void deploy` builds the app, provisions resources, applies migrations, and uploads it to your saved Cloudflare or Void target. See [Deployment](./deployment.md) for setup.
 
-**Detected when any of these exist:**
-
-- `routes/` directory
-- `pages/` directory
-- `middleware/` directory
-- `crons/` directory
-- `queues/` directory
-- Custom SSR entry (`src/main.ssr.ts` or `src/main.ssr.tsx`)
-
 ## Meta Frameworks
 
 Void supports deploying Vite-based meta-framework apps with `void deploy`. The framework owns routing and SSR. Void handles [binding inference](../reference/resource-inference.md), [typed DB queries](./database.md), migrations, and deployment.
@@ -50,15 +39,11 @@ Void supports deploying Vite-based meta-framework apps with `void deploy`. The f
 | [Analog](https://analogjs.org/)                     | `@analogjs/platform`    | [Guide](../integrations/frameworks/analog.md)         |
 | [Astro](https://astro.build/)                       | `astro`                 | [Guide](../integrations/frameworks/astro.md)          |
 
-Add `voidPlugin()` to the framework's Vite config to get binding inference, typed DB generation, migration management, cron jobs, queues, and caching. Void-managed auth is not supported in framework mode; use Better Auth's official integration for your framework. See the [Meta Frameworks Integration](../integrations/frameworks/overview.md) for the full feature matrix, deploy pipeline, and per-framework setup guides.
-
-**Deploy:** `void deploy` runs your framework's build, provisions resources, applies migrations, and deploys to the selected target. Your framework continues to handle routing and rendering.
-
-**Detected when** any of the above packages is in your dependencies.
+Add `voidPlugin()` to the framework's Vite config to get binding inference, typed DB generation, migration management, cron jobs, queues, and caching. Void-managed auth is not supported in framework mode; use Better Auth's official integration for your framework. See the [Meta Frameworks Integration](../integrations/frameworks/overview.md) for supported features and setup guides.
 
 ## Pre-built Static Sites
 
-Any project that produces static files, whether that is an SPA, a static site, or a plain directory. Assets are served directly from the edge, and a minimal passthrough worker is generated automatically. You do not need to write worker code yourself.
+Any project that produces static files, whether that is an SPA, a static site, or a plain directory. Void serves the assets without requiring application code.
 
 **SPAs** (client-side single-page apps) fall back all non-file paths to `index.html` with a 200 status, so client-side routing works out of the box. Detected when `vite` is a dependency and no backend files exist.
 
@@ -116,20 +101,6 @@ To deploy only the static output, set:
 { "inference": { "appType": "static" } }
 ```
 
-## Auto-Detection
-
-When running `void deploy` and no `inference.appType` is set in `void.config.ts`, the detection logic runs in this order:
-
-| Priority | Condition                                                                                                       | Type                                        |
-| -------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
-| 1        | `--dir` flag                                                                                                    | Static (or SPA with `--spa`)                |
-| 2        | Known SSG in dependencies (`vitepress`, `@docusaurus/core`)                                                     | Static, builds with SSG CLI                 |
-| 2a       | ...and backend files also exist                                                                                 | Refused — set `inference.appType` yourself  |
-| 3        | `@tanstack/react-start`, `@react-router/dev`, `@sveltejs/kit`, `nuxt`, `@analogjs/platform`, or `astro` in deps | Framework                                   |
-| 4        | Backend files exist (`routes/`, `pages/`, `middleware/`, `crons/`, `queues/`, SSR entry)                        | Void app                                    |
-| 5        | `vite` or `vite-plus` in dependencies, no backend files                                                         | SPA, builds with `vite build` or `vp build` |
-| 6        | `dist/index.html` or `./index.html` exists                                                                      | Static (no build step)                      |
-
 ## Explicit Configuration
 
 To lock the app type and skip auto-detection, set `inference.appType` in [`void.config.ts`](../reference/config.md):