@@ -6,9 +6,9 @@
 //!
 //! ## Storage Location
 //!
-//! By default, the development server stores data at `.edgezero/kv.redb`
-//! in your project directory. Custom store names get their own derived
-//! database file under `.edgezero/`. Add this path to your `.gitignore`:
+//! The development server stores each declared KV store in its own file,
+//! `.edgezero/kv-<slug>-<hash>.redb`, derived from the resolved store name
+//! (see `kv_store_path` in `dev_server.rs`). Add this path to your `.gitignore`:
 //!
 //! ```gitignore
 //! .edgezero/
 
@@ -911,9 +911,10 @@ pub trait KvStore: Send + Sync {
     /// Store raw bytes with a time-to-live. After `ttl` has elapsed the key
     /// should be treated as expired. Eviction timing is backend-specific:
     /// - **Axum (`PersistentKvStore`)**: lazy eviction — expired keys are removed
-    ///   on the next `get_bytes` call for that key. Keys never accessed after
-    ///   expiration remain in the database until deleted, so `.edgezero/kv.redb`
-    ///   grows without bound on long-running dev servers.
+    ///   on the next `get_bytes` call for that key, or by any `list_keys` scan
+    ///   that reaches them. Keys neither read nor listed after expiration remain
+    ///   in the store's `.edgezero/kv-<slug>-<hash>.redb` file, which grows
+    ///   without bound on long-running dev servers.
     /// - **Fastly/Cloudflare**: eviction is managed by the platform and is not
     ///   guaranteed to be immediate.
     async fn put_bytes_with_ttl(
 
@@ -38,6 +38,7 @@ export default defineConfig({
           { text: 'Middleware', link: '/guide/middleware' },
           { text: 'Streaming', link: '/guide/streaming' },
           { text: 'Proxying', link: '/guide/proxying' },
+          { text: 'KV Storage', link: '/guide/kv' },
         ],
       },
       {
 
@@ -27,14 +27,15 @@ crates/my-app-adapter-axum/
 The Axum entrypoint wires the adapter:
 
 ```rust
+use edgezero_adapter_axum::dev_server::run_app;
 use my_app_core::App;
 
 fn main() -> anyhow::Result<()> {
-    edgezero_adapter_axum::run_app::<App>()
+    run_app::<App>()
 }
 ```
 
-`run_app` installs `simple_logger`, builds the app, and reads bind /
+`run_app` installs `simple_logger` (unless `owns_logging = true`), builds the app, and reads bind /
 store / logging config at runtime from `EDGEZERO__*` environment
 variables (see [the migration guide](../manifest-store-migration.md)).
 The portable store metadata baked into `App` by the `app!` macro
@@ -82,20 +83,26 @@ The binary is placed in `target/release/my-app-adapter-axum`.
 The Axum adapter provides a native HTTP client for proxying:
 
 ```rust
-use edgezero_adapter_axum::AxumProxyClient;
+use edgezero_adapter_axum::proxy::AxumProxyClient;
 use edgezero_core::proxy::ProxyService;
 
-let client = AxumProxyClient::default();
+let client = AxumProxyClient::try_new()?;
 let response = ProxyService::new(client).forward(request).await?;
 ```
 
-This uses `reqwest` under the hood for outbound HTTP requests.
+This uses `reqwest` under the hood for outbound HTTP requests. `try_new` is
+fallible because it builds a `reqwest::Client`; it returns a `reqwest::Error` if
+the TLS backend cannot be initialised on the host.
 
 ## Logging
 
-The Axum adapter's `run_app` helper installs `simple_logger` and reads logging configuration
-from `edgezero.toml` (level and `echo_stdout`). If you want a different logger, wire your own
-entrypoint using `App::build_app()` and `AxumDevServer`.
+The Axum adapter's `run_app` helper installs `simple_logger` at the level read from
+`EDGEZERO__LOGGING__LEVEL`, falling back to `info` when the variable is unset or
+unparseable. It does not read `edgezero.toml`, and `echo_stdout` has no effect on
+the runtime. To install a different logger, set `owns_logging = true` on your `app!`
+declaration so `run_app` skips its own logger, then install yours in `main`. Wiring
+`App::build_app()` and `AxumDevServer` by hand remains the fallback if you also need
+to control the bind address or store setup.
 
 ::: tip Logging status
 `run_app` wires logging automatically; custom entrypoints should install a logger explicitly.
@@ -136,6 +143,31 @@ cargo test -p my-app-core
 cargo test -p my-app-adapter-axum
 ```
 
+## KV Storage
+
+Each declared `[stores.kv]` id resolves to a `redb`-backed store on disk under
+`.edgezero/`, so values persist across dev-server restarts. The file name is
+derived from the platform store name, which comes from
+`EDGEZERO__STORES__KV__<ID>__NAME` or defaults to the logical id:
+
+```
+.edgezero/kv-<slug>-<hash>.redb
+```
+
+The database file grows over time and does not shrink after deletions. To reclaim
+space, delete the file in `.edgezero/`; the data is lost. See [KV Storage](/guide/kv)
+for the portable API.
+
+## Secret Store
+
+A declared `[stores.secrets]` id resolves to an `EnvSecretStore`, which looks up each
+secret name verbatim in the process environment. Axum lists `secrets` in its
+`single_store_kinds`, so only one secrets id may be declared:
+
+```bash
+API_KEY=mysecret edgezero serve --adapter axum
+```
+
 ## Config Store
 
 For local development, each declared `[stores.config]` id resolves to a
@@ -205,8 +237,14 @@ CMD ["my-app-adapter-axum"]
 Configure the Axum adapter in `edgezero.toml`. See [Configuration](/guide/configuration) for the full
 manifest reference.
 
-The `axum.toml` file is used by the Axum CLI helper to locate the crate and display the port.
-The runtime currently binds to `127.0.0.1:8787` regardless of the `axum.toml` port value.
+The `axum.toml` file is used by the Axum CLI helper to locate the crate and carry a
+default port. `edgezero serve --adapter axum` resolves the bind address with this
+precedence, highest first: the `EDGEZERO__ADAPTER__HOST` / `EDGEZERO__ADAPTER__PORT`
+environment variables, then `[adapters.axum.adapter]` in `edgezero.toml`, then
+`axum.toml`, then `127.0.0.1:8787`. The CLI passes the resolved address to the child
+process as `EDGEZERO__ADAPTER__HOST` / `EDGEZERO__ADAPTER__PORT`. Running the binary
+directly bypasses that resolution: it reads only those two environment variables and
+otherwise falls back to `127.0.0.1:8787`.
 
 ## Development Workflow
 
@@ -231,7 +269,7 @@ A typical development workflow:
 | Concurrency | Multi-threaded | Single-threaded   |
 
 ::: tip Development Parity
-While Axum provides a convenient development environment, always test on actual edge platforms before deploying. Some edge-specific features (KV stores, geolocation) aren't available in the Axum adapter.
+While Axum provides a convenient development environment, always test on actual edge platforms before deploying. Provider-specific behaviour such as store backends and request context differs on the real targets.
 :::
 
 ## Next Steps
 
@@ -5,7 +5,7 @@ Deploy EdgeZero applications to Cloudflare Workers using WebAssembly.
 ## Prerequisites
 
 - [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/)
-- worker-builder: `cargo install worker-builder`
+- worker-build: `cargo install worker-build`
 - Rust `wasm32-unknown-unknown` target: `rustup target add wasm32-unknown-unknown`
 
 ## Project Setup
@@ -28,10 +28,10 @@ The Wrangler manifest configures your Worker:
 ```toml
 name = "my-app"
 main = "build/worker/shim.mjs"
-compatibility_date = "2024-01-01"
+compatibility_date = "2023-05-01"
 
 [build]
-command = "edgezero build --adapter cloudflare"
+command = "worker-build --release"
 ```
 
 ### Entrypoint
@@ -56,10 +56,35 @@ derived from the baked store ids and queried individually). Per-id
 request extensions automatically. No `edgezero.toml` is loaded by
 the runtime — see [the migration guide](../manifest-store-migration.md).
 
-The low-level `dispatch()` helper remains available only for fully manual wiring and does not inject
-store metadata. Prefer `run_app` or `dispatch_with_config` for normal use.
-`dispatch_with_config_handle` exists for advanced/manual cases where you already have a prepared
-`ConfigStoreHandle`.
+For fully manual wiring, `CloudflareService::new(&app)` builds a dispatcher one
+store at a time: `.with_config(binding)` (a KV binding name),
+`.with_config_handle(handle)`, `.with_kv(binding)`, `.with_secrets()`, the
+matching `.require_kv()` / `.require_secrets()` flags, and finally
+`.dispatch(req, env, ctx).await`, which needs the worker `Env` and `Context`
+to open bindings:
+
+```rust
+use edgezero_adapter_cloudflare::request::CloudflareService;
+use edgezero_core::app::Hooks as _;
+use my_app_core::App;
+use worker::*;
+
+#[event(fetch)]
+pub async fn main(req: Request, env: Env, ctx: Context) -> Result<Response> {
+    let app = App::build_app();
+    CloudflareService::new(&app)
+        .with_config("app_config")
+        .with_kv("sessions")
+        .dispatch(req, env, ctx)
+        .await
+}
+```
+
+This path takes bindings verbatim and does not resolve `EDGEZERO__STORES__*`
+selectors, so prefer `run_app` unless you are mocking a backend.
+`run_app` dispatches through an internal registry-based path; unlike Fastly's
+`dispatch_with_registries`, it is not part of the Cloudflare adapter's public
+API.
 
 ## Building
 
@@ -98,7 +123,7 @@ wrangler deploy --cwd crates/my-app-adapter-cloudflare
 Cloudflare Workers use the global `fetch` API for outbound requests:
 
 ```rust
-use edgezero_adapter_cloudflare::CloudflareProxyClient;
+use edgezero_adapter_cloudflare::proxy::CloudflareProxyClient;
 use edgezero_core::proxy::ProxyService;
 
 let client = CloudflareProxyClient;
@@ -124,7 +149,7 @@ Access Cloudflare-specific APIs via the request context extensions:
 
 ```rust
 use edgezero_core::context::RequestContext;
-use edgezero_adapter_cloudflare::CloudflareRequestContext;
+use edgezero_adapter_cloudflare::context::CloudflareRequestContext;
 
 async fn handler(ctx: RequestContext) -> Result<Response, EdgeError> {
     if let Some(cf_ctx) = CloudflareRequestContext::get(ctx.request()) {
@@ -138,19 +163,18 @@ async fn handler(ctx: RequestContext) -> Result<Response, EdgeError> {
 }
 ```
 
-## Environment Variables & Secrets
+## Environment Variables
 
-Define variables in `wrangler.toml`:
+Define non-secret variables in `wrangler.toml`; the adapter reads the
+`EDGEZERO__*` selectors from the same `[vars]` table:
 
 ```toml
 [vars]
 API_URL = "https://api.example.com"
-
-# Secrets are set via wrangler CLI
-# wrangler secret put API_KEY
 ```
 
-Access in handlers via the Cloudflare context or environment bindings.
+Secrets go through the Worker secret store instead; see
+[Secret Store](#secret-store).
 
 ## Config Store
 
@@ -174,23 +198,61 @@ id      = "abc123…"
 
 The binding name comes from `EDGEZERO__STORES__CONFIG__APP_CONFIG__NAME`
 (defaulting to the logical id `app_config` when unset). Populate the
-namespace via `wrangler kv:key put`. Missing bindings log a one-time
+namespace via `wrangler kv key put`. Missing bindings log a one-time
 warning and the id is dropped from the registry. See
 [the migration guide](../manifest-store-migration.md) if you are coming
 from the pre-rewrite `[vars]`-backed JSON-string form.
 
+KV and config share the same `[[kv_namespaces]]` binding space on Cloudflare,
+so the same logical id must not appear under both `[stores.kv]` and
+`[stores.config]`; both would resolve to a single underlying namespace at
+runtime. `edgezero config validate` rejects the collision.
+
+## Secret Store
+
+Worker Secrets is a single flat bag with no namespace concept, so exactly one
+`[stores.secrets]` id is permitted; `edgezero config validate --strict` rejects
+more than one. Handlers read values through the `Secrets` extractor or
+`ctx.secret_store(id)`, and a secret with no matching binding resolves to `None`
+rather than erroring.
+
+```toml
+# edgezero.toml
+[stores.secrets]
+ids = ["default"]
+```
+
+Populate secrets with the Wrangler CLI; there is no binding flag, since the
+secret name is the binding:
+
+```bash
+wrangler secret put API_KEY
+```
+
 ## KV Storage
 
-Use Cloudflare KV for edge storage:
+Each declared `[stores.kv]` id maps to a KV namespace binding, exactly like a
+config id:
+
+```toml
+# edgezero.toml
+[stores.kv]
+ids = ["sessions"]
+```
 
 ```toml
 # wrangler.toml
 [[kv_namespaces]]
-binding = "MY_KV"
-id = "abc123"
+binding = "sessions"
+id      = "abc123…"
 ```
 
-Access via the Cloudflare environment bindings in your handler.
+The binding name comes from `EDGEZERO__STORES__KV__SESSIONS__NAME`, defaulting
+to the logical id. `edgezero provision --adapter cloudflare` creates the
+namespace and appends the binding for you. Handlers reach the store through the
+portable `Kv` extractor or `ctx.kv_store(id)`; a hand-picked binding that is not
+declared under `[stores.kv]` is never opened. See [KV Storage](/guide/kv) for
+the API.
 
 ## Durable Objects
 
@@ -206,7 +268,7 @@ bindings = [
 
 ## Streaming
 
-Cloudflare Workers support streaming via `ReadableStream`. The adapter automatically converts `Body::stream` to Cloudflare's streaming format.
+Cloudflare Workers support streaming via `ReadableStream`. The adapter automatically converts `Body::Stream` to Cloudflare's streaming format.
 
 See the [Streaming guide](/guide/streaming) for examples and patterns.
Original file line number	Diff line number	Diff line change
`@@ -38,6 +38,7 @@ export default defineConfig({`
`38`	`38`	`{ text: 'Middleware', link: '/guide/middleware' },`
`39`	`39`	`{ text: 'Streaming', link: '/guide/streaming' },`
`40`	`40`	`{ text: 'Proxying', link: '/guide/proxying' },`
	`41`	`+ { text: 'KV Storage', link: '/guide/kv' },`
`41`	`42`	`],`
`42`	`43`	`},`
`43`	`44`	`{`