devflare 1.0.0-next.1 → 1.0.0-next.11

package/LLM.md

@@ -1,976 +1,1790 @@
 # Devflare
 
-This file is for LLMs and developers **using** the `devflare` library.
+This file is the truth-first contract for `devflare` as implemented today.
 
-It explains the public mental model, the intended project structure, and the practical authoring patterns that make Devflare different from using raw Wrangler + Miniflare directly.
+Use it when you are:
 
-It does **not** document the internal repository layout or example cases. Treat it as package-facing guidance.
+- generating code
+- reviewing code
+- updating docs
+
+Use `Quick start` for the safest defaults, `Trust map` when similar layers are getting mixed together, and `Sharp edges` before documenting advanced behavior. If an example and the implementation disagree, trust the implementation and update the docs.
 
 ---
 
-## What Devflare is
+## Quick start: safest supported path
 
-Devflare is a **developer platform for Cloudflare Workers built on top of Miniflare, Wrangler-compatible config, and framework-aware tooling**.
+Prefer this shape unless you have a concrete reason not to:
 
-The short version:
+- explicit `files.fetch`
+- `src/fetch.ts` as the main HTTP entry
+- a named event-first `fetch(event)` or `handle(event)` export
+- request-wide middleware via `sequence(...)`
+- explicit bindings in config
+- `createTestContext()` for core integration tests
+- `ref()` for cross-worker composition
 
-> Miniflare gives you a local Workers runtime. Devflare turns that runtime into a coherent developer system.
+```ts
+import { defineConfig } from 'devflare'
 
-Devflare does this by combining:
+export default defineConfig({
+	name: 'hello-worker',
+	compatibilityDate: '2026-03-17',
+	files: {
+		fetch: 'src/fetch.ts'
+	}
+})
+```
 
-- typed config via `defineConfig()`
-- convention-driven file discovery
-- binding compilation to Wrangler-compatible config
-- local Miniflare orchestration
-- Node ↔ Worker bridging where needed
-- dedicated test helpers for each handler type
-- framework integration for Vite and SvelteKit
-- local development features that Miniflare alone does not provide cleanly, such as **browser rendering support**, multi-surface orchestration, and a consistent file-structured app model
+```ts
+import type { FetchEvent } from 'devflare/runtime'
 
-If you are building Cloudflare applications and want more structure than a single `worker.ts` plus manual plumbing, Devflare is the layer that supplies that structure.
+export async function fetch(event: FetchEvent): Promise<Response> {
+	return Response.json({
+		path: new URL(event.request.url).pathname
+	})
+}
+```
 
 ---
 
-## How Devflare extends Miniflare
+## Trust map
+
+### Layers that are easy to confuse
 
-This is the most important concept to understand.
+Keep these layers separate until you have a reason to connect them:
 
-Devflare is **not** trying to replace Miniflare. It **extends** Miniflare so developers can work with a higher-level application model.
+1. config-time `process.env`
+2. `devflare.config.ts`
+3. generated `wrangler.jsonc`
+4. runtime Worker `env` bindings
+5. local dev/test helpers
 
-### Raw Miniflare gives you a runtime
+The classic mixups are:
 
-Miniflare is excellent at local execution and local emulation of many Cloudflare bindings.
+- `files.routes` vs top-level `routes`
+- `vars` vs `secrets`
+- Bun or host `.env*` loading vs runtime secret loading
+- config-time `.env*` files vs local runtime `.dev.vars*` files
+- Devflare `config.env` overrides vs Wrangler environment blocks
+- main-entry `env` vs runtime `env`
 
-But by itself, it does not define:
+### Source of truth vs generated output
 
-- how your project should be structured
-- how `fetch`, `queue`, `scheduled`, `email`, routes, DOs, and entrypoints should relate
-- how cross-worker references should stay typed
-- how tests should address each handler surface consistently
-- how framework output and auxiliary workers should be wired together
-- how to simulate browser rendering locally in a coherent workflow
+Treat these as generated output, not authoring input:
 
-### Devflare adds the missing platform layer
+- `.devflare/`
+- `env.d.ts`
+- generated `wrangler.jsonc`
 
-Devflare adds those higher-level capabilities on top of Miniflare.
+The source of truth is still:
 
-Concretely, it provides:
+- `devflare.config.ts`
+- your source files under `src/`
+- your tests
 
-1. **Convention-first file structure**
-   - `src/fetch.ts`
-   - `src/queue.ts`
-   - `src/scheduled.ts`
-   - `src/email.ts`
-   - `src/routes/**`
-   - `do.*.ts`
-   - `ep.*.ts`
-   - `wf.*.ts`
-   - `src/transport.ts`
+If generated output looks wrong, fix the source and regenerate it. Do not hand-edit generated artifacts.
 
-2. **Config compilation**
-   - Devflare compiles your config into Wrangler-compatible config rather than making you hand-maintain the low-level representation yourself.
+---
 
-3. **Responsibility isolation**
-   - Instead of one giant worker file containing every concern, Devflare encourages one surface per responsibility: fetch, queue, cron, email, routes, Durable Objects, WorkerEntrypoints, workflows, and transport.
+## What Devflare is
 
-4. **Unified testing surface**
-   - `cf.worker`
-   - `cf.queue`
-   - `cf.scheduled`
-   - `cf.email`
-   - `cf.tail`
+Devflare is a developer-first layer on top of Cloudflare Workers tooling.
 
-5. **Bridge-backed local development**
-   - Devflare handles Node-side access, env access, transport decoding, and Miniflare orchestration so tests and tooling feel like one system.
+It composes existing tools instead of replacing them:
 
-6. **Capabilities beyond raw Miniflare**
-   - most notably **browser rendering support** through a local browser shim that lets browser-rendering workflows run locally in a way Miniflare does not provide directly
+- **Miniflare** supplies the local Workers runtime
+- **Wrangler** supplies deployment config and deploy workflows
+- **Vite** participates when the current package opts into Vite-backed mode
+- **Bun** is the CLI runtime and affects process-level `.env` loading
+- **Devflare** ties those pieces into one authoring model
 
-7. **Framework integration**
-   - Vite and SvelteKit support with config generation, worker-aware transforms, auxiliary Durable Object workers, and websocket-aware local dev workflows
+Core public capabilities today:
 
-So the design goal is not just “run a Worker locally”.
+- typed config via `defineConfig()`
+- compilation from Devflare config into Wrangler-compatible output
+- event-first runtime helpers
+- request-scoped proxies and per-surface getters
+- typed multi-worker references via `ref()`
+- local orchestration around Miniflare, Vite, and test helpers
+- framework-aware Vite and SvelteKit integration
 
-The design goal is:
+Devflare is not a replacement runtime. It is a higher-level developer system that sits on top of the Cloudflare ecosystem.
 
-> let developers build Cloudflare systems using coherent, isolated responsibilities while Devflare composes those responsibilities into a working local and testable whole
+The shortest truthful mental model is:
 
----
+- **Vite** is the optional outer app/framework host. Devflare plugs into it only when the current package has a local `vite.config.*`.
+- **Rolldown** is the inner builder Devflare uses when Devflare itself needs to transform Worker source into runnable Worker modules. Today that shows up most clearly in the Durable Object bundler and its watch/rebuild loop.
 
-## The authoring model Devflare wants you to use
+### Authoring model
 
-Devflare is opinionated in a useful way.
+A **surface** is a distinct handler or entry file that Devflare treats as its own concern. The common surfaces are:
 
-It wants you to think in **surfaces** rather than in “one file that does everything”.
+- HTTP via `src/fetch.ts`
+- queue consumers via `src/queue.ts`
+- scheduled handlers via `src/scheduled.ts`
+- incoming email via `src/email.ts`
+- Durable Objects via `do.*.ts`
+- WorkerEntrypoints via `ep.*.ts`
+- workflows via `wf.*.ts`
+- custom transport definitions via `src/transport.ts`
 
-### HTTP surface
+Prefer one responsibility per file unless you have a strong reason to combine surfaces. That keeps runtime behavior, testing, and multi-worker composition easier to reason about.
 
-Use `src/fetch.ts` for normal request handling.
+---
 
-### Queue surface
+## Package entrypoints
 
-Use `src/queue.ts` for queue consumers.
+Use the narrowest import path that matches where the code runs.
 
-### Scheduled surface
+| Import | Use it for | Practical rule |
+|---|---|---|
+| `devflare` | main package entrypoint | config helpers, `ref()`, `workerName`, the main-entry `env`, and selected Node-side helpers |
+| `devflare/runtime` | handler/runtime code | event types, middleware, strict `env` / `ctx` / `event` / `locals`, and per-surface getters |
+| `devflare/test` | tests | `createTestContext()`, `cf.*`, and test helpers |
+| `devflare/vite` | Vite integration | explicit Vite-side helpers |
+| `devflare/sveltekit` | SvelteKit integration | SvelteKit-facing helpers |
+| `devflare/cloudflare` | Cloudflare account and resource helpers | account/resource/usage helpers |
+| `devflare/decorators` | decorators only | `durableObject()` and related decorator utilities |
 
-Use `src/scheduled.ts` for cron triggers.
+### `devflare` vs `devflare/runtime`
 
-### Email surface
+Default rule:
 
-Use `src/email.ts` for incoming email handling. Use `sendEmail` bindings in config for outgoing email.
+1. use handler parameters first
+2. use `devflare/runtime` in helpers that run inside a live handler trail
+3. use the main `devflare` entry when you specifically want the fallback-friendly `env`
 
-### Routing surface
+`import { env } from 'devflare/runtime'` is strict request-scoped access. It works only while Devflare has established an active handler context.
 
-Use `files.routes` with a directory like `src/routes` when you want file-based HTTP routing instead of one monolithic fetch file.
+`import { env } from 'devflare'` is the main-entry proxy. It prefers active handler context and can also fall back to test or bridge-backed context when no live request is active.
 
-### Durable Object surface
+Practical example:
 
-Use `do.*.ts` files for Durable Objects.
+```ts
+// worker code
+import { env, locals, type FetchEvent } from 'devflare/runtime'
+
+export async function fetch(event: FetchEvent<DevflareEnv>): Promise<Response> {
+	const pathname = new URL(event.request.url).pathname
+	locals.startedAt = Date.now()
+
+	const cached = await env.CACHE.get(pathname)
+	if (cached) {
+		return new Response(cached, {
+			headers: {
+				'x-cache': 'hit'
+			}
+		})
+	}
+
+	return new Response(`miss:${pathname}`)
+}
+```
+
+```ts
+// test or bridge code
+import { env } from 'devflare'
+import { createTestContext } from 'devflare/test'
 
-### RPC / service-entry surface
+await createTestContext()
+await env.CACHE.put('health', 'ok')
+```
 
-Use `ep.*.ts` files for named WorkerEntrypoints.
+### Worker-safe caveat for the main entry
 
-### Workflow surface
+`devflare/runtime` is the explicit worker-safe runtime entry and should be the default teaching path for worker code.
 
-Use `wf.*.ts` files for Workflow classes.
+The main `devflare` entry can also resolve to a worker-safe bundle when the resolver selects the package `browser` condition. Treat that as a compatibility detail, not as a signal that the main entry is the best place to import runtime helpers.
 
-### Transport surface
+In that worker-safe main bundle:
 
-Use `src/transport.ts` when values crossing boundaries need custom serialization.
+- the browser-safe subset of the main entry remains usable
+- Node-side APIs such as config loading, CLI helpers, Miniflare orchestration, and test-context setup are not available and intentionally throw if called
 
-This is one of Devflare’s biggest advantages: it turns Cloudflare development from “single worker blob” into **separated, discoverable, testable responsibilities**.
+If you need `ctx`, `event`, `locals`, middleware, or per-surface getters, import them from `devflare/runtime`.
 
 ---
 
-## Public package entry points
+## Runtime and HTTP model
 
-Use the package subpaths intentionally.
+### Event-first handlers are the public story
 
-| Import | Use for |
-|---|---|
-| `devflare` | config, `ref()`, `env`, bridge/test convenience exports |
-| `devflare/runtime` | runtime-safe utilities for Worker code |
-| `devflare/test` | test context, mocks, `cf.*` helpers |
-| `devflare/vite` | Vite integration |
-| `devflare/sveltekit` | SvelteKit integration |
-| `devflare/cloudflare` | Cloudflare-specific helpers |
-| `devflare/decorators` | decorators such as `durableObject()` |
+Fresh Devflare code should be event-first. Use shapes like:
 
----
+- `fetch(event: FetchEvent)`
+- `queue(event: QueueEvent)`
+- `scheduled(event: ScheduledEvent)`
+- `email(event: EmailEvent)`
+- `tail(event: TailEvent)` when you are wiring a tail surface
+- Durable Object handlers with their matching event types
+
+These event types augment native Cloudflare inputs rather than replacing them with unrelated wrappers.
+
+| Event type | Also behaves like | Convenience fields |
+|---|---|---|
+| `FetchEvent` | `Request` | `request`, `env`, `ctx`, `params`, `locals`, `type` |
+| `QueueEvent` | `MessageBatch<T>` | `batch`, `env`, `ctx`, `locals`, `type` |
+| `ScheduledEvent` | `ScheduledController` | `controller`, `env`, `ctx`, `locals`, `type` |
+| `EmailEvent` | `ForwardableEmailMessage` | `message`, `env`, `ctx`, `locals`, `type` |
+| `TailEvent` | `TraceItem[]` | `events`, `env`, `ctx`, `locals`, `type` |
+| `DurableObjectFetchEvent` | `Request` | `request`, `env`, `ctx`, `state`, `locals`, `type` |
+| `DurableObjectAlarmEvent` | event object only | `env`, `ctx`, `state`, `locals`, `type` |
+| `DurableObjectWebSocketMessageEvent` | `WebSocket` | `ws`, `message`, `env`, `ctx`, `state`, `locals`, `type` |
+| `DurableObjectWebSocketCloseEvent` | `WebSocket` | `ws`, `code`, `reason`, `wasClean`, `env`, `ctx`, `state`, `locals`, `type` |
+| `DurableObjectWebSocketErrorEvent` | `WebSocket` | `ws`, `error`, `env`, `ctx`, `state`, `locals`, `type` |
+
+On worker surfaces, `event.ctx` is the current `ExecutionContext`.
+
+On Durable Object surfaces, `event.ctx` is the current `DurableObjectState`, and Devflare also exposes it as `event.state` for clarity.
+
+### Runtime access: parameters, getters, and proxies
 
-## Core ideas you should internalize
+Prefer runtime access in this order:
 
-### `defineConfig()` is the center of the project
+1. handler parameters such as `fetch(event: FetchEvent)`
+2. per-surface getters when a deeper helper needs the current concrete surface
+3. generic runtime proxies when surface-agnostic access is enough
 
-Always define your worker through `defineConfig()`.
+Devflare carries the active event through the current handler call trail, so deeper helpers can recover the current surface without manually threading arguments.
+
+Proxy semantics:
+
+- `env`, `ctx`, and `event` from `devflare/runtime` are readonly
+- `locals` is the mutable request-scoped storage object
+- `event.locals` and `locals` point at the same underlying object
+- strict runtime helpers throw when there is no active Devflare-managed context
+
+Per-surface getters:
+
+- worker surfaces: `getFetchEvent()`, `getQueueEvent()`, `getScheduledEvent()`, `getEmailEvent()`, `getTailEvent()`
+- Durable Object surfaces: `getDurableObjectEvent()`, `getDurableObjectFetchEvent()`, `getDurableObjectAlarmEvent()`
+- Durable Object WebSocket surfaces: `getDurableObjectWebSocketMessageEvent()`, `getDurableObjectWebSocketCloseEvent()`, `getDurableObjectWebSocketErrorEvent()`
+
+Every getter also exposes `.safe()`, which returns `null` instead of throwing.
+
+Practical example:
 
 ```ts
-import { defineConfig } from 'devflare'
+import { getFetchEvent, locals, type FetchEvent } from 'devflare/runtime'
 
-export default defineConfig({
-	name: 'my-worker'
-})
+function currentPath(): string {
+	return new URL(getFetchEvent().request.url).pathname
+}
+
+export async function fetch(event: FetchEvent): Promise<Response> {
+	locals.requestId = crypto.randomUUID()
+
+	return Response.json({
+		path: currentPath(),
+		requestId: String(locals.requestId),
+		requestUrl: getFetchEvent.safe()?.request.url ?? null,
+		method: event.request.method
+	})
+}
 ```
 
-This is the source of truth Devflare uses to:
+### Manual context helpers are advanced/internal
 
-- understand your bindings
-- understand your file layout
-- generate Wrangler-compatible config
-- drive dev mode
-- drive test mode
+Normal Devflare application code should **not** need `runWithEventContext()` or `runWithContext()`.
 
-### Convention beats boilerplate
+Devflare establishes the active event/context automatically before invoking user code in the flows developers normally use:
 
-If your filenames follow the defaults, you do not need to spell everything out.
+- generated worker entrypoints for `fetch`, `queue`, `scheduled`, and `email`
+- Durable Object wrappers
+- HTTP middleware and route resolution
+- `createTestContext()` helpers such as `cf.worker`, `cf.queue`, `cf.scheduled`, `cf.email`, and `cf.tail`
 
-Defaults include:
+That means getters like `getQueueEvent()`, `getScheduledEvent()`, `getEmailEvent()`, and `getDurableObjectFetchEvent()` should work inside ordinary handlers without manual wrapping.
 
-- `src/fetch.ts`
-- `src/queue.ts`
-- `src/scheduled.ts`
-- `src/email.ts`
-- `src/transport.ts`
-- `**/do.*.{ts,js}`
-- `**/ep.*.{ts,js}`
-- `**/wf.*.{ts,js}`
+Keep these helpers in the "advanced escape hatch" bucket:
 
-### `ref()` is how cross-worker systems stay clean
+- `runWithEventContext(event, fn)` preserves the exact event you provide
+- `runWithContext(env, ctx, request, fn, type)` is a lower-level compatibility helper
 
-If one worker depends on another worker or on another worker’s Durable Objects, use `ref()` instead of manually duplicating names.
+Important difference:
 
-That keeps cross-worker relationships typed and centralized.
+- `runWithContext()` only synthesizes rich augmented events for `fetch` and `durable-object-fetch` when a `Request` is available
+- if you are manually constructing a non-fetch surface and truly need per-surface getters outside normal Devflare-managed entrypoints, `runWithEventContext()` is the correct low-level helper
 
-### `env` is the unified access point
+### HTTP entry, middleware, and method handlers
 
-Use:
+Think of the built-in HTTP path today as:
+
+`src/fetch.ts` request-wide entry → same-module method handlers → matched `src/routes/**` leaf module
+
+When the HTTP surface matters to build or deploy output, prefer making it explicit in config:
 
 ```ts
-import { env } from 'devflare'
+files: {
+	fetch: 'src/fetch.ts'
+}
 ```
 
-Devflare makes `env` work coherently across request handling, tests, and bridge-backed local flows.
+The file router is enabled automatically when a `src/routes` directory exists, unless you set `files.routes: false`.
+Use `files.routes` when you want to change the route root or mount it under a prefix.
 
----
+Supported primary entry shapes today:
 
-## Why file structure matters so much in Devflare
+- `export async function fetch(...) { ... }`
+- `export const fetch = ...`
+- `export const handle = ...`
+- `export default async function (...) { ... }`
+- `export default { fetch(...) { ... } }`
+- `export default { handle(...) { ... } }`
 
-In plain Worker setups, it is common to end up with a single file that mixes:
+`fetch` and `handle` are aliases for the same primary HTTP entry. Export one or the other, not both.
 
-- HTTP routing
-- queue handling
-- scheduled jobs
-- email handling
-- Durable Object exports
-- auxiliary RPC handlers
-- test-specific wiring
+When this document says a `handle` export here, it means the primary fetch export name, not the legacy `handle(...handlers)` helper.
 
-Devflare pushes in the opposite direction.
+Request-wide middleware belongs in `src/fetch.ts` and composes with `sequence(...)`.
 
-It gives each responsibility a natural home and then composes them together.
+```ts
+import { sequence } from 'devflare/runtime'
+import type { FetchEvent, ResolveFetch } from 'devflare/runtime'
 
-That has several benefits:
+async function authHandle(event: FetchEvent, resolve: ResolveFetch): Promise<Response> {
+	if (!event.request.headers.get('authorization')) {
+		return new Response('Unauthorized', { status: 401 })
+	}
 
-- lower mental overhead
-- easier code generation
-- easier code review
-- easier testing
-- fewer accidental runtime coupling mistakes
-- clearer ownership boundaries within a team
+	return resolve(event)
+}
 
-For LLM generation specifically, this matters a lot.
+async function appFetch({ request }: FetchEvent): Promise<Response> {
+	return new Response(new URL(request.url).pathname)
+}
 
-When generating Devflare code, prefer **separate files with clear responsibilities** over giant all-in-one worker files.
+export const handle = sequence(authHandle, appFetch)
+```
 
----
+`sequence(...)` uses the usual nested middleware flow:
+
+1. outer middleware before `resolve(event)`
+2. inner middleware before `resolve(event)`
+3. downstream leaf handler
+4. inner middleware after `resolve(event)`
+5. outer middleware after `resolve(event)`
+
+Same-module method exports are real runtime behavior:
+
+- method handlers such as `GET`, `POST`, and `ALL` are supported in the fetch module
+- if `HEAD` is not exported, it falls back to `GET` with an empty body
+- this is same-module dispatch, not file-system routing
+- if a module exports a primary `fetch` or `handle` entry and also exports method handlers, the method handlers are the downstream leaf handlers reached through `resolve(event)`
+- if no primary `fetch` or `handle` exists, Devflare can still dispatch directly to same-module method handlers
+
+### Routing today
+
+`src/routes/**` is now a real built-in router.
+
+Default behavior:
+
+- if `src/routes` exists, Devflare discovers it automatically
+- `files.routes.dir` changes the route root
+- `files.routes.prefix` mounts the discovered routes under a fixed prefix such as `/api`
+- `files.routes: false` disables file-route discovery
+
+Filename conventions:
+
+- `index.ts` → directory root
+- `[id].ts` → single dynamic segment
+- `[...slug].ts` → rest segment, one or more path parts
+- `[[...slug]].ts` → optional rest segment, including the directory root
+- files or directories beginning with `_` are ignored so route-local helpers can live beside handlers
+
+Dispatch semantics:
+
+- route params are populated on `event.params`
+- route modules use the same handler forms as fetch modules: HTTP method exports, primary `fetch`, or primary `handle`
+- if `src/fetch.ts` exports same-module `GET` / `POST` / `ALL` handlers, those run before the file router for matching methods
+- for route-tree apps, keep `src/fetch.ts` focused on request-wide middleware and whole-app concerns
+- `resolve(event)` from the primary fetch module falls through to the matched route module when no same-module method handler responded
 
-## Config example
+| Key | What it means today | What it does not do |
+|---|---|---|
+| `files.routes` | built-in file router configuration for `src/routes/**` discovery, custom route roots, and optional prefixes | it does not replace top-level Cloudflare deployment `routes` |
+| top-level `routes` | Cloudflare deployment route patterns such as `example.com/*`, compiled into generated Wrangler config | it does not choose handlers inside your app |
+| `wsRoutes` | dev-only WebSocket proxy rules that forward matching local upgrade requests to Durable Objects | it does not replace deployment `routes` or act as general HTTP app routing |
 
-This is a good realistic starting point.
+Practical route-tree example:
 
 ```ts
+// devflare.config.ts
 import { defineConfig } from 'devflare'
 
 export default defineConfig({
-	name: 'my-app',
+	name: 'api-worker',
 	files: {
+		fetch: 'src/fetch.ts',
 		routes: {
 			dir: 'src/routes',
 			prefix: '/api'
 		}
-	},
-	bindings: {
-		kv: {
-			CACHE: 'cache-kv-id'
-		},
-		d1: {
-			DB: 'db-id'
-		},
-		r2: {
-			FILES: 'files-bucket'
-		},
-		durableObjects: {
-			COUNTER: 'Counter'
-		},
-		queues: {
-			producers: {
-				TASK_QUEUE: 'task-queue'
-			},
-			consumers: [
-				{
-					queue: 'task-queue',
-					maxBatchSize: 10,
-					maxRetries: 3
-				}
-			]
-		},
-		browser: {
-			binding: 'BROWSER'
-		}
-	},
-	triggers: {
-		crons: ['0 */6 * * *']
-	},
-	vars: {
-		LOG_LEVEL: 'info'
 	}
 })
 ```
 
+```ts
+// src/fetch.ts
+import { sequence } from 'devflare/runtime'
+
+export const handle = sequence(async (event, resolve) => {
+	const response = await resolve(event)
+	const next = new Response(response.body, response)
+	next.headers.set('x-user-id', event.params.id ?? 'none')
+	return next
+})
+```
+
+```ts
+// src/routes/users/[id].ts
+import type { FetchEvent } from 'devflare/runtime'
+
+export async function GET({ params }: FetchEvent): Promise<Response> {
+	return Response.json({ id: params.id })
+}
+```
+
+```ts
+// GET /api/users/123
+// -> { "id": "123" }
+// and x-user-id: 123
+```
+
 ---
 
-## File-based routing
+## Configuration and compilation
 
-Devflare supports a file-structured routing model through `files.routes`.
+### Stable config flow
 
-That is important because it moves you away from hand-written request dispatch in one file and toward a more maintainable app structure.
+This is the stable public flow for Devflare config:
 
-Example:
+1. write `devflare.config.*` and export it with `defineConfig()`
+2. Devflare loads the base config
+3. if you select an environment, Devflare merges `config.env[name]` into the base config
+4. Devflare compiles the resolved config into Wrangler-compatible output
+5. commands such as `dev`, `build`, `deploy`, and `types` use that resolved config for their own work
+
+Current implementation note: Devflare validates config against its schema before compilation, and some commands write generated `wrangler.jsonc` files as build artifacts. Treat generated Wrangler config as output, not source of truth.
+
+### Supported config files and `defineConfig()`
+
+Supported config filenames:
+
+- `devflare.config.ts`
+- `devflare.config.mts`
+- `devflare.config.js`
+- `devflare.config.mjs`
+
+Use a plain object when your config is static. Use a sync or async function when you need to compute values from `process.env`, the selected environment, or project state.
 
 ```ts
 import { defineConfig } from 'devflare'
 
 export default defineConfig({
-	name: 'my-api',
+	name: 'api-worker',
+	compatibilityDate: '2026-03-17',
 	files: {
-		routes: {
-			dir: 'src/routes',
-			prefix: '/api'
-		}
+		fetch: 'src/fetch.ts'
+	},
+	vars: {
+		APP_NAME: 'api-worker'
 	}
 })
 ```
 
-Conceptually, this means:
+TypeScript note: `defineConfig<T>()` is an advanced typing helper. It is mainly useful when you want stronger `ref()` and entrypoint inference after `env.d.ts` exists.
 
-- route files map onto URL paths
-- route handlers can stay focused on their specific endpoint logic
-- your HTTP surface can scale without turning `fetch.ts` into a switch-statement graveyard
+### Top-level keys
 
-If you only need a small Worker, `src/fetch.ts` is perfect.
+Most projects only need a small set of config keys at first. Start with `name`, `compatibilityDate`, `files`, and the `bindings`, `vars`, `secrets`, `triggers`, `routes`, or `env` your worker actually needs.
 
-If your HTTP surface is growing, `files.routes` is usually the better model.
+Current defaults worth knowing:
 
----
+- `compatibilityDate` defaults to the current date when omitted
+- current default compatibility flags include `nodejs_compat` and `nodejs_als`
+
+Common keys:
+
+| Key | Use it for |
+|---|---|
+| `name` | Worker name |
+| `compatibilityDate` | Workers compatibility date |
+| `compatibilityFlags` | Workers compatibility flags |
+| `files` | explicit handler paths and discovery globs |
+| `bindings` | Cloudflare bindings |
+| `triggers` | scheduled trigger config |
+| `vars` | non-secret string bindings |
+| `secrets` | secret binding declarations |
+| `routes` | Cloudflare deployment routes |
+| `env` | environment overrides merged before compile |
+
+Secondary keys:
+
+| Key | Use it for |
+|---|---|
+| `accountId` | account selection for remote and deploy flows |
+| `observability` | Workers observability settings |
+| `migrations` | Durable Object migrations |
+| `assets` | static asset config |
+| `limits` | worker limits |
+| `wsRoutes` | local WebSocket proxy rules for dev |
+| `vite` | Devflare Vite metadata |
+| `rolldown` | Durable Object bundler options |
+| `wrangler.passthrough` | raw Wrangler overrides after compile |
+
+### Complete config property reference
+
+Treat this as the exhaustive property checklist for `defineConfig({...})`. The later sections explain behavior in narrative form; this section answers “what keys exist right now, what shape do they accept, and what do they control?”
+
+#### Root properties
+
+| Property | Shape | Required | Current behavior |
+|---|---|---|---|
+| `name` | `string` | yes | Worker name compiled to Wrangler `name`. It is also the base name used for generated auxiliary DO workers (`${name}-do`) when Devflare creates one. |
+| `accountId` | `string` | no | Compiled to Wrangler `account_id`. Most relevant for deploy flows and remote-oriented bindings such as AI and Vectorize. Not currently supported inside `config.env`. |
+| `compatibilityDate` | `string` (`YYYY-MM-DD`) | no | Compiled to Wrangler `compatibility_date`. Defaults to the current date when omitted. |
+| `compatibilityFlags` | `string[]` | no | Additional Workers compatibility flags. Devflare also forces `nodejs_compat` and `nodejs_als`. |
+| `files` | object | no | Explicit surface file paths and discovery globs. Use this when a surface matters to generated output. |
+| `bindings` | object | no | Cloudflare binding declarations. These compile to Wrangler binding sections and also drive generated typing. |
+| `triggers` | object | no | Scheduled trigger configuration such as cron expressions. |
+| `vars` | `Record<string, string>` | no | Non-secret runtime bindings compiled into Wrangler `vars`. |
+| `secrets` | `Record<string, { required?: boolean }>` | no | Secret declarations only. Values do not live here. |
+| `routes` | `Array<{ pattern; zone_name?; zone_id?; custom_domain? }>` | no | Cloudflare deployment routes. This is separate from the built-in file router. |
+| `wsRoutes` | `Array<{ pattern; doNamespace; idParam?; forwardPath? }>` | no | Dev-only WebSocket proxy rules that forward matching upgrade requests to Durable Objects. Not compiled into Wrangler config. |
+| `assets` | `{ directory: string; binding?: string }` | no | Static asset directory config compiled into Wrangler `assets`. |
+| `limits` | `{ cpu_ms?: number }` | no | Worker execution limits compiled into Wrangler `limits`. |
+| `observability` | `{ enabled?: boolean; head_sampling_rate?: number }` | no | Workers observability and sampling config compiled into Wrangler `observability`. |
+| `migrations` | `Migration[]` | no | Durable Object migration history compiled into Wrangler `migrations`. |
+| `rolldown` | object | no | Rolldown builder configuration for Devflare's own code-transformation path, currently focused on Durable Object workers. This is not a replacement for `vite.config.*`. |
+| `vite` | object | no | Devflare-owned Vite metadata namespace. Raw Vite server/build/resolve config still belongs in local `vite.config.*`. |
+| `env` | `Record<string, EnvOverride>` | no | Named environment overlays merged into the base config before compile/build/deploy. |
+| `wrangler` | `{ passthrough?: Record<string, unknown> }` | no | Escape hatch for unsupported Wrangler keys, merged after native Devflare compile. |
+| `build` | object | legacy | Deprecated alias normalized into `rolldown`. Keep accepting it for compatibility; teach `rolldown` in new docs. |
+| `plugins` | `unknown[]` | legacy | Deprecated alias normalized into `vite.plugins`. Raw Vite plugin wiring still belongs in `vite.config.*`. |
+
+#### `files`
+
+`files` is where Devflare discovers or pins the files that make up your worker surfaces.
+
+| Key | Shape | Default or convention | Meaning |
+|---|---|---|---|
+| `fetch` | `string \| false` | `src/fetch.ts` when present | Main HTTP entry. Keep this explicit when build or deploy output depends on it. |
+| `queue` | `string \| false` | `src/queue.ts` when present | Queue consumer surface. |
+| `scheduled` | `string \| false` | `src/scheduled.ts` when present | Scheduled/cron surface. |
+| `email` | `string \| false` | `src/email.ts` when present | Inbound email surface. |
+| `durableObjects` | `string \| false` | `**/do.*.{ts,js}` | Discovery glob for Durable Object classes. Respects `.gitignore`. |
+| `entrypoints` | `string \| false` | `**/ep.*.{ts,js}` | Discovery glob for `WorkerEntrypoint` classes. Respects `.gitignore`. |
+| `workflows` | `string \| false` | `**/wf.*.{ts,js}` | Discovery glob for workflow classes. Respects `.gitignore`. |
+| `routes` | `{ dir: string; prefix?: string } \| false` | `src/routes` when that directory exists | Built-in route-tree config. `dir` changes the route root; `prefix` mounts it under a static pathname prefix such as `/api`; `false` disables route discovery. |
+| `transport` | `string \| null` | `src/transport.{ts,js,mts,mjs}` when present | Custom serialization transport file. The file must export a named `transport` object. Set `null` to disable autodiscovery explicitly. |
+
+Current `files` rules worth keeping explicit:
+
+- `compileConfig()` only writes Wrangler `main` when `files.fetch` is explicit
+- higher-level `build`, `deploy`, and `devflare/vite` flows may still generate a composed `.devflare/worker-entrypoints/main.ts` when multiple surfaces must be stitched together
+- `wrangler.passthrough.main` opts out of that composed-entry generation path
+- `createTestContext()` and local dev can still auto-discover conventional files even when you omit them from config
+
+#### `bindings`
+
+`bindings` groups Cloudflare service bindings by kind.
+
+| Key | Shape | Meaning |
+|---|---|---|
+| `kv` | `Record<string, string>` | KV namespace binding name → namespace id |
+| `d1` | `Record<string, string>` | D1 binding name → database id |
+| `r2` | `Record<string, string>` | R2 binding name → bucket name |
+| `durableObjects` | `Record<string, string \| { className: string; scriptName?: string }>` | Durable Object namespace binding. String form is shorthand for `{ className }`. Object form also covers cross-worker DOs and `ref()`-driven bindings. |
+| `queues` | `{ producers?: Record<string, string>; consumers?: QueueConsumer[] }` | Queue producer bindings plus consumer settings |
+| `services` | `Record<string, { service: string; environment?: string; entrypoint?: string }>` | Worker service bindings. `ref().worker` and `ref().worker('Entrypoint')` normalize here. |
+| `ai` | `{ binding: string }` | Workers AI binding |
+| `vectorize` | `Record<string, { indexName: string }>` | Vectorize index bindings |
+| `hyperdrive` | `Record<string, { id: string }>` | Hyperdrive bindings |
+| `browser` | `{ binding: string }` | Browser Rendering binding |
+| `analyticsEngine` | `Record<string, { dataset: string }>` | Analytics Engine dataset bindings |
+| `sendEmail` | `Record<string, { destinationAddress?: string; allowedDestinationAddresses?: string[]; allowedSenderAddresses?: string[] }>` | Outbound email bindings |
+
+Queue consumer objects currently support:
+
+| Field | Shape | Meaning |
+|---|---|---|
+| `queue` | `string` | Queue name to consume |
+| `maxBatchSize` | `number` | Max messages per batch |
+| `maxBatchTimeout` | `number` | Max seconds to wait for a batch |
+| `maxRetries` | `number` | Max retry attempts |
+| `deadLetterQueue` | `string` | Queue for permanently failed messages |
+| `maxConcurrency` | `number` | Max concurrent batch invocations |
+| `retryDelay` | `number` | Delay between retries in seconds |
+
+Two `bindings` details that matter in practice:
+
+- `bindings.sendEmail` must use either `destinationAddress` or `allowedDestinationAddresses`, not both
+- `bindings.durableObjects.*.scriptName` is how you point a binding at another worker when the class does not live in the main worker bundle
+
+#### `triggers`, `routes`, and `wsRoutes`
+
+| Property | Shape | Current behavior |
+|---|---|---|
+| `triggers.crons` | `string[]` | Cloudflare cron expressions compiled into Wrangler `triggers.crons` |
+| `routes[].pattern` | `string` | Deployment route pattern such as `example.com/*` |
+| `routes[].zone_name` | `string` | Optional zone association |
+| `routes[].zone_id` | `string` | Optional zone association alternative to `zone_name` |
+| `routes[].custom_domain` | `boolean` | Mark route as a custom domain |
+| `wsRoutes[].pattern` | `string` | Local URL pattern to intercept for WebSocket upgrades |
+| `wsRoutes[].doNamespace` | `string` | Target Durable Object namespace binding name |
+| `wsRoutes[].idParam` | `string` | Query parameter used to pick the DO instance. Defaults to `'id'`. |
+| `wsRoutes[].forwardPath` | `string` | Path forwarded inside the DO. Defaults to `'/websocket'`. |
+
+Remember the split:
+
+- `files.routes` is app routing
+- top-level `routes` is Cloudflare deployment routing
+- `wsRoutes` is local dev-time WebSocket proxy routing for Durable Objects
+
+#### `vars` and `secrets`
+
+| Property | Shape | Current behavior |
+|---|---|---|
+| `vars` | `Record<string, string>` | Non-secret runtime bindings compiled into Wrangler `vars` |
+| `secrets` | `Record<string, { required?: boolean }>` | Secret declarations only. `required` defaults to `true`. Values must come from Cloudflare secrets, tests, or upstream local tooling. |
+
+#### `assets`, `limits`, and `observability`
+
+| Property | Shape | Current behavior |
+|---|---|---|
+| `assets.directory` | `string` | Required asset directory path |
+| `assets.binding` | `string` | Optional asset binding name for programmatic access |
+| `limits.cpu_ms` | `number` | Optional CPU limit for unbound workers |
+| `observability.enabled` | `boolean` | Enable Worker Logs |
+| `observability.head_sampling_rate` | `number` | Log sampling rate from `0` to `1` |
+
+#### `migrations`
+
+Each migration object has this shape:
+
+| Field | Shape | Meaning |
+|---|---|---|
+| `tag` | `string` | Required migration version label |
+| `new_classes` | `string[]` | Newly introduced DO classes |
+| `renamed_classes` | `Array<{ from: string; to: string }>` | DO class renames with state preservation |
+| `deleted_classes` | `string[]` | Deleted DO classes |
+| `new_sqlite_classes` | `string[]` | DO classes migrating to SQLite storage |
+
+#### `rolldown`
+
+`rolldown` config applies to Devflare's Durable Object bundler.
+
+| Key | Shape | Current behavior |
+|---|---|---|
+| `target` | `string` | Bundle target for emitted DO bundles |
+| `minify` | `boolean` | Minify DO bundles |
+| `sourcemap` | `boolean` | Emit source maps for DO bundles |
+| `options` | `DevflareRolldownOptions` | Additional Rolldown input/output options and plugins, minus Devflare-owned fields |
+
+Current `rolldown.options` ownership rules:
+
+- Devflare owns `cwd`, `input`, `platform`, and `watch`
+- Devflare also owns output `codeSplitting`, `dir`, `file`, `format`, and `inlineDynamicImports`
+- output stays single-file ESM so the local DO bundling story remains worker-friendly
+- `rolldown.options.plugins` is the intended extension point for custom transforms and Rollup-compatible plugins
+
+#### `vite`
+
+`vite` is the Devflare-side Vite metadata namespace, not the place for raw Vite app config.
+
+| Key | Shape | Current behavior |
+|---|---|---|
+| `plugins` | `unknown[]` | Accepted by the schema and normalized from the legacy top-level `plugins` alias |
+| any other key | `unknown` | Preserved by the schema as Devflare-level Vite metadata, but raw Vite server/build/resolve/plugin wiring still belongs in local `vite.config.*` |
+
+That distinction is intentional:
+
+- put real Vite config in `vite.config.ts`
+- use `devflare/vite` helpers when Devflare needs to participate in the Vite pipeline
+- treat `config.vite` as Devflare-owned metadata, not as a drop-in replacement for Vite's own config file
+
+#### `env`
+
+`env` is `Record<string, EnvOverride>`, where each environment can currently override these keys:
 
-## Queues: produce in one place, consume in another
+- `name`
+- `compatibilityDate`
+- `compatibilityFlags`
+- `files`
+- `bindings`
+- `triggers`
+- `vars`
+- `secrets`
+- `routes`
+- `assets`
+- `limits`
+- `observability`
+- `migrations`
+- `rolldown`
+- `vite`
+- `wrangler`
+- deprecated `build`
+- deprecated `plugins`
 
-Devflare wants queue production and queue consumption to live in obvious places.
+Current exclusions still matter:
 
-- produce messages from `fetch` or another handler via the bound queue producer
-- consume them in `src/queue.ts`
-- test them with `cf.queue`
+- `accountId` is not supported inside `env`
+- `wsRoutes` is not supported inside `env`
+- nested `env` blocks are not part of the override shape
 
-### Queue config example
+Merge behavior is also part of the contract:
+
+- scalars override base values
+- nested objects merge
+- arrays append instead of replacing
+- `null` and `undefined` do not delete inherited values
+
+#### `wrangler`
+
+`wrangler` currently exposes one native child key:
+
+| Key | Shape | Current behavior |
+|---|---|---|
+| `passthrough` | `Record<string, unknown>` | Shallow-merged on top of the compiled Wrangler config. Use this for unsupported Wrangler keys or to take full ownership of `main`. |
+
+#### Deprecated aliases
+
+| Legacy key | Current canonical key | Notes |
+|---|---|---|
+| `build.target` | `rolldown.target` | Deprecated but still normalized |
+| `build.minify` | `rolldown.minify` | Deprecated but still normalized |
+| `build.sourcemap` | `rolldown.sourcemap` | Deprecated but still normalized |
+| `build.rolldownOptions` | `rolldown.options` | Deprecated but still normalized |
+| `plugins` | `vite.plugins` | Deprecated top-level alias; raw Vite plugin wiring still belongs in `vite.config.*` |
+
+### Native config coverage vs `wrangler.passthrough`
+
+Devflare natively models the common Worker config it actively composes around. It does **not** try to mirror every Wrangler field one-by-one as a first-class Devflare schema key.
+
+Use `wrangler.passthrough` for unsupported Wrangler options.
+
+Current merge order is:
+
+1. compile native Devflare config
+2. shallow-merge `wrangler.passthrough` on top
+3. if the same key exists in both places, the passthrough value wins
+
+Practical example:
 
 ```ts
 import { defineConfig } from 'devflare'
 
 export default defineConfig({
-	name: 'tasks-app',
-	bindings: {
-		queues: {
-			producers: {
-				TASK_QUEUE: 'task-queue'
-			},
-			consumers: [
-				{
-					queue: 'task-queue',
-					maxBatchSize: 10,
-					maxRetries: 3
-				}
-			]
-		},
-		kv: {
-			RESULTS: 'results-kv-id'
+	name: 'advanced-worker',
+	files: {
+		fetch: 'src/fetch.ts'
+	},
+	wrangler: {
+		passthrough: {
+			placement: {
+				mode: 'smart'
+			}
 		}
 	}
 })
 ```
 
-### Producer example from `fetch`
+Two practical rules:
 
-```ts
-import { env } from 'devflare'
+- if you want Devflare-managed entry composition, keep using `files.fetch`, `files.routes`, and related surface config, and do **not** set `wrangler.passthrough.main`
+- if you want total control of the Worker `main` entry, set `wrangler.passthrough.main` and own that entry file yourself
 
-export default async function fetch(request: Request): Promise<Response> {
-	const url = new URL(request.url)
+### `files`
 
-	if (url.pathname === '/tasks') {
-		const task = {
-			id: crypto.randomUUID(),
-			type: 'resize-image'
-		}
+`files` tells Devflare where your surfaces live. Use explicit paths for any surface that matters to build or deploy output, especially `files.fetch`.
 
-		await env.TASK_QUEUE.send(task)
-		return Response.json({ queued: true, task })
-	}
+| Key | Shape | Default convention | Meaning |
+|---|---|---|---|
+| `fetch` | <code>string &#124; false</code> | `src/fetch.ts` | main HTTP handler |
+| `queue` | <code>string &#124; false</code> | `src/queue.ts` | queue consumer handler |
+| `scheduled` | <code>string &#124; false</code> | `src/scheduled.ts` | scheduled handler |
+| `email` | <code>string &#124; false</code> | `src/email.ts` | incoming email handler |
+| `durableObjects` | <code>string &#124; false</code> | `**/do.*.{ts,js}` | Durable Object discovery glob |
+| `entrypoints` | <code>string &#124; false</code> | `**/ep.*.{ts,js}` | WorkerEntrypoint discovery glob |
+| `workflows` | <code>string &#124; false</code> | `**/wf.*.{ts,js}` | workflow discovery glob |
+| `routes` | <code>{ dir, prefix? } &#124; false</code> | `src/routes` when that directory exists | built-in file router configuration |
+| `transport` | <code>string &#124; null</code> | `src/transport.{ts,js,mts,mjs}` when one of those files exists | custom transport definition file |
 
-	return new Response('Not found', { status: 404 })
-}
-```
+Discovery does not behave identically in every subsystem:
 
-### Consumer example in `src/queue.ts`
+- local dev and `createTestContext()` can fall back to conventional handler files when present
+- local dev, `createTestContext()`, and higher-level worker-entry generation also auto-discover `src/routes/**` unless `files.routes` is `false`
+- type generation and discovery use default globs for Durable Objects, entrypoints, and workflows
+- `compileConfig()` only writes Wrangler `main` when `files.fetch` is explicit
+- higher-level `build`, `deploy`, and `devflare/vite` flows may still generate a composed `.devflare/worker-entrypoints/main.ts`, including route trees
+- `wrangler.passthrough.main` disables that composed-entry generation path
 
-```ts
-import type { MessageBatch } from '@cloudflare/workers-types'
+Safe rule: if a surface matters to build or deploy output, declare it explicitly even if another subsystem can discover it by convention.
 
-type Task = {
-	id: string
-	type: string
-}
+Practical example:
 
-export default async function queue(
-	batch: MessageBatch<Task>,
-	env: DevflareEnv
-): Promise<void> {
-	for (const message of batch.messages) {
-		try {
-			await env.RESULTS.put(
-				`result:${message.body.id}`,
-				JSON.stringify({ status: 'completed', type: message.body.type })
-			)
-			message.ack()
-		} catch {
-			message.retry()
-		}
+```ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig({
+	name: 'multi-surface-worker',
+	files: {
+		fetch: 'src/fetch.ts',
+		queue: 'src/queue.ts',
+		scheduled: 'src/scheduled.ts',
+		email: 'src/email.ts',
+		routes: {
+			dir: 'src/routes',
+			prefix: '/api'
+		},
+		durableObjects: 'src/do/**/*.ts',
+		entrypoints: 'src/rpc/**/*.ts',
+		workflows: 'src/workflows/**/*.ts'
 	}
-}
+})
 ```
 
-Authoring guidance:
+`files.transport` is convention-first. `createTestContext()` auto-loads `src/transport.{ts,js,mts,mjs}` when present, a string value points at a different transport file, and `files.transport: null` disables transport loading explicitly. The file must export a named `transport` object.
 
-- put queue consumers in `src/queue.ts` unless you have a strong reason not to
-- keep message bodies plain and serializable
-- use `message.ack()` on success and `message.retry()` on failure
-- bind persistence or downstream systems in config rather than hiding them in globals
+There is no public `files.tail` config key today.
 
----
+### `.env`, `.dev.vars`, `vars`, `secrets`, and `config.env`
 
-## Email: receiving and sending
+Keep these layers separate:
 
-Devflare supports two sides of email: **receiving** incoming messages and **sending** outgoing ones.
+| Layer | Holds values? | Compiled into generated config? | Use it for |
+|---|---|---|---|
+| `.env` / `process.env` | yes | indirectly, only when your config reads from it | local process-time inputs |
+| `.env.dev` / `.env.<name>` | tool/runtime-dependent | indirectly at most, only if the surrounding tool has already populated `process.env` | local process-time variants, not a Devflare-native contract |
+| `.dev.vars` / `.dev.vars.<name>` | yes | no | local runtime secret/value files in upstream Cloudflare tooling when applicable |
+| `vars` | yes | yes | non-secret string bindings |
+| `secrets` | no, declaration only | no | required/optional runtime secret bindings |
+| `config.env` | yes, as config overlays | yes after merge | environment-specific config overrides |
 
-### Receiving email
+#### `.env`, `.env.dev`, and process env
 
-Export an `email` function from `src/email.ts`. Devflare wires it as the worker's incoming email handler.
+`loadConfig()` does not do dotenv loading by itself. The Devflare CLI runs under Bun, and Bun may auto-load `.env` files into `process.env`.
 
-```ts
-// src/email.ts
-import { env } from 'devflare'
-import type { ForwardableEmailMessage } from '@cloudflare/workers-types'
-
-export async function email(message: ForwardableEmailMessage): Promise<void> {
-	const id = crypto.randomUUID()
-
-	// Log the email to KV
-	await env.EMAIL_LOG.put(
-		`email:${id}`,
-		JSON.stringify({
-			from: message.from,
-			to: message.to,
-			receivedAt: new Date().toISOString()
-		})
-	)
+Important boundary:
 
-	// Forward every incoming message to admin
-	await message.forward('admin@example.com')
-}
-```
+- Devflare sets `dotenv: false` in its config loader
+- Devflare does **not** define special first-class semantics for `.env.dev` or `.env.<name>`
+- if those files affect `process.env`, that comes from the surrounding host tool/runtime rather than a Devflare-native loader
+- config-time/build-time code can still read `process.env` inside `defineConfig()` or other Node-side tooling
 
-The `ForwardableEmailMessage` object also supports `message.reply(replyMessage)` for auto-responses.
+Treat `.env*` files as **config/build-time inputs**, not as Devflare's runtime secret system.
 
-### Sending email (the `sendEmail` binding)
+#### `.dev.vars` and local runtime secrets
 
-To send outgoing email, declare a `sendEmail` binding in config. Each key becomes a typed `env` property of type `SendEmail`.
+Devflare does **not** currently implement its own first-class `.dev.vars` / `.dev.vars.<name>` loader for worker-only dev mode or `createTestContext()`.
 
-The value object accepts an optional `destinationAddress`:
+That means:
 
-- **With `destinationAddress`** — every email sent through that binding is locked to that recipient.
-- **Without it (`{}`)** — you choose the recipient at send time.
+- do not document `.dev.vars*` as a guaranteed Devflare-native feature across all modes
+- `secrets` declares the names of expected runtime secrets, but does not provide values
+- worker-only dev and `createTestContext()` should not be described as automatically materializing secret values from `.dev.vars*`
 
-```ts
-import { defineConfig } from 'devflare'
+In Vite-backed flows, some local runtime variable behavior may come from upstream Cloudflare/Vite tooling rather than from Devflare itself. Document that as inherited upstream behavior, not as a unified Devflare contract.
 
-export default defineConfig({
-	name: 'support-mail',
-	bindings: {
-		kv: {
-			EMAIL_LOG: 'email-log-kv-id'
-		},
-		sendEmail: {
-			// Locked destination — always delivers to admin
-			ADMIN_EMAIL: { destinationAddress: 'admin@example.com' },
+#### `vars`
 
-			// Open destination — specify per message
-			EMAIL: {}
-		}
-	}
-})
-```
+Use `vars` for non-secret runtime values that can safely appear in generated config, such as public URLs, modes, IDs, and feature flags.
 
-This produces:
+In the current native Devflare schema, `vars` is:
 
-- `env.ADMIN_EMAIL: SendEmail` — hardcoded to `admin@example.com`
-- `env.EMAIL: SendEmail` — recipient provided at send time
+```ts
+Record<string, string>
+```
 
-### Testing email
+#### `secrets`
 
-Use the `email` helper from `devflare/test`:
+`secrets` is a declaration layer. Use it to say which secret bindings your worker expects and whether they are required. Do not put secret values here.
+
+In the current schema, each secret has the shape:
 
 ```ts
-import { email } from 'devflare/test'
+{ required?: boolean }
+```
 
-const response = await email.send({
-	from: 'sender@example.com',
-	to: 'recipient@example.com',
-	subject: 'Test message',
-	body: 'Hello from the test suite.'
-})
+`required` defaults to `true`, so this:
 
-expect(response.ok).toBe(true)
+```ts
+secrets: {
+	API_KEY: {}
+}
 ```
 
-Authoring guidance:
+means “`API_KEY` is a required runtime secret,” not “optional secret with no requirements.”
 
-- use `src/email.ts` for incoming mail handling
-- use `message.forward(...)` for routing workflows
-- use `message.reply(...)` when implementing auto-replies
-- use `sendEmail` bindings with `destinationAddress` when the recipient is always the same
-- use `sendEmail` bindings with `{}` when you need flexible per-message recipients
-- log metadata to KV or D1 if you need observability or replay/debugging context
+In practice, secret **values** come from outside Devflare config:
 
----
+- Cloudflare-stored runtime secrets in deployed environments
+- explicit test injection or lower-level mocks in tests
+- upstream local-dev tooling when you intentionally rely on it
 
-## Browser rendering is a real example of Devflare extending Miniflare
+Do not describe `secrets` as a place that stores values.
 
-This is worth emphasizing.
+#### Example files such as `.env.example` and `.dev.vars.example`
 
-Devflare supports **browser rendering** locally via a browser shim layer.
+Example files are a **team convention**, not a Devflare feature.
 
-That matters because browser rendering is not something Miniflare gives you directly as a complete local developer workflow.
+Current truthful guidance:
 
-With Devflare, browser rendering becomes part of the same system as the rest of your bindings and local development story:
+- use `.env.example` to document required config-time/build-time variables that your config or Node-side tooling reads from `process.env`
+- use `.dev.vars.example` to document expected local runtime secret names **if your project chooses to rely on upstream `.dev.vars` workflows**
+- keep example files committed with placeholder or fake values only
+- do not claim that Devflare auto-generates, auto-loads, or validates these example files today
 
-- declare the browser binding in config
-- run the app through Devflare’s orchestration
-- use the browser capability locally with the rest of your worker system
+#### Canonical env and secrets layout
 
-This is exactly the kind of feature that demonstrates the Devflare philosophy:
+If you want the lowest-confusion setup, use this split:
 
-> take a low-level runtime foundation, then add the higher-level orchestration developers actually need
+- `.env.example` documents config-time/build-time inputs
+- `.dev.vars.example` documents local runtime secret names **only if your project intentionally relies on upstream `.dev.vars` workflows**
+- `devflare.config.ts` reads config-time values from `process.env`, puts safe runtime values in `vars`, and declares required runtime secret names in `secrets`
+- deployed secret values live in Cloudflare, not in your repo
 
----
+Recommended project shape:
 
-## Durable Objects and multi-worker systems
+```text
+my-worker/
+├─ .env.example
+├─ .dev.vars.example        # optional; only if you intentionally use upstream .dev.vars flows
+├─ .gitignore
+├─ devflare.config.ts
+└─ src/
+	└─ fetch.ts
+```
 
-Devflare is designed to keep multi-worker and DO-heavy systems manageable.
+Example `.env.example`:
 
-### Local Durable Objects
+```dotenv
+WORKER_NAME=my-worker
+API_ORIGIN=http://localhost:3000
+```
 
-Bind them in config:
+Example `.dev.vars.example`:
 
-```ts
-bindings: {
-	durableObjects: {
-		COUNTER: 'Counter'
-	}
-}
+```dotenv
+API_KEY=replace-me
+SESSION_SECRET=replace-me
 ```
 
-Put their classes in `do.*.ts` files.
+Typical git ignore pattern for user projects:
 
-### Complete local Durable Object example
+```gitignore
+.env
+.env.*
+!.env.example
+.dev.vars
+.dev.vars.*
+!.dev.vars.example
+```
 
-If you need to generate a normal local Durable Object and call it from HTTP code, prefer this shape.
+Example `devflare.config.ts`:
 
 ```ts
-// devflare.config.ts
 import { defineConfig } from 'devflare'
 
 export default defineConfig({
-	name: 'sessions-app',
-	bindings: {
-		durableObjects: {
-			SESSION: 'SessionStore'
+	name: process.env.WORKER_NAME ?? 'my-worker',
+	compatibilityDate: '2026-03-17',
+	files: {
+		fetch: 'src/fetch.ts'
+	},
+	vars: {
+		API_ORIGIN: process.env.API_ORIGIN ?? 'http://localhost:3000'
+	},
+	secrets: {
+		API_KEY: {},
+		SESSION_SECRET: {}
+	},
+	env: {
+		production: {
+			vars: {
+				API_ORIGIN: 'https://api.example.com'
+			}
 		}
 	}
 })
 ```
 
+Example `src/fetch.ts`:
+
 ```ts
-// src/do.session.ts
-import { DurableObject } from 'cloudflare:workers'
+import type { FetchEvent } from 'devflare/runtime'
 
-export class SessionStore extends DurableObject<DevflareEnv> {
-	private data = new Map<string, string>()
+export async function GET({ env }: FetchEvent<DevflareEnv>): Promise<Response> {
+	return Response.json({
+		origin: env.API_ORIGIN,
+		hasApiKey: Boolean(env.API_KEY),
+		hasSessionSecret: Boolean(env.SESSION_SECRET)
+	})
+}
+```
 
-	getValue(key: string): string | null {
-		return this.data.get(key) ?? null
-	}
+Deployed runtime secrets should be created with Cloudflare/Wrangler tooling, not committed to config files or example files.
 
-	setValue(key: string, value: string): void {
-		this.data.set(key, value)
-	}
+Typical deployed secret flow:
 
-	clearAll(): void {
-		this.data.clear()
-	}
-}
+```bash
+bunx --bun wrangler secret put API_KEY
+bunx --bun wrangler secret put SESSION_SECRET
 ```
 
-```ts
-// src/fetch.ts
-import { env } from 'devflare'
+If you use named Cloudflare environments, set the secret in that environment explicitly:
 
-export default async function fetch(request: Request): Promise<Response> {
-	const url = new URL(request.url)
-	const sessionId = url.searchParams.get('session') ?? 'default'
+```bash
+bunx --bun wrangler secret put API_KEY --env production
+bunx --bun wrangler secret put SESSION_SECRET --env production
+```
 
-	const id = env.SESSION.idFromName(sessionId)
-	const session = env.SESSION.get(id)
+Practical rule of thumb:
 
-	if (url.pathname === '/set') {
-		const key = url.searchParams.get('key') ?? 'name'
-		const value = url.searchParams.get('value') ?? 'Arthur'
-		await session.setValue(key, value)
-		return Response.json({ ok: true })
-	}
+- if a value is needed while evaluating config, put it in the `.env*` / `process.env` bucket
+- if a value should exist as a runtime binding but must not be committed, declare it in `secrets`
+- if a project wants local runtime secret files, treat `.dev.vars*` as an upstream convention and document it explicitly per project
 
-	if (url.pathname === '/get') {
-		const key = url.searchParams.get('key') ?? 'name'
-		const value = await session.getValue(key)
-		return Response.json({ value })
-	}
+#### `devflare types`
 
-	if (url.pathname === '/clear') {
-		await session.clearAll()
-		return Response.json({ ok: true })
-	}
+`devflare types` generates `env.d.ts` from the resolved config plus discovered surfaces. The stable public result is typed `DevflareEnv` coverage for bindings such as `vars`, `secrets`, services, Durable Objects, and discovered entrypoints.
 
-	return new Response('Not found', { status: 404 })
-}
-```
+Import-path behavior stays the same as described earlier: the main-entry `env` is the broader typed access story, while `devflare/runtime` is the strict request-scoped runtime helper.
 
-Important authoring notes:
+#### `config.env`
 
-- extend `DurableObject` from `cloudflare:workers`
-- bind the namespace in `bindings.durableObjects`
-- put the class in a `do.*.ts` file so discovery works naturally
-- create a stub with `env.SESSION.get(env.SESSION.idFromName(...))`
-- keep RPC-style method inputs and outputs simple and serializable
+`config.env` is Devflare’s environment override layer. When you pass `--env <name>` or call `compileConfig(config, name)`, Devflare starts from the base config, merges `config.env[name]` into it, and compiles the resolved result.
 
-### Transport layer example: Devflare encodes and decodes for you
+Current merge behavior uses deep merge semantics:
 
-Use `src/transport.ts` when a Worker or Durable Object returns custom classes that should survive supported RPC/test boundaries as real instances.
+- scalar fields override base values
+- nested objects inherit omitted keys
+- arrays append instead of replacing
+- `null` and `undefined` do not delete base values
 
-```ts
-// src/DoubleableNumber.ts
-export class DoubleableNumber {
-	value: number
+If you need full replacement behavior, compute the final value in `defineConfig()` instead of relying on `config.env`.
 
-	constructor(n: number) {
-		this.value = n
-	}
-
-	get double() {
-		return this.value * 2
-	}
-}
-```
+Example:
 
 ```ts
-// src/transport.ts
-import { DoubleableNumber } from './DoubleableNumber'
+import { defineConfig } from 'devflare'
 
-export const transport = {
-	DoubleableNumber: {
-		encode: (v: unknown) => v instanceof DoubleableNumber && v.value,
-		decode: (v: number) => new DoubleableNumber(v)
+export default defineConfig({
+	name: 'api',
+	files: {
+		fetch: 'src/fetch.ts'
+	},
+	vars: {
+		APP_ENV: 'development',
+		API_ORIGIN: 'http://localhost:3000'
+	},
+	bindings: {
+		kv: {
+			CACHE: 'api-cache-dev'
+		}
+	},
+	env: {
+		production: {
+			vars: {
+				APP_ENV: 'production',
+				API_ORIGIN: 'https://api.example.com'
+			},
+			bindings: {
+				kv: {
+					CACHE: 'api-cache'
+				}
+			}
+		}
 	}
-}
+})
 ```
 
-```ts
-// src/do.counter.ts
-import { DoubleableNumber } from './DoubleableNumber'
+With `--env production`, the resolved config keeps `files.fetch`, overrides the `vars`, and overrides `bindings.kv.CACHE`.
 
-export class Counter {
-	private count = 0
+Current limitation: `accountId` and `wsRoutes` are not supported inside `config.env`. Compute those in the outer `defineConfig()` function when you need environment-specific values.
 
-	getValue(): DoubleableNumber {
-		return new DoubleableNumber(this.count)
-	}
+---
+
+## Bindings and multi-worker composition
+
+### Binding groups
+
+| Group | Members | Coverage wording | Safe promise |
+|---|---|---|---|
+| Core bindings | `kv`, `d1`, `r2`, `durableObjects`, `queues.producers`, `queues.consumers` | well-covered | safest public binding path today across config, generated types, and local dev/test |
+| Services and `ref()` | `services` | well-covered with a named-entrypoint caveat | worker-to-worker composition is solid; validate generated output when a named entrypoint matters |
+| Remote-oriented bindings | `ai`, `vectorize` | remote-dependent | supported and typed, but not full local equivalents of KV or D1 |
+| Narrower bindings | `hyperdrive`, `analyticsEngine`, `browser` | supported, narrower-scope | real public surfaces, but less central than the core storage/runtime path |
+| Outbound email binding | `sendEmail` | supported public surface | real outbound email binding; keep it separate from inbound email handling |
+
+### Core bindings
+
+KV, D1, R2, Durable Objects, and queues have the clearest end-to-end story today across config, generated types, and local dev/test flows.
+
+### R2 browser access and public URLs
+
+`bindings.r2` gives you real R2 binding access in local dev, tests, generated types, and compiled config.
 
-	increment(n: number = 1): DoubleableNumber {
-		this.count += n
-		return new DoubleableNumber(this.count)
+What Devflare does **not** currently expose as a public contract is a stable browser-facing local bucket URL.
+
+If you need browser-visible local asset flows:
+
+- serve them through your Worker routes or app endpoints
+- test real public/custom-domain URL behavior against an intentional staging bucket
+- do not hard-code frontend assumptions about a magic local bucket origin
+
+For delivery patterns and production recommendations, see [`R2.md`](./R2.md).
+
+Practical example:
+
+```ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig({
+	name: 'orders-worker',
+	bindings: {
+		kv: {
+			CACHE: 'orders-cache'
+		},
+		d1: {
+			DB: 'orders-db'
+		},
+		durableObjects: {
+			COUNTER: 'Counter'
+		},
+		queues: {
+			producers: {
+				TASK_QUEUE: 'orders-tasks'
+			}
+		}
 	}
-}
+})
 ```
 
 ```ts
-// tests/counter.test.ts
-import { beforeAll, afterAll, describe, expect, test } from 'bun:test'
-import { createTestContext } from 'devflare/test'
-import { env } from 'devflare'
-import { DoubleableNumber } from '../src/DoubleableNumber'
+import type { FetchEvent } from 'devflare/runtime'
 
-beforeAll(() => createTestContext())
-afterAll(() => env.dispose())
+export async function POST({ env }: FetchEvent<DevflareEnv>): Promise<Response> {
+	const status = await env.DB.prepare('select 1 as ok').first()
+	await env.CACHE.put('health', JSON.stringify(status))
+	await env.TASK_QUEUE.send({ type: 'reindex-orders' })
+	return Response.json({ ok: true })
+}
+```
 
-describe('counter transport', () => {
-	test('result is decoded back into a class instance', async () => {
-		const id = env.COUNTER.idFromName('main')
-		const counter = env.COUNTER.get(id)
-		const result = await counter.increment(2)
+### Services and named entrypoints
 
-		expect(result).toBeInstanceOf(DoubleableNumber)
-		expect(result.double).toBe(4)
-	})
-})
-```
+Service bindings can be written directly or via `ref()`.
 
-What Devflare is doing for the developer:
+```ts
+import { defineConfig, ref } from 'devflare'
 
-1. your DO returns `new DoubleableNumber(...)`
-2. Devflare finds a matching encoder in `src/transport.ts`
-3. the value is serialized while crossing the boundary
-4. Devflare applies the decoder on the receiving side
-5. your code gets a real `DoubleableNumber` instance back
+const auth = ref(() => import('../auth/devflare.config'))
 
-This means the developer writes the codec once and then works with real domain objects rather than manual serialization code.
+export default defineConfig({
+	name: 'gateway',
+	bindings: {
+		services: {
+			AUTH: auth.worker,
+			ADMIN: auth.worker('AdminEntrypoint')
+		}
+	}
+})
+```
 
-### Cross-worker references
+Direct worker-to-worker service composition is a strong public path. Named service entrypoints are typed and configurable, but if a specific entrypoint matters at deployment time, validate the generated output in your project.
 
-Use `ref()` when one worker depends on another worker or another worker’s DO bindings.
+Practical example:
 
 ```ts
+// gateway/devflare.config.ts
 import { defineConfig, ref } from 'devflare'
 
-const authWorker = ref(() => import('../auth/devflare.config'))
+const auth = ref(() => import('../auth/devflare.config'))
 
 export default defineConfig({
 	name: 'gateway',
 	bindings: {
 		services: {
-			AUTH: authWorker.worker
+			ADMIN: auth.worker('AdminEntrypoint')
 		}
 	}
 })
 ```
 
-This is cleaner than scattering worker names and entrypoint names by hand throughout the codebase.
-
----
+```ts
+// gateway/src/fetch.ts
+import type { FetchEvent } from 'devflare/runtime'
 
-## Runtime-safe helpers
+export async function GET({ env }: FetchEvent<DevflareEnv>): Promise<Response> {
+	const stats = await env.ADMIN.getStats()
+	return Response.json(stats)
+}
+```
 
-Import runtime-only utilities from `devflare/runtime` when the code runs inside Workers.
+### Remote-oriented and narrower bindings
 
-Important helpers include:
+`ai` and `vectorize` are remote-dependent bindings. Devflare supports their config and typing, but they should not be documented as full local equivalents of KV or D1.
 
-- `sequence()`
-- `resolve()`
-- `pipe()`
-- context-related utilities
+`hyperdrive`, `analyticsEngine`, and `browser` are supported narrower-scope surfaces. `browser` also sits closer to the dev-orchestration layer than to the core fetch/queue path.
 
-Use this path when you want runtime-safe middleware composition without pulling in Node-oriented orchestration code.
+### `sendEmail` and inbound email
 
----
+`sendEmail` is the outbound email binding surface. It is supported across config, generated types, and local development flows.
 
-## Testing model
+Incoming email is a separate worker surface:
 
-Devflare testing is one of the library’s biggest strengths.
+- `files.email`
+- `src/email.ts`
+- `EmailEvent`
 
-### Integration-style local tests
+Keep outbound `sendEmail` and inbound email handling separate in docs and examples.
 
-Use `createTestContext()` when you want a real local Devflare environment backed by Miniflare orchestration.
+Practical example:
 
 ```ts
-import { beforeAll, afterAll, describe, expect, test } from 'bun:test'
-import { createTestContext, cf } from 'devflare/test'
-import { env } from 'devflare'
+// devflare.config.ts
+import { defineConfig } from 'devflare'
 
-beforeAll(() => createTestContext())
-afterAll(() => env.dispose())
+export default defineConfig({
+	name: 'mail-worker',
+	files: {
+		fetch: 'src/fetch.ts',
+		email: 'src/email.ts'
+	},
+	bindings: {
+		sendEmail: {
+			EMAIL: {
+				destinationAddress: 'team@example.com'
+			}
+		}
+	}
+})
+```
 
-describe('worker', () => {
-	test('GET /health', async () => {
-		const response = await cf.worker.get('/health')
-		expect(response.status).toBe(200)
+```ts
+// src/fetch.ts
+import type { FetchEvent } from 'devflare/runtime'
+
+export async function POST({ env }: FetchEvent<DevflareEnv>): Promise<Response> {
+	await env.EMAIL.send({
+		from: 'noreply@example.com',
+		to: 'team@example.com',
+		subject: 'Welcome',
+		text: 'Hello from Devflare'
 	})
-})
+
+	return new Response('sent')
+}
 ```
 
-### Mock/unit-style tests
+```ts
+// src/email.ts
+import type { EmailEvent } from 'devflare/runtime'
 
-Use `createMockTestContext()`, `withTestContext()`, and the mock binding helpers when you want pure logic tests.
+export async function email({ message }: EmailEvent<DevflareEnv>): Promise<void> {
+	await message.forward('ops@example.com')
+}
+```
 
-### Why this is better than ad hoc Miniflare setup
+### `ref()` and multi-worker composition
 
-Devflare gives you a single mental model for testing each handler surface:
+Use `ref()` when one worker depends on another worker config.
 
-- HTTP via `cf.worker`
-- queues via `cf.queue`
-- cron via `cf.scheduled`
-- email via `cf.email`
-- tail events via `cf.tail`
+Main public story:
 
-That consistency is part of the value. Instead of every project inventing its own test harness, Devflare gives you one coherent interface.
+- `ref(...).worker` for a default service binding backed by `src/worker.ts` or `src/worker.js`
+- `ref(...).worker('EntrypointName')` for a named service entrypoint
+- typed cross-worker Durable Object handles
+
+```ts
+const auth = ref(() => import('../auth/devflare.config'))
+```
+
+```ts
+const auth = ref('custom-auth-name', () => import('../auth/devflare.config'))
+```
+
+Why `ref()` matters:
+
+- worker names stay centralized
+- cross-worker Durable Object bindings stay typed
+- entrypoint names can be typed from generated `Entrypoints`
+- multi-worker systems avoid scattered magic strings
+
+Advanced members such as `.name`, `.config`, `.configPath`, and `.resolve()` are real, but secondary to the main composition story.
 
 ---
 
-## Vite and SvelteKit integration
+## Development workflows
 
-Devflare includes dedicated framework-aware entry points.
+### Vite vs Rolldown: the truthful mental model
 
-### `devflare/vite`
+They are both important, but they are not two names for the same job.
 
-Use this when you want:
+| Tool | Role inside Devflare | When it matters most | What it is not |
+|---|---|---|---|
+| `Vite` | the optional outer dev/build host for packages that are already Vite apps or frameworks; Devflare plugs generated Worker config, config watching, auxiliary DO workers, and bridge behavior into that pipeline | packages with a local `vite.config.*`, SvelteKit, frontend HMR | not Devflare's own Worker bundler |
+| `Rolldown` | the inner code-transforming builder Devflare uses when Devflare itself bundles Worker code | Durable Object bundles, watch/rebuild, worker-side plugin transforms such as `.svelte` imported by a DO module | not the main app's Vite build |
 
-- config compilation during dev and build
-- worker-aware transforms
-- auxiliary Durable Object worker generation
-- websocket-aware proxying for local development
+Three practical consequences fall straight out of the implementation:
 
-### `devflare/sveltekit`
+- remove `vite.config.*`, and Devflare drops back to worker-only mode instead of starting Vite
+- import `.svelte` from a Durable Object, and the compilation belongs to `rolldown.options.plugins`, not to the main Vite plugin chain
+- generated `.devflare/worker-entrypoints/main.ts` is separate glue code produced by Devflare when it needs to compose fetch, queue, scheduled, email, or route-tree surfaces into one Worker entry
 
-Use this when your app needs:
+### Operational decision rules
 
-- a Devflare-aware platform object
-- integration between SvelteKit and Worker bindings
-- local dev behavior that still fits the Devflare model
+Use these rules in order:
 
-This is another example of Devflare going beyond raw local runtime emulation. It helps compose framework tooling, worker bindings, auxiliary workers, and local dev behavior into one predictable setup.
+1. a local `vite.config.*` in the current package decides whether `dev`, `build`, and `deploy` run in Vite-backed mode or worker-only mode
+2. `devflare/vite` is an explicit helper layer, not a separate CLI mode
+3. worker-only mode is a supported first-class path; no local `vite.config.*` means Devflare does not start Vite
+4. raw Vite config belongs in `vite.config.*`; `config.vite` is Devflare metadata, not full Vite config
+5. treat `.devflare/*`, `env.d.ts`, and generated Wrangler config as outputs, not authoring inputs
+6. remote mode is mainly for remote-oriented services such as AI and Vectorize, not a blanket “make everything remote” switch
 
----
+### Vite-backed workflows
 
-## Remote-only services
+A package enters Vite-backed mode when it has a local `vite.config.*`. In that mode, Vite is the outer application pipeline: it owns the package's dev server and app build, while Devflare injects Worker-aware config, generated Wrangler output, auxiliary DO worker config, and bridge behavior into that Vite stack.
 
-Some Cloudflare services are not meaningfully local.
+Current Vite-backed flow:
 
-Most importantly:
+1. Devflare loads and validates `devflare.config.*`
+2. `devflarePlugin()` compiles that config into a generated `.devflare/wrangler.jsonc`
+3. Devflare may generate `.devflare/worker-entrypoints/main.ts` when multiple surfaces must be composed into one Worker entry
+4. if Durable Object files are discovered, Devflare builds an auxiliary DO worker config for Vite / Cloudflare interop
+5. in serve mode, Devflare watches the resolved Devflare config file and triggers a full reload when it changes
+6. if `wsRoutes` are configured, Devflare can proxy matching WebSocket upgrade paths to the Miniflare bridge
+7. on build, Devflare runs `bunx vite build` only after it has prepared the Worker config for that package
 
-- Workers AI
-- Vectorize
+Two ownership rules matter here:
 
-Devflare treats those as explicit remote-mode concerns rather than pretending they are fully local.
+- setting `wrangler.passthrough.main` tells Devflare to preserve your explicit Worker `main` instead of generating a composed one
+- no local `vite.config.*` means none of this Vite-specific behavior runs; the package stays in worker-only mode
 
-That is a good thing.
+#### `devflare/vite` helpers
 
-It keeps the local story honest while still giving you an intentional path to test remote capabilities when needed.
+| Helper | Use it for | Timing |
+|---|---|---|
+| `devflarePlugin(options)` | generated `.devflare/wrangler.jsonc`, config watching, DO discovery, DO transforms, and WebSocket proxy wiring | include it in `vite.config.*` plugins |
+| `getCloudflareConfig(options)` | compiled programmatic config for `cloudflare({ config })` | call during Vite config creation |
+| `getDevflareConfigs(options)` | compiled config plus `auxiliaryWorkers` array for DO workers | call during Vite config creation |
+| `getPluginContext()` | read resolved plugin state such as `wranglerConfig`, `cloudflareConfig`, discovered DOs, and `projectRoot` | advanced use only, after Vite has resolved config |
 
-Use the `devflare remote` workflow and guard remote-only tests appropriately.
+`devflarePlugin(options)` currently supports these options:
 
----
+| Option | Default | What it changes |
+|---|---|---|
+| `configPath` | auto-resolve local supported config | point Vite at a specific `devflare.config.*` file |
+| `environment` | no explicit override | resolve `config.env[name]` before compilation |
+| `doTransforms` | `true` | enable or disable Devflare's DO code transforms |
+| `watchConfig` | `true` | watch the resolved config file and full-reload on change |
+| `bridgePort` | `process.env.DEVFLARE_BRIDGE_PORT`, then `8787` when proxying | choose the Miniflare bridge port for WebSocket proxying |
+| `wsProxyPatterns` | `[]` | add extra WebSocket proxy patterns beyond configured `wsRoutes` |
 
-## Generated artifacts
+Timing rule of thumb:
 
-Devflare uses `.devflare/` for generated local artifacts.
+- if you need config while building the Vite config object, use `getCloudflareConfig()` or `getDevflareConfigs()`
+- if another Vite plugin needs to inspect the already-resolved Devflare state, `getPluginContext()` is the advanced hook
 
-Treat that directory as generated output rather than hand-authored source.
+#### Minimal Vite wiring
 
----
+```ts
+import { defineConfig } from 'vite'
+import { devflarePlugin } from 'devflare/vite'
 
-## Recommended project structure
+export default defineConfig({
+	plugins: [devflarePlugin()]
+})
+```
 
-Here is a strong default layout for most projects.
+#### Explicit `@cloudflare/vite-plugin` wiring
 
-```text
-.
-├── devflare.config.ts
-├── env.d.ts
-├── src/
-│   ├── fetch.ts
-│   ├── queue.ts
-│   ├── scheduled.ts
-│   ├── email.ts
-│   ├── transport.ts
-│   ├── routes/
-│   ├── do.counter.ts
-│   ├── ep.admin.ts
-│   └── wf.sync.ts
-└── tests/
-    └── worker.test.ts
-```
-
-You will not always need every file.
-
-But this shape captures the Devflare philosophy well:
-
-- each capability gets an isolated home
-- config stays declarative
-- tests target named surfaces
-- local orchestration is handled by Devflare instead of bespoke glue
+```ts
+import { defineConfig } from 'vite'
+import { cloudflare } from '@cloudflare/vite-plugin'
+import { devflarePlugin, getDevflareConfigs } from 'devflare/vite'
+
+export default defineConfig(async () => {
+	const { cloudflareConfig, auxiliaryWorkers } = await getDevflareConfigs()
+
+	return {
+		plugins: [
+			devflarePlugin(),
+			cloudflare({
+				config: cloudflareConfig,
+				auxiliaryWorkers: auxiliaryWorkers.length > 0 ? auxiliaryWorkers : undefined
+			})
+		]
+	}
+})
+```
 
----
+That is the current high-signal pattern when you want Vite to stay the package's app/build host while Devflare owns Worker config compilation and Durable Object discovery.
 
-## Guidance for LLMs generating Devflare code
+#### SvelteKit-backed Worker example
 
-When generating Devflare projects or edits, follow these rules.
+```ts
+// devflare.config.ts
+import { defineConfig } from 'devflare'
 
-### Prefer conventions first
+export default defineConfig({
+	name: 'notes-app',
+	files: {
+		fetch: '.svelte-kit/cloudflare/_worker.js',
+		durableObjects: 'src/do/**/*.ts',
+		transport: 'src/transport.ts'
+	},
+	bindings: {
+		durableObjects: {
+			CHAT_ROOM: 'ChatRoom'
+		}
+	}
+})
+```
 
-Only override paths when there is a real reason.
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { sveltekit } from '@sveltejs/kit/vite'
+import { devflarePlugin } from 'devflare/vite'
 
-### Prefer separation of responsibilities
+export default defineConfig({
+	plugins: [
+		devflarePlugin(),
+		sveltekit()
+	]
+})
+```
 
-Do **not** collapse fetch, queue, scheduled, email, DOs, and entrypoints into a single file unless the task explicitly demands that shape.
+```ts
+// src/hooks.server.ts
+export { handle } from 'devflare/sveltekit'
+```
 
-### Prefer `defineConfig()`
+Use `createHandle({...})` from `devflare/sveltekit` when you need custom binding hints or want to compose Devflare with other SvelteKit handles via `sequence(...)`.
 
-Never emit untyped ad hoc config objects when a normal Devflare config is appropriate.
+### Rolldown bundling and plugin workflows
 
-### Prefer `ref()` for cross-worker relationships
+`rolldown` is not just a namespace of knobs. Rolldown is the builder Devflare uses for the code Devflare actively bundles itself. Today that means the Durable Object path: Devflare discovers DO source files, applies its own transforms, lets user plugins transform imports, and emits runnable single-file ESM Worker modules that Miniflare can execute.
 
-Avoid manually duplicating worker names and binding metadata.
+That is why `rolldown` is important but different from Vite:
 
-### Prefer `devflare/test` for tests
+- Vite may host the outer app or framework pipeline
+- Rolldown is the inner code-transform step that turns DO source into actual runnable worker code
+- if a Durable Object imports `.svelte`, that compilation belongs to the Rolldown plugin pipeline, not to the main Vite app plugin chain
 
-Use `createTestContext()` for integration-style tests and mock helpers for unit tests.
+It is still not Vite config, not a replacement for your app's `vite.config.*`, and not the place to configure the main fetch build.
 
-### Prefer `env` for ergonomic binding access
+Current DO bundler behavior:
 
-Use `import { env } from 'devflare'` when it improves clarity.
+- Devflare discovers DO files from `files.durableObjects`
+- discovered DO entries are bundled to worker-compatible ESM
+- code splitting is disabled so Devflare can emit a worker-friendly single-file bundle
+- user `rolldown.options.plugins` are merged into the bundle pipeline
+- internal externals cover `cloudflare:*`, `node:*`, and other worker/runtime modules that should stay external
+- Devflare also injects a `debug` alias shim so worker bundles do not accidentally drag in a Node-only debug dependency
+- this same DO bundling path still matters in unified Vite dev; Vite can host the app while Rolldown rebuilds DO worker code underneath it
 
-### Respect remote-only boundaries
+Rolldown's plugin API is almost fully compatible with Rollup's, which is why Rollup-style plugins can often be passed through in `rolldown.options.plugins`. That said, compatibility is high, not magical: keep integration tests around nontrivial plugin stacks.
 
-Do not fake fully local AI or Vectorize support.
+#### Minimal custom transform example
 
-### Use routing when HTTP complexity grows
+```ts
+import { defineConfig } from 'devflare'
+import type { Plugin as RolldownPlugin } from 'rolldown'
 
-If the app has many endpoints, prefer `files.routes` and route files over a giant `fetch.ts` dispatcher.
+const inlineSvelteFixturePlugin: RolldownPlugin = {
+	name: 'inline-svelte-fixture',
+	transform(_code, id) {
+		if (!id.endsWith('.svelte')) {
+			return null
+		}
 
----
+		return {
+			code: 'export default { render() { return { html: "<h1>Hello from Svelte</h1>" } } }',
+			map: null
+		}
+	}
+}
+
+export default defineConfig({
+	name: 'do-worker',
+	files: {
+		durableObjects: 'src/do/**/*.ts'
+	},
+	bindings: {
+		durableObjects: {
+			GREETER: 'Greeter'
+		}
+	},
+	rolldown: {
+		options: {
+			plugins: [inlineSvelteFixturePlugin]
+		}
+	}
+})
+```
+
+That mirrors the kind of `.svelte` transform path the repo's own DO bundler tests exercise.
+
+#### Svelte plugin example for Rolldown
 
-## Minimal example
+This example is intentionally about a `.svelte` import inside a Durable Object module. In that situation, Rolldown — not the main Vite app build — is the plugin pipeline doing the compilation.
+
+For this pattern you typically install `svelte`, `rollup-plugin-svelte`, and `@rollup/plugin-node-resolve` in the package that owns the Durable Object code.
 
 ```ts
-// devflare.config.ts
 import { defineConfig } from 'devflare'
+import resolve from '@rollup/plugin-node-resolve'
+import type { Plugin as RolldownPlugin } from 'rolldown'
+import svelte from 'rollup-plugin-svelte'
 
 export default defineConfig({
-	name: 'hello-worker'
+	name: 'chat-worker',
+	files: {
+		durableObjects: 'src/do/**/*.ts'
+	},
+	bindings: {
+		durableObjects: {
+			CHAT_ROOM: 'ChatRoom'
+		}
+	},
+	rolldown: {
+		target: 'es2022',
+		sourcemap: true,
+		options: {
+			plugins: [
+				svelte({
+					emitCss: false,
+					compilerOptions: {
+						generate: 'ssr'
+					}
+				}) as unknown as RolldownPlugin,
+				resolve({
+					browser: true,
+					exportConditions: ['svelte'],
+					extensions: ['.svelte']
+				}) as unknown as RolldownPlugin
+			]
+		}
+	}
 })
 ```
 
+```svelte
+<!-- src/do/Greeting.svelte -->
+<script lang='ts'>
+	export let name: string
+</script>
+
+<h1>Hello {name} from Svelte</h1>
+```
+
 ```ts
-// src/fetch.ts
-export default async function fetch(): Promise<Response> {
-	return new Response('Hello from Devflare')
+// src/do/chat-room.ts
+import { DurableObject } from 'cloudflare:workers'
+import Greeting from './Greeting.svelte'
+
+export class ChatRoom extends DurableObject {
+	async fetch(): Promise<Response> {
+		return new Response(Greeting.render({ name: 'Devflare' }).html, {
+			headers: {
+				'content-type': 'text/html; charset=utf-8'
+			}
+		})
+	}
 }
 ```
 
+What happens in this flow:
+
+1. Devflare discovers `src/do/**/*.ts` from `files.durableObjects`
+2. the DO module imports `Greeting.svelte`
+3. Rolldown runs the configured plugin pipeline, including `rollup-plugin-svelte`
+4. the Svelte component becomes JavaScript before the DO bundle is written
+5. Devflare writes a runnable single-file Worker bundle for that DO
+
+Why this example is shaped that way:
+
+- `emitCss: false` keeps the DO bundle single-file instead of emitting a separate CSS asset pipeline
+- `generate: 'ssr'` fits the Worker-side rendering story better than a browser DOM target
+- `@rollup/plugin-node-resolve` helps `.svelte` files and `exports.svelte` packages resolve cleanly
+- some Rollup plugins need a type cast to satisfy Rolldown's TypeScript types even when the runtime hooks work fine
+- this example is specifically about worker-side component compilation inside a DO; if your Svelte code lives in the main app or SvelteKit shell, that outer build is still Vite's job
+
+If a plugin relies on Rollup-only hooks that Rolldown does not support yet, keep that plugin in your main Vite build instead of the DO bundler.
+
+### Daily development loop
+
+Use the same CLI loop for both worker-only and Vite-backed packages. The presence of a local `vite.config.*` changes the mode automatically.
+
+```bash
+bunx --bun devflare dev
+bunx --bun devflare types
+bunx --bun devflare doctor
+bunx --bun devflare build --env staging
+bunx --bun devflare deploy --dry-run --env staging
+```
+
+Use `--env <name>` on build and deploy when you want Devflare to resolve a named config environment before compilation.
+
+### CLI reference
+
+| Command | What it does | Important note |
+|---|---|---|
+| `devflare init` | scaffold a project | current templates generate `src/fetch.ts` and explicit `files.fetch` |
+| `devflare dev` | start local development | worker-only by default, Vite-backed only when the current package has a local `vite.config.*` |
+| `devflare build` | build from resolved config | skips Vite for worker-only packages |
+| `devflare deploy` | build and deploy | supports `--env` and `--dry-run` |
+| `devflare types` | generate `env.d.ts` | supports `--output` |
+| `devflare doctor` | check project configuration | supports `--config` |
+| `devflare account` | inspect accounts, resources, usage, and limits | `global` and `workspace` are account-selection flows, not resource-reporting subcommands |
+| `devflare ai` | show Workers AI model pricing | informational command |
+| `devflare remote` | manage remote test mode | helper flow for remote-oriented services |
+| `devflare help` | show help | direct command and flag form both work |
+| `devflare version` | show package version | sourced from installed package metadata |
+
+### `doctor`
+
+Current `doctor` behavior:
+
+- it checks for supported Devflare config filenames
+- it can inspect an explicit config path via `--config`
+- it accepts project-root `wrangler.jsonc`
+- Vite-backed flows may instead generate `.devflare/wrangler.jsonc`
+
+---
+
+## Testing model
+
+Use `devflare/test`.
+
+The default pairing is:
+
 ```ts
-// tests/worker.test.ts
-import { beforeAll, afterAll, describe, expect, test } from 'bun:test'
-import { createTestContext, cf } from 'devflare/test'
+import { beforeAll, afterAll } from 'bun:test'
+import { createTestContext } from 'devflare/test'
 import { env } from 'devflare'
 
 beforeAll(() => createTestContext())
 afterAll(() => env.dispose())
+```
+
+`createTestContext()` is the recommended default for most integration-style tests.
+
+Current behavior:
+
+- it can auto-discover the nearest supported config file by walking upward from the calling test file
+- it sets up the main-entry test env used by `import { env } from 'devflare'`
+- it resolves service bindings and cross-worker Durable Object references
+- it can infer conventional fetch, queue, scheduled, and email handler files when present
+- it also auto-detects `src/tail.ts` when present, even though there is no public `files.tail` config key
+- it auto-detects `src/transport.{ts,js,mts,mjs}` when present unless `files.transport` is `null`
+- it does not have a first-class `.dev.vars*` loader for populating declared secret values
 
-describe('hello-worker', () => {
-	test('GET / returns text', async () => {
-		const response = await cf.worker.get('/')
+Practical example:
+
+```ts
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import { cf, createTestContext } from 'devflare/test'
+import { env } from 'devflare'
+
+beforeAll(() => createTestContext())
+afterAll(() => env.dispose())
+
+describe('users routes', () => {
+	test('GET /users/123 uses the built-in file router', async () => {
+		const response = await cf.worker.get('/users/123')
 		expect(response.status).toBe(200)
-		expect(await response.text()).toBe('Hello from Devflare')
+		expect(await response.json()).toEqual({ id: '123' })
+	})
+
+	test('queue side effects can be asserted with real bindings', async () => {
+		await cf.queue.trigger([
+			{ type: 'reindex', id: 'job-1' }
+		])
+
+		expect(await env.RESULTS.get('job-1')).toBe('done')
 	})
 })
 ```
 
+### Helper behavior
+
+Do not assume every `cf.*` helper behaves the same way.
+
+| Helper | What it does | Waits for `waitUntil()`? | Important nuance |
+|---|---|---|---|
+| `cf.worker.fetch()` | invokes the configured HTTP surface, including built-in file routes | No | returns when the handler resolves |
+| `cf.queue.trigger()` | invokes the configured queue consumer | Yes | drains queued background work before returning |
+| `cf.scheduled.trigger()` | invokes the configured scheduled handler | Yes | drains queued background work before returning |
+| `cf.email.send()` | sends a raw email through the helper | Yes on the direct-handler path; fallback endpoint behavior is runtime-driven | when `createTestContext()` has wired an email handler, it imports and invokes that handler directly; otherwise it falls back to the local email endpoint |
+| `cf.tail.trigger()` | directly invokes a tail handler | Yes | `createTestContext()` auto-detects `src/tail.ts` when present, but there is still no public `files.tail` config key |
+
+Two important consequences:
+
+- `cf.worker.fetch()` is not a “wait for all background work” helper
+- helper availability does not mean every helper replays the full Cloudflare dispatch path in the same way
+
+### Email testing
+
+Email testing has two directions:
+
+- incoming email helper dispatch via `cf.email.send()` / `email.send()`
+- outgoing email observation via helper state
+
+When `createTestContext()` has wired an email handler, the helper imports that handler directly, creates an `EmailEvent`, and waits for queued `waitUntil()` work.
+
+If no email handler has been wired, the helper falls back to posting the raw email to the local email endpoint.
+
+That makes the helper useful for handler-level tests, but ingress-fidelity-sensitive flows should still use higher-level integration testing.
+
+### Tail testing
+
+Tail helpers are exported publicly, and `createTestContext()` auto-detects `src/tail.ts` when present.
+
+So the truthful public statement is:
+
+- `cf.tail.trigger()` is exported
+- `createTestContext()` wires it automatically when `src/tail.ts` exists
+- `cf.tail.trigger()` directly imports and invokes that handler and waits for `waitUntil()`
+- there is no public `files.tail` config key to advertise today
+
+### Remote mode in tests
+
+Remote mode is mainly about AI and Vectorize. Use `shouldSkip` for cost-sensitive or remote-only test gating. Do not treat remote mode as a blanket “make every binding remote” switch.
+
 ---
 
-## What to remember
+## Sharp edges
+
+Keep these caveats explicit:
+
+- `files.routes` configures the built-in file router; it is not the same thing as Cloudflare deployment `routes`
+- route trees are real now, but `src/fetch.ts` same-module method handlers still take precedence over file routes for matching methods
+- route files that normalize to the same pattern are rejected as conflicts
+- `_`-prefixed files and directories inside the route tree are ignored
+- `vars` values are strings in the current native schema
+- `secrets` declares runtime secret bindings; it does not store secret values
+- `.env*` and `.dev.vars*` are not a unified Devflare-native loading/validation system; any effect they have comes from Bun or upstream Cloudflare tooling, depending on the mode
+- `wrangler.passthrough` is the escape hatch for unsupported Wrangler keys and is merged after native compilation
+- named service entrypoints need deployment-time validation if they are critical to your app
+- local R2 binding support is real, but there is still no stable public/browser local bucket URL contract to document as public API
+- `sendEmail` is a supported outbound binding, while inbound email is a separate worker surface
+- email and tail helpers have real, useful test paths, but they should not be described as identical to full Cloudflare ingress or tail replay
+- Vite and Rolldown are different systems and should not be blurred together
+- `rolldown` config affects Durable Object bundling, not the main Vite app build
+- `wrangler.passthrough.main` suppresses Devflare's composed main-entry generation in higher-level build and Vite-backed flows
+- `getCloudflareConfig()` and `getDevflareConfigs()` are the safe config-time Vite helpers; `getPluginContext()` is advanced post-resolution state
+- Rollup-compatible plugins often work in `rolldown.options.plugins`, but compatibility is high-not-total and plugin-specific validation still matters
+- higher-level flows may generate composed main worker entries more aggressively than older docs implied
+
+---
 
-If you remember only seven things, remember these:
+## Summary
 
-1. `defineConfig()` is the source of truth
-2. Devflare extends Miniflare into a full developer workflow
-3. file structure is a feature, not a side detail
-4. responsibilities should live in separate surfaces and files
-5. browser rendering is a concrete example of Devflare adding capabilities above raw Miniflare
-6. `devflare/test` gives you a coherent test API across handler types
-7. use routing, refs, and framework integrations when the app grows beyond a tiny single-worker shape
+Prefer explicit config over discovery, separated surfaces over a monolithic Worker file, and generated output as output rather than source. The safest public path today is explicit `files.fetch`, event-first handlers, explicit bindings, `createTestContext()` for core tests, and `ref()` for cross-worker composition.