void 0.22.0 → 0.23.0

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

@@ -6,7 +6,7 @@ outline: deep
 
 `void deploy` builds your app, provisions its resources, applies migrations, and deploys it to your own Cloudflare account or a Void platform run by your team.
 
-Choose Cloudflare for your own account or Void for a shared team platform. You can [install a Void platform](./self-hosted-platform.md) in your team's Cloudflare account.
+You can [install a Void platform](./self-hosted-platform.md) for shared team deployments.
 
 ## Deployment Targets
 
@@ -51,21 +51,13 @@ Your choice is saved in `.void/project.json`, so the next deploy is just `void d
 
 Already have a Cloudflare Worker and a root `wrangler.jsonc` or `wrangler.json`? Run `void deploy`. If no destination is selected, Void offers to link and deploy using the existing Worker and resources. Accept once to keep deploying to that site. See [Deploy an existing Worker](../integrations/cloudflare.md#deploy-an-existing-worker) for the first-deployment checks.
 
-To connect to your team's platform and sign in, run `void connect <url>` using the URL from your administrator. Use `void connect --platform cloudflare` to set up your own Cloudflare account. Connecting preserves existing project links. New Void projects need a platform connection.
+To set up deployment later, use `void connect --platform cloudflare` or `void connect <platform-url>`.
 
 Owners can [share a platform project](./project-collaboration.md) with readers, collaborators, and project administrators. This does not apply to direct Cloudflare deployments.
 
 ### Migrations
 
-If your app uses Drizzle, `void deploy` runs migrations as part of the deploy flow:
-
-1. Build the app
-2. Read SQL migrations from `db/migrations/`
-3. Check that the migrations match your current schema
-4. Apply pending migrations to the target database
-5. Make the new deploy live
-
-If you've changed your schema without a matching migration, deploy stops. Run `void db generate`, review and commit the SQL, then deploy again. For the full database workflow and backend-specific details, see the [Database guide](./database.md).
+Deploy applies pending SQL migrations from `db/migrations/`. If your schema has changes without a migration, deploy stops. Run `void db generate`, review and commit the SQL, then deploy again. See the [Database guide](./database.md).
 
 ### Flags
 
@@ -117,131 +109,53 @@ If your platform supports managed GitHub builds, the Void GitHub App can build a
 
 You don't need a deployment workflow file or a repository `VOID_TOKEN` for this path.
 
-1. Initialize your Void project
-
-```bash
-void init
-# Or, for existing Void project:
-void project link
-```
-
-2. Install the Void GitHub app
+With a linked project, connect the repository:
 
-```bash
+```sh
 void github install
-```
-
-Void opens GitHub so you can install and authorize the `Void Deploy` app.
-
-In the browser, select the GitHub account/organization and grant access to the repository.
-
-:::details If someone already installed the App for your organization
-Join that installation instead:
-
-```bash
-void github join
-```
-
-:::
-
-3. Link your repository to your project
-
-```bash
 void github connect --executor container
-```
-
-Organization installations always require a browser proof for the specific repository, including for the person who installed the App. Void does not reveal the installation's full private repository list.
-
-4. Verify the connection
-
-```bash
 void github status
 ```
 
-The output shows the repository, branch, and build executor:
+If your organization already installed the App, Void can join that installation during setup. Organization repositories require browser authorization.
 
-```bash
-Repository      <owner/repository>
-Branch          main
-Build executor  container
-Deploy workflow .github/workflows/void-deploy.yml (unused for container builds)
+Push to the configured branch to deploy, then follow progress with `void build logs --follow`. See [GitHub commands](../reference/cli/github.md#github) for installation sharing and connection options.
 
-```
+### GitHub Actions
 
-5. Push to the configured branch to trigger a new deploy
+Run `void init --github` to generate the workflow for your saved platform and package manager. On Void platforms with GitHub Actions support, authorize the repository once:
 
-```bash
-git push origin main
+```sh
+void github connect <project> --repo <owner/repo> --executor github_actions
 ```
 
-6. Follow the build
+Set the repository's `VOID_API_URL` variable to your platform's API URL. Keep `permissions: id-token: write` in the workflow for [GitHub OIDC](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect). The workflow uses your linked project, or the `VOID_PROJECT` repository variable.
 
-```bash
-void build logs --follow
-```
-
-### GitHub Actions
+Core self-hosted installations do not support this integration. Use your own CI workflow with a [project deploy token](./platform/installation/first-deployment.md).
 
-On platforms that support it, the generated workflow uses [GitHub OIDC](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect) to obtain a short-lived deploy token for your project. `void deploy` handles the exchange automatically. Keep `permissions: id-token: write` in the workflow so GitHub can issue that credential.
-
-The generated workflow uses the platform selected during `void init`. Core self-hosted installations don't yet support this integration, so Void doesn't offer the workflow for them. For a platform that does, the npm version looks like this; set the repository's `VOID_API_URL` variable to your platform's API URL:
-
-```yaml
-name: Deploy to Void
-on:
-  push:
-    branches: [main]
-
-# Latest push wins: a newer commit cancels an in-flight deploy for the same
-# repo + branch, so an older commit can never overtake a newer one.
-concurrency:
-  group: void-deploy-${{ github.repository }}-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  id-token: write
-  contents: read
-
-env:
-  VOID_API_URL: ${{ vars.VOID_API_URL }}
-  VOID_PROJECT: my-app
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-node@v6
-        with:
-          node-version: lts/*
-          cache: npm
-      - run: npm ci
-      - name: Deploy
-        run: npx void deploy --platform void --project "$VOID_PROJECT"
-```
+## Other Targets
 
-Authorize the repository once with `void github connect <project> --repo <owner/repo> --executor github_actions`. Choose the `github_actions` executor for this workflow; `container` runs builds on the platform instead.
+### Your own Cloudflare account
 
-The generated workflow uses your package manager and linked project. If no project is linked, it reads the `VOID_PROJECT` repository variable.
+Select Cloudflare during setup, or run `void deploy --platform cloudflare`. See the [Cloudflare guide](../integrations/cloudflare.md) for configuration, CI credentials, and deployment limits.
 
-## Other Targets
+### Node.js, Bun, and Deno
 
-### Your own Cloudflare account
+Set [`target`](../reference/config.md#target) in `void.config.ts` to build a standalone server for Node.js, Bun, or Deno. You can run the result on your own server or in a container.
 
-Select Cloudflare during setup, or run:
+Deploy `dist/ssr` and `dist/client` together. See the target guide for startup commands.
 
-```sh
-void deploy --platform cloudflare
-```
+These targets don't provide Cloudflare bindings such as D1, KV, R2, and Workers AI. See the [Node.js, Bun, and Deno guide](../integrations/nodejs-bun-deno.md) for the features available on each target.
 
-Void supports full Worker apps, static sites, SPAs, and Cloudflare builds from supported frameworks. It provisions resources, applies migrations, and manages secrets for you. `.env` stays local; production server keys declared in `env.ts` must exist in encrypted remote secret storage and are rejected as plaintext Worker vars. Commands such as `void secret put`, `void project logs`, and `void project rollback` then use the same account and Worker.
+## Usage and execution limit pages
 
-See the [Cloudflare guide](../integrations/cloudflare.md#deploy-to-your-own-cloudflare-account) for supported features, CI setup, and deployment limits.
+Void platforms show a built-in page when an app exhausts its request allowance or an invocation exceeds its CPU limit. API requests and Pages action requests receive a structured HTTP 429 with `code: 'usage_limit'`, `resource`, `reason`, and `message`.
 
-### Node.js, Bun, and Deno
+To customize browser error pages, add either optional file to your app's public assets:
 
-Set [`target`](../reference/config.md#target) in `void.config.ts` to build a standalone server for Node.js, Bun, or Deno. You can run the result on your own server or in a container.
+- `public/usage-limit.html` for exhausted request allowances.
+- `public/execution-limit.html` for execution limits.
 
-Deploy `dist/ssr` and `dist/client` together. The server loads the Pages client manifest and assets relative to its emitted module; start it from the app root with `node dist/ssr/index.js`, `bun dist/ssr/index.js`, or `deno run -A dist/ssr/index.js`.
+Use standalone HTML with inline CSS and data-URL images. These pages run with scripts, external assets and form submissions disabled, so they remain usable while application requests are blocked. Void serves them directly from the deployed assets; your Worker, loaders and database are not involved. A missing or unreadable custom page uses the built-in page.
 
-These targets don't provide Cloudflare bindings such as D1, KV, R2, and Workers AI. See the [Node.js, Bun, and Deno guide](../integrations/nodejs-bun-deno.md) for the features available on each target.
+Responses are not cached. Once a streaming response has started, it cannot be replaced with an error page; clients should display stream failures and end their pending state. These platform pages apply to Void platform deployments. Direct Cloudflare runtime limits use Cloudflare's own response behavior.

package/skills/void/docs/guide/durable-state.md

@@ -6,9 +6,9 @@ outline: deep
 
 Use a Durable Object when requests need to share state under one name, such as a shopping cart, room, or rate limiter. Void gives you typed methods and stores the object's state between calls.
 
-Void turns each module in `durable-objects/` into a SQLite-backed Cloudflare Durable Object. The filename determines the binding, Worker class, and initial Cloudflare migration, so no manual Cloudflare configuration is needed.
+Create a module in `durable-objects/` with `defineDurableState()`. Void provides a SQLite-backed Cloudflare Durable Object for it. This feature supports native Void apps deployed directly to Cloudflare.
 
-Void records the inferred binding and migration entry in `void.lock.json`. Commit that file: Cloudflare Durable Object migrations are append-only, and the persisted order ensures a newly added module is migrated after every class already deployed.
+Commit `void.lock.json` when Void adds a resource. Keep its deployed migration entries in their original order.
 
 ## Define state and methods
 
@@ -32,21 +32,11 @@ export const Counter = defineDurableState({
 export default Counter;
 ```
 
-The default export must be the object returned by `defineDurableState()`. Void uses it to export the generated Cloudflare class and associate the inferred binding at worker startup.
-
-For `counter.ts`, Void generates:
-
-| Resource                 | Generated name            |
-| ------------------------ | ------------------------- |
-| Binding                  | `COUNTER`                 |
-| Worker class             | `CounterDurableObject`    |
-| Cloudflare migration tag | `void-durable-counter-v1` |
-
-Names are derived from kebab-case filenames: `shopping-cart.ts` becomes `SHOPPING_CART` and `ShoppingCartDurableObject`.
+Default-export the object returned by `defineDurableState()`.
 
 ## Call it from a route
 
-Import the same named definition and select an object by name. Calls are typed from the method definitions, including arguments and return values.
+Import your definition and call `get()` with a name to select an object. Method arguments and return values are typed:
 
 ```ts
 // routes/api/counter.ts
@@ -64,8 +54,6 @@ The same name always resolves to the same Durable Object. Use `getById(id)` when
 
 ## Execution and persistence
 
-Typed methods run through Cloudflare RPC on the generated Durable Object class. Only your declared methods are exposed; Void’s state-loading and persistence helpers stay private.
-
 Void loads state before the first operation and runs RPC methods one at a time. After a method, `fetch`, or `alarm` handler succeeds, it saves the updated state.
 
 If the handler or save fails, Void restores `context.state` to its previous value. Direct writes to `context.storage` aren't included in that rollback.
@@ -127,14 +115,51 @@ export const Counter = defineDurableState({
 export default Counter;
 ```
 
-These state migrations are separate from Cloudflare's Durable Object class migration. Void generates the latter with `new_sqlite_classes` when it discovers the file.
+State migrations update your saved values. Void manages Cloudflare’s separate class migrations in `void.lock.json`.
 
 Do not delete or reorder generated Durable Object migrations in `void.lock.json` after deployment. For a class addition, rename, or removal on an existing Worker, review the migration and run `void deploy --platform cloudflare --atomic`. If this Worker needs atomic publication on every deploy, set `deploy: { cloudflare: { mode: 'atomic' } }` in `void.config.ts`. Cloudflare applies class lifecycle changes in one deployment. The Worker receives traffic before Void checks readiness, and you cannot roll back across that migration boundary. Staged deploys keep pre-traffic readiness verification.
 
+## Rename a file while keeping its state
+
+Before renaming a deployed definition, run:
+
+```sh
+void info
+```
+
+For `durable-objects/counter.ts`, Void prints:
+
+```text
+To preserve this resource when moving its code, add this to 'defineDurableState':
+  name: "counter",
+```
+
+Add that property to the existing definition:
+
+```ts
+export const Counter = defineDurableState({
+  name: 'counter',
+  initialState: { count: 0 },
+  methods: {
+    read(context) {
+      return context.state.count;
+    },
+  },
+});
+
+export default Counter;
+```
+
+Rename the file within `durable-objects/`, update its imports, and deploy. Keep `name: 'counter'` and the names passed to `Counter.get()` unchanged to preserve the stored state.
+
+`name` is optional. Use a static string, either inline or in a local `const`, containing words that start with a letter, such as `'shopping-cart'`. Names must produce distinct Worker classes and bindings. Changing an existing resource's `name` selects a different resource.
+
+If you already moved the file, `void info` also shows resources recorded in `void.lock.json` without a matching definition. Identify the original resource and use its suggested name. If no name can be suggested, restore the original file from source history and run `void info` before moving it again. Keep the existing lock and migration history.
+
 ## Deployment support
 
 Typed state works in local development and direct Cloudflare deploys of native Void apps. Deploy with `void deploy --platform cloudflare`.
 
-Deploying custom Durable Object modules to a Void platform isn't supported yet. `void deploy --platform void` stops before building and points you to the Cloudflare path. Meta-frameworks and Node.js, Bun, and Deno targets also reject `durable-objects/` with guidance.
+Custom Durable Object modules are not supported on Void platforms, in meta-frameworks, or on Node.js, Bun, and Deno.
 
 This is separate from [typed WebSocket routes](./websockets.md), which also use SQLite-backed Durable Objects and work on both direct Cloudflare and hosted Void deployments.

package/skills/void/docs/guide/edge/headers.md

@@ -25,44 +25,13 @@ Define custom response headers in [`void.config.ts`](../../reference/config) usi
 - All matching rules are merged. When multiple rules set the same header name, the **last match wins**.
 - User-defined `Cache-Control` overrides the built-in default. The default still applies when no rule matches.
 
-## Example: security headers
-
-```json
-{
-  "routing": {
-    "headers": {
-      "/*": [
-        "X-Frame-Options: DENY",
-        "X-Content-Type-Options: nosniff",
-        "Referrer-Policy: strict-origin-when-cross-origin"
-      ]
-    }
-  }
-}
-```
-
-## Example: override caching
-
-```json
-{
-  "routing": {
-    "headers": {
-      "/*.html": ["Cache-Control: public, max-age=300"],
-      "/config.json": ["Cache-Control: no-store"]
-    }
-  }
-}
-```
-
 ## Scope
 
-The dispatch Worker applies header rules to static assets, SSR pages, and API responses, including hashed assets served from cache. For example, you can add the cross-origin headers a page needs for Worker or WebAssembly files.
+Header rules apply to static assets, SSR pages, and API responses, including hashed assets served from cache.
 
 For hashed assets, you can add headers, but the platform keeps control of caching and response encoding. Rules cannot replace `Cache-Control`, `Content-Type`, `Content-Encoding`, `Content-Length`, `Content-Range`, `Accept-Ranges`, or `Transfer-Encoding` on these files.
 
-Header rules do not apply to:
-
-- ISR cache responses (these have their own cache-control headers)
+Header rules do not apply to ISR cache responses.
 
 ### Blocked headers
 
@@ -70,17 +39,4 @@ Header rules do not apply to:
 
 ## Framework `_headers` files
 
-Meta-frameworks like SvelteKit, Nuxt, and Astro generate a `_headers` file with cache rules for their hashed asset directories. Void automatically parses this file during deploy and merges the rules into the deploy manifest.
-
-- Framework-generated rules are applied **before** `void.config.ts` rules. Since the last match wins, `routing.headers` in `void.config.ts` takes precedence and can override framework defaults.
-- The `_headers` file is not uploaded as a static asset. Its contents are parsed and included in the manifest only.
-
-No configuration is needed. If the framework generates a `_headers` file, it is picked up automatically.
-
-## How headers work
-
-1. `void deploy` reads header rules from the framework `_headers` file (if present) and `routing.headers` in `void.config.ts`, then includes them in the deploy manifest.
-2. The platform stores the rules in the KV routing entry for your project.
-3. The dispatch Worker adds matching headers before returning a response. Most cached responses include those headers. Hashed assets get header rules on each response, including cache hits, so a rule change takes effect without changing the file.
-
-Headers are applied at the edge as part of serving the response; no separate network request is needed.
+Void reads `_headers` files produced by supported frameworks. Your `routing.headers` rules run afterward, so they can override framework defaults. No additional setup is needed.

package/skills/void/docs/guide/edge/prerendering.md

@@ -4,7 +4,7 @@ outline: deep
 
 # Edge Prerendering
 
-You can instruct Void to prerender a page so it is served from cache immediately after a new deploy. Prerendering happens on the platform at deploy time. The platform invokes the uploaded worker and writes the result to the edge cache.
+Prerender pages at deploy time so the first visitor receives cached HTML.
 
 - [Markdown pages](../pages-routing/markdown.md) are auto-prerendered.
 - [Island pages](../pages-routing/islands) with no companion loader and no dynamic params are also auto-prerendered.
@@ -16,13 +16,9 @@ Export `prerender = true` from the companion `.server.ts` file:
 ```ts
 // pages/about.server.ts
 export const prerender = true;
-
-export const loader = defineHandler(async (c) => {
-  // ...
-});
 ```
 
-Pages with no dynamic params are automatically prerendered at their URL pattern (e.g. `/about`).
+Pages without dynamic params do not need `getPrerenderPaths()`.
 
 ## Dynamic pages (with params)
 
@@ -36,10 +32,6 @@ export async function getPrerenderPaths() {
   // Return param objects matching the URL pattern
   return [{ slug: 'hello-world' }, { slug: 'getting-started' }];
 }
-
-export const loader = defineHandler(async (c) => {
-  // ...
-});
 ```
 
 ## Custom SSR
@@ -53,21 +45,15 @@ export const prerender = true;
 export async function getPrerenderPaths() {
   return ['/', '/about', '/blog/hello-world'];
 }
-
-export default defineRender(async (c, assetTags) => {
-  // ...
-});
 ```
 
 ## Relationship to revalidation
 
 Setting `routing.isr: false` in `void.config.ts` disables ISR and this edge-prerendering behavior, including per-page exports. It does not disable build-time HTML generation with `output: "static"`.
 
-Pages with long revalidate TTLs (e.g. 1 year) are effectively static, but the first visitor after a deploy hits a cold cache. This is where prerendering helps - it ensures your users never get slow requests.
-
-Enabling prerendering for a page automatically sets `revalidate` to 1 year, so you don't need to export it yourself. Since the ISR cache is cleared on every deploy, the TTL only needs to be long enough to last between deploys.
+Prerendered pages default to a one-year revalidate TTL. Deploys clear the ISR cache.
 
-You can also explicitly set to it a different value to override the default:
+Override the TTL per page:
 
 ```ts
 // pages/about.server.ts
@@ -75,11 +61,10 @@ export const prerender = true;
 export const revalidate = 3600;
 ```
 
-Just be aware that if no new deploy happens before the revalidate expires, the first user request after expiration will miss the cache and incur a full render.
+If the cached page expires before your next deploy, the next request waits for a fresh render.
 
 ## Behavior details
 
 - Prerender happens once per deployment, before traffic is routed to the new version. Prerendered pages are cached at the edge.
-- Each deploy clears the ISR cache. The deployment shows `"prerendering"` during this phase.
 - Only paths with a positive revalidate TTL are prerendered (TTL `0` is skipped).
 - Prerender failures are logged but never block the deploy. The page will render on the first request as usual.

package/skills/void/docs/guide/edge/redirects.md

@@ -23,42 +23,12 @@ Define URL redirects in [`void.config.ts`](../../reference/config) using the `ro
 - **Destinations** can be strings (default `302`) or objects with `to` and optional `status`. Supported statuses: `301`, `302`, `303`, `307`, `308`.
 - `:splat` in the destination is replaced with the portion of the path matched by `*` in the source pattern.
 - Destination query strings are merged into the `Location` header (the destination's parameters take precedence on per-key conflict). To drop the incoming query, write an explicit reset like `?`.
-- When multiple rules match, the **first match wins**. Put more-specific rules above more-general ones (matches Netlify `_redirects` and Vercel `vercel.json` semantics).
+- When multiple rules match, the **first match wins**. Put specific patterns before catch-all patterns.
 - Redirects are evaluated **before** the request reaches the worker, so they short-circuit static asset serving, ISR, and SSR.
 
-## Example: permanent redirect
-
-```json
-{
-  "routing": {
-    "redirects": {
-      "/old-page": { "to": "/new-page", "status": 301 }
-    }
-  }
-}
-```
-
-## Example: path prefix migration
-
-```json
-{
-  "routing": {
-    "redirects": {
-      "/blog/*": { "to": "/posts/:splat", "status": 301 }
-    }
-  }
-}
-```
-
-A request to `/blog/hello-world` redirects to `/posts/hello-world` with a `301` status.
-
 ## Domain-level redirects
 
-Scope a redirect to a specific Host header by prefixing the source with `https://host`. Useful for:
-
-- **Domain consolidation** — redirect everything from an old marketing domain to a new one without per-host deploy config.
-- **Canonical host enforcement** — `www.example.com` → `example.com`.
-- **Per-domain rules on a multi-domain project** — when you've bound several custom domains to one project but want different behavior on each.
+Prefix a source with `https://host` to redirect only requests to that domain:
 
 ```json
 {
@@ -74,43 +44,20 @@ Scope a redirect to a specific Host header by prefixing the source with `https:/
 The `_redirects` file accepts the same syntax:
 
 ```
-https://www.example.com/*  https://example.com/:splat  301!
+https://www.example.com/*  https://example.com/:splat  301
 ```
 
-The host portion is split off the source and stored as a `host` field on the rule. Path-only sources (no `https://` prefix) apply to every domain bound to the project — that's the existing behavior. Host-prefixed sources only fire when the request's `Host` header matches.
-
-### Validation
-
-- The host must be a literal hostname — wildcards (`*.example.com`), ports, paths, and userinfo are rejected.
-- Only `https://` is accepted. `http://` and protocol-relative `//` sources are rejected — TLS terminates upstream of the worker, so an `http://`-scoped rule physically cannot fire.
-- The host must be **bound to your project** (either `<slug>.void.app` or a custom domain you've added via `void domain add`). `void deploy` rejects rules scoped to hosts that aren't on the project — staging the rule in the same change as the domain is the recommended flow.
-- Custom domains in `pending` (DCV-in-progress) state are accepted. The rule deploys but stays inert until DCV completes; once the certificate is issued, the rule starts firing automatically without a redeploy.
-
-### Combined with external destinations
+Path-only sources apply to every domain on the project. Host-prefixed sources apply only to the named domain.
 
-The source `host` and the destination URL are independent. Combining them lets you express domain-consolidation redirects in a single rule:
-
-```
-https://old.example.com/*  https://www.example.com/:splat  301!
-```
-
-Reads as "when a request hits `old.example.com` on any path, send a 301 to the same path on `www.example.com`."
+The source must use `https://` and a literal hostname without wildcards or a port. Add the domain to your project with `void domain add` before deploying the rule. A domain awaiting certificate verification starts redirecting once it becomes active.
 
 ## Framework `_redirects` files
 
-Meta-frameworks may generate a `_redirects` file during build. Void parses this file at deploy time and merges the rules into the deploy manifest.
+Void reads `_redirects` files produced by supported frameworks. You can also place one in Vite's `publicDir`:
 
-- `void.config.ts` rules are applied **before** framework-generated `_redirects` rules. Since the first match wins, `routing.redirects` in `void.config.ts` takes precedence.
-- Both 3xx redirect rules and status `200` [rewrite rules](./rewrites) are supported in `_redirects` files.
-- The `!` force suffix is only meaningful on `200` entries (see [rewrites — `_redirects` file](./rewrites#redirects-file)). On 3xx entries (`301!`, `302!`, `307!`, `308!`) it's silently stripped — a redirect always "forces" by nature, so the suffix is redundant. `void deploy` prints a single aggregated warning tallying every such entry so you can clean them up.
-- The `_redirects` file is not uploaded as a static asset. Its contents are parsed and included in the manifest only.
-
-Precedence when the same source appears in both sources follows the same rules as rewrites — config rules are merged before file rules within each phase, and first match wins, so `void.config.ts` overrides `_redirects`. See [rewrite precedence](./rewrites.md) for a worked example.
-
-## How redirects work
-
-1. `void deploy` reads redirect rules from the framework `_redirects` file (if present) and `routing.redirects` in `void.config.ts`, then includes them in the deploy manifest.
-2. The platform stores the rules in the KV routing entry for your project.
-3. The dispatch worker checks redirect rules before any worker invocation, so matching requests get a redirect response immediately.
+```text
+/old-page  /new-page     301
+/blog/*    /posts/:splat 301
+```
 
-Because rules are evaluated at the edge before invoking the worker, redirects add no latency to the request path.
+Rules in `void.config.ts` take precedence over file rules. Use `200` for a fallback or `200!` for a [rewrite](./rewrites#redirects-file). Redirects don't need the `!` suffix.

package/skills/void/docs/guide/edge/revalidation.md

@@ -74,13 +74,9 @@ When multiple sources set a revalidate TTL, the most specific wins:
 
 ## How revalidation works
 
-1. **First request:** there is no cache entry yet. The worker renders the page, returns the response, and writes the result to KV in the background.
+The first request renders and caches the page. While the cached page is fresh, visitors receive it immediately. Once it becomes stale, Void serves it while rendering an updated version in the background.
 
-2. **Subsequent requests (fresh):** the cached response is served from the edge cache or KV. No worker call is needed.
-
-3. **Subsequent requests (stale):** the stale cached response is served immediately, and the worker re-renders in the background. The next request gets the fresh version.
-
-While a stale entry is available, visitors can receive it without waiting for the refresh. A request without a cached entry still needs to render the page.
+A request without a cached entry waits for the page to render.
 
 ## Per-response TTL override
 
@@ -100,8 +96,9 @@ export const GET = defineHandler(async (c) => {
 
 Only complete `200` responses are cached. A response with `Cache-Control: private`,
 `no-store`, or `no-cache`, or any `Set-Cookie` header, stays private to that request.
-If a previously public page starts returning one of those headers during background
-revalidation, Void removes its HTML, Pages JSON, and KV cache entries.
+If a public page starts returning one of those headers, Void removes its cached response.
+
+Responses that vary by request headers, such as `Vary: Accept-Language` or `Vary: Origin`, are rendered live. `Vary: *` also disables shared caching. Void's `X-VoidPages` header is supported because HTML and Pages JSON have separate cached responses.
 
 ## Cache bypass
 
@@ -115,16 +112,6 @@ Query parameters are excluded by default. Add `routing.revalidateQueryAllowlist`
 
 Purge the destination pathname with `revalidate({ paths })`. Purging `/en/docs/foo` clears both direct and rewritten variants. Purging only `/docs/foo` won't clear them, because the entries are stored under the destination.
 
-::: details Upgrading from the older ISR cache format
-
-The current format uses a `v3` host-scoped prefix and a cache-policy version in its
-metadata. Entries written before the current response-privacy policy are treated as
-cold misses and refill only from responses that are safe to share.
-
-Adding a rewrite also changes the affected page's cache key, so that page starts with a cold cache again.
-
-:::
-
 ## On-demand revalidation
 
 You can purge ISR cache entries programmatically from a route handler: