void 0.10.12 → 0.20.0

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

@@ -0,0 +1,109 @@
+# Environment migration
+
+The environment model now uses `.env` for local development only and remote secrets for every server-side production value. There are no compatibility shims for the previous four-file behavior.
+
+## 1. Preserve production values and consolidate local development values
+
+Before changing any dotenv files, securely back up the production values you need to migrate outside the project directory. Keep them out of Git. Do not delete the original files until the upload and verification in step 3 succeed.
+
+Merge the values you still need locally into `.env`:
+
+```text
+.env.local
+.env.development
+.env.development.local
+→ .env
+```
+
+Keep the legacy files for now. You will remove them in step 5, after migrating their values.
+
+Ensure `.env` is ignored by Git:
+
+```text
+.env
+```
+
+## 2. Remove masking modifiers
+
+Update `env.ts` before running any secret commands: they import the schema to validate values, and the removed modifiers cause that import to fail.
+
+Change:
+
+```ts
+export default defineEnv({
+  STRIPE_KEY: string().secret(),
+  VITE_API_ORIGIN: url().public(),
+});
+```
+
+to:
+
+```ts
+export default defineEnv({
+  STRIPE_KEY: string(),
+  VITE_API_ORIGIN: url(),
+});
+```
+
+Server storage is selected by the absence of the client prefix, not a modifier. Invalid input is redacted uniformly.
+
+## 3. Move production server values remotely
+
+For managed Void projects, upload each non-client schema key:
+
+```sh
+void secret put DATABASE_URL
+void secret put STRIPE_KEY
+```
+
+To migrate a production file in one pass, prepare a copy outside the project directory containing only server keys declared in `env.ts`, then upload it:
+
+```sh
+void secret sync /secure/path/production-secrets.txt
+```
+
+The sync command validates every entry against `env.ts`. It rejects undeclared names, invalid values, and client-prefixed names. Keep client-prefixed values for step 4 instead of including them in this file.
+
+For direct Cloudflare deployments, select Cloudflare and use the same commands:
+
+```sh
+void connect --platform cloudflare
+void secret put DATABASE_URL
+void secret put STRIPE_KEY
+```
+
+After the upload succeeds, confirm that all expected server names appear in the remote store:
+
+```sh
+void secret list
+```
+
+Remote stores return names only; plaintext values are validated during upload and again at worker startup. If an upload fails or a name is missing, retain the source values and retry before continuing.
+
+For direct Cloudflare deployments, remove the migrated server keys from `vars` in `wrangler.jsonc` after confirming the upload. Void now treats any schema-declared server key in Worker `vars` as an error.
+
+## 4. Supply client values at build time
+
+Move `VITE_*` production values to CI/build-shell variables, or make the value an explicit schema default:
+
+```sh
+export VITE_API_ORIGIN=https://api.example.com
+```
+
+Keep these variables set for the remote check and deployment in step 5. Client values are compiled into browser assets and are public.
+
+The same public values are embedded in the server bundle for boot validation and `env.VITE_*` reads during server rendering. Do not upload them as remote secrets.
+
+## 5. Remove legacy files and verify
+
+Once the local values are in `.env`, the server values are uploaded and listed remotely, and the client values are available to the build, delete every `.env.*` file, `.env.example`, and `.dev.vars*` file from the project. Keep the secure backup until verification succeeds. Void's environment checks and deployment fail fast when they find a legacy file, rather than silently applying a precedence order.
+
+`void env example` was removed because `.env.example` created a second dotenv source. Treat `env.ts` as the checked-in list of names, types, defaults, and requiredness.
+
+Then verify:
+
+```sh
+void env check
+void env check --remote
+void deploy
+```

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

@@ -1,309 +1,131 @@
----
-outline: deep
----
+# Environment variables
 
-# Environment Variables
+Void uses one schema, one local dotenv file, and one production rule:
 
-Void provides typed, validated environment variables via a single `env.ts` file at the root of your project. The schema serves three purposes:
+- `env.ts` declares every application environment variable.
+- `.env` supplies local development values only. It is never deployed.
+- Production server values live in the platform's encrypted secret store.
+- Client-prefixed values are embedded at build time, so they are public by definition.
 
-1. **Runtime validation** — declared keys are validated on first access; missing/invalid values produce a clear error
-2. **TypeScript** — `env.X` and `c.env.X` become typed automatically (no manual interface to maintain)
-3. **Deploy safety** — `void deploy` refuses to upload if a required key is missing from `.env*` files or remote secrets
+This removes the distinction between “plain” and “secret-looking” server variables. Every server variable uses the same secure production path.
 
-## `env.ts` (recommended)
+## Define the schema
 
-Place an `env.ts` at your project root and call `defineEnv` once:
-
-::: tip Scaffolded on `void init`
-If you already have `.env` or `.env.example` files when you run `void init`, Void generates an `env.ts` seeded from those keys. Inference is conservative — values that unambiguously parse as a boolean (`true`/`false`), an `http(s)://` URL, or a small integer get typed accordingly; everything else stays `string()`. The generated file carries a banner comment asking you to review and tighten types before running dev.
-:::
+Create `env.ts` at the project root:
 
 ```ts
-// env.ts
-import { defineEnv, string, number, boolean, oneOf, url } from 'void/env';
+import { defineEnv, number, string, url } from 'void/env';
 
 export default defineEnv({
+  DATABASE_URL: url(),
   STRIPE_KEY: string(),
   PORT: number().default(3000),
-  NODE_ENV: oneOf(['development', 'production']),
-  WEBHOOK_URL: url(),
-  DEBUG: boolean().optional(),
-  VITE_APP_TITLE: string(),
+  VITE_API_ORIGIN: url(),
 });
 ```
 
-Then read values from anywhere in your app:
+Void generates `.void/env.d.ts`, validates values, and provides the typed `env` proxy:
 
 ```ts
 import { env } from 'void/env';
 
-console.log(env.STRIPE_KEY); // typed as string
-console.log(env.PORT); // typed as number
+const databaseUrl = env.DATABASE_URL;
 ```
 
-`c.env.STRIPE_KEY` inside Hono handlers is also typed once the schema is declared.
-
-### Built-in helpers
+The built-in helpers are `string()`, `number()`, `boolean()`, `url()`, `email()`, `oneOf([...])`, and `json<T>()`. They support `.optional()` and `.default(value)`. Any [Standard Schema](https://standardschema.dev/) validator can also be used directly.
 
-`string()`, `number()`, `boolean()`, `url()`, `email()`, `oneOf([...])`, `json<T>()` cover the common cases. Each helper returns a Standard Schema-conformant builder with `.optional()` and `.default(value)` modifiers.
+Defaults are source-code constants. They are appropriate for non-sensitive fallback behavior; do not put credentials in a default.
 
-For richer validation (regex, transforms, branded types), drop in any [Standard Schema](https://standardschema.dev) library — valibot, zod, or arktype work out of the box, and you can mix them with the built-ins:
+## Local development
 
-```ts
-import * as v from 'valibot';
+Put local values in a single root `.env` file:
 
-export default defineEnv({
-  STRIPE_KEY: string(), // built-in
-  WEBHOOK_URL: v.pipe(v.string(), v.url(), v.endsWith('/webhook')), // valibot
-});
+```ini
+DATABASE_URL=postgres://localhost/my-app
+STRIPE_KEY=sk_test_example
+VITE_API_ORIGIN=http://localhost:5173
 ```
 
-### Client vs server
-
-Keys matching Vite's `envPrefix` (default `VITE_`) are exposed to client code; Vite enforces this at the bundler level. All other keys are server-only — referencing one from a client module fails the build with a file:line:col error from `void:env-client-guard`, and the runtime proxy still throws as a backstop.
-
-If your project sets a custom `envPrefix` (e.g. `'PUBLIC_'` or an array like `['PUBLIC_', 'NEXT_PUBLIC_']`) in `vite.config.ts`, the build guard honours it automatically. Schema keys that match any configured prefix pass the client check.
+`.env` should be gitignored. Void rejects legacy `.env.local`, `.env.development`, `.env.production`, `.env.example`, other `.env.*` files, and Wrangler `.dev.vars*` files so there is no hidden precedence order.
 
-### Build-time constant folding
+Run the local check at any time:
 
-In production client builds, static reads of a client-exposed key are folded into string literals so the bundler can dead-code-eliminate conditional branches — exactly what Vite already does for `import.meta.env.MODE`.
-
-```ts
-// source
-import { env } from 'void/env';
-if (env.MODE === 'production') {
-  initAnalytics();
-}
-
-// production client bundle (after folding + DCE)
-initAnalytics();
+```sh
+void env check
 ```
 
-Rules:
-
-- **Client bundles only.** Server / SSR / worker code keeps the full runtime proxy so secrets, runtime-injected vars, and HMR keep working.
-- **Prefix-gated.** Only keys matching Vite's `envPrefix` (default `VITE_`, honours custom string or array config) are ever folded — server-only keys never appear as literals in client output.
-- **Static access only.** `env.FOO` and `env["FOO"]` get folded. Dynamic access (`env[key]`), destructuring, and reassignment fall back to the runtime proxy.
-- **Values come from** the same source Vite already uses for `import.meta.env`: `.env*` files (respecting `envDir`) plus schema `.default(x)` values for missing keys. Unknown keys are left untouched and the proxy serves them at runtime.
-- **Build-only.** Dev keeps going through the proxy so editing `.env.local` takes effect without a full rebuild.
-- **Zero-config.** No flags, no opt-in — just works.
-
-### Vite `define` interop
-
-Vite's `define` option performs build-time literal replacement (e.g. `define: { 'process.env.VERSION': '"1.0"' }`). It does **not** flow through schema validation or the typed `env` proxy — using both `define` and `defineEnv` for the same name causes silent skew (compiled client code sees the define value, runtime proxy and validation see the schema source). Void emits a warning at config time when this overlap is detected.
+Local database, migration, auth, and dev-server tooling all read the same `.env` file. Shell values override it.
 
-### `envDir`
+## Production server values
 
-Void honours Vite's `envDir` option for `.env` file loading (both the worker `vars` injection and dev-time validation). Defaults to the project root. The deploy CLI still reads from the project root regardless — keep production `.env` files there.
+Every schema key that is not client-prefixed is a server value. Set it remotely:
 
-### Imports inside `env.ts`
-
-`env.ts` is loaded outside Vite's plugin pipeline — the dev plugin and the deploy CLI both read it through Node's native `import()`. That means only **relative imports** (`./shared/env-keys`) and **bare package names** (`zod`, `valibot`) resolve. Known limitations:
-
-- **tsconfig path aliases are not resolved.** Writing `import { X } from "@/shared/env-keys"` or `import { Y } from "~/foo"` inside `env.ts` fails to load; Void detects this and re-throws with a hint pointing at the offending specifier. Use a relative import instead.
-- **Custom Vite plugins don't run.** Anything that needs Vite's transform pipeline (SVG-as-component, GraphQL loaders, virtual modules, etc.) won't apply to `env.ts`. Keep this file to pure TS + schema declarations.
-
-In practice `env.ts` should only import schema helpers from `void/env` and — at most — a shared constants file via a relative path.
-
-## `.env` files
-
-Void uses Vite's standard `.env` convention to populate the schema:
-
-Whether a file's values ship depends on which deploy path you use:
-
-| File                    | Loaded in dev | Shipped by `void deploy` | Shipped by `--backend cloudflare` |
-| ----------------------- | ------------- | ------------------------ | --------------------------------- |
-| `.env`                  | yes           | yes (`plain_text`)       | yes (worker `vars`)               |
-| `.env.local`            | yes           | no                       | **yes** (worker `vars`)           |
-| `.env.production`       | yes           | yes (`plain_text`)       | yes (worker `vars`)               |
-| `.env.production.local` | yes           | no                       | **yes** (worker `vars`)           |
-
-`.local` files are gitignored by convention — use them for secrets you don't want in source control.
-
-::: warning `.local` files are not deploy-excluded on `--backend cloudflare`
-Managed `void deploy` reads only `.env` and `.env.production`, so a `.local` file keeps secrets off the platform. The self-host `void deploy --backend cloudflare` path instead runs Vite's production env loading, which reads all four files and bakes them into the worker's `vars` as plaintext. A value that is also `export`ed in the shell with the same value is stripped back out, so this bites hardest in CI, where the variable usually only exists in the file.
-
-On that path, keep real secrets out of every `.env*` file and use `wrangler secret put <NAME>` instead. See [Cloudflare deploy](/integrations/cloudflare).
-:::
-
-### Dotenv variable expansion
-
-Values can reference other keys defined in the same (or earlier-precedence) `.env` file using `${VAR}` or `$VAR`:
-
-```ini
-# .env
-BASE_URL=https://api.example.com
-API_URL=${BASE_URL}/v1        # → "https://api.example.com/v1"
-BUILD=$BASE_URL/build.json    # bare form also works
-LITERAL=\$NOT_EXPANDED        # → "$NOT_EXPANDED" (backslash-escape)
+```sh
+void secret put DATABASE_URL
+void secret put STRIPE_KEY
 ```
 
-Nested references resolve transitively (`A=${B}`, `B=${C}`, `C=value` → `A=value`). Cycles are detected and leave the raw literal (Void emits a warning rather than looping). Missing references expand to the empty string.
-
-Expansion runs identically across every path that reads your `.env*` files: the runtime typed `env` proxy, `void env check`, `void deploy`, and the `void init` scaffold inference. Importantly, references **only** resolve against values declared in the `.env*` files themselves — shell `process.env` values are not substituted in. This stops a developer-machine variable from silently materialising in committed examples or deploy manifests. (Vite's own `loadEnv` does consult `process.env` during expansion for the dev-server path; Void filters the shell pollution back out via `filterLoadedEnv` so the observable surface stays the same.)
+For bulk upload, prepare a dotenv-formatted file containing only production server values:
 
-## Production secrets
-
-For values that should never live in a `.env` file (Stripe keys, OAuth secrets, etc.), upload them as encrypted secret bindings on your deployed worker:
-
-```bash
-void secret put STRIPE_KEY            # prompts for value
-void secret put STRIPE_KEY < key.txt  # from stdin
-void secret sync .env.production      # bulk upload from a dotenv file
-void secret list
-void secret delete STRIPE_KEY
+```sh
+void secret sync production-secrets.txt
 ```
 
-Remote secrets count as "present" for deploy validation — `void deploy` checks both `.env*` and the remote secret list before uploading.
-
-## Defaults
-
-Schema defaults from `defineEnv({ PORT: number().default(3000) })` flow into:
-
-- The typed `env` proxy: `env.PORT` returns `3000` when no value is set.
-- Worker bindings (`c.env.PORT`, `process.env.PORT` on Node target): the
-  default value is injected as a stringified `var` in dev, in `void deploy`
-  manifests, and in prerender bindings, so any code path that reads the raw
-  env sees the same fallback.
-- Client-exposed keys (`VITE_*` by default, or your configured `envPrefix`):
-  defaults are added to Vite's client env, so browser code reading
-  `env.VITE_APP_TITLE` sees the same fallback.
-
-User-provided `.env` / shell values always win — defaults only fill gaps.
-
-## Validation behavior
-
-| Phase                | Behavior                                                                                                         |
-| -------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| Dev server start     | Warns about missing/invalid keys (does not block).                                                               |
-| First runtime access | Throws `EnvValidationError` with the failing key and reason.                                                     |
-| `void env check`     | Validates `.env` + `.env.production` (and optionally remote secrets with `--remote`); exits non-zero on failure. |
-| `void deploy`        | Hard-errors before upload if any required key is missing from the union of `.env*` and remote secrets.           |
+`void secret put` and `void secret sync` validate the plaintext against `env.ts` before upload. The remote store encrypts the accepted value and only returns its name later, so subsequent deploy checks can prove presence but cannot re-read the plaintext. The worker validates the real value again at runtime.
 
-Use `void env check --remote` in CI before deploying — it catches missing prod secrets without running a full build.
+Client-prefixed keys are rejected by secret commands. Keep local development credentials and `VITE_*` values out of the production secrets file.
 
-## Manual type regeneration
+`void deploy` never adds `.env` values to its manifest. It requires every required server key to exist remotely before upload.
 
-Types are auto-generated to `.void/env.d.ts` on dev server start and whenever `env.ts` changes. To regenerate manually (e.g. after a fresh clone):
+For direct Cloudflare deployment, select Cloudflare and use the same Void commands:
 
-```bash
-void env types
+```sh
+void connect --platform cloudflare
+void secret put DATABASE_URL
+void secret put STRIPE_KEY
+void deploy --platform cloudflare
 ```
 
-## Scaffolding `.env.example`
+Void stores the values as encrypted Worker secrets, emits the required server names through `secrets.required`, and refuses to deploy a schema-declared server key as a plaintext Worker `vars` entry.
 
-Generate (or refresh) a `.env.example` from your `env.ts` schema:
+## Client values
 
-```bash
-void env example           # creates or refreshes the void-managed block
-void env example --force   # silences the "appended block" notice (use in CI)
-```
+Keys beginning with `VITE_` are client values. This boundary is fixed, so the CLI, build, and secret commands always classify a name the same way even when a framework customizes Vite's own `envPrefix`.
 
-`void env example` manages a marker-delimited block inside `.env.example` — anything outside the markers (custom CI tokens, build flags, comments) is preserved verbatim across refreshes. The block looks like this:
+Client values are embedded in browser JavaScript and are never secrets. Supply them through the build shell or use a schema default:
 
-```ini
-# >>> void env: managed block — do not edit between markers <<<
-# Run `void env example` to refresh.
-# required
-STRIPE_KEY=
-# with defaults
-PORT=3000
-# >>> end void env <<<
+```sh
+VITE_API_ORIGIN=https://api.example.com void deploy
 ```
 
-On first run, Void writes a fresh `.env.example` containing only the marker block. On subsequent runs, only the lines between the markers are replaced. If the file already exists with no markers, the block is appended at the end and Void prints a one-line notice (suppressed by `--force`).
-
-The managed block is grouped into `required`, `with defaults`, and `optional` sections. Keys defined via `oneOf([...])` get a leading `# enum: A | B | C` comment listing the valid values, and keys with a `.default(x)` are prefilled. Commit the `.env.example` — it's the single source of truth for teammates and coding agents setting up the project.
-
-## Secret redaction
-
-Env validation errors, dev-server warnings, and CLI reports automatically replace secret-looking values with `<redacted>` before they surface. This keeps tokens out of Discord screenshots, GitHub issues, and CI logs when you paste an `EnvValidationError` stack.
-
-Redaction is belt-and-braces:
-
-1. **Explicit override.** The built-in helpers support `.secret()` and `.public()` modifiers, and they win over every heuristic:
-
-   ```ts
-   export default defineEnv({
-     STRIPE_KEY: string().secret(), // always redacted
-     PUBLIC_KEY: string().public(), // never redacted (opts out of the KEY heuristic)
-     PORT: number(),
-   });
-   ```
-
-   Third-party Standard Schema validators (valibot, zod, arktype) can't carry this flag — they fall back to the heuristics below.
-
-2. **Key-name heuristic.** Values for keys matching `/KEY|TOKEN|SECRET|PASSWORD|PASS(WD)?|CREDENTIAL|PRIVATE|AUTH|BEARER|APIKEY|DSN/i` are redacted by default.
-
-3. **Value-content heuristic.** Even on neutral keys, values that start with `sk_` / `pk_` / `ghp_` / `xoxb-` / `AKIA` or look like a ≥24-char high-entropy string are redacted. This catches wrong-file typos like `PORT=sk_live_abc123`, where the key is innocent but the value is a Stripe key.
-
-The **key name itself is never masked** — you need it to locate the offending entry.
-
-For local debugging, set `VOID_ENV_UNMASK=1` in your shell to see raw values in error output. On activation Void prints a one-shot notice to stderr so the loosened output is visibly attributed; unset it before sharing logs.
-
-## Using `env.ts` with a meta-framework
-
-The full env story works on every framework `voidPlugin()` supports — typegen, leak guard, folding, runtime reads on both server and client, plus all CLI-level features.
-
-| Framework         | `env.ts` typegen | Client leak guard | Constant folding |   `env` on server   |     `env` on client     | `void env check` + deploy gate |
-| ----------------- | :--------------: | :---------------: | :--------------: | :-----------------: | :---------------------: | :----------------------------: |
-| Void (Pages mode) |       yes        |        yes        |       yes        |         yes         |     yes (`VITE_*`)      |              yes               |
-| TanStack Start    |       yes        |        yes        |       yes        |         yes         |     yes (`VITE_*`)      |              yes               |
-| React Router v7   |       yes        |        yes        |       yes        | yes (in `loader()`) |     yes (`VITE_*`)      |              yes               |
-| SvelteKit         |       yes        |        yes        |       yes        | yes (runtime proxy) |     yes (`VITE_*`)      |              yes               |
-| Nuxt              |       yes        |        yes        |       yes        |         yes         |     yes (`VITE_*`)      |              yes               |
-| Analog            |       yes        |        yes        |       yes        |         yes         |     yes (`VITE_*`)      |              yes               |
-| Astro             |       yes        |        yes        |       yes        |         yes         | yes (`envPrefix`-gated) |              yes               |
+```ts
+export default defineEnv({
+  VITE_API_ORIGIN: url().default('https://api.example.com'),
+});
+```
 
-What you always get, regardless of framework:
+Builds ignore client values from `.env`; this prevents a developer's local value from silently becoming production configuration.
 
-- `void env check [--remote]` validates `.env*` files + remote secret names against the schema.
-- `void deploy` hard-fails before upload when any required key is missing.
-- `void env example` generates the marker-delimited `.env.example` block.
-- `void init` scaffolds `env.ts` from existing dotenv files.
-- Typed `.void/env.d.ts` so `env.X` autocompletes in editors.
-- `void:env-client-guard` fails the build with a file:line:col error when a server-only key is referenced from a client module.
-- Build-time constant folding for `envPrefix`-matched reads in the client bundle.
+The server bundle embeds those same public build values. Worker boot validation and server-side `env.VITE_*` reads use them without requiring remote secrets, keeping server rendering consistent with the browser. Server-only keys still come from runtime bindings and are validated at boot.
 
-On Nuxt / Analog / Astro, `import { env }` works server-side through the same runtime proxy used on Class A targets — the proxy reads from the worker's `env` binding at request time. You're free to keep using the framework's native mechanism (`useRuntimeConfig()`, `event.context.cloudflare.env`, `import { env } from "cloudflare:workers"`, `Astro.locals.runtime.env`, `astro:env`) wherever it fits better — but you no longer _have_ to.
+Prerender path discovery can read route metadata without the deployed server secrets. Application requests, readiness checks, and actual page rendering still validate the runtime environment; a path generator that reads a required secret must have that value available.
 
-## Migration from untyped `c.env`
+## Validation and redaction
 
-If you don't have an `env.ts`, `c.env.X` continues to work as `unknown` — no breaking change. To opt in, create `env.ts`, declare your keys, and the existing call sites become typed automatically. The recommended access pattern for new code is `import { env } from "void/env"`.
+```sh
+void env check           # validate .env + shell for local development
+void env check --remote  # validate build-time client values and remote server names
+void env types           # regenerate .void/env.d.ts
+```
 
-## How it compares
+Invalid-value diagnostics redact the supplied value by default. Set `VOID_ENV_UNMASK=1` only for deliberate local debugging; Void prints a notice when redaction is disabled.
 
-`void/env` is a Void-only module — it isn't a standalone env library you'd pull into a Nuxt, SvelteKit, or bare-Vite project. This section exists so you can see what the integrated Void env story includes relative to what you'd otherwise assemble yourself on those stacks, not as a pick-one-of-many benchmark.
+There are no `.secret()` or `.public()` schema modifiers. Storage now follows the server/client boundary, and diagnostics follow one redaction rule.
 
-Most frameworks ship _parts_ of an env story — loading, typing, validation, deploy checks — but stitching them together is left to the user. Here's how Void's single `env.ts` stacks up against the tools people reach for on other stacks today.
+## Imports inside `env.ts`
 
-| Feature                                         | Void `env.ts` | `@t3-oss/env` | Astro `astro:env` | SvelteKit `$env` | Vite `import.meta.env` | Nuxt `runtimeConfig` | `dotenv` + `zod` (DIY) |
-| ----------------------------------------------- | :-----------: | :-----------: | :---------------: | :--------------: | :--------------------: | :------------------: | :--------------------: |
-| Single schema file                              |      yes      |      yes      |   yes (config)    |        no        |           no           |       partial        |          yes           |
-| Runtime validation                              |      yes      |      yes      |        yes        |        no        |           no           |          no          |          yes           |
-| Auto-generated types                            |      yes      |      yes      |        yes        |       yes        |   manual `env.d.ts`    |      yes (aug.)      |         manual         |
-| Bring-your-own validator (Standard Schema)      |      yes      |      yes      |        no         |        no        |           no           |          no          |          yes           |
-| Built-in helpers without installing a validator |      yes      |      no       |        yes        |        —         |           —            |          —           |           no           |
-| Build-time guard against leaking server env     |      yes      |      yes      |        yes        |       yes        |      prefix only       |     prefix only      |           no           |
-| Custom `envPrefix` honoured                     |      yes      |      yes      |        n/a        |       n/a        |          yes           |         n/a          |          n/a           |
-| Schema defaults flow into runtime bindings      |      yes      |    partial    |        yes        |        no        |           no           |       partial        |         manual         |
-| Async validators                                |      yes      |      no       |        no         |        no        |           no           |          no          |          yes           |
-| `.env.example` scaffolding from schema          |      yes      |      no       |        no         |        no        |           no           |          no          |           no           |
-| Deploy-time check (local + remote secrets)      |      yes      |      no       |        no         |        no        |           no           |          no          |           no           |
-| Automatic secret redaction in validation errors |      yes      |      no       |        no         |        no        |           no           |          no          |           no           |
-| Cloudflare secret store integration             |      yes      |      no       |        no         |        no        |           no           |          no          |           no           |
-| Zero-config (auto-discovered, no plugin wiring) |      yes      |      no       |        yes        |       yes        |          yes           |         yes          |           no           |
-| Schema scaffolded from existing `.env` files    |      yes      |      no       |        no         |        no        |           no           |          no          |           no           |
-| `${VAR}` expansion, no `process.env` leakage    |      yes      |      no       |        no         |        no        |    partial (leaks)     |          no          |      needs plugin      |
+Void loads `env.ts` through Node's native `import()` before Vite transforms application code. Use relative imports or package names for schema helpers and shared constants. TypeScript path aliases and imports requiring custom Vite transforms are not supported in this file.
 
-### Where Void differs
+## Migrating from the multi-file model
 
-- **One file, one call.** `defineEnv({...})` is the whole API surface. `@t3-oss/env` is the closest analogue but splits into `server`/`client`/`runtimeEnv` blocks and expects you to hand it `process.env`. Void auto-discovers `env.ts`, loads `.env*` via Vite's own resolver (honouring `envDir`), and wires the result into the plugin, the worker bundle, the CLI, and generated types without extra config.
-- **Helpers _and_ Standard Schema, mixable.** Most solutions force a choice: either Zod-only (t3-env, many DIY setups), or a bespoke helper DSL with no escape hatch (Astro, SvelteKit). Void ships `string()`, `number()`, `boolean()`, `url()`, `email()`, `oneOf()`, `json<T>()` so a small project pulls in zero validator dependencies, and any [Standard Schema](https://standardschema.dev) library (valibot, zod, arktype) drops into the same object for richer rules.
-- **Build-time leak prevention with source locations.** The `void:env-client-guard` plugin walks client module graphs and fails the build with a file:line:col pointer when a non-prefixed key is imported from the browser bundle. Vite on its own only enforces this through the _prefix convention_ — a renamed variable silently leaks. Void enforces both the prefix rule and the schema's server/client split.
-- **Build-time constant folding for client reads.** Production client builds inline static `env.VITE_FOO` reads as literals so `if (env.MODE === 'production') { … }` branches tree-shake the same way `import.meta.env.MODE` already does. Server / SSR / worker code keeps the runtime proxy untouched, and only prefix-matching keys are ever folded — no schema-required validation is bypassed because the same values still flow through `defineEnv` on boot.
-- **Defaults propagate everywhere.** `PORT: number().default(3000)` fills the typed proxy, the worker `vars` block in dev, the deploy manifest, and the prerender bindings — so `process.env.PORT`, `c.env.PORT`, and `env.PORT` all return `3000` when unset. t3-env and Nuxt only surface defaults in the typed object; the raw `process.env` still reads `undefined`.
-- **Deploy is the enforcement point.** `void deploy` unions `.env*` with the remote secret list and hard-fails on any missing required key _before_ upload. No competing solution in the table treats deploy as a validation gate — the closest substitute is a handwritten CI script calling `zod.parse(process.env)`, which doesn't know about the target platform's remote secrets.
-- **`.env.example` is generated, not maintained by hand.** `void env example` writes a marker-delimited block grouped into `required`, `with defaults`, `optional`, with enum hints for `oneOf` keys. Everything outside the markers (team CI tokens, comments) survives refresh. No other tool in the comparison ships this.
-- **Async validators.** A validator can return a `Promise` — useful for probing a URL, fetching a JWKS, or resolving a secret reference at startup. t3-env and schema-based systems assume synchronous parsing.
-- **Onboarding from an existing `.env`.** `void init` detects pre-existing dotenv files and writes a seeded `env.ts` with conservative type inference (boolean/URL/number/string) and a banner comment prompting you to tighten the guesses. Every other solution in the table requires you to hand-write the schema from scratch even when your team already has a `.env.example` committed.
+See [Environment migration](/guide/env-migration) for the breaking-change checklist.

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

@@ -4,9 +4,11 @@ outline: deep
 
 # What is Void?
 
-This guide explains how Void fits together before you dive into individual features. It starts with the mental model, then moves into routing, data, platform features, and deployment. If you want to get something running first, jump to [Quickstart](./quickstart).
+Void is a fullstack SDK for Vite apps. It connects your server code, database, and frontend types, and deploys your app to Cloudflare Workers. To try it, start with the [Quickstart](./quickstart).
 
-Void combines a Vite plugin, a backend SDK, and a deployment platform. Add one plugin to your app, and the imports in your code drive the infrastructure around it. A database, key-value store, object storage, AI inference, and deployment all line up without a separate layer of config files or dashboard setup.
+Add the Vite plugin to your app. As you use features such as a database, key-value storage, or queues, Void detects what you need and sets up the corresponding resources.
+
+The CLI and build tools require Node.js 24.21.0 or later.
 
 ```sh
 npm install -D vite void
@@ -22,34 +24,30 @@ export default defineConfig({
 ```
 
 ```sh
+void init   # choose your framework and deployment target
 void deploy
-# app live at <your-subdomain>.void.app!
 ```
 
 ## The idea
 
-With most stacks, your app and its platform do not talk to each other directly. You end up stitching them together with config files, environment setup, resource provisioning, and deployment scripts. Once the app is live, caching, scaling, and limits often live in a separate control plane too.
+Your code often already describes the resources it needs. Import `db` from `void/db`, for example, and Void provides a database for local development and provisions its production resource when you deploy. The same pattern applies to `kv`, `storage`, queues, and AI.
 
-Void closes that gap. It connects your app directly to the platform through Vite. Import `db` from `void/db` and you have a database in local development plus the matching production resource on deploy. The same idea applies to `kv`, `storage`, queues, and AI. In most cases, the code already describes what the platform needs to provision.
+Types follow your data through the app: from a Drizzle schema to a route handler, then to the frontend calling that route. You can change a field in one place and let TypeScript show you the code that needs updating.
 
-This is what it unlocks:
+Void brings these pieces together:
 
-- **Write code, not config:** no infrastructure files, no dashboard clicks, and no manual resource declarations. Your imports are the contract.
+- **Resources from your code:** imports tell Void which supported resources to provision. Use `void.json` or your Cloudflare config when you need to customize them.
 - **Types from database to frontend:** your Drizzle schema defines DB types, route handlers infer return types, and the [typed fetch client](./typed-fetch.md) checks calls at the usage site. One [Standard Schema](https://standardschema.dev/) validator can drive both runtime validation and compile-time types.
-- **Real runtime in development:** `vite dev` runs your server code in the same runtime used in production, with local database, KV, and storage.
+- **Local Cloudflare development:** native Void apps run server code in `workerd`, with local database, KV, and storage.
 - **Deploy that understands the app:** `void deploy` reads your migrations, provisions the resources you actually use, and ships the result to the edge.
 
 ## The platform
 
-Void deploys to [Cloudflare Workers](https://developers.cloudflare.com/workers/). Your server code runs at the edge, close to users, and scales without extra platform work on your side.
+Void deploys to [Cloudflare Workers](https://developers.cloudflare.com/workers/). You can use your own Cloudflare account or connect to a Void platform managed by your team. Both use the same SDK and CLI.
 
-- [Static assets](./edge/static-assets) are served from the edge with proper cache headers. [Incremental revalidation](./edge/revalidation) (ISR) and [prerendering](./edge/prerendering) let you cache dynamic pages while keeping data fresh.
-- Database reads are fast everywhere via D1's read replication.
-- Custom domains with automatic TLS.
-- Secrets and environment variables managed via CLI or dashboard, scoped per project.
-- A dashboard for deployments, usage metrics, and project settings.
+[Static assets](./edge/static-assets) are cached at the edge. [Prerendering](./edge/prerendering) builds pages ahead of time, while [incremental revalidation](./edge/revalidation) caches pages rendered on demand. Database, storage, secrets, and deployment commands are available through Void.
 
-You do not need a Cloudflare account or Cloudflare-specific knowledge to get started. If you want full control later, every build still produces a standard Cloudflare Worker, so you can [self-host](../integrations/cloudflare#deploy-to-your-own-cloudflare-account) with your own `wrangler.json`.
+For a single app, [deploy to your own account](../integrations/cloudflare#deploy-to-your-own-cloudflare-account). To give a team a shared deployment service, [install a Void platform](./self-hosted-platform.md), then let developers connect to its URL.
 
 ## How it works
 
@@ -61,7 +59,7 @@ import { storage }            →  R2 bucket (auto-provisioned)
 import { ai }                 →  Workers AI inference (metered)
 db/schema.ts                  →  Drizzle schema (source of truth for DB types)
 db/migrations/*.sql           →  Applied to D1 on deploy
-void deploy                   →  Live at https://<slug>.void.app
+void deploy                   →  Deploy to the saved Cloudflare or Void target
 ```
 
 The plugin scans your source code at build time, detects which imports you use, and provisions the corresponding Cloudflare bindings on deploy.
@@ -70,7 +68,7 @@ Void also works with existing frameworks. [TanStack Start](/integrations/framewo
 
 If you are building a full-stack app without a meta-framework, Void also gives you [file-based server routing](./server-routing) with method exports, dynamic params, middleware, and validation. It also includes [pages routing](./pages-routing/overview) for server-rendered UI, SPA navigation, co-located data loading, and typed forms across React, Vue, Svelte, and Solid.
 
-Void auto-detects your [app type](./app-types) and adapts accordingly.
+Void detects your [app type](./app-types) and chooses the appropriate build and deployment flow.
 
 ## Next steps