devflare 1.0.0-next.1 → 1.0.0-next.2

package/LLM.md

@@ -1,253 +1,365 @@
 # Devflare
 
-This file is for LLMs and developers **using** the `devflare` library.
+This file is for LLMs and developers **using** the published `devflare` package.
 
-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.
+It documents the public package contract, the actual config/runtime model, and the places where Devflare adds behavior on top of Bun, Vite, Miniflare, Wrangler, and Cloudflare.
 
-It does **not** document the internal repository layout or example cases. Treat it as package-facing guidance.
+It does **not** document this repository’s internal implementation details, test fixtures, or example-case layout except when those details directly affect the public behavior of the package.
+
+The most important thing to understand is that Devflare spans **multiple layers** that are easy to confuse:
+
+1. config-time `process.env`
+2. `devflare.config.ts`
+3. generated `wrangler.jsonc`
+4. runtime Worker `env` bindings
+5. local-only dev/test helpers
+
+If two things have similar names but live in different layers, assume they are different until proven otherwise. The classic troublemakers are:
+
+- `files.routes` vs top-level `routes`
+- `vars` vs `secrets`
+- Bun `.env` loading vs local runtime secret loading
+- Devflare `env` overrides vs raw Wrangler environment sections
 
 ---
 
 ## What Devflare is
 
-Devflare is a **developer platform for Cloudflare Workers built on top of Miniflare, Wrangler-compatible config, and framework-aware tooling**.
+Devflare is a **developer platform layer for Cloudflare Workers**.
 
-The short version:
+Miniflare gives you a local Workers runtime. Wrangler gives you deployment configuration and deployment workflows. Vite gives you a frontend/build pipeline. Bun gives you the CLI runtime and process environment behavior.
 
-> Miniflare gives you a local Workers runtime. Devflare turns that runtime into a coherent developer system.
+Devflare sits on top of those pieces and turns them into one coherent authoring model.
 
-Devflare does this by combining:
+Concretely, Devflare provides:
 
 - 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
+- convention-first file discovery for worker surfaces
+- compilation from Devflare config into Wrangler-compatible config
+- local orchestration around Miniflare, Vite, and bridge-backed tooling
+- typed multi-worker references via `ref()`
+- test helpers for HTTP, queues, scheduled handlers, email, and tail events
+- framework-aware integration for Vite and SvelteKit
+- local features that are awkward or incomplete in raw Miniflare-only setups, including browser-rendering workflows, websocket-aware dev proxying, and unified test ergonomics
 
-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.
+So Devflare is **not** “a different Workers runtime”.
+
+It is a higher-level developer system that uses the Cloudflare ecosystem underneath.
 
 ---
 
-## How Devflare extends Miniflare
+## The authoring model Devflare wants
 
-This is the most important concept to understand.
+Devflare is intentionally opinionated.
 
-Devflare is **not** trying to replace Miniflare. It **extends** Miniflare so developers can work with a higher-level application model.
+It wants you to think in **surfaces** rather than “one giant worker file that does everything”.
 
-### Raw Miniflare gives you a runtime
+Typical surfaces are:
 
-Miniflare is excellent at local execution and local emulation of many Cloudflare bindings.
+- HTTP requests via `src/fetch.ts`
+- queue consumers via `src/queue.ts`
+- cron handlers via `src/scheduled.ts`
+- incoming email via `src/email.ts`
+- file-based HTTP routes via `src/routes/**`
+- Durable Objects via `do.*.ts`
+- WorkerEntrypoints via `ep.*.ts`
+- workflows via `wf.*.ts`
+- custom RPC serialization via `src/transport.ts`
 
-But by itself, it does not define:
+This separation is one of Devflare’s biggest advantages:
 
-- 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
+- responsibility boundaries stay clear
+- test helpers map naturally onto handler types
+- multi-worker systems stay readable
+- LLM-generated code stays composable instead of collapsing into a single blob
 
-### Devflare adds the missing platform layer
+When generating or reviewing Devflare code, prefer **one responsibility per file** unless there is a very strong reason not to.
 
-Devflare adds those higher-level capabilities on top of Miniflare.
+---
 
-Concretely, it provides:
+## Package entrypoints
 
-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`
+Use package subpaths intentionally.
 
-2. **Config compilation**
-   - Devflare compiles your config into Wrangler-compatible config rather than making you hand-maintain the low-level representation yourself.
+| Import | What it is for | What it exposes in practice |
+|---|---|---|
+| `devflare` | Main package entrypoint | `defineConfig`, config loading/compilation helpers, `ref()`, unified `env`, CLI helpers, bridge helpers, decorators, transform helpers, test helpers re-exported for convenience, `workerName` |
+| `devflare/runtime` | Worker-safe runtime utilities | middleware helpers like `sequence()`, `resolve()`, `pipe()`, validation helpers, decorators |
+| `devflare/test` | Testing API | `createTestContext`, `cf`, `email`, `queue`, `scheduled`, `worker`, `tail`, mock helpers, remote skip helpers, bridge test context |
+| `devflare/vite` | Vite integration | `devflarePlugin`, plugin context helpers, config helpers, Vite-side types |
+| `devflare/sveltekit` | SvelteKit integration | `handle`, `createDevflarePlatform`, `createHandle`, dev/reset helpers, integration types |
+| `devflare/cloudflare` | Cloudflare account/auth/usage helpers | `account` helper object, auth/account/resource inspection, usage tracking, limits/preferences helpers, Cloudflare API errors |
+| `devflare/decorators` | Decorators only | `durableObject()` and related decorator utilities |
 
-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.
+### Important runtime note
 
-4. **Unified testing surface**
-   - `cf.worker`
-   - `cf.queue`
-   - `cf.scheduled`
-   - `cf.email`
-   - `cf.tail`
+`devflare/runtime` is intentionally **smaller** than the main package.
 
-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.
+Today it does **not** export the unified `env` proxy from the main `devflare` entrypoint. If you want `import { env } from 'devflare'`, import it from `devflare`, not `devflare/runtime`.
 
-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
+### Common main-package exports
 
-7. **Framework integration**
-   - Vite and SvelteKit support with config generation, worker-aware transforms, auxiliary Durable Object workers, and websocket-aware local dev workflows
+The most common exports from `devflare` are:
 
-So the design goal is not just “run a Worker locally”.
+- `defineConfig`
+- `loadConfig`
+- `compileConfig`
+- `stringifyConfig`
+- `ref`
+- `env`
+- `workerName`
 
-The design goal is:
+The main package also exports advanced tooling APIs such as CLI helpers, bridge helpers, DO transform helpers, WorkerEntrypoint transform helpers, decorators, and test helpers.
 
-> let developers build Cloudflare systems using coherent, isolated responsibilities while Devflare composes those responsibilities into a working local and testable whole
+Two small but useful details:
 
----
+- the package default export is also `defineConfig`
+- `workerName` is a build-time-injected worker-name helper, with dev/test fallback behavior rather than being a dynamic Cloudflare metadata API
 
-## The authoring model Devflare wants you to use
+### Deprecated and compatibility exports
 
-Devflare is opinionated in a useful way.
+The package still exposes a few compatibility surfaces so older code keeps working.
 
-It wants you to think in **surfaces** rather than in “one file that does everything”.
+Prefer the newer APIs in fresh code:
 
-### HTTP surface
+- `resolveRef` and `serviceBinding` are legacy helpers around the newer `ref()` model
+- test helpers are re-exported from the main package for convenience, but `devflare/test` is the clearer import path for test code
+- `createMultiWorkerContext` and `createEntrypointScript` from `devflare/test` are deprecated in favor of `createTestContext()` and the worker-entrypoint pattern
+- `isRemoteModeEnabled()` is a deprecated alias; treat the remote-mode flow and `shouldSkip` helpers as the primary public story
+- `testEnv` belongs to the bridge-test-context API, not to the main unified `env` proxy
 
-Use `src/fetch.ts` for normal request handling.
+---
 
-### Queue surface
+## Config lifecycle
 
-Use `src/queue.ts` for queue consumers.
+This is the actual config lifecycle Devflare uses.
 
-### Scheduled surface
+1. You author `devflare.config.ts` with `defineConfig()`
+2. Devflare loads and validates it with the Zod-backed schema
+3. If an environment is selected, Devflare merges `config.env[environment]` into the base config
+4. Devflare compiles the resolved config into a Wrangler-compatible object
+5. Build/deploy flows write a generated `wrangler.jsonc`
+6. Vite/Wrangler/Miniflare then use the generated result in their respective phases
 
-Use `src/scheduled.ts` for cron triggers.
+### Config file names
 
-### Email surface
+`loadConfig()` looks for these filenames, in this order:
 
-Use `src/email.ts` for incoming email handling. Use `sendEmail` bindings in config for outgoing email.
+- `devflare.config.ts`
+- `devflare.config.mts`
+- `devflare.config.js`
+- `devflare.config.mjs`
 
-### Routing surface
+### `defineConfig()` supported forms
 
-Use `files.routes` with a directory like `src/routes` when you want file-based HTTP routing instead of one monolithic fetch file.
+`defineConfig()` accepts all of these forms:
 
-### Durable Object surface
+```ts
+import { defineConfig } from 'devflare'
 
-Use `do.*.ts` files for Durable Objects.
+export default defineConfig({
+	name: 'my-worker'
+})
+```
 
-### RPC / service-entry surface
+```ts
+import { defineConfig } from 'devflare'
 
-Use `ep.*.ts` files for named WorkerEntrypoints.
+export default defineConfig(() => ({
+	name: process.env.WORKER_NAME ?? 'my-worker'
+}))
+```
 
-### Workflow surface
+```ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig(async () => ({
+	name: 'my-worker'
+}))
+```
 
-Use `wf.*.ts` files for Workflow classes.
+It also supports a generic entrypoint type parameter:
 
-### Transport surface
+```ts
+import { defineConfig } from 'devflare'
 
-Use `src/transport.ts` when values crossing boundaries need custom serialization.
+export default defineConfig<import('./env').Entrypoints>({
+	name: 'my-worker'
+})
+```
 
-This is one of Devflare’s biggest advantages: it turns Cloudflare development from “single worker blob” into **separated, discoverable, testable responsibilities**.
+That generic exists to improve type inference for `ref().worker('SomeEntrypoint')` after `env.d.ts` has been generated.
 
 ---
 
-## Public package entry points
+## How env files, `vars`, and `secrets` actually work
 
-Use the package subpaths intentionally.
+This is the section people most often get wrong.
 
-| 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()` |
+### The short version
 
----
+- `loadConfig()` itself does **not** run dotenv loading
+- the Devflare CLI runs under **Bun**, and Bun **does** auto-load `.env` files into `process.env`
+- `vars` are plain configuration values compiled into generated Wrangler config and exposed at runtime as normal bindings
+- `secrets` are **declarations of expected runtime secrets**, not a place to store secret values
+- actual secret values should come from Cloudflare secret storage or the local secret mechanisms used by Wrangler/Cloudflare tooling
+
+### The four sources you must distinguish
 
-## Core ideas you should internalize
+| Thing | Source of truth | Used when | Appears in generated `wrangler.jsonc` | Available as runtime binding | Safe for secrets |
+|---|---|---|---|---|---|
+| `process.env` | Bun process environment, shell env, or manually loaded env files | config evaluation time and build tooling | No, unless you copy values into config | Not automatically | Only if your own process handling is secure |
+| `vars` | `devflare.config.ts` | compile time and runtime | **Yes** | **Yes** | **No** |
+| `secrets` | secret declaration in `devflare.config.ts` plus actual runtime secret store | runtime | **No secret values are compiled** | **Yes**, if runtime values are provided | **Yes** |
+| local runtime secret files such as `.dev.vars` or Wrangler-style local `.env` usage | local Cloudflare/Wrangler runtime layer | local runtime only | No | Yes | Yes |
+| Cloudflare secret store | Cloudflare platform | deployed runtime | No | Yes | Yes |
 
-### `defineConfig()` is the center of the project
+### What Devflare itself does and does not load
 
-Always define your worker through `defineConfig()`.
+`loadConfig()` calls the underlying config loader with `dotenv: false`.
+
+That means **Devflare’s config loader does not provide its own dotenv layer**.
+
+However, the published CLI entrypoint runs via Bun, and Bun auto-loads env files such as:
+
+- `.env`
+- `.env.<NODE_ENV>`
+- `.env.local`
+
+So when you run the Devflare CLI normally, `process.env` is often already populated **before** `devflare.config.ts` is evaluated.
+
+That gives you this effective behavior:
+
+- **CLI usage under Bun**: `.env` values are usually available via `process.env`
+- **programmatic `loadConfig()` in another runtime**: do **not** assume env files were loaded unless your process already loaded them
+
+This distinction matters a lot. The env-file loading is coming from **Bun**, not from Devflare’s config loader.
+
+### Recommended mental model
+
+Treat config-time env and runtime env as separate layers:
+
+1. read config-time values from `process.env`
+2. put **non-secret** values that should become Worker bindings in `vars`
+3. declare **secret names** in `secrets`
+4. provide actual secret values through local runtime secret files or Cloudflare secret storage
+
+### Example: non-secret build/runtime config vs runtime secret
 
 ```ts
 import { defineConfig } from 'devflare'
 
-export default defineConfig({
-	name: 'my-worker'
-})
+export default defineConfig(() => ({
+	name: 'billing-worker',
+	vars: {
+		PUBLIC_API_BASE: process.env.PUBLIC_API_BASE ?? 'http://localhost:5173',
+		LOG_LEVEL: process.env.LOG_LEVEL ?? 'info'
+	},
+	secrets: {
+		STRIPE_SECRET_KEY: { required: true },
+		POSTMARK_TOKEN: { required: true }
+	}
+}))
 ```
 
-This is the source of truth Devflare uses to:
-
-- understand your bindings
-- understand your file layout
-- generate Wrangler-compatible config
-- drive dev mode
-- drive test mode
+What this means:
 
-### Convention beats boilerplate
+- `PUBLIC_API_BASE` and `LOG_LEVEL` are not treated as secret and may be baked into generated config
+- `STRIPE_SECRET_KEY` and `POSTMARK_TOKEN` are declared as required runtime secrets
+- the **values** for those secrets should come from a runtime secret source, not from `vars`
 
-If your filenames follow the defaults, you do not need to spell everything out.
+### Why `vars` are not secrets
 
-Defaults include:
+Devflare’s compiler writes `vars` into the generated Wrangler config object.
 
-- `src/fetch.ts`
-- `src/queue.ts`
-- `src/scheduled.ts`
-- `src/email.ts`
-- `src/transport.ts`
-- `**/do.*.{ts,js}`
-- `**/ep.*.{ts,js}`
-- `**/wf.*.{ts,js}`
+That means they are part of the deployment configuration shape. In other words:
 
-### `ref()` is how cross-worker systems stay clean
+- they are configuration
+- they are intentionally reproducible
+- they are suitable for public base URLs, feature flags, modes, IDs, and other non-secret values
+- they are **not** suitable for API keys, tokens, passwords, or signing secrets
 
-If one worker depends on another worker or on another worker’s Durable Objects, use `ref()` instead of manually duplicating names.
+### What `secrets` actually mean in Devflare
 
-That keeps cross-worker relationships typed and centralized.
+The current `secrets` field is a declaration layer. It tells Devflare which secret names exist and whether they are required.
 
-### `env` is the unified access point
-
-Use:
+Today, each secret is configured as:
 
 ```ts
-import { env } from 'devflare'
+secrets: {
+	MY_SECRET: { required: true }
+}
 ```
 
-Devflare makes `env` work coherently across request handling, tests, and bridge-backed local flows.
+What this does **not** mean:
 
----
+- it does not embed the secret value in `devflare.config.ts`
+- it does not compile secret values into `wrangler.jsonc`
+- it does not create a second custom secret-store format on top of Cloudflare/Wrangler
 
-## Why file structure matters so much in Devflare
+What it **does** mean:
 
-In plain Worker setups, it is common to end up with a single file that mixes:
+- you are declaring an expected runtime binding
+- generated types can treat that binding as a string-like secret binding
+- your runtime still needs the actual value from a proper secret source
 
-- HTTP routing
-- queue handling
-- scheduled jobs
-- email handling
-- Durable Object exports
-- auxiliary RPC handlers
-- test-specific wiring
+### Local env-file overlap warning
 
-Devflare pushes in the opposite direction.
+The filename `.env` can be confusing because it may participate in **two different stories**:
 
-It gives each responsibility a natural home and then composes them together.
+1. Bun may read it at process start and populate `process.env`
+2. local Cloudflare/Wrangler tooling may also use `.env`-style files for runtime bindings
 
-That has several benefits:
+So the same file can accidentally influence both config-time and runtime behavior.
 
-- lower mental overhead
-- easier code generation
-- easier code review
-- easier testing
-- fewer accidental runtime coupling mistakes
-- clearer ownership boundaries within a team
+If you want clearer separation, prefer this mental split:
 
-For LLM generation specifically, this matters a lot.
+- use Bun-loaded `.env` only for config-time inputs that you intentionally read via `process.env`
+- use local secret files such as `.dev.vars` for runtime secrets
 
-When generating Devflare code, prefer **separate files with clear responsibilities** over giant all-in-one worker files.
+### If you need strict control over env loading
+
+Because the CLI runs under Bun, Bun’s own env-file controls still matter. If you invoke the CLI through Bun directly, Bun-level flags such as explicit env-file selection or env-file disabling control that part of the story.
 
 ---
 
-## Config example
+## Top-level config reference
+
+This table shows what each top-level config key means, which layer uses it, and whether it becomes part of compiled Wrangler output.
+
+| Key | Meaning | Used by | Compiled to `wrangler.jsonc` | Notes |
+|---|---|---|---|---|
+| `name` | Worker name | all phases | Yes | required |
+| `accountId` | Cloudflare account ID | compile, dev, remote integrations | Yes | especially relevant for remote services |
+| `compatibilityDate` | Workers compatibility date | compile/runtime | Yes | defaults to current date |
+| `compatibilityFlags` | Workers compatibility flags | compile/runtime | Yes | Devflare always includes `nodejs_compat` and `nodejs_als` |
+| `files` | handler paths and discovery globs | Devflare discovery/dev/test/build tooling | Partly | `files.fetch` influences compiled `main`; most of `files` is Devflare-only metadata |
+| `bindings` | Cloudflare bindings | compile/dev/test/runtime | Mostly | some bindings are stronger than others, see caveats below |
+| `triggers` | cron triggers | compile/runtime | Yes | currently `crons` |
+| `vars` | non-secret runtime bindings | compile/runtime | Yes | string values only in current schema |
+| `secrets` | secret declarations | typing/validation/runtime expectations | No secret values | declaration layer only |
+| `routes` | Cloudflare deployment routes | compile/deploy | Yes | this is edge routing, not file-based app routing |
+| `wsRoutes` | dev-mode websocket-to-DO proxy rules | local dev | No | Devflare-only dev feature |
+| `assets` | static assets config | compile/dev/runtime | Yes | current native shape is `{ directory, binding? }` |
+| `limits` | worker runtime limits | compile/runtime | Yes | current native shape only models `cpu_ms` |
+| `observability` | worker logs / sampling | compile/runtime | Yes | passes through directly |
+| `migrations` | Durable Object migrations | compile/runtime | Yes | used for DO class evolution |
+| `build` | build metadata/options | schema/dev/build tooling | No direct compiler output | see caveats below |
+| `plugins` | Vite plugin list / build-time extension point | schema/build tooling | No direct compiler output | see caveats below |
+| `env` | environment-specific overrides | Devflare pre-compilation merge layer | Not as nested env blocks | only a subset of top-level keys is supported inside each env block; see the dedicated section |
+| `wrangler.passthrough` | raw Wrangler fields not modeled natively | compiler/deploy | Yes | merged at top level into compiled config |
+
+### Minimal config
 
-This is a good realistic starting point.
+```ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig({
+	name: 'hello-worker'
+})
+```
+
+### Realistic starting config
 
 ```ts
 import { defineConfig } from 'devflare'
@@ -300,13 +412,74 @@ export default defineConfig({
 
 ---
 
-## File-based routing
+## `files`: conventions, discovery, and what each tool does with them
 
-Devflare supports a file-structured routing model through `files.routes`.
+The `files` section tells Devflare where to find handlers and discovery targets.
 
-That is important because it moves you away from hand-written request dispatch in one file and toward a more maintainable app structure.
+| Key | Shape | Default convention | Meaning |
+|---|---|---|---|
+| `fetch` | `string | false` | `src/fetch.ts` or `src/fetch.js` | main HTTP handler |
+| `queue` | `string | false` | `src/queue.ts` | queue consumer handler |
+| `scheduled` | `string | false` | `src/scheduled.ts` | cron/scheduled handler |
+| `email` | `string | false` | `src/email.ts` | incoming email handler |
+| `durableObjects` | `string | false` | `**/do.*.{ts,js}` | DO class discovery glob |
+| `entrypoints` | `string | false` | `**/ep.*.{ts,js}` | WorkerEntrypoint discovery glob |
+| `workflows` | `string | false` | `**/wf.*.{ts,js}` | Workflow discovery glob |
+| `routes` | `{ dir, prefix? } or false` | no implicit route dir unless configured | file-based HTTP routing |
+| `transport` | `string` | `src/transport.ts` | custom encode/decode transport definitions |
 
-Example:
+### Discovery rules
+
+- discovery globs respect `.gitignore`
+- ignored/generated directories such as `node_modules`, `dist`, and `.devflare` are excluded
+- setting a handler/discovery key to `false` explicitly disables that surface
+
+### Test-context config resolution is more limited than `loadConfig()`
+
+`loadConfig()` supports `.ts`, `.mts`, `.js`, and `.mjs` config filenames.
+
+However, the current automatic nearest-config search used by `createTestContext()` only looks for:
+
+- `devflare.config.ts`
+- `devflare.config.js`
+
+That means:
+
+- if your project uses `devflare.config.mts` or `devflare.config.mjs`, pass the config path explicitly to `createTestContext()`
+- explicit config paths in `createTestContext()` are resolved relative to the calling test file, not always relative to `process.cwd()`
+- monorepos are safest when tests pass an explicit config path instead of relying on upward auto-discovery
+
+### `files.transport` must export a named `transport`
+
+When `createTestContext()` loads `files.transport`, it expects a named `transport` export.
+
+If the file exists but does not export `transport`, Devflare currently warns and falls back to testing without custom transport encoding/decoding.
+
+### Very important nuance: conventions are not used identically by every tool
+
+Devflare is convention-friendly, but not every subsystem consumes conventions in the exact same way.
+
+Current important behavior:
+
+- local dev and `createTestContext()` can fall back to conventional handler files when present
+- type generation and discovery use default globs for DOs, entrypoints, and workflows
+- `compileConfig()` only writes Wrangler `main` when `files.fetch` is explicitly a string
+
+So the safest rule is:
+
+> If a surface matters to build/deploy output, prefer making it explicit in config even if Devflare can discover it conventionally in some other paths.
+
+### `files.routes` vs top-level `routes` vs `wsRoutes`
+
+These three are different and should never be conflated.
+
+| Key | What it does | Layer |
+|---|---|---|
+| `files.routes` | enables Devflare file-based HTTP route discovery inside your app | Devflare app structure |
+| top-level `routes` | defines Cloudflare deployment route matching like `example.com/*` | Cloudflare deployment config |
+| `wsRoutes` | defines local dev websocket upgrade forwarding to Durable Objects | Devflare dev server |
+
+### File-based routing example
 
 ```ts
 import { defineConfig } from 'devflare'
@@ -322,451 +495,613 @@ export default defineConfig({
 })
 ```
 
-Conceptually, this means:
+Typical route-tree mental model:
 
-- 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
-
-If you only need a small Worker, `src/fetch.ts` is perfect.
+```text
+src/routes/
+├── index.ts
+├── users/
+│   ├── index.ts
+│   └── [id].ts
+└── health.ts
+```
 
-If your HTTP surface is growing, `files.routes` is usually the better model.
+Use `files.routes` when the HTTP surface is large enough that a single `fetch.ts` would become a switch-statement graveyard.
 
 ---
 
-## Queues: produce in one place, consume in another
+## `bindings`: supported binding types and what they mean
 
-Devflare wants queue production and queue consumption to live in obvious places.
+Bindings are the heart of the runtime contract.
 
-- produce messages from `fetch` or another handler via the bound queue producer
-- consume them in `src/queue.ts`
-- test them with `cf.queue`
+### Binding reference
 
-### Queue config example
+| Binding type | Shape | Compiles natively | Notes |
+|---|---|---|---|
+| `kv` | `Record<string, string>` | Yes | binding name → KV namespace ID |
+| `d1` | `Record<string, string>` | Yes | binding name → D1 database ID |
+| `r2` | `Record<string, string>` | Yes | binding name → bucket name |
+| `durableObjects` | `Record<string, string | { className, scriptName? }>` | Yes | string shorthand or object form, including cross-worker refs |
+| `queues.producers` | `Record<string, string>` | Yes | binding name → queue name |
+| `queues.consumers` | array of consumer objects | Yes | batch size, retries, timeout, DLQ, concurrency, retry delay |
+| `services` | `Record<string, { service, environment?, entrypoint? }>` or `ref().worker` | Mostly | see named-entrypoint caveat below |
+| `ai` | `{ binding }` | Yes | remote-oriented service |
+| `vectorize` | `Record<string, { indexName }>` | Yes | remote-oriented service |
+| `hyperdrive` | `Record<string, { id }>` | Yes | PostgreSQL acceleration |
+| `browser` | `{ binding }` | Yes | browser-rendering support with local shim behavior |
+| `analyticsEngine` | `Record<string, { dataset }>` | Yes | Analytics Engine datasets |
+| `sendEmail` | `Record<string, { destinationAddress? }>` | **Not fully** | schema exists, but support is lighter than core bindings |
 
-```ts
-import { defineConfig } from 'devflare'
+### Core storage bindings
 
-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'
-		}
+These are straightforward binding-name maps:
+
+```ts
+bindings: {
+	kv: {
+		CACHE: 'cache-kv-id'
+	},
+	d1: {
+		DB: 'db-id'
+	},
+	r2: {
+		FILES: 'files-bucket'
 	}
-})
+}
 ```
 
-### Producer example from `fetch`
+### Durable Objects
+
+Durable Object bindings support both shorthand and object form.
+
+Shorthand local form:
 
 ```ts
-import { env } from 'devflare'
+bindings: {
+	durableObjects: {
+		COUNTER: 'Counter'
+	}
+}
+```
 
-export default async function fetch(request: Request): Promise<Response> {
-	const url = new URL(request.url)
+Explicit form:
 
-	if (url.pathname === '/tasks') {
-		const task = {
-			id: crypto.randomUUID(),
-			type: 'resize-image'
+```ts
+bindings: {
+	durableObjects: {
+		COUNTER: {
+			className: 'Counter'
 		}
-
-		await env.TASK_QUEUE.send(task)
-		return Response.json({ queued: true, task })
 	}
-
-	return new Response('Not found', { status: 404 })
 }
 ```
 
-### Consumer example in `src/queue.ts`
+Cross-worker form uses `scriptName` or a `ref()`-produced DO binding.
 
-```ts
-import type { MessageBatch } from '@cloudflare/workers-types'
+### Queues
+
+Producers and consumers are separated intentionally.
 
-type Task = {
-	id: string
-	type: string
+```ts
+bindings: {
+	queues: {
+		producers: {
+			TASK_QUEUE: 'task-queue'
+		},
+		consumers: [
+			{
+				queue: 'task-queue',
+				maxBatchSize: 10,
+				maxBatchTimeout: 5,
+				maxRetries: 3,
+				deadLetterQueue: 'task-queue-dlq'
+			}
+		]
+	}
 }
+```
+
+Important distinction:
+
+- `queues.producers` creates runtime bindings that your code can call
+- `queues.consumers` configures delivery behavior for queue names and does not create extra env binding names by itself
+
+### Services and entrypoints
 
-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()
+Service bindings can be written directly or via `ref()`.
+
+Direct form:
+
+```ts
+bindings: {
+	services: {
+		AUTH: {
+			service: 'auth-worker'
 		}
 	}
 }
 ```
 
-Authoring guidance:
+Current compiler nuance:
 
-- 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
+- the service-binding schema and `ref().worker('EntrypointName')` surface can model named entrypoints
+- the current config compiler emits `service` and optional `environment`
+- it does **not** currently emit a native compiled `entrypoint` field into generated Wrangler config
 
----
+So named-entrypoint service bindings should be treated as a typed/public surface with deployment-time caution.
+
+`ref()` form:
+
+```ts
+import { defineConfig, ref } from 'devflare'
 
-## Email: receiving and sending
+const auth = ref(() => import('../auth/devflare.config'))
 
-Devflare supports two sides of email: **receiving** incoming messages and **sending** outgoing ones.
+export default defineConfig({
+	name: 'gateway',
+	bindings: {
+		services: {
+			AUTH: auth.worker,
+			ADMIN: auth.worker('AdminEntrypoint')
+		}
+	}
+})
+```
 
-### Receiving email
+### Browser rendering
 
-Export an `email` function from `src/email.ts`. Devflare wires it as the worker's incoming email handler.
+Browser rendering is one of the clearest examples of Devflare adding meaningful orchestration on top of a local Workers runtime.
 
 ```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()
-		})
-	)
-
-	// Forward every incoming message to admin
-	await message.forward('admin@example.com')
+bindings: {
+	browser: {
+		binding: 'BROWSER'
+	}
 }
 ```
 
-The `ForwardableEmailMessage` object also supports `message.reply(replyMessage)` for auto-responses.
+In local dev, Devflare adds browser-shim orchestration so browser workflows can participate in the same system as the rest of your worker app.
 
-### Sending email (the `sendEmail` binding)
+### AI and Vectorize
 
-To send outgoing email, declare a `sendEmail` binding in config. Each key becomes a typed `env` property of type `SendEmail`.
+These services are fundamentally remote-oriented.
 
-The value object accepts an optional `destinationAddress`:
+Devflare can type them, configure them, and help you test them intentionally, but it does **not** pretend they are fully local equivalents of KV or D1.
 
-- **With `destinationAddress`** — every email sent through that binding is locked to that recipient.
-- **Without it (`{}`)** — you choose the recipient at send time.
+In the current high-level test setup, these are also the bindings that switch to Cloudflare-backed remote proxies when remote mode is enabled. They are the clearest “remote-only” part of the public testing story.
 
-```ts
-import { defineConfig } from 'devflare'
+### `sendEmail`
 
-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' },
+`sendEmail` is present in the schema and examples, with this current shape:
 
-			// Open destination — specify per message
-			EMAIL: {}
+```ts
+bindings: {
+	sendEmail: {
+		ADMIN_EMAIL: {
+			destinationAddress: 'admin@example.com'
 		}
 	}
-})
+}
 ```
 
-This produces:
+However, this binding is currently **not wired through the compiler/types/runtime helpers as completely as core bindings like KV, D1, R2, DOs, queues, and services**. Treat it as a lighter/partial area and validate actual generated output before relying on it in deployment-critical paths.
+
+---
 
-- `env.ADMIN_EMAIL: SendEmail` — hardcoded to `admin@example.com`
-- `env.EMAIL: SendEmail` — recipient provided at send time
+## `vars`, `secrets`, and generated types
 
-### Testing email
+### `vars`
 
-Use the `email` helper from `devflare/test`:
+Current Devflare schema models `vars` as:
 
 ```ts
-import { email } from 'devflare/test'
+Record<string, string>
+```
 
-const response = await email.send({
-	from: 'sender@example.com',
-	to: 'recipient@example.com',
-	subject: 'Test message',
-	body: 'Hello from the test suite.'
-})
+That is stricter than the broadest possible Wrangler configuration story.
+
+So in Devflare today:
 
-expect(response.ok).toBe(true)
+- treat `vars` as **string-valued bindings**
+- serialize more complex values yourself if needed
+- do not assume arbitrary JSON-valued vars are a first-class Devflare config feature
+
+### `secrets`
+
+Current Devflare schema models each secret as:
+
+```ts
+{ required?: boolean }
 ```
 
-Authoring guidance:
+That means the native configuration is about **declaring expected secret names and whether they are required**, not about storing the secret values themselves.
 
-- 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
+One subtle but important default: `required` defaults to `true`.
 
----
+So this:
 
-## Browser rendering is a real example of Devflare extending Miniflare
+```ts
+secrets: {
+	API_KEY: {}
+}
+```
 
-This is worth emphasizing.
+means “`API_KEY` is a required runtime secret”, not “optional secret with no requirements”.
 
-Devflare supports **browser rendering** locally via a browser shim layer.
+### `devflare types`
 
-That matters because browser rendering is not something Miniflare gives you directly as a complete local developer workflow.
+`devflare types` generates `env.d.ts` and uses config/discovery information to generate:
 
-With Devflare, browser rendering becomes part of the same system as the rest of your bindings and local development story:
+- a global `DevflareEnv` interface
+- binding members for `vars`
+- binding members for `secrets`
+- discovered WorkerEntrypoints
+- entrypoint union types such as `Entrypoints`
+- service/DO typing for cross-worker references
 
-- 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
+Recommended invocation:
 
-This is exactly the kind of feature that demonstrates the Devflare philosophy:
+```text
+bunx --bun devflare types
+```
 
-> take a low-level runtime foundation, then add the higher-level orchestration developers actually need
+After generation, project code can use the global `DevflareEnv` interface and typed `ref()` entrypoints.
 
 ---
 
-## Durable Objects and multi-worker systems
+## Environment overrides via `config.env`
+
+Devflare’s `env` field is a **Devflare-level merge layer**.
+
+It is not simply a verbatim mirror of raw Wrangler `[env.someName]` sections.
+
+### How it works
+
+When you call `compileConfig(config, environment)` or run CLI commands with `--env <name>`, Devflare:
 
-Devflare is designed to keep multi-worker and DO-heavy systems manageable.
+1. takes the base config
+2. reads `config.env?.[name]`
+3. merges that override object into the base config with `defu`
+4. compiles the **resolved result**
 
-### Local Durable Objects
+That means omitted nested fields inherit from the base config.
 
-Bind them in config:
+### Keys that can actually appear inside `env`
+
+The current `env` schema supports overrides for these keys:
+
+- `name`
+- `compatibilityDate`
+- `compatibilityFlags`
+- `files`
+- `bindings`
+- `triggers`
+- `vars`
+- `secrets`
+- `routes`
+- `assets`
+- `limits`
+- `observability`
+- `migrations`
+- `build`
+- `wrangler`
+
+Not currently supported inside `config.env.<name>`:
+
+- `accountId`
+- `wsRoutes`
+- `plugins`
+
+So if you need environment-specific values for one of those unsupported keys, compute them in the outer `defineConfig()` function yourself instead of assuming `config.env` can hold them.
+
+### Merge semantics are `defu`, not “replace the base object”
+
+Devflare currently resolves environments with:
 
 ```ts
-bindings: {
-	durableObjects: {
-		COUNTER: 'Counter'
-	}
-}
+defu(config.env[environment], config)
 ```
 
-Put their classes in `do.*.ts` files.
+That means all of the following are true:
 
-### Complete local Durable Object example
+- leftmost values win when both sides define the same scalar field
+- nested objects inherit omitted keys from the base config
+- arrays are concatenated rather than replaced, with env-specific array items first and base items appended afterward
+- `null` and `undefined` are skipped rather than used as a deletion mechanism
 
-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: 'app',
+	triggers: {
+		crons: ['0 0 * * *']
+	},
+	vars: {
+		API_URL: 'https://api.example.com',
+		DEBUG: 'false'
+	},
 	bindings: {
-		durableObjects: {
-			SESSION: 'SessionStore'
+		kv: {
+			CACHE: 'prod-cache-id'
+		}
+	},
+	env: {
+		dev: {
+			triggers: {
+				crons: ['*/5 * * * *']
+			},
+			vars: {
+				DEBUG: 'true'
+			},
+			bindings: {
+				kv: {
+					CACHE: 'dev-cache-id'
+				}
+			}
 		}
 	}
 })
 ```
 
-```ts
-// src/do.session.ts
-import { DurableObject } from 'cloudflare:workers'
+Selecting `dev` gives you a merged result equivalent to:
 
-export class SessionStore extends DurableObject<DevflareEnv> {
-	private data = new Map<string, string>()
+- `vars.API_URL = 'https://api.example.com'`
+- `vars.DEBUG = 'true'`
+- `bindings.kv.CACHE = 'dev-cache-id'`
+- `triggers.crons = ['*/5 * * * *', '0 0 * * *']`
 
-	getValue(key: string): string | null {
-		return this.data.get(key) ?? null
-	}
+That last point surprises people. If you expected the env-specific cron array to **replace** the base array, that is not how the current merge works.
 
-	setValue(key: string, value: string): void {
-		this.data.set(key, value)
-	}
+### Practical rule for arrays
+
+If an array should be totally different per environment, do **not** rely on `config.env` to replace it.
+
+Instead, compute the final value in `defineConfig(() => ...)` yourself and return the already-resolved array.
+
+### `wrangler.passthrough` is applied after compilation
+
+Another important precedence rule: after Devflare compiles the resolved config, it applies `wrangler.passthrough` with a top-level `Object.assign()`.
+
+That means passthrough values can overwrite fields that Devflare just compiled.
+
+This is powerful, but it also means `wrangler.passthrough` is an escape hatch with override power, not just a harmless bag of extra settings.
+
+### Why this matters
+
+Raw Wrangler environments have their own rules, and some sections in Wrangler are famously non-inheritable.
+
+Devflare’s `config.env` is more ergonomic:
+
+- you write only the differences
+- Devflare resolves a single environment-specific config first
+- then it compiles the resolved config
+
+So the correct mental model is:
+
+> `config.env` is a Devflare **pre-compilation override system**, not just a literal nested dump into Wrangler.
+
+---
+
+## `routes`, `assets`, `observability`, `limits`, `migrations`, and passthrough
 
-	clearAll(): void {
-		this.data.clear()
+### Deployment `routes`
+
+Top-level `routes` are Cloudflare deployment routes.
+
+```ts
+routes: [
+	{
+		pattern: 'example.com/*',
+		zone_name: 'example.com'
 	}
-}
+]
 ```
 
-```ts
-// src/fetch.ts
-import { env } from 'devflare'
+These are about **which hostnames/paths invoke the worker in deployment**.
 
-export default async function fetch(request: Request): Promise<Response> {
-	const url = new URL(request.url)
-	const sessionId = url.searchParams.get('session') ?? 'default'
+They are not related to file-based app routing.
 
-	const id = env.SESSION.idFromName(sessionId)
-	const session = env.SESSION.get(id)
+### `wsRoutes`
 
-	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 })
-	}
+`wsRoutes` are for Devflare local development. They describe how websocket upgrade requests should be forwarded into Durable Objects during dev.
 
-	if (url.pathname === '/get') {
-		const key = url.searchParams.get('key') ?? 'name'
-		const value = await session.getValue(key)
-		return Response.json({ value })
-	}
+Current shape:
 
-	if (url.pathname === '/clear') {
-		await session.clearAll()
-		return Response.json({ ok: true })
+```ts
+wsRoutes: [
+	{
+		pattern: '/chat/api',
+		doNamespace: 'CHAT_ROOM',
+		idParam: 'roomId',
+		forwardPath: '/websocket'
 	}
+]
+```
+
+These are **not** compiled into Wrangler config.
 
-	return new Response('Not found', { status: 404 })
+### `assets`
+
+Current native Devflare assets shape is:
+
+```ts
+assets: {
+	directory: './public',
+	binding: 'ASSETS'
 }
 ```
 
-Important authoring notes:
+The native modeled shape is currently focused on `directory` plus optional binding access.
 
-- 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
+If you need more advanced asset-related Wrangler fields, use `wrangler.passthrough`.
 
-### Transport layer example: Devflare encodes and decodes for you
+### `observability`
 
-Use `src/transport.ts` when a Worker or Durable Object returns custom classes that should survive supported RPC/test boundaries as real instances.
+Current native shape:
 
 ```ts
-// src/DoubleableNumber.ts
-export class DoubleableNumber {
-	value: number
-
-	constructor(n: number) {
-		this.value = n
-	}
-
-	get double() {
-		return this.value * 2
-	}
+observability: {
+	enabled: true,
+	head_sampling_rate: 0.1
 }
 ```
 
-```ts
-// src/transport.ts
-import { DoubleableNumber } from './DoubleableNumber'
+This compiles directly.
 
-export const transport = {
-	DoubleableNumber: {
-		encode: (v: unknown) => v instanceof DoubleableNumber && v.value,
-		decode: (v: number) => new DoubleableNumber(v)
-	}
+### `limits`
+
+Current native shape only models:
+
+```ts
+limits: {
+	cpu_ms: 50
 }
 ```
 
-```ts
-// src/do.counter.ts
-import { DoubleableNumber } from './DoubleableNumber'
+If you need Wrangler/Cloudflare limit-related fields outside that native shape, use `wrangler.passthrough`.
 
-export class Counter {
-	private count = 0
+### `migrations`
 
-	getValue(): DoubleableNumber {
-		return new DoubleableNumber(this.count)
-	}
+Durable Object migrations compile directly and are required when evolving DO classes over time.
+
+Current supported migration keys include:
+
+- `tag`
+- `new_classes`
+- `renamed_classes`
+- `deleted_classes`
+- `new_sqlite_classes`
+
+### `wrangler.passthrough`
 
-	increment(n: number = 1): DoubleableNumber {
-		this.count += n
-		return new DoubleableNumber(this.count)
+Use `wrangler.passthrough` for supported Wrangler fields that Devflare does not model natively.
+
+Example:
+
+```ts
+wrangler: {
+	passthrough: {
+		placement: { mode: 'smart' },
+		workers_dev: true
 	}
 }
 ```
 
-```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'
+The compiler merges these keys directly into the top level of the generated Wrangler config.
 
-beforeAll(() => createTestContext())
-afterAll(() => env.dispose())
+This is the correct escape hatch when native Devflare config is intentionally narrower than Wrangler’s full surface.
 
-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)
+---
 
-		expect(result).toBeInstanceOf(DoubleableNumber)
-		expect(result.double).toBe(4)
-	})
-})
-```
+## `build` and `plugins`
+
+Devflare’s schema includes:
 
-What Devflare is doing for the developer:
+- `build`
+- `plugins`
 
-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
+Current `build` shape includes:
 
-This means the developer writes the codec once and then works with real domain objects rather than manual serialization code.
+- `target`
+- `minify`
+- `sourcemap`
+- `rolldownOptions`
 
-### Cross-worker references
+However, it is important to understand the current maturity of these fields:
 
-Use `ref()` when one worker depends on another worker or another worker’s DO bindings.
+- they exist in the config schema
+- they are meaningful as project-level Devflare metadata and extension points
+- but the default CLI build/deploy path still primarily runs `bunx vite build`
+- they are **not** emitted directly by `compileConfig()` into `wrangler.jsonc`
+
+So do not assume that every field in `build` or every item in `plugins` is already consumed by every CLI/build path.
+
+When these fields matter, validate the actual Vite/build behavior in your project.
+
+---
+
+## `ref()`: multi-worker composition without stringly-typed glue
+
+Use `ref()` when one worker depends on another worker config.
+
+Supported forms include:
+
+```ts
+const auth = ref(() => import('../auth/devflare.config'))
+```
+
+```ts
+const auth = ref('custom-auth-name', () => import('../auth/devflare.config'))
+```
+
+From a `ref()` result you can access:
+
+- `.name`
+- `.config`
+- `.configPath`
+- `.worker`
+- `.worker('EntrypointName')`
+- uppercase DO binding access like `.COUNTER`
+- `.resolve()` for manual resolution
+
+### Service-binding example
 
 ```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
+			AUTH: auth.worker,
+			ADMIN: auth.worker('AdminEntrypoint')
+		},
+		durableObjects: {
+			AUTH_CACHE: auth.AUTH_CACHE
 		}
 	}
 })
 ```
 
-This is cleaner than scattering worker names and entrypoint names by hand throughout the codebase.
+Why `ref()` matters:
+
+- worker names stay centralized
+- cross-worker DO bindings stay typed
+- entrypoint names can be typed from generated `Entrypoints`
+- multi-worker systems avoid magic strings scattered everywhere
 
 ---
 
-## Runtime-safe helpers
+## Unified `env`
 
-Import runtime-only utilities from `devflare/runtime` when the code runs inside Workers.
+Importing `env` from the main package gives you a **unified environment proxy**.
 
-Important helpers include:
+```ts
+import { env } from 'devflare'
+```
 
-- `sequence()`
-- `resolve()`
-- `pipe()`
-- context-related utilities
+Current resolution order is:
 
-Use this path when you want runtime-safe middleware composition without pulling in Node-oriented orchestration code.
+1. request-scoped context
+2. test context
+3. bridge env
 
----
+That means the same import can work across:
 
-## Testing model
+- real request handling
+- test contexts created by `devflare/test`
+- bridge-backed local flows outside the request callback itself
 
-Devflare testing is one of the library’s biggest strengths.
+### What `env.dispose()` is for
 
-### Integration-style local tests
+`env.dispose()` is primarily a **test cleanup hook**.
 
-Use `createTestContext()` when you want a real local Devflare environment backed by Miniflare orchestration.
+Typical test pattern:
 
 ```ts
 import { beforeAll, afterAll, describe, expect, test } from 'bun:test'
@@ -784,79 +1119,509 @@ describe('worker', () => {
 })
 ```
 
-### Mock/unit-style tests
+### When to use imported `env` vs handler parameters
+
+Both are valid patterns.
+
+- use handler parameters when you want explicit dependency flow
+- use `import { env } from 'devflare'` when it improves ergonomics, shared helper usage, or test symmetry
+
+---
+
+## Testing model
+
+Devflare testing is one of the strongest parts of the package, but there are **two different layers** and the helpers are not all symmetric.
+
+### Main testing entrypoint
+
+Use `devflare/test`.
+
+The most important exports are:
+
+- `createTestContext`
+- `cf`
+- `email`
+- `queue`
+- `scheduled`
+- `worker`
+- `tail`
+- `shouldSkip`
+- `isRemoteModeEnabled`
+- mock helpers such as `createMockKV`, `createMockD1`, `createMockR2`, `createMockQueue`, `createMockEnv`
+- bridge helpers such as `createBridgeTestContext` and `testEnv`
+
+### `createTestContext()` — the recommended high-level test harness
+
+`createTestContext()` is the recommended default for most app and integration tests.
+
+Important behavior:
+
+- it resolves config relative to the **calling test file** when you pass an explicit config path
+- when you do not pass a config path, it searches upward from the caller directory for the nearest supported config file used by the test harness auto-search
+- it sets up the unified test env used by `import { env } from 'devflare'`
+- it resolves service bindings and cross-worker DO references
+- it can inject remote AI/Vectorize bindings when remote mode is enabled
+- it can fall back to conventional handler files for `fetch`, `queue`, and `scheduled` when those files exist
+
+### Handler helpers are intentionally asymmetric
+
+Do **not** assume every `cf.*` helper runs handlers the same way.
+
+| Helper | What it does | Waits for `waitUntil()`? | Important nuance |
+|---|---|---|---|
+| `cf.worker.fetch()` | imports the HTTP handler directly and calls default export or named `fetch` | **No** | returns as soon as the handler resolves; background work may still be pending |
+| `cf.queue.trigger()` | imports the queue handler directly and calls default export or named `queue` | **Yes** | waits for queued `waitUntil()` promises before returning the trigger result |
+| `cf.scheduled.trigger()` | imports the scheduled handler directly and calls default export or named `scheduled` | **Yes** | cron defaults to `* * * * *` if you do not provide one |
+| `email.send()` / `cf.email.send()` | posts a raw email to Miniflare’s local email endpoint | runtime-driven | this is how incoming email handlers are triggered locally |
+| `cf.tail.trigger()` | directly invokes a tail handler and waits for `waitUntil()` | **Yes, if configured** | standard `createTestContext()` currently does **not** auto-configure a tail handler path |
+
+Two especially important consequences:
+
+- `cf.worker.fetch()` is **not** a full “wait for all background work” helper
+- if you need to assert post-response side effects, queue/scheduled tests are more eager about draining `waitUntil()` than worker fetch tests
+
+### Email testing has two different directions
+
+For email, Devflare exposes both an incoming-message trigger and outgoing-message observation.
+
+- `email.send()` simulates an incoming email delivered to your worker’s `email()` handler
+- `email.onReceive()` and `email.getSentEmails()` observe outgoing emails produced by `env.EMAIL.send()`, `message.forward()`, or `message.reply()`
+
+Those are related, but they are not the same action.
+
+### Remote mode inside `createTestContext()`
+
+When remote mode is enabled, the current high-level test context only swaps in remote proxies for:
+
+- AI
+- Vectorize
+
+Other bindings remain local Miniflare-style or locally resolved bindings.
+
+Also note:
+
+- `config.vars` are still injected into the test env in remote mode
+- remote mode is not a blanket “make every binding remote” switch
+
+### `createBridgeTestContext()` — lower-level real Miniflare bindings
+
+`createBridgeTestContext()` is the lower-level integration surface.
+
+Use it when you want direct access to the real Miniflare bindings rather than the higher-level `cf.*` handler helpers.
+
+It gives you:
+
+- a running Miniflare instance
+- direct `env` bindings
+- `testEnv` proxy access from `devflare/test`
+- manual lifecycle control via `stop()` and `reset()`
+
+Important caveat:
+
+- `reset()` currently clears KV namespaces, but it does **not** fully reset every other binding type for you
+- if your test mutates D1, R2, Durable Objects, or similar resources, plan your own cleanup strategy
+
+### Transport loading in tests
+
+If you rely on custom transport encoding/decoding, the test context loads `files.transport` and expects a named `transport` export.
+
+If that export is missing, Devflare currently warns and continues without custom transport logic.
+
+### Tail support caveat
+
+`tail` is publicly exported from `devflare/test`, but the standard `createTestContext()` currently configures the tail helper with no handler path.
+
+So you should **not** assume `cf.tail.trigger()` works out of the box in the same way that `cf.worker`, `cf.queue`, or `cf.scheduled` do.
+
+### Mock/unit helpers
+
+For logic tests that should not spin up the full local environment, use:
 
-Use `createMockTestContext()`, `withTestContext()`, and the mock binding helpers when you want pure logic tests.
+- `createMockTestContext`
+- `withTestContext`
+- mock binding factories such as `createMockKV` and `createMockD1`
 
-### Why this is better than ad hoc Miniflare setup
+### Skip helpers and remote-only tests
 
-Devflare gives you a single mental model for testing each handler surface:
+Some services are intentionally treated as remote-only or cost-sensitive. Devflare includes skip helpers so tests do not accidentally become surprise invoice generators.
 
-- HTTP via `cf.worker`
-- queues via `cf.queue`
-- cron via `cf.scheduled`
-- email via `cf.email`
-- tail events via `cf.tail`
+Important current behavior:
 
-That consistency is part of the value. Instead of every project inventing its own test harness, Devflare gives you one coherent interface.
+- AI and Vectorize are treated as remote-only services
+- `shouldSkip.<service>` checks remote-mode enablement when relevant, authentication, effective account selection, and usage-limit state
+- skip decisions are cached per service at module level
+- operational issues such as auth failures, timeouts, network errors, and rate limits are treated as skip conditions rather than hard test failures
+
+Use:
+
+- `shouldSkip`
+- `devflare/cloudflare` account usage helpers when needed
+
+Treat `isRemoteModeEnabled()` as a compatibility alias, not the center of the modern test-guard story.
 
 ---
 
-## Vite and SvelteKit integration
+## Local dev, build, deploy, and generated artifacts
+
+### CLI commands
+
+Current CLI commands are:
+
+- `init`
+- `dev`
+- `build`
+- `deploy`
+- `types`
+- `doctor`
+- `account`
+- `ai`
+- `remote`
+- `help`
+- `version`
+
+Recommended invocation style:
+
+```text
+bunx --bun devflare <command>
+```
+
+### `dev`
+
+`devflare dev` is not “just run Miniflare”.
+
+It is a combined local development system that includes:
+
+- Vite dev server behavior
+- Miniflare-backed Cloudflare bindings
+- bridge-backed communication between Bun/Node-side tooling and the worker runtime
+- DO-oriented local orchestration and bundling behavior
+- websocket-aware proxying for local DO workflows
+- browser-shim behavior for browser rendering
+- local migration handling when relevant resources are configured
+
+Dev command flags include:
+
+- `--port`
+- `--persist`
+- `--verbose`
+- `--log`
+- `--log-temp`
+
+### Config path and environment selection in CLI commands
+
+For the current build and deploy flows:
+
+- config is loaded from the current working directory unless you pass `--config <file>`
+- `--env <name>` selects `config.env.<name>` during Devflare compilation
+- on `deploy`, the same `--env <name>` is also forwarded to `wrangler deploy`
+
+So `--env` on `deploy` affects both the Devflare-side resolution step **and** Wrangler’s deploy command.
+
+### `build`
+
+`devflare build`:
+
+1. loads config
+2. applies the selected Devflare environment override if `--env` is provided
+3. compiles a resolved Wrangler-compatible config
+4. writes `wrangler.jsonc`
+5. runs `bunx vite build`
+
+The build subprocess receives `DEVFLARE_BUILD=true` in its environment.
+
+That means project build code can branch on “Devflare build mode” if it needs to.
+
+### `deploy`
+
+`devflare deploy` performs the same config-resolution step, then builds and runs Wrangler deploy.
 
-Devflare includes dedicated framework-aware entry points.
+Important nuances:
+
+- `--dry-run` prints the resolved compiled config and exits without deploying
+- `--env <name>` is forwarded to Wrangler after Devflare resolves the same environment locally
+- unlike `build`, the current deploy command does **not** inject `DEVFLARE_BUILD=true` into the Vite build subprocess
+
+So do not assume build-time code sees identical environment flags under `build` and `deploy`.
+
+### `types`
+
+`devflare types` generates `env.d.ts`, which is a key part of the typed Devflare workflow.
+
+### `doctor`
+
+`devflare doctor` is a project diagnostics command.
+
+It currently checks for things such as:
+
+- a resolvable `devflare.config.*`
+- config validity
+- `package.json`
+- `vite` and `@cloudflare/vite-plugin` dependencies
+- a Vite config file
+- `tsconfig.json`
+- generated `wrangler.jsonc`
+
+Use it as a quick environment sanity check, not as a proof that every runtime behavior is correct.
+
+### Generated artifacts
+
+Treat these as generated output:
+
+- project-root `wrangler.jsonc` written by build/deploy flows
+- `.devflare/` generated output used by the Vite/plugin side of the toolchain
+- `.devflare/wrangler.jsonc` generated by the Vite plugin integration
+- generated `env.d.ts`
+
+Do not hand-edit generated outputs and then expect them to remain the source of truth. The source of truth is still `devflare.config.ts` plus your code files.
+
+---
+
+## Framework integration
 
 ### `devflare/vite`
 
-Use this when you want:
+This subpath exposes:
+
+- `devflarePlugin`
+- `getPluginContext`
+- `getCloudflareConfig`
+- `getDevflareConfigs`
+
+Use it when you need Devflare-aware Vite integration, worker-aware transforms, or auxiliary worker configuration support.
+
+### Recommended Vite mental model
+
+The Vite plugin does more than inject one helper.
+
+It currently:
 
-- config compilation during dev and build
-- worker-aware transforms
-- auxiliary Durable Object worker generation
-- websocket-aware proxying for local development
+- loads and compiles `devflare.config.ts`
+- injects `__DEVFLARE_WORKER_NAME__` for `workerName`
+- writes `.devflare/wrangler.jsonc`
+- discovers Durable Object classes using `files.durableObjects` or the default DO glob
+- creates an auxiliary `${name}-do` worker config when DO classes are discovered
+- adds WebSocket proxy rules in dev mode from `wsRoutes` plus any explicit `wsProxyPatterns`
+- reloads the dev server when the Devflare config changes if config watching is enabled
+
+If you want the least guesswork in `vite.config.ts`, use `getDevflareConfigs()` and pass the returned config into `@cloudflare/vite-plugin` explicitly.
+
+```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 ? auxiliaryWorkers : undefined
+			})
+		]
+	}
+})
+```
 
 ### `devflare/sveltekit`
 
-Use this when your app needs:
+This subpath exposes:
+
+- `handle`
+- `createDevflarePlatform`
+- `createHandle`
+- `resetPlatform`
+- `resetConfigCache`
+- `isDevflareDev`
+- `getBridgePort`
 
-- a Devflare-aware platform object
-- integration between SvelteKit and Worker bindings
-- local dev behavior that still fits the Devflare model
+Use it when SvelteKit should run against a Devflare-aware platform object and dev/runtime bridge.
 
-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.
+### Simplest SvelteKit setup
+
+The simplest integration is:
+
+```ts
+export { handle } from 'devflare/sveltekit'
+```
+
+Current behavior of the prebuilt `handle`:
+
+- it only activates when `NODE_ENV !== 'production'` and `DEVFLARE_DEV === 'true'`
+- it auto-loads binding hints from `devflare.config.ts` in the current working directory
+- it creates a bridge-backed `platform.env`
+- it supplies mocked `caches` and a synthetic development `cf` object for local use
+
+If you need more control, use `createHandle()` or `createDevflarePlatform()` directly.
+
+That is the better choice when:
+
+- your project is in a monorepo
+- `process.cwd()` is not the same directory as the relevant config
+- you want explicit binding hints
+- you want a custom enable/disable condition
+
+Also note:
+
+- platform instances are cached by bridge URL
+- `resetPlatform()` and `resetConfigCache()` are mainly test/reset helpers, not everyday app APIs
 
 ---
 
-## Remote-only services
+## `devflare/cloudflare`
 
-Some Cloudflare services are not meaningfully local.
+`devflare/cloudflare` is the Cloudflare-account helper module.
 
-Most importantly:
+Its main export is the `account` helper object, which provides:
 
-- Workers AI
-- Vectorize
+- authentication inspection
+- Wrangler-auth inspection
+- account selection and account summary helpers
+- resource listing for Workers, KV, D1, R2, Vectorize, and AI
+- service-status queries
+- usage tracking and per-service usage summaries
+- limit enforcement and test-guard helpers
+- preference helpers for default/global/workspace account selection
+
+This module is especially useful when writing tooling, diagnostics, or guardrails around remote services.
+
+### Account selection precedence
 
-Devflare treats those as explicit remote-mode concerns rather than pretending they are fully local.
+The effective account selection order is currently:
 
-That is a good thing.
+1. workspace account
+2. global default account
+3. primary Cloudflare account
 
-It keeps the local story honest while still giving you an intentional path to test remote capabilities when needed.
+### Where account preferences are stored
 
-Use the `devflare remote` workflow and guard remote-only tests appropriately.
+Devflare stores account preferences in more than one place.
+
+- workspace account: nearest `package.json` under `devflare.accountId`
+- global default account: local cache at `~/.devflare/preferences.json`
+- global default account sync: Cloudflare KV namespace titled `devflare-usage`
+
+That means `devflare account workspace` edits project files, while `devflare account global` updates user-level state and may also sync to Cloudflare-managed storage.
+
+### Remote mode storage and precedence
+
+Remote mode state is also persisted.
+
+- stored remote-mode config lives at `~/.devflare/remote.json`
+- `devflare remote enable [minutes]` writes that file and clamps duration to the range `1` to `1440` minutes
+- `DEVFLARE_REMOTE=1`, `true`, or `yes` takes precedence over the stored file
+
+This leads to one important practical detail:
+
+- `devflare remote disable` removes the stored config file
+- it does **not** unset `DEVFLARE_REMOTE`
+- so remote mode can still remain active after “disable” if the environment variable is set
+
+### Usage guards and test skipping
+
+The Cloudflare helper layer is also part of Devflare’s remote-test guardrail story.
+
+Current public behavior includes:
+
+- usage summaries and per-service limits
+- `account.canProceedWithTest()` and `account.shouldSkip()` helpers
+- best-effort behavior when auth/network/API issues occur
+
+In practice, this means remote-sensitive tests often choose between:
+
+- running normally
+- being skipped because remote mode is off
+- being skipped because the user is unauthenticated, over limits, or hitting operational API issues
 
 ---
 
-## Generated artifacts
+## Current caveats and partial areas
+
+This section exists on purpose. It is better to be accurate than accidentally over-promise.
 
-Devflare uses `.devflare/` for generated local artifacts.
+### Strong, well-defined areas
 
-Treat that directory as generated output rather than hand-authored source.
+These are core Devflare strengths today:
+
+- typed config via `defineConfig()`
+- config loading/validation/compilation
+- `vars`
+- file-based handler conventions
+- DO bindings and multi-worker references
+- queues
+- local test ergonomics
+- unified `env`
+- Vite/SvelteKit integration surfaces
+- browser binding orchestration
+
+### Important caveats
+
+1. **`secrets` are declaration-oriented, not a secret-value store**
+	- Devflare currently models secret names and `required` status
+	- `required` defaults to `true`
+	- it does not compile secret values into `wrangler.jsonc`
+	- actual secret values must come from runtime secret sources
+
+2. **`vars` are string-only in current Devflare config**
+	- do not assume arbitrary JSON-valued vars are a native Devflare feature
+
+3. **`config.env` only supports a subset of top-level config keys**
+	- it does not currently support environment-local `accountId`, `wsRoutes`, or `plugins`
+
+4. **`config.env` uses `defu` merge semantics**
+	- nested objects inherit from the base config
+	- arrays concatenate instead of replacing
+	- `null` and `undefined` are skipped rather than deleting base values
+
+5. **`wrangler.passthrough` is merged last and can override compiled fields**
+	- this is intentional escape-hatch power, but it means passthrough is not purely additive
+
+6. **`sendEmail` support is lighter than core bindings**
+	- it exists in the schema and examples
+	- but compiler/types/runtime support is not as complete as KV/D1/R2/DO/queues/services
+
+7. **named service entrypoints need caution**
+	- the schema and `ref().worker('Entrypoint')` surface model named entrypoints
+	- but the current config compiler writes `service` and optional `environment`, and does not currently emit a native `entrypoint` field into generated Wrangler config
+	- validate generated output if named-entrypoint deployment wiring matters to your app
+
+8. **`createTestContext()` auto-discovery is narrower than `loadConfig()`**
+	- the test-harness auto-search currently looks for `devflare.config.ts` and `devflare.config.js`
+	- projects using `.mts` or `.mjs` should pass an explicit config path
+
+9. **test helpers do not all model background work the same way**
+	- `cf.worker.fetch()` does not wait for `waitUntil()` promises
+	- queue and scheduled helpers do wait for `waitUntil()`
+
+10. **`cf.tail.trigger()` is public, but standard `createTestContext()` does not auto-wire it today**
+	 - treat tail testing as a more manual/partial area than worker, queue, or scheduled testing
+
+11. **`createBridgeTestContext().reset()` is not a full universal reset**
+	 - KV is cleared
+	 - other binding types may still need test-specific cleanup
+
+12. **workflows are a lighter area than fetch/queue/DO/entrypoints**
+	 - workflow discovery naming is modeled
+	 - but the broader runtime/compiler/test story is less mature than the most central surfaces
+
+13. **`build` and `plugins` are schema-level extension points, not guaranteed end-to-end behavior in every path**
+	 - the default build/deploy commands still center on Vite output
+	 - verify actual project behavior when relying on these fields
+
+14. **native config intentionally models only part of Wrangler’s total surface**
+	 - for unsupported or not-yet-modeled Wrangler keys, use `wrangler.passthrough`
+
+This is the right way to think about Devflare:
+
+> Prefer native Devflare config where it exists, use passthrough for unsupported Wrangler features, and do not confuse schema presence with complete end-to-end implementation maturity.
 
 ---
 
-## Recommended project structure
+## Recommended project shape
 
-Here is a strong default layout for most projects.
+This is a strong default layout for many Devflare apps:
 
 ```text
 .
@@ -876,52 +1641,53 @@ Here is a strong default layout for most projects.
     └── worker.test.ts
 ```
 
-You will not always need every file.
-
-But this shape captures the Devflare philosophy well:
+You will not always need every file, but this shape matches the Devflare mental model well:
 
-- each capability gets an isolated home
-- config stays declarative
+- config is declarative
+- each runtime surface has a natural home
 - tests target named surfaces
-- local orchestration is handled by Devflare instead of bespoke glue
+- multi-worker concerns can be expressed explicitly with `ref()`
 
 ---
 
 ## Guidance for LLMs generating Devflare code
 
-When generating Devflare projects or edits, follow these rules.
-
-### Prefer conventions first
+When generating Devflare code, follow these rules.
 
-Only override paths when there is a real reason.
+1. **Prefer `defineConfig()`**
+   - do not invent ad hoc config shapes when a normal Devflare config is appropriate
 
-### Prefer separation of responsibilities
+2. **Prefer separation of concerns**
+   - do not merge fetch, queue, scheduled, email, DOs, routes, and entrypoints into one file unless explicitly asked
 
-Do **not** collapse fetch, queue, scheduled, email, DOs, and entrypoints into a single file unless the task explicitly demands that shape.
+3. **Prefer explicit config for deploy-critical surfaces**
+   - conventions are great, but explicit `files.fetch`, bindings, routes, and migrations are safer when deployment behavior matters
 
-### Prefer `defineConfig()`
+4. **Use `vars` only for non-secret runtime configuration**
+   - feature flags, public URLs, modes, IDs, log levels, and similar values belong here
 
-Never emit untyped ad hoc config objects when a normal Devflare config is appropriate.
+5. **Use `secrets` only to declare secret bindings**
+   - actual secret values must come from runtime secret sources, not from committed config
 
-### Prefer `ref()` for cross-worker relationships
+6. **Prefer `ref()` for cross-worker composition**
+   - do not duplicate worker names and DO script names manually if a config reference is available
 
-Avoid manually duplicating worker names and binding metadata.
+7. **Prefer `devflare/test` for tests**
+   - use `createTestContext()` and `cf.*` for integration-style tests
+   - use mock helpers for pure unit tests
+	- pass an explicit config path in monorepos or when using `.mts`/`.mjs` config files
 
-### Prefer `devflare/test` for tests
+8. **Use imported `env` when it improves ergonomics**
+   - especially in tests and shared helpers
 
-Use `createTestContext()` for integration-style tests and mock helpers for unit tests.
+9. **Respect remote-only boundaries**
+   - do not pretend AI or Vectorize is “just local”
 
-### Prefer `env` for ergonomic binding access
+10. **Use `wrangler.passthrough` instead of inventing unsupported native fields**
+   - if you need a Wrangler option Devflare does not model yet, passthrough is the supported escape hatch
 
-Use `import { env } from 'devflare'` when it improves clarity.
-
-### Respect remote-only boundaries
-
-Do not fake fully local AI or Vectorize support.
-
-### Use routing when HTTP complexity grows
-
-If the app has many endpoints, prefer `files.routes` and route files over a giant `fetch.ts` dispatcher.
+11. **Do not assume every test helper drains `waitUntil()` the same way**
+	- `cf.worker.fetch()` and queue/scheduled helpers have importantly different behavior
 
 ---
 
@@ -932,7 +1698,10 @@ If the app has many endpoints, prefer `files.routes` and route files over a gian
 import { defineConfig } from 'devflare'
 
 export default defineConfig({
-	name: 'hello-worker'
+	name: 'hello-worker',
+	files: {
+		fetch: 'src/fetch.ts'
+	}
 })
 ```
 
@@ -965,12 +1734,18 @@ describe('hello-worker', () => {
 
 ## What to remember
 
-If you remember only seven things, remember these:
+If you only remember a few things, remember these:
 
 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
+2. Devflare extends Miniflare into a broader developer workflow rather than replacing Cloudflare’s runtime model
+3. Bun env-file loading and Devflare config loading are related but not the same thing
+4. `vars` are built into generated config and are not secrets
+5. `secrets` declare runtime secret bindings, default to `required: true`, and still need real runtime secret sources
+6. `config.env` is a Devflare merge layer applied before compilation, and it supports only part of the top-level config surface
+7. `config.env` uses `defu`, so arrays concatenate and nullish values do not delete base config
+8. `wrangler.passthrough` is merged last and can override compiled fields
+9. `files.routes`, top-level `routes`, and `wsRoutes` are three different concepts
+10. `createTestContext()` is caller-relative and not every test helper behaves the same way around `waitUntil()`
+11. `devflare/test` plus unified `env` is a major part of the package’s value
+12. use `ref()` for multi-worker composition instead of magic strings
+13. when native config does not cover a Wrangler feature, use `wrangler.passthrough`