devflare 1.0.0-next.0 → 1.0.0-next.2

package/LLM.md

@@ -0,0 +1,1751 @@
+# Devflare
+
+This file is for LLMs and developers **using** the published `devflare` package.
+
+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 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 layer for Cloudflare Workers**.
+
+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.
+
+Devflare sits on top of those pieces and turns them into one coherent authoring model.
+
+Concretely, Devflare provides:
+
+- typed config via `defineConfig()`
+- 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
+
+So Devflare is **not** “a different Workers runtime”.
+
+It is a higher-level developer system that uses the Cloudflare ecosystem underneath.
+
+---
+
+## The authoring model Devflare wants
+
+Devflare is intentionally opinionated.
+
+It wants you to think in **surfaces** rather than “one giant worker file that does everything”.
+
+Typical surfaces are:
+
+- 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`
+
+This separation is one of Devflare’s biggest advantages:
+
+- 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
+
+When generating or reviewing Devflare code, prefer **one responsibility per file** unless there is a very strong reason not to.
+
+---
+
+## Package entrypoints
+
+Use package subpaths intentionally.
+
+| 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 |
+
+### Important runtime note
+
+`devflare/runtime` is intentionally **smaller** than the main package.
+
+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`.
+
+### Common main-package exports
+
+The most common exports from `devflare` are:
+
+- `defineConfig`
+- `loadConfig`
+- `compileConfig`
+- `stringifyConfig`
+- `ref`
+- `env`
+- `workerName`
+
+The main package also exports advanced tooling APIs such as CLI helpers, bridge helpers, DO transform helpers, WorkerEntrypoint transform helpers, decorators, and test helpers.
+
+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
+
+### Deprecated and compatibility exports
+
+The package still exposes a few compatibility surfaces so older code keeps working.
+
+Prefer the newer APIs in fresh code:
+
+- `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
+
+---
+
+## Config lifecycle
+
+This is the actual config lifecycle Devflare uses.
+
+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
+
+### Config file names
+
+`loadConfig()` looks for these filenames, in this order:
+
+- `devflare.config.ts`
+- `devflare.config.mts`
+- `devflare.config.js`
+- `devflare.config.mjs`
+
+### `defineConfig()` supported forms
+
+`defineConfig()` accepts all of these forms:
+
+```ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig({
+	name: 'my-worker'
+})
+```
+
+```ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig(() => ({
+	name: process.env.WORKER_NAME ?? 'my-worker'
+}))
+```
+
+```ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig(async () => ({
+	name: 'my-worker'
+}))
+```
+
+It also supports a generic entrypoint type parameter:
+
+```ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig<import('./env').Entrypoints>({
+	name: 'my-worker'
+})
+```
+
+That generic exists to improve type inference for `ref().worker('SomeEntrypoint')` after `env.d.ts` has been generated.
+
+---
+
+## How env files, `vars`, and `secrets` actually work
+
+This is the section people most often get wrong.
+
+### 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
+
+| 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 |
+
+### What Devflare itself does and does not load
+
+`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: '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 }
+	}
+}))
+```
+
+What this means:
+
+- `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`
+
+### Why `vars` are not secrets
+
+Devflare’s compiler writes `vars` into the generated Wrangler config object.
+
+That means they are part of the deployment configuration shape. In other words:
+
+- 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
+
+### What `secrets` actually mean in Devflare
+
+The current `secrets` field is a declaration layer. It tells Devflare which secret names exist and whether they are required.
+
+Today, each secret is configured as:
+
+```ts
+secrets: {
+	MY_SECRET: { required: true }
+}
+```
+
+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
+
+What it **does** mean:
+
+- 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
+
+### Local env-file overlap warning
+
+The filename `.env` can be confusing because it may participate in **two different stories**:
+
+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
+
+So the same file can accidentally influence both config-time and runtime behavior.
+
+If you want clearer separation, prefer this mental split:
+
+- 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
+
+### 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.
+
+---
+
+## 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
+
+```ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig({
+	name: 'hello-worker'
+})
+```
+
+### Realistic starting config
+
+```ts
+import { defineConfig } from 'devflare'
+
+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'
+	}
+})
+```
+
+---
+
+## `files`: conventions, discovery, and what each tool does with them
+
+The `files` section tells Devflare where to find handlers and discovery targets.
+
+| 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 |
+
+### 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'
+
+export default defineConfig({
+	name: 'my-api',
+	files: {
+		routes: {
+			dir: 'src/routes',
+			prefix: '/api'
+		}
+	}
+})
+```
+
+Typical route-tree mental model:
+
+```text
+src/routes/
+├── index.ts
+├── users/
+│   ├── index.ts
+│   └── [id].ts
+└── health.ts
+```
+
+Use `files.routes` when the HTTP surface is large enough that a single `fetch.ts` would become a switch-statement graveyard.
+
+---
+
+## `bindings`: supported binding types and what they mean
+
+Bindings are the heart of the runtime contract.
+
+### Binding reference
+
+| 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 |
+
+### Core storage bindings
+
+These are straightforward binding-name maps:
+
+```ts
+bindings: {
+	kv: {
+		CACHE: 'cache-kv-id'
+	},
+	d1: {
+		DB: 'db-id'
+	},
+	r2: {
+		FILES: 'files-bucket'
+	}
+}
+```
+
+### Durable Objects
+
+Durable Object bindings support both shorthand and object form.
+
+Shorthand local form:
+
+```ts
+bindings: {
+	durableObjects: {
+		COUNTER: 'Counter'
+	}
+}
+```
+
+Explicit form:
+
+```ts
+bindings: {
+	durableObjects: {
+		COUNTER: {
+			className: 'Counter'
+		}
+	}
+}
+```
+
+Cross-worker form uses `scriptName` or a `ref()`-produced DO binding.
+
+### Queues
+
+Producers and consumers are separated intentionally.
+
+```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
+
+Service bindings can be written directly or via `ref()`.
+
+Direct form:
+
+```ts
+bindings: {
+	services: {
+		AUTH: {
+			service: 'auth-worker'
+		}
+	}
+}
+```
+
+Current compiler nuance:
+
+- 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'
+
+const auth = ref(() => import('../auth/devflare.config'))
+
+export default defineConfig({
+	name: 'gateway',
+	bindings: {
+		services: {
+			AUTH: auth.worker,
+			ADMIN: auth.worker('AdminEntrypoint')
+		}
+	}
+})
+```
+
+### Browser rendering
+
+Browser rendering is one of the clearest examples of Devflare adding meaningful orchestration on top of a local Workers runtime.
+
+```ts
+bindings: {
+	browser: {
+		binding: 'BROWSER'
+	}
+}
+```
+
+In local dev, Devflare adds browser-shim orchestration so browser workflows can participate in the same system as the rest of your worker app.
+
+### AI and Vectorize
+
+These services are fundamentally remote-oriented.
+
+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.
+
+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.
+
+### `sendEmail`
+
+`sendEmail` is present in the schema and examples, with this current shape:
+
+```ts
+bindings: {
+	sendEmail: {
+		ADMIN_EMAIL: {
+			destinationAddress: 'admin@example.com'
+		}
+	}
+}
+```
+
+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.
+
+---
+
+## `vars`, `secrets`, and generated types
+
+### `vars`
+
+Current Devflare schema models `vars` as:
+
+```ts
+Record<string, string>
+```
+
+That is stricter than the broadest possible Wrangler configuration story.
+
+So in Devflare today:
+
+- 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 }
+```
+
+That means the native configuration is about **declaring expected secret names and whether they are required**, not about storing the secret values themselves.
+
+One subtle but important default: `required` defaults to `true`.
+
+So this:
+
+```ts
+secrets: {
+	API_KEY: {}
+}
+```
+
+means “`API_KEY` is a required runtime secret”, not “optional secret with no requirements”.
+
+### `devflare types`
+
+`devflare types` generates `env.d.ts` and uses config/discovery information to generate:
+
+- 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
+
+Recommended invocation:
+
+```text
+bunx --bun devflare types
+```
+
+After generation, project code can use the global `DevflareEnv` interface and typed `ref()` entrypoints.
+
+---
+
+## 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:
+
+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**
+
+That means omitted nested fields inherit from the base 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
+defu(config.env[environment], config)
+```
+
+That means all of the following are true:
+
+- 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
+
+### Example
+
+```ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig({
+	name: 'app',
+	triggers: {
+		crons: ['0 0 * * *']
+	},
+	vars: {
+		API_URL: 'https://api.example.com',
+		DEBUG: 'false'
+	},
+	bindings: {
+		kv: {
+			CACHE: 'prod-cache-id'
+		}
+	},
+	env: {
+		dev: {
+			triggers: {
+				crons: ['*/5 * * * *']
+			},
+			vars: {
+				DEBUG: 'true'
+			},
+			bindings: {
+				kv: {
+					CACHE: 'dev-cache-id'
+				}
+			}
+		}
+	}
+})
+```
+
+Selecting `dev` gives you a merged result equivalent to:
+
+- `vars.API_URL = 'https://api.example.com'`
+- `vars.DEBUG = 'true'`
+- `bindings.kv.CACHE = 'dev-cache-id'`
+- `triggers.crons = ['*/5 * * * *', '0 0 * * *']`
+
+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.
+
+### 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
+
+### Deployment `routes`
+
+Top-level `routes` are Cloudflare deployment routes.
+
+```ts
+routes: [
+	{
+		pattern: 'example.com/*',
+		zone_name: 'example.com'
+	}
+]
+```
+
+These are about **which hostnames/paths invoke the worker in deployment**.
+
+They are not related to file-based app routing.
+
+### `wsRoutes`
+
+`wsRoutes` are for Devflare local development. They describe how websocket upgrade requests should be forwarded into Durable Objects during dev.
+
+Current shape:
+
+```ts
+wsRoutes: [
+	{
+		pattern: '/chat/api',
+		doNamespace: 'CHAT_ROOM',
+		idParam: 'roomId',
+		forwardPath: '/websocket'
+	}
+]
+```
+
+These are **not** compiled into Wrangler config.
+
+### `assets`
+
+Current native Devflare assets shape is:
+
+```ts
+assets: {
+	directory: './public',
+	binding: 'ASSETS'
+}
+```
+
+The native modeled shape is currently focused on `directory` plus optional binding access.
+
+If you need more advanced asset-related Wrangler fields, use `wrangler.passthrough`.
+
+### `observability`
+
+Current native shape:
+
+```ts
+observability: {
+	enabled: true,
+	head_sampling_rate: 0.1
+}
+```
+
+This compiles directly.
+
+### `limits`
+
+Current native shape only models:
+
+```ts
+limits: {
+	cpu_ms: 50
+}
+```
+
+If you need Wrangler/Cloudflare limit-related fields outside that native shape, use `wrangler.passthrough`.
+
+### `migrations`
+
+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`
+
+Use `wrangler.passthrough` for supported Wrangler fields that Devflare does not model natively.
+
+Example:
+
+```ts
+wrangler: {
+	passthrough: {
+		placement: { mode: 'smart' },
+		workers_dev: true
+	}
+}
+```
+
+The compiler merges these keys directly into the top level of the generated Wrangler config.
+
+This is the correct escape hatch when native Devflare config is intentionally narrower than Wrangler’s full surface.
+
+---
+
+## `build` and `plugins`
+
+Devflare’s schema includes:
+
+- `build`
+- `plugins`
+
+Current `build` shape includes:
+
+- `target`
+- `minify`
+- `sourcemap`
+- `rolldownOptions`
+
+However, it is important to understand the current maturity of these fields:
+
+- 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 auth = ref(() => import('../auth/devflare.config'))
+
+export default defineConfig({
+	name: 'gateway',
+	bindings: {
+		services: {
+			AUTH: auth.worker,
+			ADMIN: auth.worker('AdminEntrypoint')
+		},
+		durableObjects: {
+			AUTH_CACHE: auth.AUTH_CACHE
+		}
+	}
+})
+```
+
+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
+
+---
+
+## Unified `env`
+
+Importing `env` from the main package gives you a **unified environment proxy**.
+
+```ts
+import { env } from 'devflare'
+```
+
+Current resolution order is:
+
+1. request-scoped context
+2. test context
+3. bridge env
+
+That means the same import can work across:
+
+- real request handling
+- test contexts created by `devflare/test`
+- bridge-backed local flows outside the request callback itself
+
+### What `env.dispose()` is for
+
+`env.dispose()` is primarily a **test cleanup hook**.
+
+Typical test pattern:
+
+```ts
+import { beforeAll, afterAll, describe, expect, test } from 'bun:test'
+import { createTestContext, cf } from 'devflare/test'
+import { env } from 'devflare'
+
+beforeAll(() => createTestContext())
+afterAll(() => env.dispose())
+
+describe('worker', () => {
+	test('GET /health', async () => {
+		const response = await cf.worker.get('/health')
+		expect(response.status).toBe(200)
+	})
+})
+```
+
+### 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:
+
+- `createMockTestContext`
+- `withTestContext`
+- mock binding factories such as `createMockKV` and `createMockD1`
+
+### Skip helpers and remote-only tests
+
+Some services are intentionally treated as remote-only or cost-sensitive. Devflare includes skip helpers so tests do not accidentally become surprise invoice generators.
+
+Important current behavior:
+
+- 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.
+
+---
+
+## 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.
+
+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`
+
+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:
+
+- 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`
+
+This subpath exposes:
+
+- `handle`
+- `createDevflarePlatform`
+- `createHandle`
+- `resetPlatform`
+- `resetConfigCache`
+- `isDevflareDev`
+- `getBridgePort`
+
+Use it when SvelteKit should run against a Devflare-aware platform object and dev/runtime bridge.
+
+### 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
+
+---
+
+## `devflare/cloudflare`
+
+`devflare/cloudflare` is the Cloudflare-account helper module.
+
+Its main export is the `account` helper object, which provides:
+
+- 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
+
+The effective account selection order is currently:
+
+1. workspace account
+2. global default account
+3. primary Cloudflare account
+
+### Where account preferences are stored
+
+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
+
+---
+
+## Current caveats and partial areas
+
+This section exists on purpose. It is better to be accurate than accidentally over-promise.
+
+### Strong, well-defined areas
+
+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 shape
+
+This is a strong default layout for many Devflare apps:
+
+```text
+.
+├── devflare.config.ts
+├── env.d.ts
+├── src/
+│   ├── fetch.ts
+│   ├── queue.ts
+│   ├── scheduled.ts
+│   ├── email.ts
+│   ├── transport.ts
+│   ├── routes/
+│   ├── do.counter.ts
+│   ├── ep.admin.ts
+│   └── wf.sync.ts
+└── tests/
+    └── worker.test.ts
+```
+
+You will not always need every file, but this shape matches the Devflare mental model well:
+
+- config is declarative
+- each runtime surface has a natural home
+- tests target named surfaces
+- multi-worker concerns can be expressed explicitly with `ref()`
+
+---
+
+## Guidance for LLMs generating Devflare code
+
+When generating Devflare code, follow these rules.
+
+1. **Prefer `defineConfig()`**
+   - do not invent ad hoc config shapes when a normal Devflare config is appropriate
+
+2. **Prefer separation of concerns**
+   - do not merge fetch, queue, scheduled, email, DOs, routes, and entrypoints into one file unless explicitly asked
+
+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
+
+4. **Use `vars` only for non-secret runtime configuration**
+   - feature flags, public URLs, modes, IDs, log levels, and similar values belong here
+
+5. **Use `secrets` only to declare secret bindings**
+   - actual secret values must come from runtime secret sources, not from committed config
+
+6. **Prefer `ref()` for cross-worker composition**
+   - do not duplicate worker names and DO script names manually if a config reference is available
+
+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
+
+8. **Use imported `env` when it improves ergonomics**
+   - especially in tests and shared helpers
+
+9. **Respect remote-only boundaries**
+   - do not pretend AI or Vectorize is “just local”
+
+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
+
+11. **Do not assume every test helper drains `waitUntil()` the same way**
+	- `cf.worker.fetch()` and queue/scheduled helpers have importantly different behavior
+
+---
+
+## Minimal example
+
+```ts
+// devflare.config.ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig({
+	name: 'hello-worker',
+	files: {
+		fetch: 'src/fetch.ts'
+	}
+})
+```
+
+```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'
+
+beforeAll(() => createTestContext())
+afterAll(() => env.dispose())
+
+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')
+	})
+})
+```
+
+---
+
+## What to remember
+
+If you only remember a few things, remember these:
+
+1. `defineConfig()` is the source of truth
+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`