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

package/README.md

@@ -2,100 +2,52 @@
 
 **Build Cloudflare Workers like an application, not a pile of glue.**
 
-Devflare is a developer-first toolkit for Cloudflare Workers that sits on top of Miniflare and Wrangler-compatible config.
+Devflare is a developer-first toolkit for Cloudflare Workers built on top of Miniflare, Bun, Vite, and Wrangler-compatible configuration.
 
 It gives you:
 
-- a clean file structure
 - typed config with `defineConfig()`
-- easier local development
-- great testing ergonomics
+- convention-first file discovery
+- local orchestration for multi-surface Worker apps
 - first-class Durable Object and multi-worker workflows
-- browser rendering support in local development
-- Vite and SvelteKit integration when your app grows up
+- testing APIs that mirror real handler surfaces
+- browser-rendering support in local development
+- Vite and SvelteKit integration
 
 Miniflare gives you a local runtime.
 
 Devflare turns that runtime into a **coherent development system**.
 
----
-
-## Why Devflare?
-
-Cloudflare development gets messy fast.
-
-You start with one Worker, then suddenly you have:
-
-- HTTP routes
-- queues
-- scheduled jobs
-- email handlers
-- Durable Objects
-- service bindings
-- framework output
-- test setup that no longer resembles runtime
-
-Devflare keeps those responsibilities isolated and composable.
-
-Instead of one giant worker file, you get a structure like this:
-
-```text
-.
-├── devflare.config.ts
-├── env.d.ts
-├── src/
-│   ├── fetch.ts
-│   ├── queue.ts
-│   ├── scheduled.ts
-│   ├── email.ts
-│   ├── routes/
-│   ├── do.counter.ts
-│   ├── ep.admin.ts
-│   └── transport.ts
-└── tests/
-    └── worker.test.ts
-```
-
-That structure is one of Devflare’s biggest strengths: **separate responsibilities, fewer surprises**.
+For the exhaustive package-facing guide, including caveats and deeper config semantics, see [`LLM.md`](./LLM.md).
 
 ---
 
-## What makes it different from plain Miniflare?
+## What Devflare adds
 
-Devflare does not replace Miniflare.
+Devflare does **not** replace Miniflare or Wrangler.
 
-It **extends** it.
+It adds the higher-level workflow around them:
 
-Miniflare gives you local execution.
-Devflare adds the developer workflow around it:
-
-- convention-first file discovery
-- config compilation to Wrangler-compatible output
-- unified test helpers for `fetch`, `queue`, `scheduled`, `email`, and `tail`
-- typed cross-worker references with `ref()`
-- local orchestration for multi-surface Worker apps
-- browser rendering support in local development
+- convention-first file structure
+- config validation and compilation
+- typed cross-worker references via `ref()`
+- unified testing helpers for `fetch`, `queue`, `scheduled`, `email`, and `tail`
+- bridge-backed local development where needed
 - framework-aware integration for Vite and SvelteKit
 
-In short:
-
-> Devflare helps you build Cloudflare systems with clear boundaries and smooth local development.
+The result is a Worker app that stays structured as it grows instead of slowly becoming a single-file boss fight.
 
 ---
 
 ## Install
 
-For a typical project, install Devflare and Wrangler as dev dependencies:
+For the recommended full workflow, install Devflare together with Wrangler, Vite, and the Cloudflare Vite plugin:
 
 ```bash
-bun add -d devflare wrangler
+bun add -d devflare wrangler vite @cloudflare/vite-plugin
 ```
 
-If you are using Vite integration, also install the Vite plugin dependencies:
-
-```bash
-bun add -d vite @cloudflare/vite-plugin
-```
+If you only need the library APIs and not the default Vite-based workflow, you can install fewer packages. The default CLI and diagnostics are built around the Vite + Cloudflare plugin setup.
 
 ---
 
@@ -108,7 +60,10 @@ bun add -d vite @cloudflare/vite-plugin
 import { defineConfig } from 'devflare'
 
 export default defineConfig({
-	name: 'hello-worker'
+	name: 'hello-worker',
+	files: {
+		fetch: 'src/fetch.ts'
+	}
 })
 ```
 
@@ -127,7 +82,7 @@ export default async function fetch(): Promise<Response> {
 bunx --bun devflare types
 ```
 
-This creates `env.d.ts` so your bindings and entrypoints stay typed.
+This generates `env.d.ts` so bindings, secrets, and discovered entrypoints stay typed.
 
 ### 4. Start development
 
@@ -157,540 +112,454 @@ describe('hello-worker', () => {
 
 ---
 
-## The Devflare way to structure an app
-
-Devflare works best when each concern lives in its own file.
+## Package entrypoints
 
-### Common files
+Use subpaths intentionally.
 
-| File | Purpose |
+| Import | Use for |
 |---|---|
-| `src/fetch.ts` | HTTP requests |
-| `src/queue.ts` | queue consumers |
-| `src/scheduled.ts` | cron handlers |
-| `src/email.ts` | email handlers |
-| `src/routes/**` | file-based routing |
-| `do.*.ts` | Durable Objects |
-| `ep.*.ts` | named WorkerEntrypoints |
-| `wf.*.ts` | workflows |
-| `src/transport.ts` | custom serialization across boundaries |
+| `devflare` | main package entrypoint: config helpers, `ref()`, unified `env`, CLI helpers, bridge helpers, decorators, test helpers, `workerName` |
+| `devflare/runtime` | worker-safe middleware/validation/decorator utilities |
+| `devflare/test` | `createTestContext`, `cf.*`, mock helpers, bridge test context, skip helpers |
+| `devflare/vite` | Vite integration |
+| `devflare/sveltekit` | SvelteKit integration |
+| `devflare/cloudflare` | Cloudflare account/auth/usage/limits/preferences helpers |
+| `devflare/decorators` | decorators only |
 
-This is more than style.
+### Important runtime note
 
-It is how Devflare helps you keep local development, testing, and runtime behavior aligned.
+The published `devflare/runtime` subpath is intentionally smaller than the main package. If you want the unified `env` proxy, import it from `devflare`, not `devflare/runtime`.
 
 ---
 
-## Example config
+## Config model
 
-```ts
-import { defineConfig } from 'devflare'
+### `defineConfig()` is the source of truth
 
-export default defineConfig({
-	name: 'my-app',
-	files: {
-		routes: {
-			dir: 'src/routes',
-			prefix: '/api'
-		}
-	},
-	bindings: {
-		kv: {
-			CACHE: 'cache-kv-id'
-		},
-		d1: {
-			DB: 'db-id'
-		},
-		durableObjects: {
-			COUNTER: 'Counter'
-		},
-		queues: {
-			producers: {
-				TASK_QUEUE: 'task-queue'
-			}
-		},
-		browser: {
-			binding: 'BROWSER'
-		}
-	},
-	triggers: {
-		crons: ['0 */6 * * *']
-	}
-})
-```
+Devflare works best when everything flows from `devflare.config.ts`.
 
----
+`defineConfig()` supports:
 
-## Routing without the giant switch statement
+- a plain object
+- a sync function
+- an async function
 
-As your HTTP surface grows, you do not need to keep stuffing logic into `fetch.ts`.
+It also supports a generic parameter for generated entrypoint typing.
 
-Use file-based routing instead:
+### Config file names
 
-```ts
-import { defineConfig } from 'devflare'
+Devflare looks for these config filenames:
 
-export default defineConfig({
-	name: 'my-api',
-	files: {
-		routes: {
-			dir: 'src/routes',
-			prefix: '/api'
-		}
-	}
-})
-```
+- `devflare.config.ts`
+- `devflare.config.mts`
+- `devflare.config.js`
+- `devflare.config.mjs`
 
-This lets your app grow naturally while keeping each endpoint focused and easy to maintain.
+### Top-level config keys
+
+These are the main config keys Devflare understands today.
+
+| Key | What it means |
+|---|---|
+| `name` | Worker name |
+| `accountId` | Cloudflare account ID |
+| `compatibilityDate` | Workers compatibility date |
+| `compatibilityFlags` | Workers compatibility flags |
+| `files` | handler paths and discovery globs |
+| `bindings` | Cloudflare bindings |
+| `triggers` | cron triggers |
+| `vars` | non-secret runtime bindings |
+| `secrets` | secret declarations |
+| `routes` | deployment routes |
+| `wsRoutes` | local websocket-to-DO proxy rules |
+| `assets` | static assets config |
+| `limits` | worker resource limits |
+| `observability` | worker logs / sampling |
+| `migrations` | Durable Object migrations |
+| `build` | build-related metadata/options |
+| `plugins` | plugin extension point |
+| `env` | environment-specific overrides |
+| `wrangler.passthrough` | escape hatch for Wrangler fields not modeled natively |
 
 ---
 
-## Queues without extra glue
+## Env files, `vars`, and `secrets`
 
-Devflare gives queues a natural place in your app:
+This is the most important config nuance to understand.
 
-- produce messages from `fetch` or other handlers
-- consume them in `src/queue.ts`
-- test them with `cf.queue`
+### The short version
 
-```ts
-// devflare.config.ts
-import { defineConfig } from 'devflare'
+- `loadConfig()` itself does **not** do dotenv loading
+- the Devflare CLI runs under **Bun**, and Bun **does** auto-load `.env` files into `process.env`
+- `vars` are plain config values compiled into generated Wrangler config
+- `secrets` declare expected runtime secret bindings, but do **not** store secret values in config
 
-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'
-		}
-	}
-})
-```
+### The layers to keep separate
 
-```ts
-// src/fetch.ts
-import { env } from 'devflare'
+| Thing | Used when | Good for secrets? |
+|---|---|---|
+| `process.env` | config evaluation and build tooling | only if your own process handling is secure |
+| `vars` | compile time and runtime | no |
+| `secrets` | declaration + runtime binding expectations | yes |
+| local runtime secret files like `.dev.vars` | local runtime | yes |
+| Cloudflare secret store | deployed runtime | yes |
 
-export default async function fetch(request: Request): Promise<Response> {
-	const url = new URL(request.url)
+### What this means in practice
 
-	if (url.pathname === '/tasks') {
-		const task = {
-			id: crypto.randomUUID(),
-			type: 'resize-image'
-		}
+If you run the CLI normally, Bun may populate `process.env` from `.env` before `devflare.config.ts` runs.
 
-		await env.TASK_QUEUE.send(task)
-		return Response.json({ queued: true, task })
-	}
+That means:
 
-	return new Response('Not found', { status: 404 })
-}
-```
+- **CLI under Bun**: `.env` values are often available via `process.env`
+- **programmatic `loadConfig()` elsewhere**: do not assume env files were loaded unless your process already loaded them
 
-```ts
-// src/queue.ts
-import type { MessageBatch } from '@cloudflare/workers-types'
+### `vars` vs `secrets`
 
-type Task = {
-	id: string
-	type: string
-}
+Use `vars` for:
 
-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()
-		}
-	}
-}
-```
+- public base URLs
+- feature flags
+- log levels
+- non-secret IDs and modes
 
----
+Use `secrets` for:
 
-## Email
+- API keys
+- tokens
+- passwords
+- signing secrets
 
-Devflare supports two sides of email: **receiving** incoming messages and **sending** outgoing ones.
+Current Devflare behavior matters here:
 
-### Receiving email
+- `vars` are compiled into generated configuration
+- `secrets` declare names and `required` status, but their values must come from a runtime secret source
 
-Export an `email` function from `src/email.ts`. Devflare wires it as the worker's incoming email handler automatically.
+### Example
 
 ```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 for later inspection
-	await env.EMAIL_LOG.put(
-		`email:${id}`,
-		JSON.stringify({
-			from: message.from,
-			to: message.to,
-			receivedAt: new Date().toISOString()
-		})
-	)
-
-	// Forward to an admin address
-	await message.forward(env.FORWARD_ADDRESS)
-}
+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 }
+	}
+}))
 ```
 
-You can also auto-reply with `message.reply(replyMessage)` — useful for sending confirmation receipts.
+---
 
-### Sending email
+## Environment overrides via `config.env`
 
-To send outgoing email, declare a `sendEmail` binding. Each key becomes an `env` property of type `SendEmail`.
+`config.env` is a **Devflare merge layer**, not just a raw mirror of Wrangler environment blocks.
 
-The value is a config object that accepts an optional `destinationAddress`. When set, every email sent through that binding goes to that address. When omitted (`{}`), you specify the recipient at send time.
+When you select an environment with `compileConfig(config, 'name')` or CLI `--env name`, Devflare:
 
-```ts
-// devflare.config.ts
-import { defineConfig } from 'devflare'
+1. starts from the base config
+2. merges `config.env[name]` into it
+3. compiles the resolved result
 
-export default defineConfig({
-	name: 'support-mail',
-	bindings: {
-		kv: {
-			EMAIL_LOG: 'email-log-kv-id'
-		},
-		sendEmail: {
-			// Locked to a specific recipient — every send goes to admin
-			ADMIN_EMAIL: { destinationAddress: 'admin@example.com' },
+That means nested values can inherit cleanly from the base config.
 
-			// Open — you choose the recipient per message
-			EMAIL: {}
-		}
-	}
-})
-```
+This is one of the biggest behavioral differences from thinking in raw Wrangler-only terms.
 
-This generates two typed bindings on `env`:
+---
 
-- `env.ADMIN_EMAIL` — always delivers to `admin@example.com`
-- `env.EMAIL` — you provide the destination when composing the message
+## File surfaces and routing
 
-### Testing email
+Devflare works best when each concern lives in its own file.
 
-Import the `email` helper from `devflare/test` to send test messages to your running dev server:
+| File / pattern | Purpose |
+|---|---|
+| `src/fetch.ts` | HTTP requests |
+| `src/queue.ts` | queue consumers |
+| `src/scheduled.ts` | cron handlers |
+| `src/email.ts` | incoming email handlers |
+| `src/routes/**` | file-based routing |
+| `do.*.ts` | Durable Objects |
+| `ep.*.ts` | WorkerEntrypoints |
+| `wf.*.ts` | workflows |
+| `src/transport.ts` | custom serialization across boundaries |
 
-```ts
-import { email } from 'devflare/test'
+### Do not confuse these three
 
-const response = await email.send({
-	from: 'sender@example.com',
-	to: 'recipient@example.com',
-	subject: 'Hello from devflare',
-	body: 'This is a test email.'
-})
+| Key | Meaning |
+|---|---|
+| `files.routes` | file-based HTTP routing inside your app |
+| top-level `routes` | Cloudflare deployment routing |
+| `wsRoutes` | local websocket proxying into Durable Objects during dev |
 
-expect(response.ok).toBe(true)
-```
+Use `files.routes` when the HTTP surface is growing beyond a small `fetch.ts` handler.
 
 ---
 
-## Durable Objects and multi-worker setups
+## Bindings and multi-worker systems
 
-Devflare makes advanced Worker architecture feel much less dramatic.
+Devflare natively models these binding categories:
 
-### Local Durable Objects
+- KV
+- D1
+- R2
+- Durable Objects
+- Queues
+- Services
+- AI
+- Vectorize
+- Hyperdrive
+- Browser Rendering
+- Analytics Engine
+- `sendEmail`
+
+### Core examples
 
 ```ts
 bindings: {
+	kv: {
+		CACHE: 'cache-kv-id'
+	},
+	d1: {
+		DB: 'db-id'
+	},
 	durableObjects: {
 		COUNTER: 'Counter'
+	},
+	queues: {
+		producers: {
+			TASK_QUEUE: 'task-queue'
+		}
 	}
 }
 ```
 
-Place the class in a `do.*.ts` file and Devflare handles the discovery flow.
-
-### Write a Durable Object and call it from `fetch`
+### Cross-worker references with `ref()`
 
-This is the most common pattern:
+Use `ref()` instead of hardcoding worker names and DO script names.
 
 ```ts
-// devflare.config.ts
-import { defineConfig } from 'devflare'
+import { defineConfig, ref } from 'devflare'
+
+const auth = ref(() => import('../auth/devflare.config'))
 
 export default defineConfig({
-	name: 'sessions-app',
+	name: 'gateway',
 	bindings: {
+		services: {
+			AUTH: auth.worker,
+			ADMIN: auth.worker('AdminEntrypoint')
+		},
 		durableObjects: {
-			SESSION: 'SessionStore'
+			AUTH_CACHE: auth.AUTH_CACHE
 		}
 	}
 })
 ```
 
-```ts
-// src/do.session.ts
-import { DurableObject } from 'cloudflare:workers'
+This keeps multi-worker systems typed and centralized.
 
-export class SessionStore extends DurableObject<DevflareEnv> {
-	private data = new Map<string, string>()
+---
 
-	getValue(key: string): string | null {
-		return this.data.get(key) ?? null
-	}
+## Testing and remote testing
 
-	setValue(key: string, value: string): void {
-		this.data.set(key, value)
-	}
+### `devflare/test`
 
-	clearAll(): void {
-		this.data.clear()
-	}
-}
-```
+The main testing entrypoint exports:
 
-```ts
-// src/fetch.ts
-import { env } from 'devflare'
+- `createTestContext`
+- `cf`
+- `email`
+- `queue`
+- `scheduled`
+- `worker`
+- `tail`
+- mock helpers like `createMockKV`, `createMockD1`, `createMockR2`, `createMockQueue`
+- bridge test helpers
+- skip helpers like `shouldSkip`
 
-export default async function fetch(request: Request): Promise<Response> {
-	const url = new URL(request.url)
-	const sessionId = url.searchParams.get('session') ?? 'default'
+### Integration-style local tests
 
-	const id = env.SESSION.idFromName(sessionId)
-	const session = env.SESSION.get(id)
+Use `createTestContext()` when you want a real local environment backed by Devflare’s orchestration.
 
-	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 })
-	}
+`cf` gives you a unified test surface:
 
-	if (url.pathname === '/get') {
-		const key = url.searchParams.get('key') ?? 'name'
-		const value = await session.getValue(key)
-		return Response.json({ value })
-	}
+- `cf.worker`
+- `cf.queue`
+- `cf.scheduled`
+- `cf.email`
+- `cf.tail`
 
-	if (url.pathname === '/clear') {
-		await session.clearAll()
-		return Response.json({ ok: true })
-	}
+### Remote-only services
 
-	return new Response('Not found', { status: 404 })
-}
+AI and Vectorize are remote-only in practice. Devflare does not pretend they are fully local equivalents of KV or D1.
+
+Use remote mode when you want to run tests against real Cloudflare infrastructure:
+
+```bash
+bunx --bun devflare remote status
+bunx --bun devflare remote enable 30
+bunx --bun devflare remote disable
 ```
 
-The flow is simple:
+Remote mode can also be enabled with:
 
-1. bind the Durable Object in `devflare.config.ts`
-2. implement the class in a `do.*.ts` file
-3. get a stub with `env.SESSION.get(env.SESSION.idFromName(...))`
-4. call your methods from `fetch`
+```text
+DEVFLARE_REMOTE=1
+```
 
-### Cross-worker references
+Remote mode is stored locally when enabled through the CLI and is intended to be temporary because it may incur real costs.
 
-Use `ref()` when one worker depends on another worker or its entrypoints/DO bindings:
+### Skip helpers
 
-```ts
-import { defineConfig, ref } from 'devflare'
+Use `shouldSkip` to gate cost-sensitive or remote-only tests:
 
-const authWorker = ref(() => import('../auth/devflare.config'))
+```ts
+import { shouldSkip } from 'devflare/test'
 
-export default defineConfig({
-	name: 'gateway',
-	bindings: {
-		services: {
-			AUTH: authWorker.worker
-		}
-	}
+describe.skipIf(await shouldSkip.ai)('AI tests', () => {
+	// ...
 })
 ```
 
-Typed relationships, less duplication, fewer paper cuts.
+The skip helpers check remote mode, authentication, account availability, and usage limits.
 
 ---
 
-## Transport for custom types, without manual serialization
-
-Sometimes your Worker or Durable Object wants to return a real class instance, not just plain JSON.
-
-That is what `src/transport.ts` is for.
+## CLI
 
-You define how to encode and decode a custom type **once**, and Devflare applies it for you across supported boundaries.
+The Devflare CLI covers the full development loop.
 
-```ts
-// src/DoubleableNumber.ts
-export class DoubleableNumber {
-	value: number
+| Command | What it does |
+|---|---|
+| `devflare init` | scaffold a project |
+| `devflare dev` | start the unified local development server |
+| `devflare build` | resolve config, write `wrangler.jsonc`, run `vite build` |
+| `devflare deploy` | build and deploy with Wrangler |
+| `devflare types` | generate `env.d.ts` |
+| `devflare doctor` | check project configuration and common workflow prerequisites |
+| `devflare account` | inspect accounts, resources, usage, and limits |
+| `devflare ai` | show Workers AI model pricing info |
+| `devflare remote` | manage remote test mode |
 
-	constructor(n: number) {
-		this.value = n
-	}
+### Useful CLI notes
 
-	get double() {
-		return this.value * 2
-	}
-}
-```
+- `build` and `deploy` accept `--env <name>` to select `config.env[name]`
+- `doctor` assumes the default Vite-based Devflare workflow and checks for config, package metadata, Vite config, TypeScript config, and generated Wrangler output
+- `account` includes subcommands like `workers`, `kv`, `d1`, `r2`, `vectorize`, `limits`, `usage`, `global`, and `workspace`
 
-```ts
-// src/transport.ts
-import { DoubleableNumber } from './DoubleableNumber'
+Recommended invocation style:
 
-export const transport = {
-	DoubleableNumber: {
-		encode: (v: unknown) => v instanceof DoubleableNumber && v.value,
-		decode: (v: number) => new DoubleableNumber(v)
-	}
-}
+```bash
+bunx --bun devflare dev
+bunx --bun devflare types
+bunx --bun devflare build
 ```
 
-```ts
-// src/do.counter.ts
-import { DoubleableNumber } from './DoubleableNumber'
+---
 
-export class Counter {
-	private count = 0
+## `devflare/cloudflare`
 
-	increment(n: number = 1): DoubleableNumber {
-		this.count += n
-		return new DoubleableNumber(this.count)
-	}
-}
-```
+`devflare/cloudflare` exposes the account helper API for Cloudflare-aware tooling.
 
 ```ts
-// tests/counter.test.ts
-import { beforeAll, afterAll, expect, test } from 'bun:test'
-import { createTestContext } from 'devflare/test'
-import { env } from 'devflare'
-import { DoubleableNumber } from '../src/DoubleableNumber'
-
-beforeAll(() => createTestContext())
-afterAll(() => env.dispose())
+import { account } from 'devflare/cloudflare'
 
-test('transport restores my custom type', 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)
-})
+const isLoggedIn = await account.isAuthenticated()
+const primary = await account.getPrimaryAccount()
 ```
 
-The important bit: **you do not manually encode before returning or manually decode after receiving**.
+It includes helpers for:
 
-Devflare handles the transport step so the developer works with the real type again.
+- authentication and Wrangler auth inspection
+- listing Workers, KV, D1, R2, Vectorize, and AI resources
+- service status
+- usage tracking
+- limit enforcement
+- test guardrails
+- global and workspace account preference management
 
----
+### Account preference storage
 
-## Testing that feels like the real app
+Current account preference behavior is:
 
-Devflare ships a clean testing API through `devflare/test`.
+- workspace account: stored in nearest `package.json` as `devflare.accountId`
+- global default: cached locally in `~/.devflare/preferences.json` and synced via Devflare-managed Cloudflare KV when possible
 
-### Integration-style tests
+This matters if your repo uses multiple Cloudflare accounts or you want deterministic test behavior across machines.
 
-Use `createTestContext()` for real local behavior backed by Devflare’s Miniflare orchestration.
+---
 
-### Mock-style tests
+## Generated artifacts
 
-Use:
+Treat these as generated output, not source of truth:
 
-- `createMockTestContext()`
-- `withTestContext()`
-- `createMockKV()`
-- `createMockD1()`
-- `createMockR2()`
-- `createMockQueue()`
+- `.devflare/`
+- `env.d.ts`
+- generated `wrangler.jsonc`
 
-### Unified handler helpers
+The source of truth is still:
 
-You can test each surface directly:
-
-- `cf.worker`
-- `cf.queue`
-- `cf.scheduled`
-- `cf.email`
-- `cf.tail`
-
-That consistency is a huge quality-of-life improvement.
+- `devflare.config.ts`
+- your source files under `src/`
+- your test files
 
 ---
 
-## Browser rendering, locally
-
-Browser rendering is a perfect example of Devflare adding capability above raw Miniflare.
+## Caveats and feature maturity
 
-With Devflare, browser rendering becomes part of the same local development story as the rest of your Worker bindings.
+Devflare has a broad surface area, but not every feature is equally mature.
 
-That means you can build richer Worker applications without stitching together a separate custom local browser setup by hand.
+### Strong core areas
 
----
+- typed config
+- config loading and compilation
+- file conventions
+- `vars`
+- Durable Objects
+- queues
+- `ref()`
+- testing ergonomics
+- unified `env`
+- Vite/SvelteKit integration surfaces
 
-## Framework support
+### Important caveats
 
-### `devflare/vite`
+1. **`vars` are string-only in current Devflare config**
+   - serialize more complex values yourself if needed
 
-Use this when you want:
+2. **`secrets` are declaration-oriented**
+   - secret values are not stored in config and are not compiled into generated Wrangler config
 
-- config compilation during dev and build
-- worker-aware transforms
-- auxiliary Durable Object worker generation
-- websocket-aware local development
+3. **`sendEmail` is lighter than core bindings**
+   - it exists in the schema and examples
+   - but it is not as fully wired as KV/D1/R2/DO/queues/services
 
-### `devflare/sveltekit`
+4. **named service entrypoints need verification in generated output**
+   - `ref().worker('Entrypoint')` is modeled at the Devflare layer
+   - validate deployment output if named entrypoint wiring is critical to your app
 
-Use this when your project needs:
+5. **workflows, `build`, and `plugins` are lighter than the most central surfaces**
+   - they exist and matter
+   - but they are not as battle-hardened as the fetch/queue/DO/test path
 
-- a Devflare-aware platform layer
-- smooth SvelteKit + Worker binding integration
-- local development that still behaves like a coherent Worker system
+6. **use `wrangler.passthrough` for unsupported native fields**
+   - if Wrangler supports something Devflare does not model yet, passthrough is the supported escape hatch
 
 ---
 
-## CLI
-
-Devflare includes a CLI for the full development loop.
+## Deprecations and preferred replacements
 
-```text
-devflare init
-devflare dev
-devflare build
-devflare deploy
-devflare types
-devflare doctor
-devflare remote
-```
+Some older APIs still exist for compatibility.
 
-Most projects will mainly use:
-
-```bash
-bunx --bun devflare dev
-bunx --bun devflare types
-bunx --bun devflare build
-```
+| Older API | Prefer instead |
+|---|---|
+| `createMultiWorkerContext()` | `createTestContext()` |
+| `createEntrypointScript()` | normal worker/entrypoint file patterns |
+| `resolveRef()` | `ref()` |
+| `serviceBinding()` | `ref().worker` or `ref().worker('Entrypoint')` |
+| `isRemoteModeEnabled()` | `shouldSkip.*` for tests and `devflare remote ...` for mode management |
 
 ---
 
@@ -702,20 +571,19 @@ bunx --bun devflare build
 ├── env.d.ts
 ├── src/
 │   ├── fetch.ts
-│   ├── routes/
 │   ├── queue.ts
 │   ├── scheduled.ts
 │   ├── email.ts
+│   ├── routes/
 │   ├── do.counter.ts
 │   ├── ep.admin.ts
+│   ├── wf.sync.ts
 │   └── transport.ts
 └── tests/
     └── worker.test.ts
 ```
 
-Not every project needs every file.
-
-But if you follow this shape, Devflare will feel very natural.
+Not every project needs every file, but this layout matches the Devflare mental model well.
 
 ---