devflare 1.0.0-next.1 → 1.0.0-next.10

package/LLM.md

@@ -1,319 +1,416 @@
 # 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
 
-This is the most important concept to understand.
+### Layers that are easy to confuse
 
-Devflare is **not** trying to replace Miniflare. It **extends** Miniflare so developers can work with a higher-level application model.
+Keep these layers separate until you have a reason to connect them:
 
-### Raw Miniflare gives you a runtime
+1. config-time `process.env`
+2. `devflare.config.ts`
+3. generated `wrangler.jsonc`
+4. runtime Worker `env` bindings
+5. local dev/test helpers
 
-Miniflare is excellent at local execution and local emulation of many Cloudflare bindings.
+The classic mixups are:
 
-But by itself, it does not define:
+- `files.routes` vs top-level `routes`
+- `vars` vs `secrets`
+- Bun `.env` loading vs runtime secret loading
+- Devflare `config.env` overrides vs Wrangler environment blocks
+- main-entry `env` vs runtime `env`
 
-- 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
+### Source of truth vs generated output
 
-### Devflare adds the missing platform layer
+Treat these as generated output, not authoring input:
 
-Devflare adds those higher-level capabilities on top of Miniflare.
+- `.devflare/`
+- `env.d.ts`
+- generated `wrangler.jsonc`
 
-Concretely, it provides:
+The source of truth is still:
 
-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`
+- `devflare.config.ts`
+- your source files under `src/`
+- your tests
 
-2. **Config compilation**
-   - Devflare compiles your config into Wrangler-compatible config rather than making you hand-maintain the low-level representation yourself.
+If generated output looks wrong, fix the source and regenerate it. Do not hand-edit generated artifacts.
 
-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.
+---
 
-4. **Unified testing surface**
-   - `cf.worker`
-   - `cf.queue`
-   - `cf.scheduled`
-   - `cf.email`
-   - `cf.tail`
+## What Devflare is
 
-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.
+Devflare is a developer-first layer on top of Cloudflare Workers tooling.
 
-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
+It composes existing tools instead of replacing them:
 
-7. **Framework integration**
-   - Vite and SvelteKit support with config generation, worker-aware transforms, auxiliary Durable Object workers, and websocket-aware local dev workflows
+- **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
 
-So the design goal is not just “run a Worker locally”.
+Core public capabilities today:
 
-The design goal is:
+- 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
 
-> let developers build Cloudflare systems using coherent, isolated responsibilities while Devflare composes those responsibilities into a working local and testable whole
+Devflare is not a replacement runtime. It is a higher-level developer system that sits on top of the Cloudflare ecosystem.
 
----
+### Authoring model
 
-## The authoring model Devflare wants you to use
+A **surface** is a distinct handler or entry file that Devflare treats as its own concern. The common surfaces are:
 
-Devflare is opinionated in a useful way.
+- 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`
 
-It wants you to think in **surfaces** rather than in “one file that does everything”.
+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.
 
-### HTTP surface
+---
 
-Use `src/fetch.ts` for normal request handling.
+## Package entrypoints
 
-### Queue surface
+Use the narrowest import path that matches where the code runs.
 
-Use `src/queue.ts` for queue consumers.
+| 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 |
 
-### Scheduled surface
+### `devflare` vs `devflare/runtime`
 
-Use `src/scheduled.ts` for cron triggers.
+Default rule:
 
-### Email surface
+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`
 
-Use `src/email.ts` for incoming email handling. Use `sendEmail` bindings in config for outgoing email.
+`import { env } from 'devflare/runtime'` is strict request-scoped access. It works only while Devflare has established an active handler context.
 
-### Routing surface
+`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.
 
-Use `files.routes` with a directory like `src/routes` when you want file-based HTTP routing instead of one monolithic fetch file.
+Practical example:
 
-### Durable Object surface
+```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'
+			}
+		})
+	}
 
-Use `do.*.ts` files for Durable Objects.
+	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
 
-## Core ideas you should internalize
+These event types augment native Cloudflare inputs rather than replacing them with unrelated wrappers.
 
-### `defineConfig()` is the center of the project
+| 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` |
 
-Always define your worker through `defineConfig()`.
+On worker surfaces, `event.ctx` is the current `ExecutionContext`.
 
-```ts
-import { defineConfig } from 'devflare'
+On Durable Object surfaces, `event.ctx` is the current `DurableObjectState`, and Devflare also exposes it as `event.state` for clarity.
 
-export default defineConfig({
-	name: 'my-worker'
-})
-```
+### Runtime access: parameters, getters, and proxies
 
-This is the source of truth Devflare uses to:
+Prefer runtime access in this order:
 
-- understand your bindings
-- understand your file layout
-- generate Wrangler-compatible config
-- drive dev mode
-- drive test mode
+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
 
-### Convention beats boilerplate
+Devflare carries the active event through the current handler call trail, so deeper helpers can recover the current surface without manually threading arguments.
 
-If your filenames follow the defaults, you do not need to spell everything out.
+Proxy semantics:
 
-Defaults include:
+- `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
 
-- `src/fetch.ts`
-- `src/queue.ts`
-- `src/scheduled.ts`
-- `src/email.ts`
-- `src/transport.ts`
-- `**/do.*.{ts,js}`
-- `**/ep.*.{ts,js}`
-- `**/wf.*.{ts,js}`
+Per-surface getters:
 
-### `ref()` is how cross-worker systems stay clean
+- worker surfaces: `getFetchEvent()`, `getQueueEvent()`, `getScheduledEvent()`, `getEmailEvent()`, `getTailEvent()`
+- Durable Object surfaces: `getDurableObjectEvent()`, `getDurableObjectFetchEvent()`, `getDurableObjectAlarmEvent()`
+- Durable Object WebSocket surfaces: `getDurableObjectWebSocketMessageEvent()`, `getDurableObjectWebSocketCloseEvent()`, `getDurableObjectWebSocketErrorEvent()`
 
-If one worker depends on another worker or on another worker’s Durable Objects, use `ref()` instead of manually duplicating names.
+Every getter also exposes `.safe()`, which returns `null` instead of throwing.
 
-That keeps cross-worker relationships typed and centralized.
+Practical example:
 
-### `env` is the unified access point
+```ts
+import { getFetchEvent, locals, type FetchEvent } from 'devflare/runtime'
 
-Use:
+function currentPath(): string {
+	return new URL(getFetchEvent().request.url).pathname
+}
 
-```ts
-import { env } from 'devflare'
+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
+	})
+}
 ```
 
-Devflare makes `env` work coherently across request handling, tests, and bridge-backed local flows.
+### Manual context helpers are advanced/internal
 
----
+Normal Devflare application code should **not** need `runWithEventContext()` or `runWithContext()`.
 
-## Why file structure matters so much in Devflare
+Devflare establishes the active event/context automatically before invoking user code in the flows developers normally use:
 
-In plain Worker setups, it is common to end up with a single file that mixes:
+- 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`
 
-- HTTP routing
-- queue handling
-- scheduled jobs
-- email handling
-- Durable Object exports
-- auxiliary RPC handlers
-- test-specific wiring
+That means getters like `getQueueEvent()`, `getScheduledEvent()`, `getEmailEvent()`, and `getDurableObjectFetchEvent()` should work inside ordinary handlers without manual wrapping.
 
-Devflare pushes in the opposite direction.
+Keep these helpers in the "advanced escape hatch" bucket:
 
-It gives each responsibility a natural home and then composes them together.
+- `runWithEventContext(event, fn)` preserves the exact event you provide
+- `runWithContext(env, ctx, request, fn, type)` is a lower-level compatibility helper
 
-That has several benefits:
+Important difference:
 
-- lower mental overhead
-- easier code generation
-- easier code review
-- easier testing
-- fewer accidental runtime coupling mistakes
-- clearer ownership boundaries within a team
+- `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
 
-For LLM generation specifically, this matters a lot.
+### HTTP entry, middleware, and method handlers
 
-When generating Devflare code, prefer **separate files with clear responsibilities** over giant all-in-one worker files.
+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
+files: {
+	fetch: 'src/fetch.ts'
+}
+```
+
+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.
 
-## Config example
+Supported primary entry shapes today:
 
-This is a good realistic starting point.
+- `export async function fetch(...) { ... }`
+- `export const fetch = ...`
+- `export const handle = ...`
+- `export default async function (...) { ... }`
+- `export default { fetch(...) { ... } }`
+- `export default { handle(...) { ... } }`
+
+`fetch` and `handle` are aliases for the same primary HTTP entry. Export one or the other, not both.
+
+When this document says a `handle` export here, it means the primary fetch export name, not the legacy `handle(...handlers)` helper.
+
+Request-wide middleware belongs in `src/fetch.ts` and composes with `sequence(...)`.
 
 ```ts
-import { defineConfig } from 'devflare'
+import { sequence } from 'devflare/runtime'
+import type { FetchEvent, ResolveFetch } from 'devflare/runtime'
 
-export default defineConfig({
-	name: 'my-app',
-	files: {
-		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'
+async function authHandle(event: FetchEvent, resolve: ResolveFetch): Promise<Response> {
+	if (!event.request.headers.get('authorization')) {
+		return new Response('Unauthorized', { status: 401 })
 	}
-})
+
+	return resolve(event)
+}
+
+async function appFetch({ request }: FetchEvent): Promise<Response> {
+	return new Response(new URL(request.url).pathname)
+}
+
+export const handle = sequence(authHandle, appFetch)
 ```
 
----
+`sequence(...)` uses the usual nested middleware flow:
 
-## File-based routing
+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)`
 
-Devflare supports a file-structured routing model through `files.routes`.
+Same-module method exports are real runtime behavior:
 
-That is important because it moves you away from hand-written request dispatch in one file and toward a more maintainable app structure.
+- 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
 
-Example:
+### 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
+
+| 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 |
+
+Practical route-tree example:
 
 ```ts
+// devflare.config.ts
 import { defineConfig } from 'devflare'
 
 export default defineConfig({
-	name: 'my-api',
+	name: 'api-worker',
 	files: {
+		fetch: 'src/fetch.ts',
 		routes: {
 			dir: 'src/routes',
 			prefix: '/api'
@@ -322,655 +419,696 @@ export default defineConfig({
 })
 ```
 
-Conceptually, this means:
+```ts
+// src/fetch.ts
+import { sequence } from 'devflare/runtime'
 
-- 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
+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
+})
+```
 
-If you only need a small Worker, `src/fetch.ts` is perfect.
+```ts
+// src/routes/users/[id].ts
+import type { FetchEvent } from 'devflare/runtime'
 
-If your HTTP surface is growing, `files.routes` is usually the better model.
+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
+```
 
 ---
 
-## Queues: produce in one place, consume in another
+## Configuration and compilation
+
+### Stable config flow
+
+This is the stable public flow for Devflare config:
+
+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.
 
-Devflare wants queue production and queue consumption to live in obvious places.
+### Supported config files and `defineConfig()`
 
-- produce messages from `fetch` or another handler via the bound queue producer
-- consume them in `src/queue.ts`
-- test them with `cf.queue`
+Supported config filenames:
 
-### Queue config example
+- `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: 'tasks-app',
-	bindings: {
-		queues: {
-			producers: {
-				TASK_QUEUE: 'task-queue'
-			},
-			consumers: [
-				{
-					queue: 'task-queue',
-					maxBatchSize: 10,
-					maxRetries: 3
-				}
-			]
-		},
-		kv: {
-			RESULTS: 'results-kv-id'
-		}
+	name: 'api-worker',
+	compatibilityDate: '2026-03-17',
+	files: {
+		fetch: 'src/fetch.ts'
+	},
+	vars: {
+		APP_NAME: 'api-worker'
 	}
 })
 ```
 
-### Producer example from `fetch`
+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.
 
-```ts
-import { env } from 'devflare'
+### Top-level keys
 
-export default async function fetch(request: Request): Promise<Response> {
-	const url = new URL(request.url)
+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 (url.pathname === '/tasks') {
-		const task = {
-			id: crypto.randomUUID(),
-			type: 'resize-image'
-		}
+Current defaults worth knowing:
 
-		await env.TASK_QUEUE.send(task)
-		return Response.json({ queued: true, task })
-	}
+- `compatibilityDate` defaults to the current date when omitted
+- current default compatibility flags include `nodejs_compat` and `nodejs_als`
 
-	return new Response('Not found', { status: 404 })
-}
-```
+Common keys:
 
-### Consumer example in `src/queue.ts`
+| 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` | worker-only bundler options |
+| `wrangler.passthrough` | raw Wrangler overrides after compile |
 
-```ts
-import type { MessageBatch } from '@cloudflare/workers-types'
+### Native config coverage vs `wrangler.passthrough`
 
-type Task = {
-	id: string
-	type: string
-}
+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.
 
-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()
-		}
-	}
-}
-```
+Use `wrangler.passthrough` for unsupported Wrangler options.
 
-Authoring guidance:
+Current merge order is:
 
-- 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
+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:
 
-## Email: receiving and sending
+```ts
+import { defineConfig } from 'devflare'
 
-Devflare supports two sides of email: **receiving** incoming messages and **sending** outgoing ones.
+export default defineConfig({
+	name: 'advanced-worker',
+	files: {
+		fetch: 'src/fetch.ts'
+	},
+	wrangler: {
+		passthrough: {
+			placement: {
+				mode: 'smart'
+			}
+		}
+	}
+})
+```
 
-### Receiving email
+Two practical rules:
 
-Export an `email` function from `src/email.ts`. Devflare wires it as the worker's incoming email handler.
+- 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
 
-```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()
-		})
-	)
+### `files`
 
-	// Forward every incoming message to admin
-	await message.forward('admin@example.com')
-}
-```
+`files` tells Devflare where your surfaces live. Use explicit paths for any surface that matters to build or deploy output, especially `files.fetch`.
 
-The `ForwardableEmailMessage` object also supports `message.reply(replyMessage)` for auto-responses.
+| 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` | `string` | none | custom transport definition file |
 
-### Sending email (the `sendEmail` binding)
+Discovery does not behave identically in every subsystem:
 
-To send outgoing email, declare a `sendEmail` binding in config. Each key becomes a typed `env` property of type `SendEmail`.
+- 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
 
-The value object accepts an optional `destinationAddress`:
+Safe rule: if a surface matters to build or deploy output, declare it explicitly even if another subsystem can discover it by convention.
 
-- **With `destinationAddress`** — every email sent through that binding is locked to that recipient.
-- **Without it (`{}`)** — you choose the recipient at send time.
+Practical example:
 
 ```ts
 import { defineConfig } from 'devflare'
 
 export default defineConfig({
-	name: 'support-mail',
-	bindings: {
-		kv: {
-			EMAIL_LOG: 'email-log-kv-id'
+	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'
 		},
-		sendEmail: {
-			// Locked destination — always delivers to admin
-			ADMIN_EMAIL: { destinationAddress: 'admin@example.com' },
-
-			// Open destination — specify per message
-			EMAIL: {}
-		}
+		durableObjects: 'src/do/**/*.ts',
+		entrypoints: 'src/rpc/**/*.ts',
+		workflows: 'src/workflows/**/*.ts'
 	}
 })
 ```
 
-This produces:
+`files.transport` is opt-in. Devflare only loads it when `files.transport` is explicitly set, and the file must export a named `transport` object.
 
-- `env.ADMIN_EMAIL: SendEmail` — hardcoded to `admin@example.com`
-- `env.EMAIL: SendEmail` — recipient provided at send time
+There is no public `files.tail` config key today.
 
-### Testing email
+### `.env`, `vars`, `secrets`, and `config.env`
 
-Use the `email` helper from `devflare/test`:
+Keep these layers separate:
 
-```ts
-import { email } from 'devflare/test'
+| 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 |
+| `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 |
 
-const response = await email.send({
-	from: 'sender@example.com',
-	to: 'recipient@example.com',
-	subject: 'Test message',
-	body: 'Hello from the test suite.'
-})
+#### `.env` and process env
 
-expect(response.ok).toBe(true)
-```
+`loadConfig()` does not do dotenv loading by itself. The Devflare CLI runs under Bun, and Bun may auto-load `.env` files into `process.env`.
 
-Authoring guidance:
+#### `vars`
 
-- 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
+Use `vars` for non-secret runtime values that can safely appear in generated config, such as public URLs, modes, IDs, and feature flags.
 
----
+In the current native Devflare schema, `vars` is:
 
-## Browser rendering is a real example of Devflare extending Miniflare
+```ts
+Record<string, string>
+```
 
-This is worth emphasizing.
+#### `secrets`
 
-Devflare supports **browser rendering** locally via a browser shim layer.
+`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.
 
-That matters because browser rendering is not something Miniflare gives you directly as a complete local developer workflow.
+In the current schema, each secret has the shape:
 
-With Devflare, browser rendering becomes part of the same system as the rest of your bindings and local development story:
+```ts
+{ required?: boolean }
+```
 
-- 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
+`required` defaults to `true`, so this:
 
-This is exactly the kind of feature that demonstrates the Devflare philosophy:
+```ts
+secrets: {
+	API_KEY: {}
+}
+```
 
-> take a low-level runtime foundation, then add the higher-level orchestration developers actually need
+means “`API_KEY` is a required runtime secret,” not “optional secret with no requirements.”
 
----
+#### `devflare types`
 
-## Durable Objects and multi-worker systems
+`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.
 
-Devflare is designed to keep multi-worker and DO-heavy systems manageable.
+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.
 
-### Local Durable Objects
+#### `config.env`
 
-Bind them in config:
+`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.
 
-```ts
-bindings: {
-	durableObjects: {
-		COUNTER: 'Counter'
-	}
-}
-```
+Current merge behavior uses deep merge semantics:
 
-Put their classes in `do.*.ts` files.
+- scalar fields override base values
+- nested objects inherit omitted keys
+- arrays append instead of replacing
+- `null` and `undefined` do not delete base values
 
-### Complete local Durable Object example
+If you need full replacement behavior, compute the final value in `defineConfig()` instead of relying on `config.env`.
 
-If you need to generate a normal local Durable Object and call it from HTTP code, prefer this shape.
+Example:
 
 ```ts
-// devflare.config.ts
 import { defineConfig } from 'devflare'
 
 export default defineConfig({
-	name: 'sessions-app',
+	name: 'api',
+	files: {
+		fetch: 'src/fetch.ts'
+	},
+	vars: {
+		APP_ENV: 'development',
+		API_ORIGIN: 'http://localhost:3000'
+	},
 	bindings: {
-		durableObjects: {
-			SESSION: 'SessionStore'
+		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.session.ts
-import { DurableObject } from 'cloudflare:workers'
+With `--env production`, the resolved config keeps `files.fetch`, overrides the `vars`, and overrides `bindings.kv.CACHE`.
 
-export class SessionStore extends DurableObject<DevflareEnv> {
-	private data = new Map<string, string>()
-
-	getValue(key: string): string | null {
-		return this.data.get(key) ?? null
-	}
+Current limitation: `accountId` and `wsRoutes` are not supported inside `config.env`. Compute those in the outer `defineConfig()` function when you need environment-specific values.
 
-	setValue(key: string, value: string): void {
-		this.data.set(key, value)
-	}
+---
 
-	clearAll(): void {
-		this.data.clear()
-	}
-}
-```
+## Bindings and multi-worker composition
 
-```ts
-// src/fetch.ts
-import { env } from 'devflare'
+### Binding groups
 
-export default async function fetch(request: Request): Promise<Response> {
-	const url = new URL(request.url)
-	const sessionId = url.searchParams.get('session') ?? 'default'
+| 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 |
 
-	const id = env.SESSION.idFromName(sessionId)
-	const session = env.SESSION.get(id)
+### Core bindings
 
-	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 })
-	}
+KV, D1, R2, Durable Objects, and queues have the clearest end-to-end story today across config, generated types, and local dev/test flows.
 
-	if (url.pathname === '/get') {
-		const key = url.searchParams.get('key') ?? 'name'
-		const value = await session.getValue(key)
-		return Response.json({ value })
-	}
+### R2 browser access and public URLs
 
-	if (url.pathname === '/clear') {
-		await session.clearAll()
-		return Response.json({ ok: true })
-	}
+`bindings.r2` gives you real R2 binding access in local dev, tests, generated types, and compiled config.
 
-	return new Response('Not found', { status: 404 })
-}
-```
+What Devflare does **not** currently expose as a public contract is a stable browser-facing local bucket URL.
 
-Important authoring notes:
+If you need browser-visible local asset flows:
 
-- 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
+- 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
 
-### Transport layer example: Devflare encodes and decodes for you
+For delivery patterns and production recommendations, see [`R2.md`](./R2.md).
 
-Use `src/transport.ts` when a Worker or Durable Object returns custom classes that should survive supported RPC/test boundaries as real instances.
+Practical example:
 
 ```ts
-// src/DoubleableNumber.ts
-export class DoubleableNumber {
-	value: number
-
-	constructor(n: number) {
-		this.value = n
-	}
+import { defineConfig } from 'devflare'
 
-	get double() {
-		return this.value * 2
+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
-// src/transport.ts
-import { DoubleableNumber } from './DoubleableNumber'
+import type { FetchEvent } from 'devflare/runtime'
 
-export const transport = {
-	DoubleableNumber: {
-		encode: (v: unknown) => v instanceof DoubleableNumber && v.value,
-		decode: (v: number) => new DoubleableNumber(v)
-	}
+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 })
 }
 ```
 
-```ts
-// src/do.counter.ts
-import { DoubleableNumber } from './DoubleableNumber'
-
-export class Counter {
-	private count = 0
+### Services and named entrypoints
 
-	getValue(): DoubleableNumber {
-		return new DoubleableNumber(this.count)
-	}
-
-	increment(n: number = 1): DoubleableNumber {
-		this.count += n
-		return new DoubleableNumber(this.count)
-	}
-}
-```
+Service bindings can be written directly or via `ref()`.
 
 ```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'
-
-beforeAll(() => createTestContext())
-afterAll(() => env.dispose())
+import { defineConfig, ref } from 'devflare'
 
-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)
+const auth = ref(() => import('../auth/devflare.config'))
 
-		expect(result).toBeInstanceOf(DoubleableNumber)
-		expect(result.double).toBe(4)
-	})
+export default defineConfig({
+	name: 'gateway',
+	bindings: {
+		services: {
+			AUTH: auth.worker,
+			ADMIN: auth.worker('AdminEntrypoint')
+		}
+	}
 })
 ```
 
-What Devflare is doing for the developer:
+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.
 
-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
-
-This means the developer writes the codec once and then works with real domain objects rather than manual serialization code.
-
-### Cross-worker references
-
-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'))
+```
 
-## Vite and SvelteKit integration
+```ts
+const auth = ref('custom-auth-name', () => import('../auth/devflare.config'))
+```
 
-Devflare includes dedicated framework-aware entry points.
+Why `ref()` matters:
 
-### `devflare/vite`
+- 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
 
-Use this when you want:
+Advanced members such as `.name`, `.config`, `.configPath`, and `.resolve()` are real, but secondary to the main composition story.
 
-- config compilation during dev and build
-- worker-aware transforms
-- auxiliary Durable Object worker generation
-- websocket-aware proxying for local development
+---
 
-### `devflare/sveltekit`
+## Development workflows
 
-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
 
----
+### Daily development loop
 
-## Remote-only services
+Use the same CLI loop for both worker-only and Vite-backed packages. The presence of a local `vite.config.*` changes the mode automatically.
 
-Some Cloudflare services are not meaningfully local.
+```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
+```
 
-Most importantly:
+Use `--env <name>` on build and deploy when you want Devflare to resolve a named config environment before compilation.
 
-- Workers AI
-- Vectorize
+### CLI reference
 
-Devflare treats those as explicit remote-mode concerns rather than pretending they are fully local.
+| 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 |
 
-That is a good thing.
+### `doctor`
 
-It keeps the local story honest while still giving you an intentional path to test remote capabilities when needed.
+Current `doctor` behavior:
 
-Use the `devflare remote` workflow and guard remote-only tests appropriately.
+- 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`
 
 ---
 
-## Generated artifacts
+## Testing model
 
-Devflare uses `.devflare/` for generated local artifacts.
+Use `devflare/test`.
 
-Treat that directory as generated output rather than hand-authored source.
+The default pairing is:
 
----
+```ts
+import { beforeAll, afterAll } from 'bun:test'
+import { createTestContext } from 'devflare/test'
+import { env } from 'devflare'
 
-## Recommended project structure
-
-Here is a strong default layout for most projects.
-
-```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
+beforeAll(() => createTestContext())
+afterAll(() => env.dispose())
 ```
 
-You will not always need every file.
+`createTestContext()` is the recommended default for most integration-style tests.
 
-But this shape captures the Devflare philosophy well:
+Current behavior:
 
-- each capability gets an isolated home
-- config stays declarative
-- tests target named surfaces
-- local orchestration is handled by Devflare instead of bespoke glue
+- 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
+- `files.transport` is opt-in rather than auto-loaded by filename convention
 
----
+Practical example:
 
-## Guidance for LLMs generating Devflare code
+```ts
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import { cf, createTestContext } from 'devflare/test'
+import { env } from 'devflare'
 
-When generating Devflare projects or edits, follow these rules.
+beforeAll(() => createTestContext())
+afterAll(() => env.dispose())
 
-### Prefer conventions first
+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.json()).toEqual({ id: '123' })
+	})
 
-Only override paths when there is a real reason.
+	test('queue side effects can be asserted with real bindings', async () => {
+		await cf.queue.trigger([
+			{ type: 'reindex', id: 'job-1' }
+		])
 
-### Prefer separation of responsibilities
+		expect(await env.RESULTS.get('job-1')).toBe('done')
+	})
+})
+```
 
-Do **not** collapse fetch, queue, scheduled, email, DOs, and entrypoints into a single file unless the task explicitly demands that shape.
+### Helper behavior
 
-### Prefer `defineConfig()`
+Do not assume every `cf.*` helper behaves the same way.
 
-Never emit untyped ad hoc config objects when a normal Devflare config is appropriate.
+| 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 |
 
-### Prefer `ref()` for cross-worker relationships
+Two important consequences:
 
-Avoid manually duplicating worker names and binding metadata.
+- `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
 
-### Prefer `devflare/test` for tests
+### Email testing
 
-Use `createTestContext()` for integration-style tests and mock helpers for unit tests.
+Email testing has two directions:
 
-### Prefer `env` for ergonomic binding access
+- incoming email helper dispatch via `cf.email.send()` / `email.send()`
+- outgoing email observation via helper state
 
-Use `import { env } from 'devflare'` when it improves clarity.
+When `createTestContext()` has wired an email handler, the helper imports that handler directly, creates an `EmailEvent`, and waits for queued `waitUntil()` work.
 
-### Respect remote-only boundaries
+If no email handler has been wired, the helper falls back to posting the raw email to the local email endpoint.
 
-Do not fake fully local AI or Vectorize support.
+That makes the helper useful for handler-level tests, but ingress-fidelity-sensitive flows should still use higher-level integration testing.
 
-### Use routing when HTTP complexity grows
+### Tail testing
 
-If the app has many endpoints, prefer `files.routes` and route files over a giant `fetch.ts` dispatcher.
+Tail helpers are exported publicly, and `createTestContext()` auto-detects `src/tail.ts` when present.
 
----
+So the truthful public statement is:
 
-## Minimal example
+- `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
 
-```ts
-// devflare.config.ts
-import { defineConfig } from 'devflare'
+### Remote mode in tests
 
-export default defineConfig({
-	name: 'hello-worker'
-})
-```
+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.
 
-```ts
-// src/fetch.ts
-export default async function fetch(): Promise<Response> {
-	return new Response('Hello from Devflare')
-}
-```
+---
 
-```ts
-// tests/worker.test.ts
-import { beforeAll, afterAll, describe, expect, test } from 'bun:test'
-import { createTestContext, cf } from 'devflare/test'
-import { env } from 'devflare'
+## Sharp edges
 
-beforeAll(() => createTestContext())
-afterAll(() => env.dispose())
+Keep these caveats explicit:
 
-describe('hello-worker', () => {
-	test('GET / returns text', async () => {
-		const response = await cf.worker.get('/')
-		expect(response.status).toBe(200)
-		expect(await response.text()).toBe('Hello from Devflare')
-	})
-})
-```
+- `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
+- `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
+- higher-level flows may generate composed main worker entries more aggressively than older docs implied
 
 ---
 
-## What to remember
-
-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.