void 0.10.12 → 0.20.0

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

@@ -0,0 +1,235 @@
+---
+outline: deep
+---
+
+# Developing a Void Platform
+
+The framework, CLI, and platform live in one repository. You can change the platform, test it locally, and deploy a runtime built from your fork into your own Cloudflare account.
+
+If you want to run the released platform without changing its implementation, start with [Install a Void Platform](./self-hosted-platform.md). Use [Platform Administration](./platform-administration.md) for managing an installed platform.
+
+## Setting Up the Repository
+
+Clone your fork and install the workspace dependencies with Vite+:
+
+```sh
+git clone https://github.com/your-org/void.git
+cd void
+vp install
+vpr install:void-dev
+void-dev --help
+```
+
+Use the Node.js version recorded in `.node-version`. The workspace uses public npm packages; a GitHub Packages token is not required.
+
+`install:void-dev` builds the CLI, shared packages, and platform runtime, then makes this checkout's built CLI globally available as `void-dev`. Public packages export their built files, so run `vp run build:core` after later source changes to refresh the alias. The installer refuses to replace an unrelated global command. Remove only this checkout's alias with `vpr uninstall:void-dev`. All commands in this guide run from the repository root.
+
+## Finding the Implementation
+
+| Directory                                            | Purpose                                                              |
+| ---------------------------------------------------- | -------------------------------------------------------------------- |
+| `packages/void`                                      | Framework, application runtime, and CLI                              |
+| `packages/platform`                                  | Installer contracts, packaged Workers, and platform migrations       |
+| `packages/deploy-core`, `packages/deploy-cloudflare` | Shared deployment contracts and Cloudflare upload code               |
+| `platform/packages/api`                              | Users, projects, deployments, provisioning, and administrator API/UI |
+| `platform/packages/dispatch`                         | Application routing and static assets                                |
+| `platform/packages/proxy`                            | AI, remote bindings, and revalidation                                |
+| `platform/packages/tail`                             | Runtime log ingestion                                                |
+| `platform/packages/dashboard`                        | Dashboard source and local UI components in `ui/`                    |
+
+The `@voidcloud/*` names identify workspace implementation packages. Their `private: true` flags prevent publishing those packages to npm. Deployable core Workers are bundled into the public `@void/platform` package.
+
+The core installer creates the API, dispatch, proxy, and tail Workers. The dashboard and managed GitHub build services are available in the source tree but are not included in that installation. Adding an optional service requires its infrastructure, bindings, authentication, and capability configuration together.
+
+## Running the API Locally
+
+Start a local PostgreSQL server and make `psql` and `pg_isready` available on your path. Then create the development database, apply its migrations, and seed an administrator:
+
+```sh
+vp run --filter @voidcloud/api setup --admin-email dev@example.com
+vp run --filter @voidcloud/api dev --local --enable-containers=false --host localhost --port 8787
+```
+
+The command disables the optional build containers, so basic API and admin work
+does not require Docker. To develop managed builds, install Docker and run the
+API with containers enabled.
+
+Open `http://localhost:8787/admin/`. Setup writes local development values to the API and dashboard `.dev.vars` files, including the development authentication bypass and local database connection. Those files are ignored by Git. Production installations get separate credentials through the installer.
+
+The API's development bypass lets you work on the browser admin UI without setting up OAuth. Operator CLI sessions still require administrator authentication; they do not use the browser bypass.
+
+## Running the Dashboard Locally
+
+The dashboard is a separate source app. After API setup, start it in another terminal:
+
+```sh
+vp run --filter @voidcloud/dashboard dev
+```
+
+Its local `.dev.vars` should point to the API you started:
+
+```dotenv
+API_URL=http://localhost:8787
+SITE_DOMAIN=apps.example.com
+```
+
+Open the Vite URL and choose **Dev login (local API)**. That button appears for a localhost API and uses the local development sign-in endpoint.
+
+You can also point the dashboard at an API that you operate. If Cloudflare Access protects that API, install `cloudflared` and opt into the dashboard's local token helper with matching origins:
+
+```dotenv
+API_URL=https://platform.example.com
+CF_ACCESS_APP_URL=https://platform.example.com
+SITE_DOMAIN=apps.example.com
+```
+
+The helper refreshes an Access session before the dev server starts. A configured `CF_ACCESS_CLIENT_ID` and `CF_ACCESS_CLIENT_SECRET` pair can be used for automation instead. This is dashboard development configuration; Access credentials are separate from platform login credentials.
+
+## Testing Changes
+
+Run tests for the area you changed while developing:
+
+```sh
+vp test run platform/packages/api/test/integration/operator-auth.test.ts
+vp run check
+```
+
+Before preparing a release, build the packages and run the complete checks:
+
+```sh
+vp run build:all
+vp run check
+vp lint
+vp run lint:platform
+vp fmt --check
+vp test run
+vp run build:docs
+```
+
+Platform integration tests use their local test database by default. To test against PostgreSQL, set `VOID_TEST_DATABASE_URL` to a disposable database: these tests clear tables between cases.
+
+To exercise a deployed application, deploy a disposable copy of `playground/kitchen-sink` and pass its URL as `SMOKE_URL` to the smoke test described in `platform/scripts/kitchen-sink-smoke-test.md`. That test creates and removes application data.
+
+## Deploying Your Runtime
+
+Build the runtime. From a Git checkout, the build automatically records the current commit in the runtime manifest. An uncommitted checkout is recorded with a `-dirty` suffix:
+
+```sh
+vp run build:core
+```
+
+Build systems may set `VOID_PLATFORM_SOURCE_REVISION` when they need to override automatic detection with another immutable revision. A source archive without Git metadata builds normally but leaves the revision unrecorded.
+
+The runtime is written to `packages/platform/dist/runtime`. Use the built CLI to preview a new installation from those files:
+
+```sh
+void-dev platform install \
+  --name my-team \
+  --application-domain example.app \
+  --zone example.app \
+  --runtime packages/platform/dist/runtime \
+  --plan
+```
+
+Before applying the plan, complete the [first-install walkthrough](./self-hosted-platform.md). Run the command without `--plan` to install. For testing before your domain is ready, replace `--application-domain` and `--zone` with `--workers-dev`; PostgreSQL and the runtime/GitHub/R2 credentials are still needed. Use `void-dev` in place of `void` and keep `--runtime packages/platform/dist/runtime` on install and resume commands. For an interrupted installation, keep that runtime build available until it completes.
+
+Later, run `void-dev platform domain set example.app`. Domain setup uses the existing installed runtime and needs no `--runtime`, rebuild, or app redeploy. It keeps the platform API URL and original workers.dev app URLs available.
+
+For an existing installation, preview an upgrade using its connection ID:
+
+```sh
+void-dev platform upgrade <installation-id> \
+  --runtime packages/platform/dist/runtime --plan
+```
+
+Then run it without `--plan` to apply the upgrade. Source-built runtimes go through the same artifact, database, ownership, and health checks as released runtimes. The CLI preserves a disabled installation's state and records the source revision in its installation checkpoint.
+
+## Deploying Source Builds from CI {#source-build-ci}
+
+Build `@void/platform` from your checkout and pass its runtime directory to `install`, `upgrade`, `repair`, `enable`, or `rollback` with `--runtime`. Custom runtimes get the same integrity, migration, health, and rollback checks as packaged releases.
+
+Void records the runtime's manifest digest, whether it was packaged or custom, and its source revision. A build from a Git checkout automatically records `HEAD`, or `<HEAD>-dirty` when the checkout has uncommitted files. Build systems can set `VOID_PLATFORM_SOURCE_REVISION` to override automatic detection.
+
+A fresh CI runner can discover the installation each time. Set `CLOUDFLARE_API_TOKEN` and `VOID_PLATFORM_DATABASE_URL` through its protected environment, then:
+
+::: details CI commands and recovery inputs
+
+```sh
+vp run build:core
+
+export VOID_PLATFORM_REGISTRY_DIR="$RUNNER_TEMP/void-platform-registry"
+export VOID_PLATFORM_RECOVERY_KEY="$(openssl rand -base64 32)"
+node packages/void/dist/cli/cli.mjs platform discover --account "$CLOUDFLARE_ACCOUNT_ID" \
+  --installation "$VOID_PLATFORM_INSTALLATION"
+node packages/void/dist/cli/cli.mjs platform upgrade "$VOID_PLATFORM_INSTALLATION" \
+  --runtime packages/platform/dist/runtime --plan
+node packages/void/dist/cli/cli.mjs platform upgrade "$VOID_PLATFORM_INSTALLATION" \
+  --runtime packages/platform/dist/runtime --yes
+```
+
+Omit the installation selector only if the account has one discoverable installation. Run one deployment per installation at a time, and let it finish before starting the next. Cancelling during migrations or Worker rollout can leave an installation waiting for recovery.
+
+Keep the management token, database URL, JWT signing secret, and complete project-encryption keyring in a protected CI environment. Upgrades inherit deployed Worker secrets. The original values are needed when recreating a missing Worker; configuration credentials are also needed when explicitly rotating them.
+
+:::
+
+## Changing the Platform Schema
+
+The schema lives in `platform/packages/api/src/schema.ts`. Generate a migration after changing it:
+
+```sh
+vp run --filter @voidcloud/api db:generate
+```
+
+Review the generated SQL and migration journal before committing them. Released migrations are append-only. An upgrade applies new migrations while the previous Workers may still serve requests, so schema changes must remain compatible with that code.
+
+`platform/packages/api/drizzle/compatibility.json` records which earlier runtimes have been verified against the new schema. Add an edge only after testing that compatibility. The runtime build checks that the migration files and recorded schema history agree. See `packages/platform/README.md` for the manifest contract.
+
+## CI in a Fork
+
+The uncredentialed test workflows use GitHub-hosted runners in forks. They build and test the workspace without requiring Void Cloud accounts, tokens, or deployment access.
+
+If your fork has a released platform version, set the repository variable
+`VOID_PLATFORM_PRODUCTION_REF` to its immutable 40-character commit SHA. Platform
+pull requests then create that version's database, seed representative user,
+project, and encrypted-secret records, and apply the proposed migrations. The
+check verifies existing data and runs the previous runtime against the upgraded
+schema. Mutable branch or tag names are rejected.
+
+Without an explicit SHA, required compatibility checks use the latest successful
+GitHub deployment to `Prod` (or `VOID_PLATFORM_PRODUCTION_ENV`). They require
+read access to deployment history and stop if no completed deployment is found.
+Advancing the production branch does not change the selected baseline. Fork
+workflows that call platform CI must grant `deployments: read` alongside
+`contents: read`.
+
+The upstream repository also contains workflows for deploying Void Cloud and publishing the official npm packages. Forks should configure their own release workflow around the built CLI and `platform upgrade --runtime`; the [source-build CI example](#source-build-ci) shows the required inputs. Keep production credentials in protected environments restricted to the appropriate release refs.
+
+Public releases use matching versions for the CLI, scaffolder, adapters, and
+packaged platform. The publish workflow rejects mismatched versions and previously
+unpublished `void` versions that npm cannot reuse. Stable versions use `latest`;
+prereleases use their named channel, such as `beta` or `rc`. Numeric prereleases
+use `next`. The scaffolder installs its exact matching CLI version, so
+`create-void@beta` cannot silently select the stable CLI. Packaged platform
+runtimes record the release commit as their source revision.
+
+The npm release job uses [trusted publishing](https://docs.npmjs.com/trusted-publishers/)
+from GitHub-hosted runners, with `id-token: write` and no stored npm publishing
+token. Configure a trusted publisher for each public package using this
+repository, `publish.yml`, and the `Release` environment, allowing direct
+`npm publish`. A brand-new package
+needs an initial authenticated publication before its trusted publisher can be
+configured; subsequent releases use OIDC.
+
+The managed build fallback CLI also derives its version from
+`packages/void/package.json`; there are no separate version pins to update.
+Build its image from the repository root with
+`docker build --file platform/packages/api/container/Dockerfile .`.
+The root `.dockerignore` limits that build context to the agent, Dockerfile,
+and public SDK manifest.
+
+Publishing requires both SDK CI and platform CI, including the platform unit and
+API integration suites. Release tags also run the Windows SDK checks; a passing
+SDK-only build cannot publish a changed control plane.
+
+For implementation history, use the design archive at `platform/meta/design-docs/README.md`. Its proposals explain earlier decisions; the source and current guides define the supported behavior.

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

@@ -4,17 +4,17 @@ outline: deep
 
 # Queues
 
-Void supports Cloudflare Queues for asynchronous message processing from a top-level `queues/` directory.
+Use queues to process work asynchronously, such as sending emails or handling uploads. Define a consumer in `queues/`, then send it typed messages from your app.
 
 ## Defining queues
 
-Create files in `queues/**/*.ts`; `.mts`, `.js`, and `.mjs` also work. The queue name is inferred from the filename. For example, `queues/emails.ts` creates a queue named `"emails"`, and `queues/order/notifications.ts` creates `"order/notifications"`.
+Create files in `queues/**/*.ts`; `.mts`, `.js`, and `.mjs` also work. The queue name is inferred from its path, with nested path segments joined by `-`. For example, `queues/emails.ts` creates a queue named `"emails"`, and `queues/order/notifications.ts` creates `"order-notifications"`. A nested path must not normalize to the same name as another file: `queues/order/notifications.ts` and `queues/order-notifications.ts` conflict, so Void reports the collision and asks you to rename one.
 
-::: warning Nested files produce a name that cannot be deployed
-Cloudflare queue names allow only letters, digits and `-`, so a name containing `/` is rejected when the queue is provisioned — on both the managed platform and a self-hosted `--backend cloudflare` deploy. Nested files work in local development, but keep queue files flat (`queues/order-notifications.ts` → `"order-notifications"`) for any app you intend to deploy.
-:::
+The resulting name must follow Cloudflare's queue naming rules: 1–63 characters, only letters, digits, and `-`, beginning and ending with a letter or digit.
 
-Each queue file should export a default handler wrapped with [`defineQueue`](../reference/api.md#definequeuet-handler). The generic `<T>` parameter defines the message body type. That is the type of each `msg.body` in the batch, and it is also used by the typed `queues` proxy for `send()` calls.
+If you previously used a nested queue locally, update producer calls from `queues['order/notifications']` to `queues['order-notifications']`. The derived binding remains `QUEUE_ORDER_NOTIFICATIONS`.
+
+Each queue file should export a default handler wrapped with [`defineQueue`](../reference/api.md#definequeue-t-handler). The generic `<T>` parameter defines the message body type. That is the type of each `msg.body` in the batch, and it is also used by the typed `queues` proxy for `send()` calls.
 
 ```ts
 // queues/emails.ts
@@ -56,7 +56,7 @@ export const POST = defineHandler(async (c) => {
 });
 ```
 
-The binding name is derived automatically: `QUEUE_` + queue name uppercased with non-alphanumeric characters replaced by `_`. For example, `queues/emails.ts` creates binding `QUEUE_EMAILS`.
+The binding name is derived automatically: `QUEUE_` + queue name uppercased with non-alphanumeric characters replaced by `_`. For example, `queues/emails.ts` creates binding `QUEUE_EMAILS`, while `queues/order/notifications.ts` creates binding `QUEUE_ORDER_NOTIFICATIONS`.
 
 ## Per-message acknowledgment
 
@@ -120,7 +120,7 @@ On deploy, Void includes all discovered queues in the deploy manifest. The platf
 
 ## Local development
 
-In **default Void mode**, Miniflare delivers queue batches natively — produce a message via the binding and the consumer fires automatically. The worker's `queue()` export serializes the batch and routes it to the same internal `/__queue` handler used in production, so behavior is consistent across environments.
+In native Void apps, sending a message through a queue binding automatically invokes the consumer in Miniflare. Local delivery uses the same handler as production.
 
 You can also manually dispatch a batch by POSTing to the dev endpoint Void exposes:
 
@@ -139,6 +139,6 @@ curl -X POST http://localhost:5173/__void/queue \
   -d '{"queue":"my-queue","messages":[{"id":"1","timestamp":'"$(date +%s000)"',"body":{"hello":"world"},"attempts":1}]}'
 ```
 
-If you set `__VOID_PROXY_TOKEN` in `.dev.vars`, that explicit token takes precedence and the printed curl command uses `x-void-internal: <your-token>` instead.
+If you set `__VOID_PROXY_TOKEN` in `.env`, that explicit token takes precedence and the printed curl command uses `x-void-internal: <your-token>` instead.
 
-In **framework mode** (SvelteKit, Nuxt, Analog, Astro, TanStack Start, React Router, vinext), the `/__void/queue` endpoint runs inside the framework adapter's request pipeline (or the dev miniflare for Class A frameworks), so the consumer sees whatever bindings the adapter exposes (D1, KV, R2, queue producers, etc.). Native Miniflare queue delivery is not wired up in framework mode — use the manual dispatch endpoint to exercise a consumer.
+In supported meta-frameworks, use `/__void/queue` to test a consumer manually. It runs inside the framework adapter's development runtime with that adapter's bindings. Sending to a queue binding doesn't automatically invoke the consumer in this mode.

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

@@ -4,39 +4,47 @@ outline: deep
 
 # Quickstart
 
+Let's create a Void app, run it locally, and deploy it. You can start in an empty directory or [add Void to an existing Vite app](#adding-to-an-existing-vite-app).
+
+Use Node.js 24.21.0 or later. New projects pin the SDK's tested Workers
+compatibility date, so the bundled local runtime can start them. An existing
+compatibility date in your project is preserved.
+
 ## Start in an Empty Directory
 
-Install the Void CLI from npm:
+Install Void in your project directory:
 
-`npm`
+::: code-group
 
-```sh
+```sh [npm]
 npm install -D void
 ```
 
-`pnpm`
-
-```sh
+```sh [pnpm]
 pnpm add -D void
 ```
 
-`yarn`
-
-```sh
+```sh [yarn]
 yarn add -D void
 ```
 
-`bun`
-
-```sh
+```sh [bun]
 bun add -D void
 ```
 
-In an empty directory, `void init` adds the matching Pages adapter and starter dependencies after you choose a scaffold toolchain and framework. Vite+ is the default toolchain and uses `vp` scripts.
+:::
+
+Then run the setup command:
 
-As part of `void init`, you'll choose Vite+ or plain Vite, then a Pages framework (React, Vue, Svelte, or Solid) and a starter type. D1 is the default top option and scaffolds a DB-backed page loader, schema, generated migration, `db/seed.ts`, and API route. PostgreSQL scaffolds the same starter and writes `"database": "pg"` to `void.json`. Static Pages skips the database and server starter files so you can start with static content and add Void features later.
+With pnpm, you can also start with `pnpm create void my-app`; the scaffolder sets
+up the required native build permissions before installing Void. If a manual
+installation reports blocked build scripts, approve `esbuild`, `sharp`, and
+`workerd` with `pnpm approve-builds`. Set `better-sqlite3: false` in
+`pnpm-workspace.yaml`'s `allowBuilds`: Void uses version 13's bundled binaries,
+so it does not need a native rebuild.
 
-After installation, run the setup flow:
+The setup install updates the pnpm lockfile to match the generated dependencies,
+including when setup runs in CI. Later builds can use `pnpm install --frozen-lockfile`.
 
 ::: code-group
 
@@ -58,36 +66,36 @@ bunx void init
 
 :::
 
-At the end of the full interactive flow, `void init` can also handle Void project setup by logging you in and linking or creating your Void project. That means the default first-time path is install packages, run `void init`, then `void deploy`.
+Void asks you to choose Vite+ or plain Vite, a UI framework, and a starter. Vite+ is the default. For a database app, D1 needs no local database server; PostgreSQL and MySQL are available if you want to use an external database. Static Pages starts with pages only.
 
-For the database-backed starters, D1 is the zero-config default for prototyping and read-heavy apps, while PostgreSQL is better when you already have Postgres infrastructure or need heavier writes and more complex queries.
+Setup also asks where you want to deploy. Choose Cloudflare to use your own account, or Void to connect to your team's platform. You can skip this and decide later.
 
 <details>
 <summary style="cursor:pointer">
 💡 <b>Notes on <code>void</code> binary usage</b>
 </summary>
 
-`void` is a local binary from the installed `void` package, so outside of npm scripts, you will have to invoke it with `npx`, `pnpm`, `yarn`, or `bunx`. For brevity, you will sometimes see unprefixed `void` usage throughout the docs. Just remember it needs to be invoked through a binary runner.
+The docs use `void` for brevity. Because it's installed in your project, run it through your package manager outside package scripts: `npx void`, `pnpm void`, `yarn void`, or `bunx void`.
 
 Alternatively, you can add `./node_modules/.bin` to your `PATH` so that you can invoke `void` directly when you are in the root directory of your app.
 
 :::warning ⚠️ Prefer local install
-We do not recommend installing `void` globally, because the CLI needs to be in sync with same version of the runtime framework. Always install `void` locally as a dev dependency of your project.
+Install `void` locally so the CLI and your app use the same version.
 :::
 
 </details>
 
 ## Using with Coding Agents
 
-`void init` detects your agent once and reuses that choice for instructions, skills linking, and MCP config.
+`void init` detects your coding agent and sets up the matching instructions and skills.
 
 If auto-detection fails, `void init` asks you to choose from a short list (Claude, Cursor, Codex, Gemini CLI, Generic).
 
-In supported agents such as Claude Code, you can invoke the `/void` skill to turn your agent into a Void export. Then, simply ask the agent to build an app with Void. See the [Coding Agents](../integrations/agents) guide for more details.
+In agents that support it, use the `/void` skill to load the relevant guidance, then describe the app you want to build. See [Coding Agents](../integrations/agents) for setup details.
 
 ## Meta Frameworks
 
-Void as a platform supports Vite-based meta frameworks, but the Void SDK itself is also a powerful and flexible meta framework via its [Pages routing](./pages-routing/overview) feature. If you only want to use an existing meta framework and deploy to Void, check out the [Framework Integration Guides](../integrations/frameworks/overview).
+You can build pages directly with Void's [Pages routing](./pages-routing/overview), or keep an existing framework such as TanStack Start, React Router, or SvelteKit. Follow the [framework integration guides](../integrations/frameworks/overview) for framework-specific setup.
 
 ## Adding to an Existing Vite App
 
@@ -111,7 +119,7 @@ bun add -D void
 
 :::
 
-Enable the plugin in `vite.config.ts`
+Enable the plugin in `vite.config.ts`:
 
 ```ts
 import { defineConfig } from 'vite';
@@ -122,7 +130,7 @@ export default defineConfig({
 });
 ```
 
-Then run the setup guide via `void` (Void CLI):
+Run setup to configure the remaining project files:
 
 ::: code-group
 
@@ -148,7 +156,7 @@ bunx void init
 
 ### 1. Edit the generated API route
 
-Your starter already includes `routes/api/hello.ts` with a named `GET` export:
+Database-backed starters include `routes/api/hello.ts`. You can edit its `GET` handler, or create this file if you started with Static Pages:
 
 ```ts
 import { defineHandler } from 'void';
@@ -169,61 +177,32 @@ Then visit:
 - App: `http://localhost:5173`
 - API route: `http://localhost:5173/api/hello`
 
-### 3. Finish Void project setup if you skipped it during `void init`
+### 3. Choose where to deploy
+
+If you chose a deployment target during setup, you're ready. If you skipped it, run `void init` again or choose Cloudflare for the first deploy:
 
 ```sh
-void auth login
+void deploy --platform cloudflare
 ```
 
-If you already logged in and linked a project during `void init`, you can skip this step.
-
-### 4. Deploy
-
-Set secrets once before deploying, if any:
+Void opens your browser to sign in when needed. To use your team's platform, connect using the API URL from your administrator:
 
 ```sh
-void secret put KEY=value
+void connect https://platform.example.com
+void project link
 ```
 
-Then run:
+### 4. Deploy
+
+With your target configured, run:
 
 ```sh
 void deploy
 ```
 
-```sh
-┌  void deploy
-│
-◇  Building...
-│  (vite build output)
-│
-ℹ  Found N migration(s)
-│
-◇  Checking assets...
-◇  Uploading X/Y assets (Z cached)
-◇  Packaging...
-◇  Deploying...
-◇  Deployed!
-│
-│  ╭─────────────────────────────────────────╮
-│  │  https://my-app.void.app           │
-│  │                                         │
-│  │  2 worker module(s), 5 static asset(s)  │
-│  │  1 migration(s) applied                 │
-│  │  SSR enabled                            │
-│  ╰─────────────────────────────────────────╯
-│
-└  Done!
-```
-
-On first deploy, Void will:
-
-- build your app
-- create or link a project if you did not already do that during `void init`
-- provision required resources (for example D1/KV/R2 when inferred)
-- deploy to `https://<slug>.void.app`
-
-Right now, only deploys via the CLI is supported. To setup push-to-deploy GitHub, run `void init --github`.
+Void builds the app, provisions the resources it uses, applies pending migrations, and prints the deployed URL. If it reports a missing production secret, [configure that secret](./env-vars.md) and deploy again.
+
+Subsequent deploys use the same target. See [Deployment](./deployment.md) for CI setup, migrations, and rollback. To generate a supported push-to-deploy workflow, run `void init --github`.
 
 ## Next steps
 

package/skills/void/docs/guide/remote-dev.md

@@ -4,16 +4,16 @@ outline: deep
 
 # Remote Development
 
-During local development, Void uses local emulations of D1, KV, and R2 through [Miniflare](https://miniflare.dev/). That covers most work, but sometimes you need real data for debugging a production issue, testing against a populated database, or validating R2 uploads end to end.
+Void normally uses local D1, KV, and R2 through [Miniflare](https://miniflare.dev/). Remote mode lets you run local code against a project deployed to your Void platform, for example to test with existing data or investigate an issue.
 
-Remote development mode connects your local dev server to the **real bindings** from your deployed project. Your code does not change. `db.select()`, `env.KV.get()`, and `env.STORAGE.get()` work the same way, but they hit remote resources instead of local emulations.
+Calls such as `db.select()` and `env.KV.get()` use the deployed resources without changing your application code. Writes affect real data, so use a staging project when possible.
 
 ## Prerequisites
 
 Before enabling remote mode, you need:
 
-1. **Logged in:** run `void auth login` if you have not already
-2. **Project linked:** run `void deploy` at least once to create and link a project
+1. Connect to your team's platform with `void connect <url>`. It signs you in when needed.
+2. Link a project with `void project link`. Deploy it at least once so its resources exist.
 
 ## Enabling Remote Mode
 
@@ -46,7 +46,7 @@ AI inference is always routed through the proxy regardless of remote mode. There
 
 ## How It Works
 
-When remote mode is active, the dev server replaces local Miniflare bindings with proxy-backed versions at runtime. Every binding call is forwarded to your deployed resources via Void's proxy service, authenticated with your login token. The proxy resolves which D1 database, KV namespace, or R2 bucket to use based on your project's binding configuration.
+In remote mode, binding calls go through your platform's proxy, authenticated with your login token. The proxy uses the linked project's configuration to choose the D1 database, KV namespace, or R2 bucket.
 
 You don't need to change any code. Imports like `import { db } from "void/db"` and direct binding access via `c.env.KV` both work transparently.
 
@@ -61,7 +61,9 @@ When the dev server starts with remote mode active, it prints:
 
 ## Limitations
 
-- **Network latency:** every binding call goes over the network, so local dev is slower than local emulation. This is expected.
+- **Network latency:** each binding call makes a network request, so responses may be slower than local development.
 - **R2 multipart uploads:** `createMultipartUpload()` and `resumeMultipartUpload()` are not supported in remote mode.
+- **R2 conditional writes:** `put(..., { onlyIf })` requires a current Void platform and an active deployment with the native remote-binding handler. Update the platform and redeploy the project if this operation is unavailable. Failed preconditions return `null`; Void never retries a conditional write as an unconditional REST upload.
 - **D1 dump:** `db.dump()` is not supported in remote mode.
+- **D1 batch compatibility:** `db.batch()` requires an active deployment with the native remote-binding handler. Void does not split a batch into REST calls because that would lose D1's atomic all-or-nothing behavior.
 - **Writes affect real data:** remote mode connects to your actual deployed resources. Inserts, updates, and deletes are real, so use it carefully or point it at a staging project.

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

@@ -4,7 +4,24 @@ outline: deep
 
 # Sandboxes
 
-Void can wire Cloudflare Sandboxes into Void apps. A sandbox gives each session an isolated container for running commands, working with files, and exposing ports from server-side code.
+> **Managed platform beta paused:** New managed Sandbox deployments and retained
+> Sandbox rollbacks are currently disabled. Native Cloudflare deployments keep
+> using Cloudflare Sandboxes directly. Platform operators upgrading an existing
+> installation must preview and complete
+> `void platform system sandbox-drain` before reopening platform traffic. The
+> preview is bounded; pass its `nextCursor` back with `--cursor` to inspect later
+> pages. Apply is resumable through a leased database checkpoint: rerun it after
+> active deployments settle, after it advances a page, or after resolving any
+> ownership verification blocker.
+
+For an `unverified_container` blocker, use the reported resource, project,
+binding, application ID, and application name to compare the application's
+Durable Object namespace with the project's managed dispatch script. Never
+delete an account application by name alone. Remove the application and stale
+resource row only after proving that both belong to this platform installation,
+then rerun the drain.
+
+Use a Cloudflare Sandbox to run commands, work with files, and expose ports from server code. Each session gets an isolated container.
 
 ```ts
 import { defineHandler } from 'void';
@@ -23,7 +40,7 @@ Importing from `void/sandbox` enables the `SANDBOX` Durable Object binding, expo
 
 ## Configuration
 
-Most apps do not need config. The default binding is `SANDBOX`, the Durable Object class is `Sandbox`, local development uses the Dockerfile bundled with `@cloudflare/sandbox`, and `void deploy` uses the matching published sandbox image.
+Most apps do not need config. The default binding is `SANDBOX`, the Durable Object class is `Sandbox`, and local development, native Cloudflare deploys, and Void Platform all use the published image matching the installed `@cloudflare/sandbox` version.
 
 Use `void.json` when you need a custom image or container size:
 
@@ -40,16 +57,16 @@ Use `void.json` when you need a custom image or container size:
 
 Available fields:
 
-| Field               | Default                        | Description                                              |
-| ------------------- | ------------------------------ | -------------------------------------------------------- |
-| `binding`           | `SANDBOX`                      | Worker binding name                                      |
-| `className`         | `Sandbox`                      | Durable Object class exported by the Worker              |
-| `containerName`     | `void-sandbox`                 | Cloudflare container app name                            |
-| `image`             | Bundled sandbox SDK Dockerfile | Dockerfile path or registry image used by Wrangler/local |
-| `imageBuildContext` | Directory of `image`           | Docker build context for Wrangler/local                  |
-| `platformImage`     | Matching sandbox SDK image     | Registry image used by `void deploy`                     |
-| `instanceType`      | `lite` on Void deploy          | Container size, such as `lite`, `basic`, `standard-1`    |
-| `maxInstances`      | `20` on Void deploy            | Maximum number of container instances                    |
+| Field               | Default                    | Description                                                           |
+| ------------------- | -------------------------- | --------------------------------------------------------------------- |
+| `binding`           | `SANDBOX`                  | Worker binding name                                                   |
+| `className`         | `Sandbox`                  | Durable Object class exported by the Worker                           |
+| `containerName`     | `void-sandbox`             | Cloudflare container app name                                         |
+| `image`             | Matching sandbox SDK image | Dockerfile path or registry image for local and native Cloudflare use |
+| `imageBuildContext` | Directory of `image`       | Docker build context for local and native Cloudflare use              |
+| `platformImage`     | Matching sandbox SDK image | Registry image used by `void deploy`                                  |
+| `instanceType`      | `lite` on Void deploy      | Container size, such as `lite`, `basic`, `standard-1`                 |
+| `maxInstances`      | `20` on Void deploy        | Maximum number of container instances                                 |
 
 ## Runtime API
 
@@ -68,13 +85,13 @@ You can also use the namespace directly from `c.env.SANDBOX` when you need lower
 
 ## State persistence
 
-There are two distinct layers to think about: stable Durable Object identity, and ephemeral container state.
+A sandbox has a persistent Durable Object identity and a container that can restart:
 
-`getSandbox(id)` always resolves to the same Durable Object instance for a given `id`, regardless of how many times the project has been deployed or rolled back. Anything written through the DO's persistent storage (`ctx.storage`, the embedded SQLite database) survives deploys, rollbacks, and container restarts. That layer is the durable home for sandbox metadata, session ids, and any data you need to outlive the container.
+`getSandbox(id)` selects the same Durable Object for that ID across deploys and rollbacks. Data saved in its persistent storage, including its SQLite database, survives container restarts. Use that storage for session metadata and other state you need to keep.
 
-The container itself — filesystem, running processes, exposed ports, in-memory shell sessions — is tied to a single container lifetime and is **not** durable. Cloudflare Containers idle out after inactivity (the SDK default is `sleepAfter: "10m"`), and a container can also restart on a process crash or a platform-side reschedule. When that happens, files in the container filesystem, background processes, and previously exposed ports are lost. Setting `keepAlive: true` disables the idle timer but does not protect against crashes or infrastructure restarts.
+Files, running processes, exposed ports, and in-memory shell sessions last only as long as the container. It can stop after inactivity (the SDK defaults to `sleepAfter: "10m"`), crash, or restart during platform scheduling. `keepAlive: true` disables the idle timer but doesn't prevent other restarts.
 
-Treat the sandbox container as a working environment, not a source of truth. Persist anything you cannot afford to lose to DO storage, your database, KV, or R2 (the SDK also offers backup/restore helpers for snapshotting a directory to R2). Project deletion destroys both layers, but plenty of routine events destroy only the container layer.
+Save anything you need to keep in Durable Object storage, your database, KV, or R2. The SDK also provides helpers to back up and restore directories through R2. Deleting the project on a Void platform removes both layers; routine container restarts only lose container state.
 
 ## Deployment