void 0.10.12 → 0.20.0

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

@@ -4,7 +4,7 @@ outline: deep
 
 # Cron Jobs
 
-Void supports cron-triggered jobs from a top-level `crons/` directory.
+Put scheduled jobs in `crons/`. Each file declares a cron expression and a handler, and Void configures the schedule when you deploy.
 
 ## Job files
 
@@ -45,7 +45,7 @@ export default defineScheduled(async (controller, env) => {
 
 ## `defineScheduled`
 
-`defineScheduled(fn)` is a typed identity helper for scheduled jobs.
+Wrap a handler with `defineScheduled()` to get types for the scheduled event, environment, and execution context.
 
 Handler signature:
 
@@ -57,13 +57,14 @@ Handler signature:
 Notes:
 
 - Jobs are matched by exact cron string.
+- When jobs share an expression, each matching job runs once per invocation. Void waits for all matching jobs, even if one fails, then reports any failures. Native triggers and managed deliveries are deduplicated by expression.
 - 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:
+Schedules don't fire automatically in local development. Test a job by sending a request to Void's development endpoint:
 
 ```
 POST /__void/scheduled
@@ -82,10 +83,12 @@ curl -X POST http://localhost:5173/__void/scheduled \
   -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.
+If you set `__VOID_PROXY_TOKEN` in `.env`, that explicit token takes precedence and the printed curl command uses `x-void-internal: <your-token>` instead.
 
-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.).
+The endpoint works in native Void apps and supported frameworks. Framework jobs run in the adapter's development runtime and use the bindings it provides.
 
 ## Deployment behavior
 
 On deploy, Void includes all discovered job schedules in the deploy manifest and configures worker cron triggers automatically.
+
+Native scheduled events do not require a manual HTTP token. For framework deployments, HTTP requests to `/__void/scheduled` require a matching `x-void-internal` token: the managed platform supplies its proxy token, or you can explicitly configure `CRON_SECRET` for manual calls. An absent or mismatched token returns `401` without running a job.

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

@@ -4,17 +4,13 @@ outline: deep
 
 # Live Event Streams
 
-`void/live` provides Durable Object-backed fanout over Server-Sent Events. Use it
-when one browser tab needs a single SSE connection that can subscribe and
-unsubscribe from many application topics over time.
+`void/live` lets a browser subscribe to several topics over one SSE connection. Publish an event from a route, scheduled job, or queue consumer, and Void delivers it to connected subscribers using Durable Objects.
 
-Use `void/sse` for request-owned streams where the producer lives inside the same
-route handler. Use `void/live` when later requests, mutations, scheduled jobs, or
-queue consumers need to publish to clients that are already connected.
+For example, a page can subscribe to updates for a post and its comments, then change those subscriptions as the user navigates. If a single request produces the whole stream, such as an AI response, [`void/sse`](./sse.md) is enough.
 
 ## Define A Stream
 
-Create a server-only live stream descriptor:
+Define a stream in a server-only module:
 
 ```ts
 // src/live.ts
@@ -95,9 +91,7 @@ await live.publish(
 );
 ```
 
-Topics are opaque strings. Payloads are application-owned JSON. `type` and
-`eventId` are copied into the JSON envelope; `void/live` does not interpret
-them, persist them, or use native SSE `id` fields.
+Choose your own topic names and JSON payloads. Void includes `type` and `eventId` in the event envelope without interpreting or storing them. It doesn't use native SSE `id` fields.
 
 If you are outside an active request/runtime context, pass env explicitly:
 
@@ -209,12 +203,11 @@ export const live = defineLiveStream({
 });
 ```
 
-`maxSubscriptionsPerTopic` cannot be raised above `256`. For larger broadcast
-workloads, shard topics in userland or use a dedicated realtime system.
+`maxSubscriptionsPerTopic` cannot be raised above `256`. For larger broadcasts, split subscribers across application topics or use a dedicated realtime system.
 
 ## Delivery Semantics
 
-`void/live` is an at-most-once live fanout primitive:
+Live delivery is at most once: clients may miss events, and Void doesn't replay them automatically.
 
 - one SSE connection can hold many topic subscriptions
 - publish cost is proportional to subscribers of the topic
@@ -222,8 +215,7 @@ workloads, shard topics in userland or use a dedicated realtime system.
 - clients using the raw HTTP protocol must resubscribe after reconnect
 - deploys, rollbacks, Worker restarts, browser reconnects, and network changes
   can drop live state
-- durable replay, cache invalidation, live queries, and client state management
-  belong in userland
+- your app handles replay, cache invalidation, live queries, and client state
 
 Use an application database, queue, or custom Durable Object for replay. Use
 `eventId` and caller-provided `lastEventId` values as application protocol

package/skills/void/docs/guide/pages-routing/actions-and-forms.md

@@ -4,7 +4,7 @@ outline: deep
 
 # Actions & Forms
 
-Actions handle mutations (POST, PUT, PATCH, DELETE) in companion `.server.ts` files. They use the same `defineHandler` API as [loaders](./loaders) and [server routes](../server-routing.md), with the same typed `c.env` bindings, `withValidator()` support, and Hono context methods.
+Use an action to change server data from a form or button. Define it in the page's `.server.ts` file with `defineHandler`, just like a [loader](./loaders) or [server route](../server-routing.md). Actions handle `POST`, `PUT`, `PATCH`, and `DELETE` requests.
 
 ## Defining an Action
 
@@ -263,7 +263,7 @@ const form = useForm('/users/:id?update', { name: '' }, { params: { id } });
 <form action={form.put}>{/* submits to /users/42?update */}</form>
 ```
 
-The URL, body fields, and error keys are typed per action. Each named action gets its own validator schema. See [Type Safety: Action -> useForm](../type-safety#action-useform) for the full typing story.
+Each named action has its own validator schema, which supplies types for its URL, body, and error keys. See [Type Safety](../type-safety#action-%E2%86%92-useform) for an example.
 
 ## `action()` Helper
 
@@ -285,13 +285,17 @@ if (!result.ok) {
 }
 ```
 
-`action()` is useful in event handlers such as button clicks, confirmation dialogs, or any place where you want to call a server action without managing form state. It uses `POST` by default and accepts `{ data, method, params }`, where `method` can be `'PUT'`, `'PATCH'`, or `'DELETE'` for alternate HTTP methods. It returns `{ ok: true, pageData }` for successful actions and `{ ok: false, error }` for call-site errors such as validation, conflicts, or missing resources.
+Call `action()` from a button or another event handler when you don't need form state. It defaults to `POST`; pass `{ data, method, params }` to set the body, route parameters, or a `PUT`, `PATCH`, or `DELETE` method.
+
+A successful call returns `{ ok: true, pageData }`. Expected errors, such as validation failures or conflicts, return `{ ok: false, error }`.
 
 ## Validation Errors
 
 When an action throws a `ValidationError`, or validation fails through `withValidator`, the errors are automatically available on `form.errors`. You do not need to wire that up manually.
 
-Void separates action failures into call-site errors and boundary errors. Call-site errors are expected local failures such as `400`, `404`, `409`, `422`, and `429`; `useForm` stores them in `form.errors` or `form.error`, and `action()` returns `{ ok: false, error }`. Boundary errors such as `401`, `403`, `500`, `502`, and unknown network/protocol failures are thrown so React error boundaries, or your framework's error handling, can handle them at a higher level.
+Expected errors such as `400`, `404`, `409`, `422`, and `429` stay with the form or action call. `useForm` stores them in `form.errors` or `form.error`; `action()` returns `{ ok: false, error }`.
+
+Authentication errors (`401`, `403`), server errors (`500`, `502`), and unknown network or protocol failures are thrown. Handle them with your framework's error boundary or error handling.
 
 Actions can throw `ValidationError` for custom validation logic:
 

package/skills/void/docs/guide/pages-routing/islands.md

@@ -45,9 +45,9 @@ function mixedItems(ext) {
 
 # Islands
 
-Islands mode is a partial hydration architecture inspired by [Astro](https://docs.astro.build/en/concepts/islands/). Instead of hydrating the whole page on the client, only the interactive components, or "islands," ship JavaScript to the browser. The rest of the page stays as static server-rendered HTML.
+Islands let you add interactive components to an otherwise static page. The server renders the page as HTML, and only the components marked as islands send JavaScript to the browser. This approach is inspired by [Astro](https://docs.astro.build/en/concepts/islands/).
 
-This gives you the best of both worlds: fast initial page loads with minimal client-side JavaScript, plus rich interactivity exactly where you need it.
+For example, a blog post can keep its article content static while loading JavaScript for a comment form or audio player.
 
 ::: tip Prerequisites
 Islands mode builds on top of [Pages Routing](./overview). You need a working Pages setup (framework adapter installed, `pages/` directory, Vite config) before using islands.
@@ -214,7 +214,7 @@ export const action = defineHandler(async (c) => {
 });
 ```
 
-The key difference is what happens after a successful action. On a regular page, the Inertia protocol redirects and the Void Router fetches fresh props as JSON. On an island page, there is no Void Router, so successful actions cause a full page reload or a redirect through `window.location`.
+After a successful action, an island page reloads or redirects through `window.location`. Regular Pages routes use the Void Router to fetch fresh props instead.
 
 ## Forms
 

package/skills/void/docs/guide/pages-routing/loaders.md

@@ -4,7 +4,7 @@ outline: deep
 
 # Loaders & Props
 
-Every page can have a companion `.server.ts` file that exports a `loader`. Server handlers use the same `defineHandler` API as [server routes](../server-routing.md), so you get the same typed `c.env` bindings and Hono context methods.
+A loader fetches the data a page needs. Define it in a companion `.server.ts` file using the same `defineHandler` API as [server routes](../server-routing.md).
 
 ## Defining a Loader
 
@@ -38,7 +38,7 @@ export const loader = defineHandler<Props>(async (c) => {
 
 ## Using the Data in Page Components
 
-The component receives loader data as props. Export the props type from your `.server.ts` file to keep the contract in one place:
+The page component receives the loader's result as props. Export the inferred type from the server file so the component stays in sync:
 
 ::: code-group
 
@@ -131,7 +131,7 @@ export const loader = defineHandler(async (c) => {
 });
 ```
 
-The page renders immediately with `projects` available. The `usage` prop is a framework-native deferred resource: React consumes it with Suspense and `use()`, while the other adapters expose a `{ loading, value, error }` state object.
+The page can render `projects` while `usage` is still loading. In React, read `usage` with `use()` inside Suspense. Other adapters expose it as `{ loading, value, error }`.
 
 ### Handling Deferred State
 
@@ -237,7 +237,9 @@ export default function Dashboard(props: Props) {
 
 ### How Streaming Works
 
-On the initial page load (SSR), React uses React 19 streaming SSR and renders the nearest Suspense fallback for deferred props; the other adapters render their loading state. As each deferred function resolves, the server streams an inline `<script>` tag that delivers the data, so no extra HTTP request is needed. Routes with `export const ssr = false` skip server-rendered component HTML but still stream deferred resolution scripts after the client-mounted shell. On SPA navigation, deferred data streams via NDJSON over the same response.
+On the first request, React renders the nearest Suspense fallback for deferred props; the other adapters render their loading state. As data becomes available, the server sends it in inline scripts on the same response.
+
+A route with `ssr = false` still receives those scripts, even though its component mounts in the browser. During client-side navigation, deferred data arrives as newline-delimited JSON on the navigation response.
 
 ### Deferred Props After Mutations
 

package/skills/void/docs/guide/pages-routing/overview.md

@@ -4,15 +4,15 @@ outline: deep
 
 # Pages Routing
 
-Pages routing provides the server-rendered, components-as-pages, collocated-data-loading routing system that is seen in many existing JavaScript meta frameworks. However, pages routing in Void is different from most in that it is **rendering framework agnostic.** It is built on patterns inspired by [Inertia.js](https://inertiajs.com/): The server returns the data, and the component receives it as props. The client-side routing logic is minimal, allowing Void to support any rendering framework Vite can support. Today, React, Vue, Svelte, and Solid have first-party adapters.
+Put UI components in `pages/` to make them routes. A page's server loader returns data, and the component receives it as props. This pattern is inspired by [Inertia.js](https://inertiajs.com/) and works with React, Vue, Svelte, and Solid.
 
-Pages mode activates when a `pages/` directory exists. It coexists with `routes/`. Use `pages/` for UI pages and `routes/` for APIs. Components in `pages/` are server-rendered, which means **they run in both Cloudflare Workers and browsers**.
+Pages mode starts when a `pages/` directory exists. It can live alongside `routes/`: use pages for UI and routes for APIs. Page components normally run on the server for the first render and in the browser for navigation and interaction.
 
-Pages mode is also entirely optional - you can use any client-side router to build a pure client-side SPA that interacts with the backend API via the [typed fetch](../typed-fetch.md) utility.
+You can also use your own client-side router and call Void's APIs with [typed fetch](../typed-fetch.md). Pages mode is optional.
 
 ## Setup
 
-If you start in a scaffoldable empty directory, `void init` can generate this setup for you: it asks whether to scaffold with Vite+ (the default) or plain Vite, asks whether you want React, Vue, Svelte, or Solid Pages mode, then lets you pick a D1 starter, a PostgreSQL starter, or Static Pages. The database-backed starters write the adapter-aware `vite.config.ts`, `pages/`, and `db/` starter files; Static Pages writes just the basic `pages/` setup so you can grow into server features later.
+In an empty project, `void init` can set up Pages for you. Choose Vite+ or plain Vite, then React, Vue, Svelte, or Solid and a database or static starter. The generated app includes the matching Vite config and page files.
 
 If you're adding Pages mode manually, install a framework adapter alongside `void`:
 
@@ -86,7 +86,7 @@ export default defineConfig({
 
 :::
 
-That is the full setup. You do not need an SSR entry, a client entry, or hydration boilerplate because the adapter generates them for you.
+The adapter generates the server entry, client entry, and hydration code.
 
 Each adapter plugin includes the framework's Vite plugin (`@vitejs/plugin-react`, `@vitejs/plugin-vue`, `@sveltejs/vite-plugin-svelte`, `vite-plugin-solid`) so you don't need to install or configure it separately. Pass framework plugin options via `voidReact({ react: { ... } })`, `voidVue({ vue: { ... } })`, `voidSvelte({ svelte: { ... } })`, or `voidSolid({ solid: { ... } })` if needed.
 
@@ -106,7 +106,7 @@ File-based routing rules are the same as [server routing](../server-routing.md):
 
 ## How Navigation Works
 
-Pages uses an Inertia-style protocol under the hood:
+The first page load and later navigations use the same server loaders:
 
 | Request               | Response                                                                                                       |
 | --------------------- | -------------------------------------------------------------------------------------------------------------- |
@@ -114,7 +114,7 @@ Pages uses an Inertia-style protocol under the hood:
 | Subsequent navigation | JSON with component name + props. Client component swap or re-render.                                          |
 | Form submission       | Runs action, then returns fresh props or a redirect.                                                           |
 
-This means the first page load is server-rendered for SEO and performance, while later navigations stay fast without full page reloads.
+The first request receives rendered HTML. Later navigations load page data and update the UI without reloading the whole document.
 
 To opt a specific route out of server-rendered component HTML, export `ssr = false` from its companion `.server.ts` file:
 

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

@@ -0,0 +1,212 @@
+---
+outline: deep
+---
+
+# Platform Administration
+
+`void platform` lets you manage the people and apps on a Void platform from your terminal. You can give teammates access, inspect their projects, follow deployment logs, and check the platform's health.
+
+These commands require an administrator account. If you're setting up a platform for the first time, start with [Install a Void Platform](./self-hosted-platform.md).
+
+## Signing In
+
+For the browser dashboard, open `<API URL>/admin` and sign in with GitHub. On a new installation, signing in with the administrator account selected during setup creates the first admin user. You do not need to create an app or sign in through the CLI first.
+
+Connect to your platform's API URL, then sign in as an administrator:
+
+```sh
+void connect https://platform.example.com --no-login
+void platform auth login
+```
+
+The first command saves the connection. The second opens your browser to sign in and saves an administrator session in your system keychain. Sessions last for one hour and are stored separately for each platform.
+
+You can check which account is signed in at any time:
+
+```sh
+void platform auth status
+```
+
+This shows your account, the session's expiry, and the features available on the platform. To end the session, run `void platform auth logout`.
+
+## Choosing a Platform
+
+If you manage more than one platform, list your connections and choose a default:
+
+```sh
+void platform list
+void platform use <connection-id>
+```
+
+You can also select a platform for a single command with `--connection`:
+
+```sh
+void platform user list --connection <connection-id>
+```
+
+Use an ID or URL from the connection list. Administrative commands use this selection even when you run them inside an app with a different deployment destination.
+
+## Giving People Access
+
+A newly installed platform restricts signup to approved identities. To let a teammate join with GitHub, add their login to the allowlist:
+
+```sh
+void platform signup allow github teammate
+```
+
+Void shows the change and asks you to confirm it. The teammate can then run `void connect` with the platform's URL and sign in.
+
+You can allow an email address or a whole email domain in the same way:
+
+```sh
+void platform signup allow email teammate@example.com
+void platform signup allow email '*@example.com'
+```
+
+Email patterns apply across the platform's sign-in providers. Quote a domain pattern so your shell passes the `*` to Void.
+
+To invite someone else by email, use:
+
+```sh
+void platform invitation send alex@example.org
+```
+
+An invitation grants signup access and sends an email when the platform has email delivery configured. If delivery is unavailable or fails, the result tells you; the person can still join using the platform's URL.
+
+Inspect the current access settings and invitations with:
+
+```sh
+void platform signup show
+void platform invitation list
+```
+
+Invitation history remains available after an involved account is removed. The stored actor ID
+remains visible when that account's login no longer exists.
+
+`void platform signup open` allows anyone to sign up. Use `void platform signup restrict` to require an allowlist match again. Removing an allowlist entry affects future signup; it does not suspend an existing account.
+
+## Managing Users and Projects
+
+Start by finding the user you want to inspect:
+
+```sh
+void platform user list --search teammate
+void platform user show <user-id>
+```
+
+Use the ID from the list in the second command. The detail view shows the user's projects and usage. You can change their plan or list just their projects:
+
+```sh
+void platform user plan <user-id> pro
+void platform project list --user <user-id>
+void platform project show <project-id>
+```
+
+Project details include resources, domains, and recent builds and deployments. The [command reference](../reference/cli.md#operator-commands) also covers suspending and restoring users, deleting projects, and removing accounts.
+
+New users on a self-hosted installation start with the `custom` profile, which
+does not cap application requests, AI usage, deployment frequency, or retained
+Worker deployments. Named profiles such as `pro` apply the platform's quota and
+retention policies; they do not purchase Cloudflare services or bill your users.
+Storage figures are not a hard storage-quota boundary. Set an operating budget
+and retention policy before opening signup beyond your invited team.
+
+The last active administrator cannot be deleted or suspended, including through
+the browser admin UI. Another administrator must still have access. Automatic
+usage limits do not remove administrator access and do not count as a manual
+suspension.
+
+When removing another administrator, Void revokes their administrator access
+before changing application traffic or deleting resources. If cleanup fails,
+access stays revoked and the error describes the partial result. A remaining
+administrator can inspect it and retry cleanup.
+
+## Previewing Changes
+
+Commands that change the platform show the affected objects before asking for confirmation. To inspect a change without applying it, add `--plan`:
+
+```sh
+void platform user suspend <user-id> --reason "Investigating unexpected traffic" --plan
+```
+
+The preview shows which account will be suspended and the effect on its projects. Run the command again without `--plan` to confirm interactively, or use `--yes` when the change is ready to apply:
+
+```sh
+void platform user suspend <user-id> --reason "Investigating unexpected traffic" --yes
+```
+
+Scripts must use `--yes` to apply these changes. Authentication commands run directly and do not use `--plan` or `--yes`. After a change, `void platform system events` shows the administrator, affected objects, and recorded outcome.
+
+Changes can take longer when an account owns many resources. Requests that change the platform allow five minutes by default; use `--timeout` to set a different limit in seconds:
+
+```sh
+void platform user delete <user-id> --timeout 600 --plan
+```
+
+If a request times out or loses its connection, some work may already have finished. Check the affected objects and `system events` before retrying. Void reports partial results when it can and does not automatically repeat the change.
+
+## Following Logs
+
+To investigate a deployment, find its ID and follow its runtime logs:
+
+```sh
+void platform deployment list --project <project-id>
+void platform deployment logs <deployment-id> --since 10m --follow
+```
+
+Runtime logs include application messages, exceptions, and HTTP status codes. Without `--follow`, the command reads a page of historical logs. Use `--since` to choose a duration, an ISO date, or a timestamp in milliseconds.
+
+Logs can become available after a request finishes. Following checks a five-minute overlap to pick up delayed records without printing them again. Records delayed longer than that may need a later historical query.
+
+Build logs use the build's ID:
+
+```sh
+void platform build logs <build-id> --follow
+```
+
+Following waits for the final logs before stopping, including diagnostics written after the build's status changes. For a GitHub Actions build, the command gives you the URL of its logs.
+
+## Checking the Platform
+
+Use the overview to see recent activity, or run a health check to test the platform's services and database:
+
+```sh
+void platform system overview
+void platform system health
+```
+
+Health checks use the services configured for the selected platform. An unhealthy result exits with a nonzero status, so the same command can be used in a script.
+
+The browser dashboard's **System Status** checks refresh every 30 seconds. Failed checks show an HTTP status or connection error beside the service name. If the dashboard cannot refresh the checks, it reports that status is unavailable instead of displaying stale results.
+
+Use `void platform upgrade`, `repair`, `disable`, and `enable` to maintain your platform. See [platform maintenance](./self-hosted-platform.md#resume-repair-recover-and-upgrade).
+
+For disaster recovery, keep a matching PostgreSQL backup, provider data backups, installation identity and complete project-encryption keyring, and immutable runtime artifacts. Keep traffic disabled while restoring data, run `discover` to reconstruct verified local metadata, and review `repair --plan` before recreating missing installer-owned infrastructure. Neither command restores backed-up data. See [Prepare for disaster recovery](./self-hosted-platform.md#prepare-for-disaster-recovery) for the full sequence.
+
+## Using Scripts
+
+Add `--json` to read a command's result from another program:
+
+```sh
+void platform user list --page 1 --limit 50 --json
+void platform system health --json
+```
+
+Results go to standard output. Command errors go to standard error as JSON and exit with a nonzero status. With `--follow`, each log response is a separate JSON line.
+
+Operator tokens expire after one hour. For CI, mint a new operator token at the start of each job from a valid full API login session belonging to an active administrator. Choose the platform explicitly, inject the full session as `VOID_TOKEN` from your secret manager, and capture the exchange output directly into the protected job environment:
+
+```sh
+export VOID_API_URL=https://platform.example.com
+VOID_OPERATOR_TOKEN="$(
+  printf '%s' "$VOID_TOKEN" | void platform auth token --token-stdin
+)" || exit 1
+export VOID_OPERATOR_TOKEN
+unset VOID_TOKEN
+void platform system health --json
+unset VOID_OPERATOR_TOKEN
+```
+
+Disable shell tracing for the exchange and do not write either token to logs or plaintext files. A full API login session expires after 30 days and can be revoked sooner; renew it through the normal authenticated login flow and update the protected CI secret. A job that runs longer than one hour must repeat the exchange while its full API session is still valid. An expired operator token cannot refresh itself, and Void does not issue permanent service tokens for administrator automation.
+
+`auth login --token-stdin` performs the same elevation and saves the one-hour operator token in the system keychain for interactive use. See [operator authentication](../reference/cli.md#operator-authentication) for the full command syntax.