void 0.10.11 → 0.10.13

package/dist/{scan-DYXkrasO.mjs → scan-ChWt4pX1.mjs}

@@ -2,7 +2,7 @@ import { a as join, i as isAbsolute, t as basename } from "./dist-DaKKDf8D.mjs";
 import { n as readProjectPaths } from "./project-paths-BQd7OmIo.mjs";
 import { n as globSync, t as glob } from "./dist-BuiRJkTd.mjs";
 import { c as isIdentifier, d as isObjectExpression, l as isLiteral, s as isCallExpression } from "./entry-D7yy4xVH.mjs";
-import { o as parseRouteFilename, s as parseWebSocketFilename, t as scanPages } from "./scan-DEwlM_Xy.mjs";
+import { c as parseWebSocketFilename, o as isRouteEnabledForEnvironment, s as parseRouteFilename, t as scanPages } from "./scan-NU4xKGci.mjs";
 import { existsSync, readFileSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { parseSync } from "vite";
@@ -261,19 +261,19 @@ function buildWebSocketRoute(root, filePath, paths = readProjectPaths(root)) {
 		hasAuthGate: info?.hasAuthGate ?? false
 	};
 }
-function parseWebSocketFiles(root, files, paths = readProjectPaths(root)) {
-	return files.filter((f) => isWebSocketRouteFile(f)).filter((f) => !f.split("/").some((segment) => segment.startsWith("_"))).map((filePath) => buildWebSocketRoute(root, filePath, paths)).sort((a, b) => {
+function parseWebSocketFiles(root, files, paths = readProjectPaths(root), environment) {
+	return files.filter((f) => isWebSocketRouteFile(f)).filter((f) => !f.split("/").some((segment) => segment.startsWith("_"))).filter((filePath) => isRouteEnabledForEnvironment(parseWebSocketFilename(filePath), environment)).map((filePath) => buildWebSocketRoute(root, filePath, paths)).sort((a, b) => {
 		if (a.catchAll !== b.catchAll) return a.catchAll ? 1 : -1;
 		return a.pattern.localeCompare(b.pattern);
 	});
 }
-async function scanWebSocketRoutes(root, paths = readProjectPaths(root)) {
+async function scanWebSocketRoutes(root, paths = readProjectPaths(root), environment) {
 	return parseWebSocketFiles(root, await glob(`**/*.{${HANDLER_EXTENSIONS.join(",")}}`, {
 		cwd: paths.routesDir,
 		absolute: false
-	}).catch(() => []), paths);
+	}).catch(() => []), paths, environment);
 }
-function scanWebSocketRoutesSync(root, paths = readProjectPaths(root)) {
+function scanWebSocketRoutesSync(root, paths = readProjectPaths(root), environment) {
 	const pattern = `**/*.{${HANDLER_EXTENSIONS.join(",")}}`;
 	let files;
 	try {
@@ -284,7 +284,7 @@ function scanWebSocketRoutesSync(root, paths = readProjectPaths(root)) {
 	} catch {
 		files = [];
 	}
-	return parseWebSocketFiles(root, files, paths);
+	return parseWebSocketFiles(root, files, paths, environment);
 }
 function isWebSocketPatternFile(filePath) {
 	return isWebSocketRouteFile(filePath);
@@ -329,7 +329,7 @@ async function scanRoutes(root, options) {
 			cwd: paths.routesDir,
 			absolute: false
 		}),
-		scanWebSocketRoutes(root, paths),
+		scanWebSocketRoutes(root, paths, options?.environment),
 		glob(ROUTE_PATTERN, {
 			cwd: paths.middlewareDir,
 			absolute: false
@@ -343,9 +343,8 @@ async function scanRoutes(root, options) {
 	]);
 	const routesDir = paths.routesDir;
 	return {
-		routes: routeFiles.filter((f) => !isWebSocketPatternFile(f)).filter((f) => !f.split("/").some((s) => s.startsWith("_"))).map((f) => {
-			const route = parseRouteFilename(f);
-			route.methods = detectHttpExports(join(routesDir, f));
+		routes: routeFiles.filter((f) => !isWebSocketPatternFile(f)).filter((f) => !f.split("/").some((s) => s.startsWith("_"))).map((file) => parseRouteFilename(file)).filter((route) => isRouteEnabledForEnvironment(route, options?.environment)).map((route) => {
+			route.methods = detectHttpExports(join(routesDir, route.filePath));
 			return route;
 		}).sort(compareRouteSpecificity),
 		websockets,
@@ -367,7 +366,7 @@ function scanMiddlewareSync(root, paths = readProjectPaths(root)) {
 	}
 	return parseMiddlewareDefinitions(middlewareFiles);
 }
-function scanRoutePatternsSync(root, paths = readProjectPaths(root)) {
+function scanRoutePatternsSync(root, paths = readProjectPaths(root), environment) {
 	let routeFiles;
 	try {
 		routeFiles = globSync(ROUTE_PATTERN, {
@@ -377,7 +376,7 @@ function scanRoutePatternsSync(root, paths = readProjectPaths(root)) {
 	} catch {
 		routeFiles = [];
 	}
-	return routeFiles.filter((f) => !isWebSocketPatternFile(f)).filter((f) => !f.split("/").some((s) => s.startsWith("_"))).map((f) => parseRouteFilename(f)).sort(compareRouteSpecificity);
+	return routeFiles.filter((f) => !isWebSocketPatternFile(f)).filter((f) => !f.split("/").some((s) => s.startsWith("_"))).map((f) => parseRouteFilename(f)).filter((route) => isRouteEnabledForEnvironment(route, environment)).sort(compareRouteSpecificity);
 }
 //#endregion
 export { scanQueuesSync as a, loadVoidAuthConfig as c, scanWebSocketRoutesSync as i, scanRoutePatternsSync as n, scanJobsSync as o, scanRoutes as r, findVoidAuthConfig as s, scanMiddlewareSync as t };

package/dist/{scan-DEwlM_Xy.mjs → scan-NU4xKGci.mjs}

@@ -74,6 +74,9 @@ function parseRouteFilename(relativePath) {
 function parseWebSocketFilename(relativePath) {
 	return parsePath(relativePath, true);
 }
+function isRouteEnabledForEnvironment(route, environment) {
+	return environment === void 0 || route.env === null || route.env === environment;
+}
 //#endregion
 //#region src/pages/layout-resolution.ts
 function isNamedLayout(layout) {
@@ -348,4 +351,4 @@ function extractFrontmatterLayout(source) {
 	return value;
 }
 //#endregion
-export { resolveNamedLayout as a, resolveLayoutIds as i, resolveEffectiveLayoutChain as n, parseRouteFilename as o, resolveLayoutChain as r, parseWebSocketFilename as s, scanPages as t };
+export { resolveNamedLayout as a, parseWebSocketFilename as c, resolveLayoutIds as i, resolveEffectiveLayoutChain as n, isRouteEnabledForEnvironment as o, resolveLayoutChain as r, parseRouteFilename as s, scanPages as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "void",
-  "version": "0.10.11",
+  "version": "0.10.13",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/voidzero-dev/void.git",
@@ -356,7 +356,7 @@
     "valibot": ">=1.0.0-beta.7",
     "vite": "^8.0.0",
     "zod": "^3.25.0 || ^4.0.0",
-    "@void/md": "0.10.11"
+    "@void/md": "0.10.13"
   },
   "peerDependenciesMeta": {
     "@void/md": {

package/schema.json

@@ -144,6 +144,11 @@
       "type": "object",
       "description": "Routing configuration — headers, redirects, rewrites, fallbacks, revalidation, prerendering.",
       "properties": {
+        "notFound": {
+          "type": "string",
+          "enum": ["single-page-application", "404-page", "none"],
+          "description": "Override how the asset layer answers a request that matched no asset and no worker route. Void infers \"single-page-application\" when the worker does not own HTML routing; set \"404-page\" for a static-site-generator build so unknown URLs serve 404.html with a real HTTP 404 instead of index.html with a 200. Does not change run_worker_first. Ignored for SvelteKit, Nuxt, Analog, and Astro deploys, which pin not_found_handling to \"none\" because the framework's own worker owns unmatched HTML."
+        },
         "revalidate": {
           "description": "Edge caching TTL in seconds. A number sets a global TTL for all SSR pages. An object maps URL patterns to TTLs (first match wins). Set to 0 to disable caching for a path.",
           "oneOf": [
@@ -355,6 +360,19 @@
           "type": "object",
           "description": "Environment variables (plain text, not secrets)",
           "additionalProperties": { "type": "string" }
+        },
+        "limits": {
+          "type": "object",
+          "description": "Worker resource limit overrides.",
+          "properties": {
+            "cpu_ms": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 300000,
+              "description": "Caps Workers CPU time per request, in milliseconds (max 300000 = 5 minutes). The platform plan may cap it lower."
+            }
+          },
+          "additionalProperties": false
         }
       },
       "additionalProperties": false

package/skills/migrate-vite-cloudflare-to-void/SKILL.md

@@ -103,7 +103,7 @@ Apply these filename rules exactly when mapping old handlers to `routes/`:
 1. Extension and suffix parsing order
 
 - Strip extension (`.ts`, `.js`, `.mts`, `.mjs`).
-- Strip env suffix (`.dev`, `.prod`).
+- Strip env suffix (`.dev`, `.prod`). The suffix restricts the route to that environment, so only use it for handlers that must not ship to the other one.
 - Strip HTTP method suffix (`.get`, `.post`, `.put`, `.delete`, `.patch`).
 - Strip trailing `index` segment.
 - Remove route group segments `(group-name)` from URL path.

package/skills/void/docs/guide/app-types.md

@@ -73,6 +73,48 @@ At the edge, the resolution order is:
 
 **Deploy:** `void deploy` or `void deploy --dir <path>` uploads static files directly. Assets are served from the edge with automatic caching.
 
+## Adding a backend to a static site
+
+A static site generator plus a few API routes is a Void app, not a static site. Auto-detection sees the SSG dependency first (priority 2 below), so if you leave `inference.appType` unset, `void deploy` refuses rather than deploying the site and silently dropping `routes/`. Tell it which you meant.
+
+To deploy the site **and** the backend, run both builds from one command and let Void's build fold the generated site into its client output:
+
+```json
+// void.json
+{
+  "inference": {
+    "appType": "void",
+    "build": "vitepress build && vite build"
+  }
+}
+```
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { voidPlugin } from 'void';
+
+export default defineConfig({
+  plugins: [voidPlugin()],
+  // The SSG's output becomes the static assets of the Void build.
+  publicDir: '.vitepress/dist',
+});
+```
+
+`vitepress build` emits the site, then `vite build` copies `publicDir` into `dist/client` and emits the worker into `dist/ssr`. Keep `voidPlugin()` in the **root** `vite.config.ts` only — not in the generator's own config (e.g. `.vitepress/config.ts`).
+
+Because the worker now owns unmatched requests, add [`routing.notFound`](../reference/config.md#routing-notfound) if you want the generator's `404.html` instead of the SPA-style `index.html` fallback:
+
+```json
+{ "routing": { "notFound": "404-page" } }
+```
+
+To deploy the static output only and **not** the backend, say so explicitly:
+
+```json
+{ "inference": { "appType": "static" } }
+```
+
 ## Auto-Detection
 
 When running `void deploy` and no `inference.appType` is set in `void.json`, the detection logic runs in this order:
@@ -81,6 +123,7 @@ When running `void deploy` and no `inference.appType` is set in `void.json`, the
 | -------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
 | 1        | `--dir` flag                                                                                                    | Static (or SPA with `--spa`)                |
 | 2        | Known SSG in dependencies (`vitepress`, `@docusaurus/core`)                                                     | Static, builds with SSG CLI                 |
+| 2a       | ...and backend files also exist                                                                                 | Refused — set `inference.appType` yourself  |
 | 3        | `@tanstack/react-start`, `@react-router/dev`, `@sveltejs/kit`, `nuxt`, `@analogjs/platform`, or `astro` in deps | Framework                                   |
 | 4        | Backend files exist (`routes/`, `pages/`, `middleware/`, `crons/`, `queues/`, SSR entry)                        | Void app                                    |
 | 5        | `vite` or `vite-plus` in dependencies, no backend files                                                         | SPA, builds with `vite build` or `vp build` |

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

@@ -62,10 +62,77 @@ If your CI pipeline runs typechecking or other static analysis before deploy, ru
 | `VOID_TOKEN`   | Auth token (for CI, skips OAuth) |
 | `VOID_PROJECT` | Project slug override            |
 
-## GitHub Actions
+## GitHub
 
 You can deploy from a GitHub repo on every push to `main`. Running `void init --github` generates `.github/workflows/void-deploy.yml` in your project.
 
+### Void GitHub App (recommended)
+
+No `.github/workflows/void-deploy.yml` or repository `VOID_TOKEN` is required.
+
+1. Initialize your Void project
+
+```bash
+void init
+# Or, for existing Void project:
+void project link
+```
+
+2. Install the Void GitHub app
+
+```bash
+void github install
+```
+
+You should receive GitHub url asking you to install and authorize `Void Deploy`.
+
+In the browser, select the GitHub account/organization and grant access to the repository.
+
+:::details If someone already installed the App for your organization
+Join that installation instead:
+
+```bash
+void github join
+```
+
+:::
+
+3. Link your repository to your project
+
+```bash
+void github connect --executor container
+```
+
+4. Verify the connection
+
+```bash
+void github status
+```
+
+You should receive an output like:
+
+```bash
+Repository      <owner/repository>
+Branch          main
+Build executor  container
+Deploy workflow .github/workflows/void-deploy.yml (unused for container builds)
+
+```
+
+5. Push to the configured branch to trigger a new deploy
+
+```bash
+git push origin main
+```
+
+6. Follow the build
+
+```bash
+void build logs --follow
+```
+
+### GitHub Actions
+
 The workflow authenticates with [GitHub OIDC](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect) — there is **no long-lived `VOID_TOKEN` secret to store or rotate**. `void deploy` detects GitHub Actions and does the exchange itself: it requests a short-lived OIDC token from GitHub (audience `void`), exchanges it at `POST $VOID_API_URL/auth/github-oidc` for a short-lived project-scoped deploy token (about 15 minutes on the free tier; longer on higher plans, capped at ~60 minutes), and deploys — so the workflow is a single `void deploy` step. `permissions: id-token: write` is still required: it is what lets the job (and the CLI) mint the OIDC token.
 
 ```yaml

package/skills/void/docs/guide/edge/static-assets.md

@@ -97,9 +97,45 @@ This is the path needed for preview auth and other middleware. Cloudflare's plat
 
 For Void apps with only `/api` routes, Void keeps the platform SPA fallback and scopes `run_worker_first` to `/api` and `/api/*`. Static assets and non-API SPA navigations stay on the asset platform. API requests, including browser document navigations such as OAuth callbacks, reach the worker instead of being rewritten to `index.html`.
 
+### Unmatched requests
+
+`not_found_handling` decides what the asset layer does with a request that matched no asset and no worker route. Void infers it:
+
+| App shape                                         | Inferred value                   | Result for an unknown URL        |
+| ------------------------------------------------- | -------------------------------- | -------------------------------- |
+| Pages or SSR                                      | `none`                           | The worker's own 404             |
+| Worker owns HTML, no `pages/`, no SSR entry       | `none` + worker fallback         | `index.html` with status **200** |
+| Asset-first (only `/api` routes, or none)         | `single-page-application`        | `index.html` with status **200** |
+| Framework deploy (SvelteKit, Nuxt, Analog, Astro) | `none` — pinned, not overridable | The framework worker's own 404   |
+
+The middle row is a worker with `middleware/`, a route outside `/api`, a document websocket, or Live, but no `pages/` and no SSR entry. `run_worker_first: ['/**']` sends everything to the worker, which bypasses the platform's SPA switch, so the generated worker does that fallback itself for HTML navigations — after your middleware has run, so auth gates and OAuth callbacks still see the request first.
+
+The SPA fallback is right for a single-page app, where deep links must boot the client router. It is wrong for a site whose HTML was generated per page: unknown URLs return 200 instead of 404, and the generator's `404.html` is never served. Nothing in a built asset tree distinguishes the two, so Void does not guess — override it with [`routing.notFound`](../../reference/config.md#routing-notfound):
+
+```json
+{ "routing": { "notFound": "404-page" } }
+```
+
+Accepted values are `"single-page-application"`, `"404-page"`, and `"none"`. `run_worker_first` keeps its inferred value, so API routes, auth, and `/__void/*` still reach the worker first. Setting anything other than `"single-page-application"` also turns off the worker-side `index.html` fallback described above — otherwise it would answer the request before `not_found_handling` was ever consulted. With `"404-page"` the worker serves whatever the asset binding returns for the unmatched path, which is Cloudflare's nearest `404.html` — but only for HTML navigations (requests whose `Accept` includes `text/html`), so an API route that deliberately returns a 404 keeps its own body, status and headers. If the build has no `404.html`, the worker's own 404 is kept.
+
+The last row is the exception: `routing.notFound` is **ignored** for SvelteKit, Nuxt, Analog, and Astro deploys, and `void deploy` warns when you set it. Those deploys emit no `run_worker_first`, so the asset layer already answers first and real prerendered files win — `not_found_handling` would only change what the framework's own `env.ASSETS.fetch()` delegation returns, where `"single-page-application"` turns genuine 404s into the prerendered home page at 200 and `"404-page"` takes the 404 away from the framework's own error route.
+
+TanStack Start, React Router, and vinext follow the rows above on a managed `void deploy` — that path resolves the asset config itself and applies it to the uploaded worker. Void writes no `assets` policy into their generated worker wrangler config:
+
+| Framework      | Generated worker config      |
+| -------------- | ---------------------------- |
+| TanStack Start | `dist/server/wrangler.json`  |
+| React Router   | `build/server/wrangler.json` |
+| vinext (App)   | `dist/server/wrangler.json`  |
+| vinext (Pages) | `dist/ssr/wrangler.json`     |
+
+So on a self-hosted `wrangler deploy` the setting takes effect only if that config declares a complete `assets` policy of its own — `binding`, `directory`, `not_found_handling`, and `run_worker_first`. Void leaves those fields alone, so a policy you write yourself is honored by the generated wrapper; with no policy at all, Cloudflare's default applies. `vite build` warns when `routing.notFound` is set so the choice is not silent.
+
 ### Generated config
 
-Void owns the generated asset routing policy during dev and build. If a root `wrangler.jsonc` contains stale `not_found_handling` or `run_worker_first` values, Void replaces those fields so generated config cannot accidentally change which layer sees a request first.
+Void owns the generated asset routing policy during dev and build for Void apps. If a root `wrangler.jsonc` contains stale `not_found_handling` or `run_worker_first` values, Void replaces those fields so generated config cannot accidentally change which layer sees a request first.
+
+TanStack Start and React Router are the exception: Void generates no asset policy for them and leaves both fields to your own wrangler config. Writing `not_found_handling` alone would make the asset layer answer unmatched requests and the framework worker would never run, and completing the policy needs `assets.binding` and `assets.directory` that the framework owns, not Void.
 
 ## API routes and SSR pages
 

package/skills/void/docs/guide/server-routing.md

@@ -14,7 +14,27 @@ Create route handlers in `routes/**/*.ts`. Each file maps to a URL path based on
 
 Dynamic segments use brackets: `[id]` becomes a route parameter and `[...slug]` becomes a catch-all. Files or directories starting with `_` are ignored. Directories wrapped in parentheses like `(admin)` are route groups. They help organize files without changing the URL.
 
-You can add a `.dev` or `.prod` suffix before the extension (e.g. `debug.dev.ts`) to include a route only in that environment.
+### Environment-only routes
+
+Add a `.dev` or `.prod` suffix before the extension to include a route in only one environment:
+
+```
+routes/
+  api/health.ts        →  always
+  api/debug.dev.ts     →  development only
+  api/metrics.prod.ts  →  production only
+```
+
+`dev` is the Vite dev server. `prod` is every build, `void deploy`, and `vite preview` — preview serves a production build, so it uses the production routes.
+
+An excluded route is stripped from the worker bundle, from the generated types, and from the generated route and WebSocket config. It is not compiled and it is not deployed.
+
+Two things do not follow the suffix:
+
+- `void prepare` boots no Vite, so it has no environment to read. It generates types for every route in both environments.
+- [Binding inference](../reference/resource-inference.md) scans your source for imports and does not read the suffix. A `void/storage` import inside `api/debug.dev.ts` still adds an R2 binding to your production config, and `void deploy` still provisions the bucket. Set the binding explicitly with [`inference.bindings`](../reference/config.md#inference-bindings) if you do not want it.
+
+The suffix applies to files in `routes/` only. It has no effect in `pages/`, `middleware/`, `crons/`, or `queues/`.
 
 Each file exports named HTTP method constants to handle specific methods:
 

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

@@ -28,6 +28,9 @@ Filename rules match regular server routes:
 - `[id].ws.ts` becomes `:id`
 - `[...slug].ws.ts` becomes a catch-all
 - route groups like `(marketing)/chat.ws.ts` are ignored in the URL
+- `chat.dev.ws.ts` / `chat.prod.ws.ts` restrict the route to one environment
+
+The environment suffix goes **before** `.ws`. `chat.ws.dev.ts` is not recognised.
 
 ## `defineRoom()`
 

package/skills/void/docs/integrations/frameworks/overview.md

@@ -77,6 +77,7 @@ Most configuration is inferred automatically. Use `void.json` to override defaul
 | `routing.prerender`  | Paths to prerender as static HTML at deploy time                                                                                                              |
 | `routing.revalidate` | Default revalidation TTL in seconds for cached responses                                                                                                      |
 | `inference.bindings` | Override inferred bindings. You only need this if auto-detection is not doing what you want. Accepts `true` or a custom binding name such as `"db": "MY_DB"`. |
+| `routing.notFound`   | **Ignored.** SvelteKit, Nuxt, Analog, and Astro pin `not_found_handling` to `"none"` — the framework worker owns unmatched HTML. `void deploy` warns if set.  |
 
 See [Configuration](../../reference/config.md) for the full reference.
 

package/skills/void/docs/node_modules/void/CLAUDE.md

@@ -144,7 +144,7 @@ Build output uses `.mjs` / `.d.mts` extensions (`vp pack` / tsdown default).
 Applied in order to a path relative to `routes/`:
 
 1. Strip extension (`.ts`, `.js`, `.mts`, `.mjs`)
-2. Strip env suffix (`.dev`, `.prod`)
+2. Strip env suffix (`.dev`, `.prod`) and record it on `RouteDefinition.env`
 3. Strip trailing `index`
 4. Remove route group dirs `(groupname)`
 5. Convert `[param]` → `:param`, `[...param]` → `:param{.+}`, `[...]` → `*`
@@ -152,6 +152,8 @@ Applied in order to a path relative to `routes/`:
 
 HTTP methods are determined by **named exports** in each file (detected by `detect-exports.ts` via `parseSync`), not by filename suffixes. Files/dirs starting with `_` are ignored by the scanner.
 
+The recorded `env` is enforced by `isRouteEnabledForEnvironment()`. The scanners take an optional `environment` (`'dev' | 'prod'`); when it is omitted no filtering happens. `dev` is the Vite dev server, `prod` is every build, `void deploy`, and `vite preview`. A dev-only route is absent from the production bundle, types, and generated route/WebSocket config. Two paths do not follow it: `void prepare` boots no Vite, passes no `environment`, and so generates types for both environments; and `inferProjectBindings()` (`plugin-inference.ts`) globs source files without parsing route filenames, so a `void/storage` import in a `.dev.ts` route still emits and provisions an R2 binding in production. Over-emitting is the deliberate safe direction — under-emitting would drop a binding the running code needs — and the environment is not knowable at the `inferProjectBindings()` call site anyway (`index.ts:678`, versus `routeEnvironment` at `index.ts:1324`). The suffix is honoured in `routes/` only, not in `pages/`, `middleware/`, `crons/`, or `queues/`.
+
 ## Code Generation (`void gen`)
 
 Rails/Laravel-style scaffolding commands for common boilerplate:

package/skills/void/docs/node_modules/void/skills/migrate-vite-cloudflare-to-void/SKILL.md

@@ -103,7 +103,7 @@ Apply these filename rules exactly when mapping old handlers to `routes/`:
 1. Extension and suffix parsing order
 
 - Strip extension (`.ts`, `.js`, `.mts`, `.mjs`).
-- Strip env suffix (`.dev`, `.prod`).
+- Strip env suffix (`.dev`, `.prod`). The suffix restricts the route to that environment, so only use it for handlers that must not ship to the other one.
 - Strip HTTP method suffix (`.get`, `.post`, `.put`, `.delete`, `.patch`).
 - Strip trailing `index` segment.
 - Remove route group segments `(group-name)` from URL path.

package/skills/void/docs/reference/cli.md

@@ -271,6 +271,30 @@ For Drizzle projects, deploy performs a read-only schema drift check. If a new m
 
 Every deploy writes a structured JSONL trace to `~/.void/logs/deploy-<timestamp>.jsonl` regardless of `--debug`. On failure the path is printed at the end of the error message so you can attach it when reporting platform issues. `VOID_DEPLOY_DEBUG=1` is accepted as an alternate trigger for stderr mirroring.
 
+When a deploy fails after it starts, the CLI also prints a summary of that trace under the error, so the cause is visible where the file is not — a CI runner, for example, is discarded with the job. The summary has two blocks: every `error` record with its flattened cause chain, then the last 20 records as a timeline.
+
+Pre-flight failures print no summary. A missing project, a rejected flag combination, or an unsupported `--backend cloudflare` feature stops before any trace exists, and each of those prints its own message explaining what to change. A build failure prints no summary either — the build streams its own output straight to the terminal.
+
+Void masks the credentials it emits itself: signed query parameters, bearer tokens, and any field whose key names a credential.
+
+Masking your own values is left to your CI platform, which holds the secrets and masks them before the log is written. GitHub Actions does this for everything under `secrets.*`. Void does not guess at credential-shaped variable names, and it does not parse credentials out of values you supplied — a password inside a `DATABASE_URL` in your build command prints as written. Register such values as CI secrets, or keep them out of the build command.
+
+```
+■  deploy: Deploy failed: deploy in progress
+│  Deployment: dpl_7zgitxdrxxz9
+│  Detailed log: ~/.void/logs/deploy-2026-08-21T03-24-19-764Z.jsonl
+│
+│  Errors
+│     9.0s  deploy_server_error
+│           deploymentId=dpl_7zgitxdrxxz9
+│           message=deploy in progress
+│
+│  Last 20 of 26 entries
+│     8.4s  info   finalize_start        assets=98 workers=0
+│     8.6s  info   stream_deployment_id  deploymentId=dpl_7zgitxdrxxz9
+│     9.0s  error  deploy_server_error   message=deploy in progress
+```
+
 Project resolution precedence:
 
 1. `--project <name>`

package/skills/void/docs/reference/config.md

@@ -254,6 +254,7 @@ Curated Cloudflare Workers configuration. Cloudflare-targeted apps require an ex
 | `compatibility_date`  | `string`   | Cloudflare Workers compatibility date  |
 | `compatibility_flags` | `string[]` | Cloudflare Workers compatibility flags |
 | `vars`                | `object`   | Plain-text worker variables            |
+| `limits`              | `object`   | Worker resource limit overrides        |
 
 ```json
 {
@@ -269,6 +270,18 @@ Curated Cloudflare Workers configuration. Cloudflare-targeted apps require an ex
 
 `worker.vars` values must be strings. They are merged into Worker bindings before `.env` files are loaded, so project `.env` values override `worker.vars` for local dev/build. Do not put secrets here; use `env.ts` plus `void secret put` for production secrets.
 
+`worker.limits.cpu_ms` caps Workers CPU time per request, in milliseconds. It must be an integer between 1 and 300000 (Cloudflare's hard maximum, 5 minutes). A deploy that requests more than your account plan's ceiling fails with an error naming both the requested value and the plan maximum. Only a rollback clamps: rolling back to a deployment whose configured limit now exceeds your plan applies the plan ceiling instead of failing. If your plan changes so that a previously valid value now exceeds the ceiling, deploys keep failing until you lower `cpu_ms` in `void.json`. On the self-hosted path (`void deploy --backend cloudflare`, or a bare `wrangler deploy` of the build output), the value is written into the generated `dist/ssr/wrangler.json` as `limits.cpu_ms` and enforced by Cloudflare directly. The Void plan ceiling does not apply there, but your Cloudflare account's own CPU-time allowance still does: the Workers Free plan caps CPU at 10 ms per request, and the Workers Paid plan allows up to 300000 ms. A value above what your Cloudflare account permits is constrained or rejected by Cloudflare, not by Void.
+
+```json
+{
+  "worker": {
+    "limits": {
+      "cpu_ms": 30000
+    }
+  }
+}
+```
+
 ### `routing`
 
 Routing and edge configuration for headers, redirects, rewrites, and caching.
@@ -378,6 +391,26 @@ Paths to prerender as static HTML at deploy time. Each path must start with `/`.
 }
 ```
 
+#### `routing.notFound`
+
+Override how the asset layer answers a request that matched no asset and no worker route. One of `"single-page-application"`, `"404-page"`, or `"none"`. If omitted, Void infers it — see [Static Assets](../guide/edge/static-assets.md#unmatched-requests).
+
+```json
+{
+  "routing": {
+    "notFound": "404-page"
+  }
+}
+```
+
+Set `"404-page"` when your assets come from a static site generator (VitePress, Docusaurus, …) and you want unknown URLs to serve the generator's own `404.html` with a real HTTP 404. Without it, an app whose only backend is API routes keeps the inferred SPA fallback, so every unknown URL returns `index.html` with a `200` — correct for a single-page app, wrong for a generated site, and bad for crawlers.
+
+`run_worker_first` is untouched, so API routes, auth, and `/__void/*` still reach the worker first. When the worker owns HTML routing it also serves the resolved behavior itself, since `run_worker_first: ["/**"]` means the platform switch never runs — see [Unmatched requests](../guide/edge/static-assets.md#unmatched-requests).
+
+This does **not** apply to SvelteKit, Nuxt, Analog, or Astro deploys: those pin `not_found_handling` to `"none"` because the framework's own worker owns unmatched HTML, and `void deploy` warns if you set `routing.notFound` anyway.
+
+TanStack Start, React Router, and vinext honor it on a managed `void deploy`, which resolves the asset config itself. Void writes no `assets` policy into their generated worker wrangler config (`dist/server` for TanStack Start and vinext App, `build/server` for React Router, `dist/ssr` for vinext Pages), so on a self-hosted `wrangler deploy` it applies only if that config declares a complete `assets` policy of its own — `binding`, `directory`, `not_found_handling`, and `run_worker_first`. Void leaves those fields untouched, so your own policy is honored; with none, Cloudflare's default applies. `vite build` warns when it is set. See [Static Assets](../guide/edge/static-assets.md#unmatched-requests) for the per-framework paths.
+
 ### `inference`
 
 Configuration for build-time inference, including how Void detects your app type, bindings, and build process.
@@ -403,12 +436,20 @@ Custom names are used in the deploy manifest, Wrangler config generation/sync, r
 
 #### `inference.build`
 
-Override the build command. Useful for frameworks with their own CLIs (Nuxt, Astro) or static apps with custom build scripts. If omitted, the CLI uses the detected default build command for the current app type.
+Override the build command. Useful for frameworks with their own CLIs (Nuxt, Astro) or static apps with custom build scripts. If omitted, the CLI uses the detected default build command for the current app type. It applies to every app type, including `"void"` (where the default is `vite build`).
 
 ```json
 { "inference": { "build": "nuxt build --preset cloudflare-module" } }
 ```
 
+The command is run through a shell from the project root, with the project's own `node_modules/.bin` on `PATH`, so bare binaries and `&&` chains work:
+
+```json
+{ "inference": { "build": "vitepress build && vite build" } }
+```
+
+That chain is how a static site generator and a Void backend ship together — see [Adding a backend to a static site](../guide/app-types.md#adding-a-backend-to-a-static-site).
+
 #### `inference.scanDirs`
 
 Override which directories are scanned for [binding inference](./resource-inference.md). Paths are relative to the project root. Replaces the default directories for the current mode.

package/skills/void/docs/reference/structure.md

@@ -80,6 +80,7 @@ File-based HTTP API endpoints built on [Hono](https://hono.dev). Each file expor
 - **Catch-all**: `[...slug]` matches the remaining path
 - **Route groups**: `(admin)/` organizes files without affecting URL paths
 - **Files starting with `_`** are ignored
+- **Environment suffix**: `debug.dev.ts` builds in development only, `metrics.prod.ts` in production only
 
 See [Server Routing](/guide/server-routing) for the full guide.