devflare 1.0.0-next.2 → 1.0.0-next.4

package/LLM.md

@@ -520,7 +520,7 @@ Bindings are the heart of the runtime contract.
 |---|---|---|---|
 | `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 |
+| `r2` | `Record<string, string>` | Yes | binding name → bucket name, not a delivery/auth strategy |
 | `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 |
@@ -550,6 +550,15 @@ bindings: {
 }
 ```
 
+An R2 binding declaration only makes the bucket available as a runtime `env` binding.
+
+It does **not** by itself decide:
+
+- how uploads should be authorized
+- whether objects are public or private
+- which URL shape should be stored in your database
+- whether files should be served through a custom domain, presigned URL, Access, WAF token auth, or a Worker
+
 ### Durable Objects
 
 Durable Object bindings support both shorthand and object form.
@@ -688,6 +697,199 @@ However, this binding is currently **not wired through the compiler/types/runtim
 
 ---
 
+## R2 workflow: uploads, delivery, local development, and preview mindset
+
+For a shorter strategy guide focused specifically on Cloudflare R2 delivery patterns, see `R2.md`.
+
+This section explains how R2 fits into the **public Devflare mental model**.
+
+### `bindings.r2` gives you storage access, not a complete delivery policy
+
+When you configure:
+
+```ts
+bindings: {
+	r2: {
+		FILES: 'files-bucket'
+	}
+}
+```
+
+Devflare is saying:
+
+- your Worker should receive an `env.FILES` R2 binding
+- local development can simulate that binding
+- build/deploy compilation can emit the corresponding Wrangler binding declaration
+
+Devflare is **not** automatically saying:
+
+- uploads should come from the browser directly
+- objects should be public
+- objects should be private
+- your app should store full URLs instead of object keys
+- local dev URLs should look like production URLs
+
+Those choices still belong to your application architecture.
+
+### Store object keys, not full URLs
+
+This is the safest default rule for R2-backed applications:
+
+- store the **object key** as the durable identifier
+- optionally store metadata such as content type, size, owner, visibility, or logical folder/prefix
+- derive the actual viewing or download URL per environment and per access policy
+
+Example durable record shape:
+
+```ts
+{
+	key: 'users/42/avatar/8d8b7f2a.png',
+	contentType: 'image/png',
+	visibility: 'private'
+}
+```
+
+Why this is better than storing full URLs:
+
+- local preview URLs can change without breaking your data model
+- staging and production can use different delivery strategies for the same object key
+- you do not couple persistent data to `localhost`, temporary signed URLs, or a specific CDN hostname
+- you can move a file from private delivery to public delivery without rewriting the canonical identifier
+
+### Recommended upload and serving models
+
+These are the recommended patterns to pair with a Devflare R2 binding.
+
+#### Direct user uploads
+
+For normal browser uploads, the safest default is:
+
+1. your frontend asks your app for upload permission
+2. your Worker authenticates the user and validates file type, size, and target key
+3. your Worker returns a short-lived presigned `PUT` URL
+4. the browser uploads directly to R2
+5. your app stores the resulting object key and metadata
+
+This keeps large uploads out of your application request path while preserving control over authorization and naming.
+
+#### Worker-generated or server-generated content
+
+If the file is produced by your Worker, by Workers AI, or by another trusted backend process, it is normal for the Worker itself to write directly to R2.
+
+That is different from browser-driven uploads, where presigned URLs are usually the cleaner fit.
+
+#### Public files
+
+For avatars, blog images, product images, and other content that anyone may read:
+
+- use a public bucket or public custom-domain access pattern
+- prefer a custom domain for stable production URLs and caching behavior
+- do not treat `r2.dev` as the production answer
+
+#### Private or authenticated files
+
+For invoices, receipts, paid media, tenant-scoped files, or other user-specific objects:
+
+- keep the bucket private
+- store only object keys in durable data
+- serve reads through a Worker that checks session, tenant, or authorization state before reading from R2
+
+#### Temporary direct reads
+
+Presigned `GET` URLs are useful when you need short-lived direct access.
+
+Important caveats:
+
+- they are bearer tokens
+- they work on the R2 S3 endpoint, not on custom domains
+- they are great for temporary access, but not the right long-term answer for polished custom-domain delivery
+
+#### Team-only or org-only buckets
+
+If the audience is your teammates or internal users, Cloudflare Access on a custom domain is often a better fit than inventing your own mini auth protocol.
+
+#### Custom-domain expiring links
+
+If you want URLs like `https://cdn.example.com/files/...` with time-limited access, use:
+
+- a Worker-controlled token/signature layer, or
+- Cloudflare WAF token authentication / HMAC validation
+
+Do **not** confuse that with R2 presigned URLs. They solve different problems.
+
+### Local development vs production
+
+#### Local development
+
+In local development, the correct default assumption is:
+
+- your Worker code runs locally
+- your R2 binding is simulated locally unless you intentionally opt into remote resources
+
+This is good. It gives you fast feedback, zero surprise cloud writes, and predictable local iteration.
+
+When you run `devflare dev --persist`, local Miniflare-backed state is persisted under `.devflare/data/`, including R2 object state under `.devflare/data/r2/`.
+
+#### Remote bindings change the risk profile
+
+If you connect development to remote resources, remember:
+
+- reads and writes touch **real buckets**
+- operations can incur **real cost**
+- local experiments can now interact with non-local data
+
+So the recommended pattern is:
+
+- use local simulated R2 for normal development
+- use separate dev or staging buckets when you need higher-fidelity integration testing
+- avoid pointing local development at production user uploads unless you truly mean to
+
+#### Production
+
+Production is where you make the real delivery choice:
+
+- public custom-domain access for public files
+- Worker-gated reads for private/authenticated files
+- Access for org-only content
+- Worker/WAF token validation for custom-domain expiring links
+
+That is why `R2.md` exists. It is the short operational guide for those production choices.
+
+### Local preview and internal route guidance
+
+Devflare already uses internal `/_devflare/*` routes during local development for gateway and bridge behavior.
+
+Treat those routes as **internal dev-server implementation details**, not as part of your application’s public URL contract.
+
+Important current rule:
+
+- do **not** assume there is a stable public `/_devflare/r2/...` contract for browser-facing local file delivery
+- do **not** persist `/_devflare/*` URLs in your database
+- do **not** design production delivery around the hope that local preview URLs and production URLs will be the same
+
+If you build custom local preview tooling or if Devflare gains a future R2 inspector surface, the safest mental model is:
+
+- it is a **dev-only convenience or inspector URL**
+- it should be treated as **read-only**
+- it should help you inspect objects, not redefine your production delivery architecture
+- the canonical identifier should still be the object key, not the preview URL
+
+Also remember that R2 is object storage, not a real filesystem. Prefix browsing can be useful in tooling, but those “folders” are naming conventions, not first-class directories.
+
+### Benefits of this model
+
+This local-first but production-explicit R2 model has real benefits.
+
+- **Faster local iteration:** you can develop upload and media flows against local simulated R2 without waiting on cloud round-trips
+- **Safer production posture:** public, private, org-only, and expiring-link delivery can be chosen intentionally instead of collapsing into one accidental URL model
+- **Better data durability:** storing keys instead of URLs keeps your database portable across local, staging, and production environments
+- **Cleaner security boundaries:** auth policy stays where it belongs, in Workers, Access, or token validation, rather than being smuggled into a fragile client-side convention
+- **Better debugging ergonomics:** local preview or inspector tooling can exist as a convenience layer without becoming the source of truth
+- **Less environment coupling:** your app does not become dependent on `localhost`, temporary presigned URLs, or an implementation-specific dev route shape
+- **Better media realism:** you can use local development for quick feedback, then use staging for production-like checks such as custom-domain caching, token auth, and large-media behavior
+
+---
+
 ## `vars`, `secrets`, and generated types
 
 ### `vars`
@@ -1285,6 +1487,34 @@ Recommended invocation style:
 bunx --bun devflare <command>
 ```
 
+### Global flags
+
+These flags are parsed at the CLI entrypoint level.
+
+| Flag | Meaning | Where it actually matters | Notes |
+|---|---|---|---|
+| `-h`, `--help` | show help text and exit | all invocations | short-circuits immediately to the help command |
+| `-v`, `--version` | show the CLI/package version and exit | all invocations | short-circuits immediately to the version command |
+| `--config <path>` | choose a config file instead of nearest default discovery | `dev`, `build`, `deploy`, `types` | currently not consumed by `doctor`, `account`, `ai`, or `remote` |
+| `--debug` | enable debug-oriented output | `dev`, `build`, `deploy`, `types` | in `dev`, this also implies verbose logging; in `build`/`deploy`/`types`, it mainly controls stack-trace output on failure |
+
+There is also a current internal/testing-oriented `--cwd` path override used by the `dev` command implementation. Treat that as an unsupported internal hook rather than part of the stable public CLI contract.
+
+### `init`
+
+Usage:
+
+```text
+devflare init [name] [--template <template>]
+```
+
+Arguments and flags:
+
+| Argument or flag | Meaning | Notes |
+|---|---|---|
+| `[name]` | project directory name | defaults to `my-devflare-app` |
+| `--template <template>` | choose a starter template | current built-in templates are `minimal` and `api`; default is `minimal` |
+
 ### `dev`
 
 `devflare dev` is not “just run Miniflare”.
@@ -1299,23 +1529,30 @@ It is a combined local development system that includes:
 - browser-shim behavior for browser rendering
 - local migration handling when relevant resources are configured
 
-Dev command flags include:
+Usage:
 
-- `--port`
-- `--persist`
-- `--verbose`
-- `--log`
-- `--log-temp`
+```text
+devflare dev [--config <path>] [--debug] [--port <port>] [--persist] [--verbose] [--log] [--log-temp]
+```
 
-### Config path and environment selection in CLI commands
+Flags:
 
-For the current build and deploy flows:
+| Flag | Meaning | Notes |
+|---|---|---|
+| `--config <path>` | load a specific `devflare.config.*` file | otherwise config is loaded from the current working directory |
+| `--debug` | enable debug mode | equivalent effect to setting `DEVFLARE_DEBUG=true` for the dev command and also implies verbose logging |
+| `--port <port>` | set the preferred Vite port | only matters when the current package has a local `vite.config.*` and Devflare actually starts Vite |
+| `--persist` | persist Miniflare storage across restarts | opt-in in the current CLI; persists KV, R2, D1, and Durable Object state under `.devflare/data/` |
+| `--verbose` | increase logging verbosity | debug mode also turns this on |
+| `--log` | tee log output to both terminal and a timestamped file | file name shape is `.log-YYYY-MM-DD_HH-MM-SS` in the project root |
+| `--log-temp` | tee log output to both terminal and `.log` | `.log` is overwritten each run; if both `--log` and `--log-temp` are passed, temp-log mode wins |
 
-- 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`
+Important current CLI behavior:
 
-So `--env` on `deploy` affects both the Devflare-side resolution step **and** Wrangler’s deploy command.
+- Devflare starts in **worker-only mode** unless the current package has a local `vite.config.ts`, `vite.config.js`, `vite.config.mts`, or `vite.config.mjs`
+- `--port` does not force Vite on by itself; it only affects startup if Vite is already enabled by local package structure
+- there is no public `--env` flag on the current `dev` command
+- without `--persist`, local Miniflare-backed state is ephemeral for that dev session
 
 ### `build`
 
@@ -1331,6 +1568,20 @@ 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.
 
+Usage:
+
+```text
+devflare build [--config <path>] [--env <name>] [--debug]
+```
+
+Flags:
+
+| Flag | Meaning | Notes |
+|---|---|---|
+| `--config <path>` | load a specific config file | otherwise uses config discovery from the current working directory |
+| `--env <name>` | select `config.env.<name>` before compilation | this affects the resolved config written to generated output |
+| `--debug` | show stack traces on failure | mainly useful when config loading, compilation, or the Vite build subprocess fails |
+
 ### `deploy`
 
 `devflare deploy` performs the same config-resolution step, then builds and runs Wrangler deploy.
@@ -1343,10 +1594,39 @@ Important nuances:
 
 So do not assume build-time code sees identical environment flags under `build` and `deploy`.
 
+Usage:
+
+```text
+devflare deploy [--config <path>] [--env <name>] [--dry-run] [--debug]
+```
+
+Flags:
+
+| Flag | Meaning | Notes |
+|---|---|---|
+| `--config <path>` | load a specific config file | otherwise uses config discovery from the current working directory |
+| `--env <name>` | select `config.env.<name>` during Devflare compilation and forward the same env to `wrangler deploy` | this is the most important CLI env flag to understand |
+| `--dry-run` | print the resolved compiled Wrangler config and exit | current implementation exits before writing `wrangler.jsonc`, running `vite build`, or calling Wrangler |
+| `--debug` | show stack traces on failure | useful for config/build/deploy debugging |
+
 ### `types`
 
 `devflare types` generates `env.d.ts`, which is a key part of the typed Devflare workflow.
 
+Usage:
+
+```text
+devflare types [--config <path>] [--output <path>] [--debug]
+```
+
+Flags:
+
+| Flag | Meaning | Notes |
+|---|---|---|
+| `--config <path>` | load a specific config file | otherwise defaults to the current project’s normal config discovery |
+| `--output <path>` | choose the output path for generated types | defaults to `env.d.ts` |
+| `--debug` | show stack traces on failure | useful when discovery or generation fails |
+
 ### `doctor`
 
 `devflare doctor` is a project diagnostics command.
@@ -1363,12 +1643,113 @@ It currently checks for things such as:
 
 Use it as a quick environment sanity check, not as a proof that every runtime behavior is correct.
 
+Usage:
+
+```text
+devflare doctor
+```
+
+Current flag behavior:
+
+- there are no command-specific public flags documented for `doctor` right now
+- current implementation checks Vite-related files only when the current package appears to opt into Vite integration
+- do not assume `--config <path>` currently redirects `doctor` in the same way it does for `build`, `deploy`, `dev`, or `types`
+
+### `account`
+
+Usage:
+
+```text
+devflare account [subcommand] [--account <accountId>]
+```
+
+Flags:
+
+| Flag | Meaning | Notes |
+|---|---|---|
+| `--account <accountId>` | inspect or mutate a specific Cloudflare account instead of the primary account | most useful for `info`, `workers`, `kv`, `d1`, `r2`, `vectorize`, `limits`, and `usage`; the interactive `global` and `workspace` selectors do not depend on it |
+
+Subcommands:
+
+| Subcommand | Meaning | Notes |
+|---|---|---|
+| `info` | show account overview | default when no subcommand is provided |
+| `workers` | list Workers scripts | requires Cloudflare auth |
+| `kv` | list KV namespaces | requires Cloudflare auth |
+| `d1` | list D1 databases | requires Cloudflare auth |
+| `r2` | list R2 buckets | requires Cloudflare auth |
+| `vectorize` | list Vectorize indexes | requires Cloudflare auth |
+| `limits` | show current Devflare-managed usage limits | supports nested actions described below |
+| `usage` | show current usage summary | requires Cloudflare auth |
+| `global` | interactively choose the global default account | stores selection under `~/.devflare/preferences.json` and may sync to cloud KV |
+| `workspace` | interactively choose the workspace account | writes nearest `package.json` |
+
+Nested `limits` actions:
+
+```text
+devflare account limits
+devflare account limits enable
+devflare account limits disable
+devflare account limits set <limit-name> <value>
+```
+
+Valid current limit names are:
+
+- `ai-requests`
+- `ai-tokens`
+- `vectorize-ops`
+
+### `ai`
+
+Usage:
+
+```text
+devflare ai
+```
+
+This command currently has no command-specific public flags. It prints Workers AI pricing/reference data.
+
+### `remote`
+
+Usage:
+
+```text
+devflare remote [status]
+devflare remote enable [minutes]
+devflare remote disable
+```
+
+This command currently has no command-specific flags. It is driven by subcommands and an optional positional minutes value.
+
+Important current behavior:
+
+- `status` is the default when you run `devflare remote` with no subcommand
+- `enable [minutes]` defaults to `30` when minutes are omitted or invalid
+- CLI enablement clamps duration into the current supported range of `1` to `1440` minutes
+- `disable` removes stored CLI remote-mode state, but does **not** unset `DEVFLARE_REMOTE`
+
+### `help` and `version`
+
+Usage:
+
+```text
+devflare help
+devflare version
+devflare --help
+devflare --version
+devflare -h
+devflare -v
+```
+
+The command forms and flag forms are equivalent public entrypoints.
+
 ### 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/data/` local persisted Miniflare state when you run `devflare dev --persist`
 - `.devflare/wrangler.jsonc` generated by the Vite plugin integration
 - generated `env.d.ts`
 
@@ -1610,7 +1991,12 @@ These are core Devflare strengths today:
 	 - 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**
+14. **there is no stable public local-R2 browser URL contract today**
+	 - Devflare uses internal `/_devflare/*` routes for dev-server behavior
+	 - treat those as implementation details rather than app-facing URLs
+	 - if you build local preview tooling, keep object keys as the durable identifier and treat preview URLs as disposable
+
+15. **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:
@@ -1748,4 +2134,6 @@ If you only remember a few things, remember these:
 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`
+13. store R2 object keys as the durable identifier instead of storing full delivery URLs
+14. treat local preview or inspector URLs as dev conveniences, not as the production file-delivery contract
+15. when native config does not cover a Wrangler feature, use `wrangler.passthrough`

package/R2.md

@@ -0,0 +1,170 @@
+# R2
+
+A short guide for handling uploads and file delivery with Cloudflare R2.
+
+---
+
+## Quick rules
+
+- Use **presigned `PUT` URLs** for direct user uploads to R2
+- Use a **public bucket on a custom domain** for truly public assets
+- Use a **private bucket + Worker authorization** for authenticated/private assets
+- Use **Cloudflare Access** for teammate/org-only buckets
+- Use **WAF token auth / HMAC validation** or a **Worker** for expiring custom-domain media links
+- Do **not** use `r2.dev` for production delivery
+- If you protect a custom-domain bucket with Access or WAF, **disable `r2.dev`** or the bucket may still be reachable there
+
+---
+
+## Uploads
+
+The usual safe upload flow is:
+
+1. frontend asks your app for upload permission
+2. your Worker/app authenticates the user and validates file type, size, and target key
+3. your backend returns a short-lived **presigned `PUT` URL**
+4. the browser uploads **directly to R2**
+5. your app stores the **object key + metadata**, not the presigned URL
+
+Good practice:
+
+- generate keys server-side, for example `users/<userId>/<uuid>.jpg`
+- restrict `Content-Type` when signing uploads
+- keep upload URLs short-lived
+- configure bucket **CORS** if the browser uploads directly
+
+Cloudflare docs:
+
+- [Presigned URLs](https://developers.cloudflare.com/r2/api/s3/presigned-urls/)
+- [Configure CORS](https://developers.cloudflare.com/r2/buckets/cors/)
+- [Storing user generated content](https://developers.cloudflare.com/reference-architecture/diagrams/storage/storing-user-generated-content/)
+
+---
+
+## Viewing / serving files
+
+### Public files
+
+For public images, media, and assets:
+
+- use a **public bucket**
+- attach a **custom domain**
+- serve stable URLs from that domain
+- let Cloudflare cache them
+
+This is the best fit for avatars, product images, blog images, and other content that anyone may view.
+
+Cloudflare docs:
+
+- [Public buckets](https://developers.cloudflare.com/r2/buckets/public-buckets/)
+
+### Private or authenticated files
+
+For invoices, receipts, private user uploads, paid content, or tenant-scoped assets:
+
+- keep the bucket **private**
+- store only the object key in your database
+- serve through a **Worker** that checks session/JWT/permissions before reading from R2
+
+This is usually the best default when access depends on the current user.
+
+Cloudflare docs:
+
+- [Use R2 from Workers](https://developers.cloudflare.com/r2/api/workers/workers-api-usage/)
+
+### Time-limited direct access
+
+You can also mint a **presigned `GET` URL** for temporary direct viewing or download.
+
+Important caveat:
+
+- presigned URLs work on the **R2 S3 endpoint**
+- they **do not work with custom domains**
+- treat them as **bearer tokens**
+
+So they are good for short-lived direct access, but not for polished custom-domain media delivery.
+
+Cloudflare docs:
+
+- [Presigned URLs](https://developers.cloudflare.com/r2/api/s3/presigned-urls/)
+
+### Team-only / org-only files
+
+If access should be limited to employees or teammates, protect the R2 custom domain with **Cloudflare Access**.
+
+Cloudflare docs:
+
+- [Protect an R2 Bucket with Cloudflare Access](https://developers.cloudflare.com/r2/tutorials/cloudflare-access/)
+
+### Signed links on a custom domain
+
+If you want expiring links on `https://cdn.example.com/...`, R2 presigned URLs are not the right tool.
+
+Instead use:
+
+- a **Worker** that signs and verifies access tokens, or
+- **Cloudflare WAF token authentication / HMAC validation** on the custom domain
+
+Cloudflare docs:
+
+- [Configure token authentication](https://developers.cloudflare.com/waf/custom-rules/use-cases/configure-token-authentication/)
+- [HMAC validation function](https://developers.cloudflare.com/ruleset-engine/rules-language/functions/#hmac-validation)
+- [Workers request signing example](https://developers.cloudflare.com/workers/examples/signing-requests/)
+
+---
+
+## Development vs production
+
+### Development
+
+By default, local Worker development uses **local simulated bindings**, including local R2-style storage.
+
+Use this for normal development.
+
+Only connect to real remote buckets when you intentionally need integration testing, and prefer **separate dev/staging buckets** instead of production buckets.
+
+Important remote-dev reality:
+
+- remote bindings touch **real data**
+- remote bindings incur **real costs**
+- avoid pointing local development at production uploads unless absolutely necessary
+
+Cloudflare docs:
+
+- [Workers development & testing](https://developers.cloudflare.com/workers/development-testing/)
+- [Remote bindings](https://developers.cloudflare.com/workers/development-testing/#remote-bindings)
+
+### Production
+
+For production:
+
+- use a **custom domain**, not `r2.dev`
+- choose public vs private intentionally per bucket or per content class
+- keep sensitive content private behind a Worker, Access, or token validation
+- configure **CORS** intentionally for browser upload/download flows
+- use separate **dev**, **staging**, and **prod** buckets
+
+Optional performance feature:
+
+- if users upload from many regions, consider **Local Uploads** for better upload performance
+
+Cloudflare docs:
+
+- [Public buckets](https://developers.cloudflare.com/r2/buckets/public-buckets/)
+- [Local uploads](https://developers.cloudflare.com/r2/buckets/local-uploads/)
+
+---
+
+## Recommended defaults
+
+If you need a sane default architecture:
+
+- **public assets** → public bucket + custom domain
+- **user uploads** → presigned `PUT` upload + object key stored in DB
+- **private assets** → private bucket + Worker-gated reads
+- **internal assets** → custom domain + Cloudflare Access
+- **custom-domain expiring links** → Worker token auth or WAF HMAC validation
+
+If you only remember one rule, remember this:
+
+> Use **presigned URLs** for short-lived direct R2 access, but use a **Worker/custom domain auth layer** for polished private media delivery.

package/dist/bridge/proxy.d.ts

@@ -20,14 +20,13 @@ export declare function createEnvProxy(options?: EnvProxyOptions & {
 /**
  * Get the global env proxy for bridge RPC
  *
- * Note: This is distinct from `devflare/runtime`'s `env` which provides
- * request-scoped context access. Use `bridgeEnv` for standalone bridge usage
- * (e.g., testing, scripts) and the runtime `env` within request handlers.
+ * Note: This is distinct from the published `import { env } from 'devflare'`
+ * proxy, which provides unified request/test/bridge-aware access.
+ * Use `bridgeEnv` for standalone internal bridge usage and `env` from the
+ * main package within request handlers and normal test flows.
  *
  * @example
  * ```ts
- * import { bridgeEnv } from 'devflare'
- *
  * await bridgeEnv.MY_KV.get('key')
  * await bridgeEnv.MY_DO.get(id).fetch(request)
  * ```