devflare 1.0.0-next.19 → 1.0.0-next.20

package/README.md

@@ -1,957 +1,375 @@
-# Devflare
-
-**Build Cloudflare Workers like an application, not a pile of glue.**
-
-Devflare is a developer-first layer on top of Cloudflare Workers, Miniflare, Bun, Vite, and Wrangler-compatible config.
-
-It gives you:
-
-- typed config with `defineConfig()`
-- convention-friendly worker surfaces
-- local orchestration for multi-surface Worker apps
-- first-class Durable Object and multi-worker workflows
-- test helpers that mirror real handler surfaces
-- worker-safe runtime helpers under `devflare/runtime`
-- optional Vite and SvelteKit integration when your package actually uses them
-
-Miniflare gives you a local runtime.
-
-Devflare turns that runtime into a **coherent development system**.
-
-For the deeper public contract, caveats, and current feature boundaries, see [`LLM.md`](./LLM.md).
-
----
-
-## Monorepo contributor workflow
-
-When you are working on `packages/devflare` inside this monorepo, use the repo-root Turbo scripts instead of assembling ad-hoc commands by hand:
-
-- `bun run devflare:dev`
-- `bun run devflare:test:watch`
-- `bun run devflare:build`
-- `bun run devflare:typecheck`
-- `bun run devflare:test`
-- `bun run devflare:types`
-- `bun run devflare:check`
-- `bun run devflare:ci`
-
-These scripts intentionally keep the default shared lane focused on the parts of the workspace that are currently stable in local development and CI. In particular, the shared test lane excludes `@devflare/case5-multi-worker`, and the shared check lane stays centered on `apps/documentation` because `cases/case18` still expects Cloudflare-backed resource resolution outside the default contributor workflow.
-
----
-
-## Install
-
-For a worker-only project, the smallest install is just Devflare:
-
-```bash
-bun add -d devflare vite @cloudflare/vite-plugin
-```
-A local `vite.config.*` opts that package into Vite-backed flows. Without one, Devflare stays in worker-only mode.
-
----
-
-## Quick start
-
-### 1. Create a config
-
-```ts
-// devflare.config.ts
-import { defineConfig } from 'devflare/config'
-
-export default defineConfig({
-	name: 'hello-worker',
-	compatibilityDate: '2026-03-17',
-	files: {
-		fetch: 'src/fetch.ts'
-	}
-})
-```
-
-Use `devflare/config` for config files so Bun only loads the lightweight config helpers instead of the full Node-side Devflare barrel.
-
-### 2. Add a fetch handler
-
-```ts
-// src/fetch.ts
-import type { FetchEvent } from 'devflare/runtime'
-
-export async function fetch({ url }: FetchEvent): Promise<Response> {
-	return new Response(`Hello from Devflare: ${url.pathname}`)
-}
-```
-
-### 3. Generate types
-
-```bash
-bunx --bun devflare types
-```
-
-### 4. Start development
-
-```bash
-bunx --bun devflare dev
-```
-
-### 5. Add a test
-
-```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')
-	})
-})
-```
-
----
-
-## Package entrypoints
-
-Use subpaths intentionally.
-
-| Import | Use for |
-|---|---|
-| `devflare` | main package entrypoint: `defineConfig`, `defineWorker`, `ref()`, the unified `env`/`ctx`/`event`/`locals` proxies, `sequence`, `defineFetchHandler`, decorators |
-| `devflare/config` | lightweight config-only entry for `devflare.config.ts` files (Bun loads only the config helpers, not the full Node-side barrel) |
-| `devflare/runtime` | worker-safe runtime helpers: strict `env`, `ctx`, `event`, `locals`, event types/getters, middleware helpers |
-| `devflare/test` | `createTestContext`, `cf.*`, mock helpers (`createMockKV`/`createMockD1`/`createMockR2`/`createMockEnv`/`createMockTestContext`/`withTestContext`) |
-| `devflare/vite` | Vite integration |
-| `devflare/sveltekit` | SvelteKit integration |
-| `devflare/cloudflare` | Cloudflare account/auth/usage/limits/preferences helpers |
-| `devflare/decorators` | decorators only |
-
-Internal bridge and transform helpers are intentionally not re-exported from bare `'devflare'`. If you previously imported them from the main entry, switch to the matching subpath — see "Public API surface and migration notes" below.
-
-### Runtime import rule of thumb
-
-- use `import { env } from 'devflare/runtime'` for **strict request-scoped runtime access**
-- use `import { env } from 'devflare'` when you want the **unified proxy** that can fall back to test or bridge context outside a live request
-
-The reduced worker-safe main entry for `devflare` is selected through the package `browser` export condition. `devflare/runtime` is the direct worker-safe runtime subpath.
-
----
-
-## Event-first handlers
-
-Fresh Devflare code should be event-first:
-
-- `fetch(event: FetchEvent)`
-- `queue(event: QueueEvent)`
-- `scheduled(event: ScheduledEvent)`
-- `email(event: EmailEvent)`
-- Durable Object lifecycle handlers with their matching event types
-
-Devflare stores the active event in `AsyncLocalStorage`, and Devflare-managed entrypoints establish that context for you before your handler runs. That includes generated worker wrappers, the local dev server, and `createTestContext()` helper surfaces.
-
-Helpers deeper in the same call trail can recover the current surface with getters like:
-
-- `getFetchEvent()`
-- `getQueueEvent()`
-- `getScheduledEvent()`
-- `getEmailEvent()`
-- `getDurableObjectFetchEvent()`
-
-Every getter also exposes `.safe()`, which returns `null` instead of throwing.
-
-In normal app code you should not need to call `runWithEventContext()` or `runWithContext()` yourself.
-
----
-
-## HTTP structure that matches the runtime today
-
-The built-in HTTP story now has **two cooperating layers**:
-
-1. an optional global fetch module at `src/fetch.ts`
-2. a built-in file router rooted at `src/routes/**`
-
-Use `src/fetch.ts` for request-wide middleware and whole-app HTTP concerns.
-Use `src/routes/**` for leaf handlers.
-
-### Request-wide middleware
-
-Use `sequence(...)` with a single exported primary fetch entry:
-
-```ts
-import { sequence } from 'devflare/runtime'
-import type { FetchEvent, ResolveFetch } from 'devflare/runtime'
-
-async function corsHandle(event: FetchEvent, resolve: ResolveFetch): Promise<Response> {
-	if (event.request.method === 'OPTIONS') {
-		return new Response(null, {
-			headers: {
-				'Access-Control-Allow-Origin': '*',
-				'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
-				'Access-Control-Allow-Headers': 'Content-Type, Authorization'
-			}
-		})
-	}
-
-	const response = await resolve(event)
-	const next = new Response(response.body, response)
-	next.headers.set('Access-Control-Allow-Origin', '*')
-	return next
-}
-
-async function appFetch({ url }: FetchEvent): Promise<Response> {
-	return Response.json({ path: url.pathname })
-}
-
-export const handle = sequence(corsHandle, appFetch)
-```
-
-Important rules:
-
-- `fetch` and `handle` are two names for the same primary HTTP entry
-- export **one** of them from a given module, never both
-- if `src/fetch.ts` exports same-module `GET()` / `POST()` handlers, those run before file routes for matching methods
-- for route-tree apps, keep `src/fetch.ts` focused on request-wide middleware and put leaf handlers in `src/routes/**`
-
-### File router
-
-`src/routes/**` is now a real built-in router.
-
-By default, Devflare discovers `src/routes/**` automatically when that directory exists.
-
-You can customize or disable it with `files.routes`:
-
-```ts
-export default {
-	name: 'api-worker',
-	files: {
-		fetch: 'src/fetch.ts',
-		routes: {
-			dir: 'src/routes',
-			prefix: '/api'
-		}
-	}
-}
-```
-
-- `files.routes.dir` changes the route root
-- `files.routes.prefix` mounts the route tree under a fixed prefix
-- `files.routes: false` disables automatic route discovery entirely
-
-Route conventions:
-
-- `src/routes/index.ts` → `/`
-- `src/routes/users/index.ts` → `/users`
-- `src/routes/users/[id].ts` → `/users/:id`
-- `src/routes/blog/[...slug].ts` → `/blog/*` with `params.slug = 'a/b'`
-- `src/routes/docs/[[...slug]].ts` → optional catch-all, including `/docs`
-- files or directories that start with `_` are ignored so you can keep route-local helpers nearby
-
-Route module exports use the same fetch-module rules as `src/fetch.ts`:
-
-- `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `OPTIONS`, `ALL`
-- route-local `fetch(event)` / `handle(event, resolve)` if you want per-route middleware
-- `HEAD` falls back to `GET` when no explicit `HEAD` export exists
-
-Route params are available on `event.params`.
-
-```ts
-// src/routes/users/[id].ts
-export async function GET(event): Promise<Response> {
-	return Response.json({ id: event.params.id })
-}
-```
-
-### Resolution order
-
-When a request comes in, Devflare resolves HTTP in this order:
-
-1. create the initial fetch event and populate `event.params` from the matched file route, if any
-2. run the primary `src/fetch.ts` `fetch` / `handle` export if present
-3. inside `resolve(event)`, try same-module method handlers from `src/fetch.ts`
-4. if no same-module handler matched, dispatch to the matched route module from `src/routes/**`
-5. return `404 Not Found` if nothing matched
-
-That means global middleware can see `event.params`, while route files remain the main leaf-handler story.
-
-For example:
-
-```ts
-// src/fetch.ts
-import { sequence } from 'devflare/runtime'
-
-export const handle = sequence(async (event, resolve) => {
-	const response = await resolve(event)
-	const next = new Response(response.body, response)
-	next.headers.set('x-user-id', event.params.id ?? 'none')
-	return next
-})
-```
-
----
-
-## Config highlights
-
-Devflare looks for these config filenames:
-
-- `devflare.config.ts`
-- `devflare.config.mts`
-- `devflare.config.js`
-- `devflare.config.mjs`
-
-The most important top-level keys are:
-
-- `name`
-- `accountId`
-- `compatibilityDate`
-- `compatibilityFlags`
-- `previews`
-- `files`
-- `bindings`
-- `triggers`
-- `vars`
-- `secrets`
-- `routes`
-- `wsRoutes`
-- `assets`
-- `limits`
-- `observability`
-- `migrations`
-- `rolldown`
-- `vite`
-- `env`
-- `wrangler.passthrough`
-
-### `vars` vs `secrets`
-
-Keep these separate:
-
-- `vars` are **string-valued config bindings** that compile into generated Wrangler config
-- `secrets` are **declarations of expected runtime secret bindings**
-
-`loadConfig()` loads the nearest workspace-root `.env` before evaluating `devflare.config.*`.
-
-When Devflare finds an ancestor `package.json` with `workspaces`, it uses that directory's `.env` file as the shared config-time source for nested packages. If no workspace root is found, it falls back to the nearest ancestor `.env`. Explicit process env values still win over `.env` entries.
-
-Important boundary:
-
-- `.env` is treated as a config/build-time input for `devflare.config.*` evaluation
-- Devflare does **not** currently provide first-class semantics for `.env.dev` or `.env.<name>`
-- Devflare does **not** currently provide a first-class `.dev.vars*` loader for worker-only dev mode or `createTestContext()`
-- example files like `.env.example` and `.dev.vars.example` are a team convention, not a Devflare feature
-
-Practical convention:
-
-- use `.env.example` for config-time/build-time variables read from `process.env`
-- use `.dev.vars.example` only if your project intentionally relies on upstream `.dev.vars` local-runtime workflows
-- keep non-secret infrastructure names such as R2 bucket names and D1 database names in `devflare.config.*`, not in `secrets` or ad-hoc CI env vars
-
-### `config.env`
-
-`config.env` is a Devflare merge layer, not a raw Wrangler env mirror.
-
-When you select `--env name`, Devflare merges `config.env[name]` into the base config before compiling.
-
-### D1 by name and resolved config reuse
-
-`bindings.d1` accepts three shapes:
-
-- `'database-name'`
-- `{ id: 'database-id' }`
-- `{ name: 'database-name' }`
-
-String shorthand is the stable-name form, so `'database-name'` is equivalent to `{ name: 'database-name' }`.
-
-Use string shorthand or `{ name }` when you want `devflare.config.*` to stay the source of truth for stable D1 naming.
-
-- local dev and tests normalize string and `{ name }` bindings into a stable local identifier, so you do **not** need Cloudflare auth just to run locally
-- `build`, `deploy`, `devflare/vite`, and `devflare config print` resolve string and `{ name }` bindings into a real Cloudflare D1 database id before they emit Wrangler-facing config
-- `compileConfig()` can only emit Wrangler `d1_databases` from concrete ids, so Node-side automation should call `loadResolvedConfig()` or `resolveConfigResources()` first
-
-That means stable names stay in config, while opaque Cloudflare ids are resolved only for the flows that actually need them.
-
-If you want to inspect or reuse those resolved values in automation, use either:
-
-- `bunx --bun devflare config print --json`
-- `bunx --bun devflare config print --json --format wrangler`
-- `loadResolvedConfig()` from Node-side tooling
-
-```ts
-import { loadResolvedConfig } from 'devflare'
-
-const config = await loadResolvedConfig({
-	cwd: process.cwd(),
-	environment: 'production'
-})
-
-console.log(config.bindings?.r2?.ASSETS)
-console.log(config.bindings?.d1?.DB)
-```
-
-If you need Cloudflare account/resource data while computing config, use an async config with `devflare/cloudflare` helpers:
-
-```ts
-import { defineConfig } from 'devflare/config'
-import { account } from 'devflare/cloudflare'
-
-export default defineConfig(async () => {
-	const primary = await account.getPrimaryAccount()
-	const buckets = await account.r2(primary.id)
-
-	if (!buckets.some((bucket) => bucket.name === 'app-assets')) {
-		throw new Error('Missing R2 bucket "app-assets" in the selected Cloudflare account')
-	}
-
-	return {
-		accountId: primary.id,
-		name: 'app-worker',
-		compatibilityDate: '2026-03-17',
-		bindings: {
-			d1: {
-				DB: { name: 'app-db' }
-			},
-			r2: {
-				ASSETS: 'app-assets'
-			}
-		}
-	}
-})
-```
-
-### Native config vs Wrangler coverage
-
-Devflare natively models the Worker config it actively composes around:
-
-- handler/file surfaces
-- core bindings and service composition
-- routes, assets, migrations, observability, and limits
-- Vite and Rolldown metadata
-- environment overlays
-
-It does **not** try to re-model every Wrangler key as a first-class Devflare schema field.
-For unsupported Wrangler options, use `wrangler.passthrough`.
-
-Current compile order is:
-
-1. Devflare compiles native config into Wrangler-compatible output
-2. `wrangler.passthrough` is shallow-merged on top
-3. if the same key exists in both places, the passthrough value wins
-
-```ts
-export default defineConfig({
-	name: 'advanced-worker',
-	files: {
-		fetch: 'src/fetch.ts'
-	},
-	wrangler: {
-		passthrough: {
-			placement: {
-				mode: 'smart'
-			}
-		}
-	}
-})
-```
-
-Special case: `wrangler.passthrough.main` tells higher-level `build`, `deploy`, and `devflare/vite` flows to stop generating a composed `.devflare/worker-entrypoints/main.ts` and use your explicit main entry instead.
-
----
-
-## Bindings
-
-Devflare natively models:
-
-- KV
-- D1
-- R2
-- Durable Objects
-- Queues
-- Services
-- AI
-- Vectorize
-- Hyperdrive
-- Browser Rendering
-- Analytics Engine
-- `sendEmail`
-
-### Caveats worth knowing up front
-
-- KV, D1, R2, Durable Objects, queues, and the core test/runtime flow are the strongest surfaces
-- AI and Vectorize are remote-oriented bindings
-- named service entrypoints are modeled at the Devflare layer, but validate generated deployment output if they are critical to your app
-- browser bindings use a named-map authoring shape such as `browser: { BROWSER: 'browser' }`, but current compile/deploy flows allow exactly one browser binding because Wrangler only supports one
-- `sendEmail` is modeled through config compilation, generated env types, and local runtime/test flows
-- R2 bindings are real in local dev/test/runtime flows, but Devflare does **not** publish a stable browser-facing local bucket URL contract; browser-visible local asset flows should go through your Worker routes
-
-For R2 delivery strategy guidance, use the `R2 uploads & delivery` page in the documentation site.
-
-For D1 and Hyperdrive, prefer stable config names when you can:
-
-```ts
-export default {
-	bindings: {
-		d1: {
-			DB: { name: 'app-db' },
-			AUDIT: { id: 'existing-d1-id' }
-		},
-		hyperdrive: {
-			DB: 'app-postgres',
-				ANALYTICS_DB: { id: 'existing-hyperdrive-id' }
-		},
-		r2: {
-			ASSETS: 'app-assets'
-		}
-	}
-}
-```
-
-Use `.env*` and `secrets` for values that are actually secret or genuinely process-specific. Do **not** move stable bucket/database/Hyperdrive names into env vars just to make other tooling happy.
-
----
-
-## Dev, build, deploy, Vite, and Rolldown
-
-Devflare is worker-only first.
-
-### Mode selection
-
-- a local `vite.config.*` or a non-empty `config.vite` opts the current package into **Vite-backed** flows
-- Vite-related dependencies without either a local config or inline `config.vite` do **not** switch the package into Vite mode
-- without a local `vite.config.*` and without inline `config.vite`, `dev`, `build`, and `deploy` stay in **worker-only** mode
-
-### Mental model
-
-Vite and Rolldown both matter here, but they do different jobs:
-
-- **Vite** is the optional outer app/framework host. Devflare enters Vite-backed mode when the current package has a local `vite.config.*` or a non-empty `config.vite`, and then Devflare merges that config into the actual Vite config it runs.
-- **Rolldown** is the inner builder Devflare uses when Devflare itself needs to transform Worker code into runnable bundles. Today that covers worker-only main-worker bundles and Durable Object bundles.
-
-Short version:
-
-- no local `vite.config.*` and no inline `config.vite` → no Vite process; Devflare stays worker-only
-- `.svelte` imported by a worker-only fetch/route/queue/scheduled/email surface or by a Durable Object → that compilation belongs to the Rolldown plugin pipeline, not to the main Vite app build
-- generated `.devflare/worker-entrypoints/main.ts` is separate Devflare glue that composes worker surfaces when needed
-
-### Current behavior that matters
-
-- worker-only `dev` is a real first-class path
-- `build` and `deploy` skip Vite only when the current package has no effective Vite config (`vite.config.*` or inline `config.vite`)
-- when Devflare runs Vite, `config.vite` is merged into the actual Vite config, and Devflare writes a generated `.devflare/vite.config.mjs` when it needs one
-- higher-level `build`, `deploy`, and `devflare/vite` flows currently synthesize `.devflare/worker-entrypoints/main.ts` whenever a fetch, route tree, queue, scheduled, or email surface is discovered
-- `wrangler.passthrough.main` disables that composed-entry generation path
-- in worker-only mode, Devflare now bundles the composed main worker to `.devflare/worker-entrypoints/main.js` via Rolldown before handing it to Miniflare or Wrangler
-- Rolldown still rebuilds Durable Object worker code in unified Vite dev flows where Vite hosts the outer app
-
-For the full contract-level explanation and a concrete Rolldown + Svelte example, see the generated [`LLM.md`](./LLM.md) handbook entries for workflow modes and Svelte in workers.
-
----
-
-## Deploys, previews, tokens, and GitHub Actions
-
-### Production deploys vs same-Worker previews
-
-`devflare deploy` publishes production the usual Wrangler way.
-
-`devflare deploy --preview` is different: it uploads a **new version of the same Worker** with `wrangler versions upload` instead of creating a separate Worker environment.
-
-Named preview deploys are now the primary preview model:
-
-- each preview scope deploys its own dedicated Worker (or Worker family)
-- preview-scoped bindings and resources can be assigned only to that scope
-- feature branches and PRs get stable preview URLs from the scope name itself
-
-Preview scope names should still be lowercase and dash-friendly so they map cleanly into Worker names and `workers.dev` URLs.
-
-Useful preview examples:
-
-```bash
-bunx --bun devflare deploy --preview next
-bunx --bun devflare deploy --preview pr-42
-```
-
-When available, Devflare prints the Worker version id and preview URL outputs after the deploy finishes.
-
-### Login and preview scope helpers
-
-`devflare login` is the thin authentication wrapper for Cloudflare.
-
-- by default it reuses existing auth when Devflare can already resolve a Cloudflare API token
-- `devflare login --force` opens `wrangler login` again even when auth is already present
-- after login, Devflare prints the primary account when Cloudflare account discovery succeeds
-
-`devflare previews` is the config-aware preview-scope surface for dedicated preview Workers.
-
-Useful commands:
-
-```bash
-bunx --bun devflare previews
-bunx --bun devflare previews bindings --scope next
-bunx --bun devflare previews cleanup --scope next --apply
-bunx --bun devflare previews cleanup --all --apply
-```
-
-Current behavior:
-
-- `devflare previews` lists stable workers plus discovered dedicated preview scopes for the current worker family using live Cloudflare Worker names
-- `devflare previews bindings` resolves preview-scoped resources for one scope and shows how many deployed workers reference them
-- `devflare previews cleanup` deletes dedicated preview Workers plus preview-scoped KV, D1, R2, Queue, Vectorize, and reusable Hyperdrive resources for one scope or every discovered scope; it is a dry run unless `--apply` is present
-- `devflare deploy` still performs best-effort internal preview metadata synchronization after successful deploys so cleanup flows can remove deleted preview workers cleanly without extra CI glue
-
-### Manage Devflare tokens
-
-`devflare tokens <bootstrap-token>` manages Devflare-owned account API tokens using a bootstrap token that already has Cloudflare API-token-management permission.
-
-The command:
-
-- resolves the effective account id from `--account`, workspace preference, or the bootstrap token's primary account
-- normalizes managed token names to the `devflare-` prefix, so `preview` becomes `devflare-preview` while `devflare-preview` stays unchanged
-- `--new [token-name]` prompts for a token name when it is omitted, then creates a new Devflare-managed account-owned token from the curated Devflare permission set
-- `--new [token-name] --all-flags` uses every reusable account-scoped permission group visible to the bootstrap token except `Account API Tokens*`, because Cloudflare does not allow sub-tokens to inherit token-management permission and account-owned tokens skip incompatible zone/user-scoped groups automatically
-- `--list` lists only the Devflare-managed tokens in the selected account
-- `--delete [token-name]` deletes the matching Devflare-managed token after normalizing the name to the `devflare-` prefix
-- `--delete-all` deletes every Devflare-managed token in the selected account while leaving non-Devflare account tokens untouched
-- prints a new token value once, because Cloudflare only returns the secret a single time
-
-Examples:
-
-```bash
-bunx --bun devflare tokens <bootstrap-token> --new preview
-bunx --bun devflare tokens <bootstrap-token> --new preview --all-flags
-bunx --bun devflare tokens <bootstrap-token> --list
-bunx --bun devflare tokens <bootstrap-token> --delete preview
-bunx --bun devflare tokens <bootstrap-token> --delete-all
-```
-
-### Thin GitHub Action and caller workflows
-
-The repo ships a reusable composite action at [`.github/actions/devflare-deploy`](../../.github/actions/devflare-deploy).
-
-The repo also ships a shared workspace setup action at [`.github/actions/devflare-setup-workspace`](../../.github/actions/devflare-setup-workspace) so one workflow job can install dependencies once and then deploy multiple preview targets from the same checkout.
-
-The repo also ships a GitHub-feedback action at [`.github/actions/devflare-github-feedback`](../../.github/actions/devflare-github-feedback) for publishing deployment results back into GitHub.
-
-The action stays intentionally thin:
-
-- the caller workflow owns the runner, triggers, permissions, and environments
-- Cloudflare credentials must be passed in explicitly
-- by default, the action asks `devflare deploy` to verify Cloudflare control-plane state before the step is considered successful
-- the caller workflow should pass a deterministic `preview-scope`, such as the branch name or `pr-<number>`, for stable dedicated preview Worker naming across PR, push, and manual workflows
-
-The reporting split is also intentional:
-
-- GitHub PR feedback should use a stable PR comment because PRs are issue-backed conversations
-- GitHub branch feedback should use Deployments + deployment statuses because GitHub does not provide first-class branch comments
-- one preview workflow can publish both branch deployment feedback and the shared PR comment in the same run when a pushed branch already belongs to an open pull request
-
-Current action inputs that matter most:
-
-- `working-directory`
-- `environment`
-- `production`
-- `preview-scope`
-- `skip-setup`
-- `skip-install`
-- `verify-deployment` (defaults to `true`)
-- `cloudflare-api-token`
-- `cloudflare-account-id`
-
-When `verify-deployment` is enabled, the action fails if Devflare cannot confirm the uploaded version in Cloudflare, or for non-preview deploys, cannot confirm that a live deployment now references that version.
-
-Action outputs:
-
-- `preview-url`
-- `version-id`
-- `status`
-- `exit-code`
-- `log-excerpt`
-
-Those extra outputs are especially useful when the caller workflow uses `continue-on-error: true` on the deploy step so it can still post a failure comment or deployment status before failing the job.
-
-Minimal preview step:
-
-```yaml
-- id: deploy
-	uses: ./.github/actions/devflare-deploy
-	with:
-		working-directory: apps/documentation
-		preview-scope: ${{ github.head_ref || github.ref_name }}
-		cloudflare-api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
-		cloudflare-account-id: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
-```
-
-This repository now keeps preview delivery in one shared workflow plus one production workflow:
-
-- [`.github/workflows/preview.yml`](../../.github/workflows/preview.yml) handles documentation + testing previews, push + PR lifecycle triggers, branch + PR targets, and cleanup flows from one place
-- [`.github/workflows/documentation-production.yml`](../../.github/workflows/documentation-production.yml) handles production deploys from the repository default branch plus GitHub deployment statuses
-- [`.github/workflow-examples/branch-preview-cleanup.example.yml`](../../.github/workflow-examples/branch-preview-cleanup.example.yml) remains as a copyable delete-triggered preview-scope cleanup template for downstream repos that want a smaller starting point
-
-The live workflows now rely on the deploy action's control-plane verification for deploy success.
-
-If you want other feedback modes in your own repo, the supported patterns are:
-
-- PR-only preview feedback: `mode: comment`
-- branch-only preview feedback: `mode: deployment`
-- combined branch deployment + PR comment feedback: either `mode: both` with `resolve-pr-from-ref: 'true'`, or separate deployment/comment steps inside one shared preview workflow when you want finer control over grouped PR comments
-
-Repository-specific runtime checks still exist where they are testing app
-behavior rather than deploy success. For example,
-[`preview.yml`](../../.github/workflows/preview.yml)
-deploys testing previews for both branch and PR scopes from one prepared job
-when a pushed branch already belongs to an open pull request, while still
-keeping its deployed-binding verification because it is validating runtime
-bindings and deployment-channel wiring rather than merely asking whether
-Cloudflare accepted the upload.
-
-For branch-scoped real preview deploys such as `apps/testing`, Devflare now
-automatically omits shared queue consumers from the deployed Wrangler config,
-and it omits cron triggers by default, when it detects the branch-preview
-strategy (`--env preview` plus branch scope, without `--preview`). That keeps
-previews from colliding on singleton Cloudflare resources while leaving the
-authoring config itself fully exhaustive for local dev, tests, and production
-deploys.
-
-If a branch-scoped preview really should keep its cron schedule, opt in with:
-
-```ts
-export default defineConfig({
-	previews: {
-		includeCrons: true
-	}
-})
-```
-
-If those previews also need preview-owned Cloudflare resources, use
-`preview.scope()` in the config authoring layer:
-
-```ts
-import { defineConfig, preview } from 'devflare/config'
-
-const pv = preview.scope()
-
-export default defineConfig({
-	bindings: {
-		kv: {
-			CACHE: pv('my-cache-kv')
-		},
-		r2: {
-			ASSETS: pv('my-assets-bucket')
-		}
-	}
-})
-```
-
-Devflare resolves those opaque markers to base names outside preview
-environments, and to preview-scoped names such as `my-cache-kv-preview` (or a
-branch-derived suffix when `DEVFLARE_PREVIEW_BRANCH`, `DEVFLARE_PREVIEW_PR`, or
-`DEVFLARE_PREVIEW_IDENTIFIER` is present) for preview resolution and deploys.
-During `devflare deploy --env preview`, Devflare also provisions missing
-preview-scoped KV, D1, R2, Queue, and Vectorize resources automatically before
-the Wrangler deploy runs. Preview-scoped Hyperdrive names are reused when the
-matching preview config already exists, and otherwise Devflare falls back to the
-base Hyperdrive config because Cloudflare does not expose stored Hyperdrive
-credentials for cloning preview configs automatically. Use
-`devflare previews cleanup --env preview --apply` during PR-close or
-branch-delete cleanup to delete the preview-owned resources again.
-Service bindings created through `ref()` still follow the referenced worker
-names, so branch-scoped worker naming remains the way to isolate preview
-service bindings.
-
----
-
-## Repo examples
-
-- [`apps/documentation/`](../../apps/documentation/) is the executable SvelteKit example for dev, build, preview deploys, production deploys, workflow automation, and browser validation
-- [`apps/testing/`](../../apps/testing/) is the exhaustive binding-matrix example for the config contract itself, including `preview.scope()`-driven preview resource names, production overrides where bindings differ by deployment channel, and a tiny `src/fetch.ts` smoke Worker exercised by repository integration tests through `devflare/test`
-
----
-
-## Testing
-
-Use `devflare/test`.
-
-The high-level entrypoint is `createTestContext()`, and the unified helper surface is `cf`:
-
-- `cf.worker`
-- `cf.queue`
-- `cf.scheduled`
-- `cf.email`
-- `cf.tail`
-
-### `createTestContext()` autodiscovery
-
-If you omit the config path, `createTestContext()` walks upward from the calling test file and looks for the nearest supported config filename:
-
-- `devflare.config.ts`
-- `devflare.config.mts`
-- `devflare.config.js`
-- `devflare.config.mjs`
-
-It also auto-detects conventional `src/fetch.ts`, `src/queue.ts`, `src/scheduled.ts`, `src/email.ts`, built-in `src/routes/**`, and `src/tail.ts` when they are present.
-
-### Important current testing truth
-
-- `cf.worker.fetch()` returns when the handler resolves and does **not** eagerly wait for all `waitUntil()` work
-- `cf.worker.fetch()` and the shorthand helpers dispatch through both `src/fetch.ts` and built-in `src/routes/**` file routes when present
-- `cf.queue.trigger()` and `cf.scheduled.trigger()` do wait for queued background work before they return
-- `cf.tail.trigger()` is exported, and `createTestContext()` auto-detects `src/tail.ts` when present; there is still no public `files.tail` config key
-- `cf.email.send()` invokes the configured email handler in `createTestContext()`-backed tests and otherwise falls back to the local email endpoint; for ingress-fidelity-sensitive flows, validate with a higher-level integration test
-- remote mode is mainly about AI and Vectorize, not “make every binding remote”
-
-### Choosing pure mocks vs Miniflare-backed `createTestContext()`
-
-`devflare/test` ships two complementary lanes. Pick by what you are validating:
-
-- **Pure mocks** (`createMockKV`, `createMockD1`, `createMockR2`, `createMockEnv`, `createMockTestContext`, `withTestContext`):
-	- Fast, in-process, no Miniflare boot
-	- Use when you are unit-testing a function that reads or writes a single binding and you control the inputs
-	- Behavior is approximate: KV is binary-safe, D1 supports `SELECT`/`INSERT` per-table fixtures, R2 stores bytes — anything beyond those primitives will diverge from production
-- **`createTestContext()` (Miniflare-backed)**:
-	- Boots a real Workers runtime locally with your `devflare.config.ts`
-	- Use when you are testing handler dispatch, multi-binding flows, queues/scheduled/email/Durable Objects, route discovery, middleware composition, or anything that needs accurate Workers semantics
-	- Slower per test, so reuse one context per test file when possible
-
-Rule of thumb: if the assertion is "given inputs X, my function returns Y", reach for the mocks. If the assertion is "the worker behaves correctly when this binding/handler/route fires", use `createTestContext()`.
-
----
-
-## Public API surface and migration notes
-
-Devflare's bare `'devflare'` import is intentionally narrow and only exposes the documented public API. Internal helpers for the bridge, transform, and test runner are reachable from dedicated subpaths instead:
-
-- `devflare` — primary public API (`defineConfig`, `defineWorker`, `sequence`, `defineFetchHandler`, runtime context accessors, etc.)
-- `devflare/test` — `createTestContext`, `cf`, mock factories
-- `devflare/runtime` — runtime accessors (`env`, `ctx`, `event`, `locals`, helpers)
-- `devflare/cloudflare` — Cloudflare API helpers
-- `devflare/sveltekit` — SvelteKit platform glue
-- `devflare/decorators` — `@durableObject` and other decorators
-
-If you previously imported internal helpers (e.g., bridge serialization or transform helpers) from bare `'devflare'`, switch to the matching subpath. The internal modules are not considered stable public API and may change between minor versions.
-
----
-
-## CLI
-
-Every top-level command supports `--help`, and nested command groups support both:
-
-- `bunx --bun devflare <command> --help`
-- `bunx --bun devflare <command> <subcommand> --help`
-- `bunx --bun devflare help <command> [subcommand]`
-
-| Command | What it does |
-|---|---|
-| `devflare init` | scaffold a project using `src/fetch.ts` and explicit `files.fetch` |
-| `devflare dev` | start the worker-only dev server, enabling Vite only when the current package has a local `vite.config.*` |
-| `devflare build` | resolve config locally, preserve named bindings in generated build artifacts, and run `vite build` only for Vite-backed packages |
-| `devflare deploy` | build or reuse a prior artifact via `--build`, provision named deploy resources, and deploy with Wrangler, including same-Worker preview uploads via `--preview` |
-| `devflare types` | generate `env.d.ts` |
-| `devflare doctor` | check project configuration plus generated artifact locations such as `.devflare/wrangler.jsonc`, `.devflare/build/wrangler.jsonc`, and `.wrangler/deploy/config.json` |
-| `devflare config` | print resolved Devflare config or resolved Wrangler JSON |
-| `devflare account` | inspect accounts, resources, usage, and limits |
-| `devflare login` | authenticate with Cloudflare via Wrangler, reusing existing auth unless `--force` is passed |
-| `devflare previews` | inspect and clean dedicated preview Workers plus preview-owned scope resources |
-| `devflare productions` | inspect live production Workers, list recent versions, roll back, or delete a live Worker script |
-| `devflare worker` | run Worker control-plane actions such as remote renaming and local config sync |
-| `devflare tokens` | create, list, and delete Devflare-managed account-owned tokens from a bootstrap token with API-token-management permission |
-| `devflare help` | print the command overview or the detailed help page for a command path |
-| `devflare version` | print the installed Devflare version |
-| `devflare ai` | show Workers AI model pricing info |
-| `devflare remote` | manage remote test mode |
-
-Command defaults:
-
-- `devflare config` defaults to `devflare config print`
-- `devflare previews` defaults to `devflare previews list`
-- `devflare productions` defaults to `devflare productions list`
-
-### Command groups
-
-| Group | Subcommands / operations |
-|---|---|
-| `account` | `info`, `workers`, `kv`, `d1`, `r2`, `vectorize`, `usage`, `limits`, `limits set`, `limits enable`, `limits disable`, `global`, `workspace` |
-| `config` | `print` |
-| `previews` | `list`, `bindings`, `cleanup` |
-| `productions` | `list`, `versions`, `rollback`, `delete` |
-| `remote` | `status`, `enable`, `disable` |
-| `worker` | `rename` |
-| `tokens` | `--list`, `--new`, `--roll`, `--delete`, `--delete-all` (flag-driven operations rather than subcommands) |
-
-Useful flags:
-
-- `build --env <name>`
-- `deploy --build <path>`
-- `deploy --env <name>`
-- `deploy --dry-run`
-- `deploy --preview <name>`
-- `login --force`
-- `previews`
-- `previews cleanup --scope <name> --apply`
-- `config print --json`
-- `config print --format wrangler`
-- `types --output <path>`
-- `doctor --config <path>`
-- `account --account <id>`
-- `tokens <bootstrap-token> --new [name]`
-- `tokens <bootstrap-token> --list`
-
-Recommended invocation style:
-
-```bash
-bunx --bun devflare dev
-bunx --bun devflare types
-bunx --bun devflare build
-bunx --bun devflare help account limits set
-bunx --bun devflare previews cleanup --help
-```
-
----
-
-## Generated artifacts
-
-Treat these as generated output, not source of truth:
-
-- `.devflare/wrangler.jsonc`
-- `.devflare/build/wrangler.jsonc`
-- `.devflare/worker-entrypoints/main.ts`
-- `.devflare/worker-entrypoints/main.js`
-- `.devflare/vite.config.mjs`
-- `.wrangler/deploy/config.json`
-- `env.d.ts`
-
-`devflare build` keeps name-based bindings as names in these generated artifacts. `devflare deploy` is the step that resolves or provisions the concrete Cloudflare resources and rewrites the generated Wrangler config with the IDs Wrangler needs.
-
-The source of truth is still:
-
-- `devflare.config.ts`
-- your source files under `src/`
-- your tests
-
----
-
-## Maintainer scripts
-
-These scripts live in `packages/devflare/scripts/` and are intended for Devflare maintainers, not for end-user applications.
-
-### `refresh-permission-groups`
-
-Fetches the live Cloudflare permission-group catalog and rewrites `src/cloudflare/known-permission-group-ids.generated.ts` so the symbolic Devflare permission-group names (`WORKERS_SCRIPTS_WRITE`, etc.) map to verified Cloudflare UUIDs instead of falling back to display-name matching.
-
-```sh
-# from the repo root
-CLOUDFLARE_API_TOKEN=... CLOUDFLARE_ACCOUNT_ID=... bun run --cwd packages/devflare refresh-permission-groups
-```
-
-Flags:
-
-- `--dry-run` — print the would-be generated file to stdout instead of writing to disk; useful for CI drift checks.
-- `--keep-existing` — keep the previously-known UUID for entries missing from the API response, instead of clearing them to `null`.
-- `--output <path>` — override the destination file; defaults to `packages/devflare/src/cloudflare/known-permission-group-ids.generated.ts`.
-
-The API token must have permission to read `/accounts/:id/tokens/permission_groups`. The script never touches `tokens.ts` directly, so the public matcher API and its display-name fallback continue to work even when the generated file ships with all-`null` entries.
-
----
-
-## In one sentence
-
-**Devflare helps you build Cloudflare Workers with clearer structure, better local tooling, and a development workflow that stays coherent as the app grows.**
+# Devflare
+
+Devflare is a developer-first toolkit for Cloudflare Workers. It keeps config,
+runtime helpers, local development, testing, preview deploys, and Cloudflare
+operations in one package without pretending Cloudflare boundaries disappear.
+
+The docs app is the authored long-form source. This README is intentionally the
+short package map: install, first Worker, import/API map, config and CLI
+surface, support stances, and links into the deeper docs. `LLM.md` is generated
+from the same docs model and shipped with the package for flattened reading.
+
+## Install
+
+For a worker-only project, install only Devflare:
+
+```bash
+bun add -d devflare
+```
+
+For Vite-backed apps, add Vite and the Cloudflare Vite plugin:
+
+```bash
+bun add -d devflare vite @cloudflare/vite-plugin
+```
+
+Assumptions used by the examples: Wrangler 4, Miniflare 4,
+`@cloudflare/workers-types` 4, Bun 1.1+, and Node 20+.
+
+## Cloudflare toolchain support
+
+Devflare targets Wrangler 4, Miniflare 4, and @cloudflare/workers-types 4.
+Devflare does not support Wrangler 3 in new projects. The package manifest pins
+the exact ranges that scaffolds, local runtime behavior, and generated types
+are validated against in CI.
+
+## Quick Start
+
+Create a config:
+
+```ts
+// devflare.config.ts
+import { defineConfig } from 'devflare/config'
+
+export default defineConfig({
+	name: 'hello-worker',
+	compatibilityDate: '2026-03-17',
+	files: {
+		fetch: 'src/fetch.ts'
+	}
+})
+```
+
+Add a fetch handler:
+
+```ts
+// src/fetch.ts
+import type { FetchEvent } from 'devflare/runtime'
+
+export async function fetch(_event: FetchEvent): Promise<Response> {
+	return new Response('Hello from Devflare')
+}
+```
+
+Generate types and start local dev:
+
+```bash
+bunx --bun devflare types
+bunx --bun devflare dev
+```
+
+Add the first runtime-shaped test:
+
+```ts
+// tests/worker.test.ts
+import { afterAll, beforeAll, expect, test } from 'bun:test'
+import { cf, createTestContext, env } from 'devflare/test'
+
+beforeAll(() => createTestContext())
+afterAll(() => env.dispose())
+
+test('GET / returns text', async () => {
+	const response = await cf.worker.get('/')
+
+	expect(response.status).toBe(200)
+	expect(await response.text()).toBe('Hello from Devflare')
+})
+```
+
+Run it:
+
+```bash
+bun test tests/worker.test.ts
+```
+
+## Choose Your Next Path
+
+| Need | Open |
+| --- | --- |
+| Add route files | `/docs/first-route-tree`, then `/docs/http-routing` |
+| Add one binding | `/docs/first-bindings`, then `/docs/binding-chooser` |
+| Pick a test helper | `/docs/test-helper-reference` |
+| Deploy safely | `/docs/deploy-command-recipes` |
+| Check support stance | `/docs/feature-index` |
+| Copy a larger example | `/docs/recipe-packs` or `cases/README.md` |
+
+## Package Entrypoints
+
+| Import | Use |
+| --- | --- |
+| `devflare` | Node-side utilities: `defineConfig`, `preview`, `loadConfig`, `loadResolvedConfig`, `compileConfig`, `stringifyConfig`, `configSchema`, `ref()`, `workerName`, `env`, `durableObject`, `getDurableObjectOptions`, `runCli`, `parseArgs` |
+| `devflare/config` | Config and compiler utilities: `defineConfig`, `preview`, `ref`, `loadConfig`, `loadResolvedConfig`, `compileConfig`, `stringifyConfig`, `configSchema`, `resolveResources`, `writeWranglerConfig`, `readWranglerConfig`, `prepareConfigResourcesForDeploy`, `prepareMaterializedConfigResourcesForDeploy`, `resolveConfigPath`, `resolveConfigForEnvironment`, `resolvePreviewIdentifier`, `materializePreviewScopedConfig`, `materializePreviewScopedString`, `isPreviewScopedName`, `resolveMaterializedConfigResources`, `compileBuildConfig`, `validateServiceBindings`, `collectReferencedServiceNames`, `getLocalKVNamespaceIdentifier`, `getLocalD1DatabaseIdentifier`, `getLocalHyperdriveConfigIdentifier`, `getSingleBrowserBindingName`, `normalizeKVBinding`, `normalizeD1Binding`, `normalizeDOBinding`, `normalizeHyperdriveBinding`, `normalizeMtlsCertificateBinding`, `normalizeDispatchNamespaceBinding`, `normalizeWorkflowBinding`, `normalizePipelineBinding`, `normalizeImagesBinding`, `normalizeMediaBinding`, `normalizeSecretsStoreBinding`, `normalizeArtifactsBinding` |
+| `devflare/runtime` | Worker-safe runtime helpers: `env`, `ctx`, `event`, `locals`, `sequence`, `defineFetchHandler`, `defineQueueHandler`, `defineScheduledHandler`, `markResolveStyle`, `markWorkerStyle`, `createResolveFetch`, `invokeFetchHandler`, `invokeFetchModule`, `matchFetchRoute`, `invokeRouteModules`, `createRouteResolve`, event creators and getters |
+| `devflare/test` | Testing helpers: `createTestContext`, `env`, `cf`, `worker`, `queue`, `scheduled`, `email`, `tail`, `shouldSkip`, `createOfflineEnv`, `createOfflineBindings`, `describeOfflineSupport`, `getOfflineSupportMatrix`, `containers`, `detectContainerEngine`, `getContainerSkipReason`, `stopActiveContainers`, `createMockEnv`, `createMockKV`, `createMockD1`, `createMockR2`, `createMockQueue`, `createMockRateLimit`, `createMockVersionMetadata`, `createMockHyperdrive`, `createMockWorkerLoader`, `createMockMTLSCertificate`, `createMockDispatchNamespace`, `createMockWorkflow`, `createMockPipeline`, `createMockImagesBinding`, `createMockMediaBinding`, `createMockArtifacts`, `createMockAISearchInstance`, `createMockAISearchNamespace`, `createMockTestContext`, `withTestContext`, `resolveServiceBindings`, `resolveDOBindings`, `clearBundleCache` |
+| `devflare/vite` | Vite integration: `devflarePlugin`, `getCloudflareConfig`, `getDevflareConfigs`, `getPluginContext`, `hasInlineViteConfig`, `resolveEffectiveViteProject`, `resolveViteUserConfig`, `writeGeneratedViteConfig` |
+| `devflare/sveltekit` | SvelteKit integration: `createDevflarePlatform`, `createHandle`, `handle`, `getBridgePort`, `isDevflareDev`, `resetPlatform`, `resetConfigCache` |
+| `devflare/cloudflare` | Cloudflare account and preview registry helpers: `account`, `ensurePreviewRegistry`, `cleanupPreviewRegistry`, `getPreviewRegistryContext`, `listTrackedRegistryState`, `listTrackedPreviewRecords`, `listTrackedPreviewScopeRecords`, `listTrackedDeploymentRecords`, `reconcilePreviewRegistry`, `retirePreviewRegistry` |
+| `devflare/decorators` | Durable Object decorators: `durableObject`, `getDurableObjectOptions` |
+
+Runtime import rule of thumb:
+
+- Use `devflare/config` in config files.
+- Use `devflare/runtime` in Worker code.
+- Use `devflare/test` in tests.
+- Use bare `devflare` for Node-side package tooling and the unified env proxy only when that is intentional.
+
+## Config Map
+
+The most important top-level keys are:
+
+- `accountId`
+- `assets`
+- `baseDir`
+- `bindings`
+- `compatibilityDate`
+- `compatibilityFlags`
+- `containers`
+- `env`
+- `files`
+- `findAdditionalModules`
+- `limits`
+- `migrations`
+- `name`
+- `observability`
+- `placement`
+- `preserveFileNames`
+- `previews`
+- `rolldown`
+- `routes`
+- `rules`
+- `secrets`
+- `secretsStoreId`
+- `tailConsumers`
+- `triggers`
+- `vars`
+- `vite`
+- `wrangler.passthrough`
+- `wsRoutes`
+
+Open `/docs/full-config`, `/docs/config-basics`, and `/docs/generated-types`
+for examples with file paths.
+
+## CLI
+
+| Command | Use |
+| --- | --- |
+| `devflare account` | inspect Cloudflare account resources, limits, and usage |
+| `devflare ai` | inspect Workers AI model pricing information |
+| `devflare build` | generate deploy-ready local artifacts |
+| `devflare config` | print resolved Devflare or Wrangler-facing config |
+| `devflare deploy` | deploy explicitly to production or preview |
+| `devflare dev` | start local development |
+| `devflare doctor` | inspect local project health |
+| `devflare help` | print help for root or nested commands |
+| `devflare init` | scaffold a starter project |
+| `devflare login` | authenticate through Wrangler |
+| `devflare previews` | inspect and clean preview scopes |
+| `devflare productions` | inspect or manage production Worker versions |
+| `devflare remote` | manage remote test mode |
+| `devflare secrets` | manage local Secrets Store values |
+| `devflare tokens` | create and manage Devflare-scoped API tokens |
+| `devflare types` | generate `env.d.ts` |
+| `devflare version` | print the installed version |
+| `devflare worker` | run Worker control-plane helpers |
+
+## Support Stance Index
+
+The full support matrix is in `/docs/feature-index`. The short version is:
+offline-first when deterministic local behavior is meaningful, remote-gated
+when Cloudflare owns the product behavior, and explicit skip helpers when CI
+cannot safely run the dependency.
+
+### AutoRAG migration stance
+
+AutoRAG is documented under AI Search. The previous `env.AI.autorag()` binding
+shape should move to native AI Search config. Use `bindings.aiSearchNamespaces`
+or `bindings.aiSearch` so the binding is visible in config, generated types,
+and tests.
+
+### AI Gateway binding methods
+
+AI Gateway does not use a separate Wrangler binding. It is a method surface on
+Workers AI: `env.AI.gateway(id)` exposes `patchLog()`, `getLog()`, `getUrl()`,
+and `run()`.
+
+### Browser Run product boundary
+
+Browser Run is the current product name for Browser Rendering. Devflare runs a
+local browser-rendering shim for the ordinary dev and test loop, but Devflare
+does not manage Live View URLs, Human in the Loop handoff, recordings, browser
+session storage, or Browser Run account-level product state.
+
+### Containers local testing
+
+Devflare supports native top-level `containers` config and local container
+testing helpers. Containers have full local support when Docker or Podman is
+available: Devflare can build local Dockerfile paths, run prebuilt image tags,
+and interact with instances through fetch, logs, state, stop, and cleanup
+helpers. Devflare container tests are offline-first by default when the image
+already exists locally or the Dockerfile can build from cached layers. Set
+`DEVFLARE_CONTAINER_TESTS=1` for container lanes, and gate them with
+`shouldSkip.containers` because GitHub Actions or Cloudflare runners may not
+have Docker/Podman. Cloudflare still owns the deployed Containers control plane,
+managed registry rollout, SSH, scaling, and hosted platform behavior.
+
+### Cloudflare Builds stance
+
+Cloudflare Builds is CI/CD orchestration, not a Worker runtime binding.
+Devflare does not connect Git repositories, manage build hooks, own Cloudflare
+Builds project settings, or replace GitHub Actions workflows.
+
+### Workers for Platforms lifecycle stance
+
+Devflare supports dispatch namespace bindings, not the tenant Worker control
+plane. Devflare does not upload user Workers, manage Worker metadata, own tenant
+routing policy, or provide the Workers for Platforms lifecycle API.
+
+### Hyperdrive local connection stance
+
+Hyperdrive has full local support when a binding has a local database connection
+string. Devflare passes `localConnectionString` or
+`CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING>` into Miniflare and
+also exposes `createMockHyperdrive()` for pure tests. Cloudflare still owns
+hosted pooling, placement, production credentials, and account state.
+
+### Worker Loaders local payload stance
+
+Worker Loaders have full local support through Miniflare worker loader bindings
+and explicit pure-test stubs. Devflare does not upload, discover, or lifecycle
+manage hosted dynamic Worker payloads.
+
+### Secrets Store local values stance
+
+Secrets Store has full local support through Miniflare wiring, local
+`devflare secrets --local` values, and explicit fixture values in
+`createOfflineEnv()` or `createMockSecretsStoreSecret()`. The local runtime is
+read-only from Worker code: write values through the CLI, keep config to store
+IDs and secret names, and let dev/test runs seed Miniflare from
+`.devflare/secrets.local.json`. Devflare does not read, provision, or sync
+remote account secret values.
+
+### Workflows local simulation stance
+
+Workflows have full local support through Miniflare wiring, WorkflowEntrypoint
+examples, and deterministic pure mocks. Use deployed or Wrangler-backed tests
+for production Workflow lifecycle behavior, retries, durability, and platform
+scheduling.
+
+### Pipelines source and sink lifecycle stance
+
+Pipelines local tests are useful for producer-code assertions. Devflare does not
+create streams, pipelines, SQL transformations, sinks, or R2 buckets for the
+deployed product lifecycle.
+
+### Images transformation testability stance
+
+Images have full local support for Worker transformation flows through
+Miniflare wiring and deterministic pure mocks. Devflare does not provision
+hosted Images storage, variants, signed URLs, or custom delivery rules.
+
+### Media Transformations local shim stance
+
+Media Transformations have full local support for Worker call chains through
+Miniflare wiring and deterministic pure mocks. Devflare does not configure
+zone-level transformation enablement, source origins, signed URL policy, cache
+behavior, or billing controls.
+
+### Artifacts persistence and deployment stance
+
+Artifacts pure mocks are in-memory and process-local. Devflare does not create
+Artifacts namespaces, persist local Git repositories, or emulate Git-over-HTTPS
+remotes.
+
+### Preview resource lifecycle policy
+
+Devflare preview provisioning is intentionally limited to KV, D1, R2, Queues,
+Vectorize, and the documented Hyperdrive reuse/resolve paths. Preview cleanup
+does not delete Workflows, Pipelines, Images, Media Transformations, Artifacts,
+AI Search, AI Gateway, Browser Run, Containers, Secrets Store, mTLS
+certificates, or dispatch namespace resources.
+
+### Cross-feature implementation decisions
+
+Remote mode decisions are per feature, not global. Generated types are emitted
+only for native binding keys. Test helpers exist when Devflare provides a
+deterministic local mock or useful pure assertion surface. Every native binding
+documented above includes a minimal config and Env usage example. Move from
+`wrangler.passthrough` to native config when a binding appears in the native
+list. Cloudflare dependency CI targets the pinned current Wrangler, Miniflare,
+and workers-types majors documented in Cloudflare toolchain support.
+
+### Offline-first testing support matrix
+
+`createOfflineEnv(config, fixtures)` derives a deterministic pure-test `env`
+from Devflare config. Offline-native means Devflare or Miniflare can run a
+useful local simulator. Offline-fixture means Devflare provides an explicit
+in-memory or handler-backed mock. Remote-boundary means meaningful behavior
+lives in Cloudflare.
+
+Use `shouldSkip.aiSearch`, `shouldSkip.aiGateway`,
+`shouldSkip.mtlsCertificates`, `shouldSkip.artifacts`, and `shouldSkip.builds`
+for remote-boundary lanes. Offline-first tests should not claim to cover real
+Workers AI inference, Vectorize search semantics, AI Search indexing/ranking/
+crawling, final Media Transformations codec fidelity, mTLS certificate
+presentation, Artifacts Git remotes, Browser Run live/HITL/recordings,
+Cloudflare Builds, or the deployed Containers control plane.
+
+## Machine-Checked Support Statements
+
+These statements are intentionally exact because the docs tests use them as
+public stance guards:
+
+- Use `bindings.aiSearchNamespaces` or `bindings.aiSearch`.
+- `env.AI.gateway(id)` exposes `patchLog()`, `getLog()`, `getUrl()`, and `run()`.
+- Devflare does not manage Live View URLs, Human in the Loop handoff.
+- Set `DEVFLARE_CONTAINER_TESTS=1`.
+- Containers have full local support when Docker or Podman is available.
+- Cloudflare still owns the deployed Containers control plane.
+- Devflare does not connect Git repositories, manage build hooks.
+- Devflare supports dispatch namespace bindings, not the tenant Worker control plane.
+- Devflare does not upload user Workers, manage Worker metadata.
+- Hyperdrive has full local support when a binding has a local database connection string.
+- Worker Loaders have full local support through Miniflare worker loader bindings.
+- Secrets Store has full local support through Miniflare wiring, local `devflare secrets --local` values, and explicit fixture values.
+- Workflows have full local support through Miniflare wiring.
+- Use deployed or Wrangler-backed tests for production Workflow lifecycle behavior.
+- Devflare does not create streams, pipelines, SQL transformations, sinks, or R2 buckets.
+- Images have full local support for Worker transformation flows.
+- Devflare does not provision hosted Images storage, variants, signed URLs, or custom delivery rules.
+- Media Transformations have full local support for Worker call chains.
+- Devflare does not configure zone-level transformation enablement, source origins, signed URL policy, cache behavior, or billing controls.
+- Devflare does not create Artifacts namespaces, persist local Git repositories, or emulate Git-over-HTTPS remotes.
+- Devflare preview provisioning is intentionally limited to KV, D1, R2, Queues, Vectorize, and the documented Hyperdrive reuse/resolve paths.
+- Preview cleanup does not delete Workflows, Pipelines, Images, Media Transformations, Artifacts, AI Search, AI Gateway, Browser Run, Containers, Secrets Store, mTLS certificates, or dispatch namespace resources.
+- Generated types are emitted only for native binding keys.
+- Test helpers exist when Devflare provides a deterministic local mock or useful pure assertion surface.
+- Every native binding documented above includes a minimal config and Env usage example.
+- Move from `wrangler.passthrough` to native config when a binding appears in the native list.
+- Cloudflare dependency CI targets the pinned current Wrangler, Miniflare, and workers-types majors documented in Cloudflare toolchain support.
+- `createOfflineEnv(config, fixtures)` derives a deterministic pure-test `env` from Devflare config.
+- Offline-native means Devflare or Miniflare can run a useful local simulator.
+- Offline-fixture means Devflare provides an explicit in-memory or handler-backed mock.
+- Remote-boundary means meaningful behavior lives in Cloudflare.
+- `shouldSkip.aiSearch`, `shouldSkip.aiGateway`, `shouldSkip.mtlsCertificates`, `shouldSkip.artifacts`, and `shouldSkip.builds`.
+- real Workers AI inference, Vectorize search semantics, AI Search indexing/ranking/crawling, final Media Transformations codec fidelity, mTLS certificate presentation, Artifacts Git remotes, Browser Run live/HITL/recordings, Cloudflare Builds, or the deployed Containers control plane.
+
+## Verification
+
+Docs and README drift are covered by:
+
+```bash
+bun run devflare:docs-integrity
+```
+
+The package publish path regenerates `packages/devflare/LLM.md` from the docs
+model through `bun run --cwd packages/devflare llm:generate`.