void 0.1.6 → 0.7.0

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

@@ -0,0 +1,298 @@
+---
+outline: deep
+---
+
+# Environment Variables
+
+Void provides typed, validated environment variables via a single `env.ts` file at the root of your project. The schema serves three purposes:
+
+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
+
+## `env.ts` (recommended)
+
+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.
+:::
+
+```ts
+// env.ts
+import { defineEnv, string, number, boolean, oneOf, url } from 'void/env';
+
+export default defineEnv({
+  STRIPE_KEY: string(),
+  PORT: number().default(3000),
+  NODE_ENV: oneOf(['development', 'production']),
+  WEBHOOK_URL: url(),
+  DEBUG: boolean().optional(),
+  VITE_APP_TITLE: string(),
+});
+```
+
+Then read values from anywhere in your app:
+
+```ts
+import { env } from 'void/env';
+
+console.log(env.STRIPE_KEY); // typed as string
+console.log(env.PORT); // typed as number
+```
+
+`c.env.STRIPE_KEY` inside Hono handlers is also typed once the schema is declared.
+
+### Built-in helpers
+
+`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.
+
+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:
+
+```ts
+import * as v from 'valibot';
+
+export default defineEnv({
+  STRIPE_KEY: string(), // built-in
+  WEBHOOK_URL: v.pipe(v.string(), v.url(), v.endsWith('/webhook')), // valibot
+});
+```
+
+### 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.
+
+### Build-time constant folding
+
+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();
+```
+
+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.
+
+### `envDir`
+
+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.
+
+### 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:
+
+| File                    | Loaded in dev | Shipped on deploy  |
+| ----------------------- | ------------- | ------------------ |
+| `.env`                  | yes           | yes (`plain_text`) |
+| `.env.local`            | yes           | no                 |
+| `.env.production`       | yes           | yes (`plain_text`) |
+| `.env.production.local` | yes           | no                 |
+
+`.local` files are gitignored by convention — use them for secrets you don't want in source control.
+
+### 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)
+```
+
+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.)
+
+## 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
+```
+
+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 both:
+
+- 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.
+
+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.           |
+
+Use `void env check --remote` in CI before deploying — it catches missing prod secrets without running a full build.
+
+## Manual type regeneration
+
+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):
+
+```bash
+void env types
+```
+
+## Scaffolding `.env.example`
+
+Generate (or refresh) a `.env.example` from your `env.ts` schema:
+
+```bash
+void env example           # creates or refreshes the void-managed block
+void env example --force   # silences the "appended block" notice (use in CI)
+```
+
+`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:
+
+```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 <<<
+```
+
+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               |
+
+What you always get, regardless of framework:
+
+- `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.
+
+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.
+
+## Migration from untyped `c.env`
+
+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"`.
+
+## How it compares
+
+`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.
+
+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.
+
+| 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      |
+
+### Where Void differs
+
+- **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.

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

@@ -0,0 +1,80 @@
+---
+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 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.
+
+```sh
+npm install -D vite void
+```
+
+```ts
+import { defineConfig } from 'vite';
+import { voidPlugin } from 'void';
+
+export default defineConfig({
+  plugins: [voidPlugin()],
+});
+```
+
+```sh
+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.
+
+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.
+
+This is what it unlocks:
+
+- **Write code, not config:** no infrastructure files, no dashboard clicks, and no manual resource declarations. Your imports are the contract.
+- **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.
+- **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.
+
+- [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.
+
+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`.
+
+## How it works
+
+```
+vite.config.ts                →  voidPlugin() (works with any Vite app)
+import { db }                 →  D1 database (auto-provisioned)
+import { kv }                 →  KV namespace (auto-provisioned)
+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
+```
+
+The plugin scans your source code at build time, detects which imports you use, and provisions the corresponding Cloudflare bindings on deploy.
+
+Void also works with existing frameworks. [TanStack Start](/integrations/frameworks/tanstack-start), [React Router](/integrations/frameworks/react-router), [SvelteKit](/integrations/frameworks/sveltekit), [Nuxt](/integrations/frameworks/nuxt), and [Astro](/integrations/frameworks/astro) can all deploy with the same `voidPlugin()`.
+
+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.
+
+## Next steps
+
+- [Quickstart](./quickstart): get a running app in minutes
+- [Server Routing](./server-routing): dynamic params, middleware, and validation
+- [Pages Routing](./pages-routing/overview): full-stack pages with server loaders and actions
+- [Supported App Types](./app-types): full-stack, meta-framework, and static site modes

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

@@ -0,0 +1,91 @@
+---
+outline: deep
+---
+
+# Cron Jobs
+
+Void supports cron-triggered jobs from a top-level `crons/` directory.
+
+## Job files
+
+Create files in `crons/**/*.ts` (`.mts`, `.js`, `.mjs` also supported).
+
+Each job file must export:
+
+- `export const cron = "<expression>"` (or an array of expressions)
+- a default handler (recommended: wrapped with `defineScheduled`)
+
+Example:
+
+```ts
+// crons/hourly-heartbeat.ts
+import { defineScheduled } from 'void';
+
+export const cron = '0 * * * *';
+
+export default defineScheduled(async (controller, env) => {
+  await env.KV.put('jobs:last-heartbeat', controller.scheduledTime.toString());
+});
+```
+
+### Multiple schedules
+
+A single job file can export an array of cron expressions:
+
+```ts
+// crons/cleanup.ts
+import { defineScheduled } from 'void';
+
+export const cron = ['0 * * * *', '30 * * * *'];
+
+export default defineScheduled(async (controller, env) => {
+  // Runs at :00 and :30 every hour
+});
+```
+
+## `defineScheduled`
+
+`defineScheduled(fn)` is a typed identity helper for scheduled jobs.
+
+Handler signature:
+
+```ts
+(controller: ScheduledController, env: CloudEnv['Bindings'], ctx: ExecutionContext) =>
+  unknown | Promise<unknown>;
+```
+
+Notes:
+
+- Jobs are matched by exact cron string.
+- Job modules are lazy-loaded at runtime.
+- Files or directories starting with `_` are ignored.
+- Missing `cron` export causes an error during scan/build.
+
+## Local development
+
+Cron triggers do not fire on their schedule during local dev — this is a Cloudflare Workers / miniflare limitation, not specific to Void. Exercise a job locally by POSTing to the dev endpoint Void exposes:
+
+```
+POST /__void/scheduled
+Content-Type: application/json
+{ "cron": "<expression>", "scheduledTime": <unix_ms> }
+```
+
+The `cron` value must match a string you exported from a `crons/*.ts` file — that's how the dispatcher routes to the right handler. Returns `{ "ok": true }` on success.
+
+The endpoint requires a local dev trigger token. Void prints a paste-ready curl command with the current token when the dev server starts.
+
+```bash
+curl -X POST http://localhost:5173/__void/scheduled \
+  -H "Content-Type: application/json" \
+  -H "x-void-dev-trigger: <printed-token>" \
+  -d '{"cron":"0 * * * *","scheduledTime":'"$(date +%s000)"'}'
+```
+
+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.
+
+This works the same in default Void mode and every supported framework — SvelteKit, Nuxt, Analog, Astro, TanStack Start, React Router, and vinext. In framework mode the cron handler runs inside the framework adapter's request pipeline (or the dev miniflare for Class A frameworks), so it sees whatever bindings the adapter exposes (D1, KV, R2, queues, AI, etc.).
+
+## Deployment behavior
+
+On deploy, Void includes all discovered job schedules in the deploy manifest and configures worker cron triggers automatically.

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

@@ -0,0 +1,107 @@
+---
+outline: deep
+---
+
+# Key-Value Storage
+
+Void provides a typed KV client with automatic JSON serialization for [Cloudflare Workers KV](https://developers.cloudflare.com/kv/). Import `kv` from `void/kv` and start reading and writing data.
+
+## Basic Operations
+
+### Get
+
+```ts
+import { kv } from 'void/kv';
+
+const user = await kv.get<User>('user:123');
+// User | null
+```
+
+Values are automatically parsed as JSON. If the stored value isn't valid JSON, the raw string is returned.
+
+### Put
+
+```ts
+await kv.put('user:123', { name: 'Alice', role: 'admin' });
+```
+
+Objects are automatically JSON-stringified. Strings are stored as-is.
+
+Add a TTL (in seconds) or absolute expiration (Unix timestamp):
+
+```ts
+await kv.put('session:abc', sessionData, { ttl: 3600 });
+await kv.put('token:xyz', tokenData, { expiration: 1700000000 });
+```
+
+Attach metadata to a key:
+
+```ts
+await kv.put('user:123', userData, {
+  metadata: { updatedBy: 'admin' },
+});
+```
+
+### Delete
+
+```ts
+await kv.delete('user:123');
+```
+
+### List
+
+```ts
+const result = await kv.list({ prefix: 'user:' });
+// { keys: [{ name: "user:1" }, { name: "user:2" }], list_complete: true }
+```
+
+Paginate with `limit` and `cursor`:
+
+```ts
+const page = await kv.list({ prefix: 'user:', limit: 100 });
+if (!page.list_complete) {
+  const next = await kv.list({ prefix: 'user:', limit: 100, cursor: page.cursor });
+}
+```
+
+### Get with Metadata
+
+```ts
+const result = await kv.getWithMetadata<User, { updatedBy: string }>('user:123');
+// { value: User | null, metadata: { updatedBy: string } | null }
+```
+
+## Typed Maps
+
+For collections of the same type, use `kv.map()` to create a scoped, typed client with automatic key prefixing:
+
+```ts
+const sessions = kv.map<Session>('sessions');
+
+await sessions.put('abc', { userId: 1, token: '...' }, { ttl: 3600 });
+// KV key: "sessions:abc"
+
+const session = await sessions.get('abc');
+// Session | null
+
+await sessions.delete('abc');
+```
+
+The map automatically prefixes all keys with `"sessions:"` and strips the prefix when listing:
+
+```ts
+const result = await sessions.list();
+// keys: [{ name: "abc" }, { name: "def" }]  (prefix stripped)
+```
+
+Maps have the same methods as the base client (`get`, `put`, `delete`, `list`, `getWithMetadata`) but with a typed value and automatic prefixing.
+
+## How It Works
+
+The KV client is a thin wrapper over the Cloudflare KV API that adds two things:
+
+1. **Auto serialization:** `put()` calls `JSON.stringify()` on non-string values. `get()` calls `JSON.parse()` with a fallback to the raw string for values that are not JSON. You can store and retrieve objects without manual serialization.
+
+2. **Typed maps:** `kv.map<T>(prefix)` returns a scoped client where all keys are prefixed with `"prefix:"` and values are typed as `T`. This is useful for organizing related data such as sessions, cache entries, and feature flags without manually managing prefixes.
+
+> **Escape hatch:** The `kv` client covers the most common KV operations. For advanced use cases like `getWithMetadata` with specific cache behaviors, you can access the raw `KVNamespace` binding via `c.env.KV` in a route handler.