Align guide docs with the code on main

[aram356]

Summary

• A page-by-page audit of docs/guide against the current crates found names that no longer exist, behaviour the code contradicts, and public surface with no coverage. This PR fixes what the audit turned up, so a reader following the guides lands on APIs and commands that exist and behave as described.
• The audit ran as a rerunnable identifier/flag/link cross-check over every page plus a source-cited review per page group; 66 findings landed, each verified against the cited source line before editing.

Changes

Crate / File	Change
docs/guide/adapters/fastly.md	Replace phantom dispatch_with_config* with the FastlyService builder; add Custom entry points (runtime_env_config, dispatch_with_registries, RUNTIME_ENV_STORE_NAME, both footguns); buffering, -C, manifest_version = 3, [setup], proxy:: import
docs/guide/adapters/cloudflare.md	CloudflareService builder; worker-build build command; context:: / proxy:: imports; wrangler kv key put; Secret Store section; kv/config merged-id collision
docs/guide/adapters/axum.md	dev_server::run_app, AxumProxyClient::try_new(), bind-address precedence, EDGEZERO__LOGGING__LEVEL, owns_logging; KV Storage and Secret Store sections; KV no longer listed as unavailable
docs/guide/adapters/spin.md	Logging, Proxy Client, Context Access, Testing sections; required = true vs default = ""
docs/guide/adapters/overview.md	Streaming current state, proxy-header and logging lists include Spin, Spin Tests, Store Capabilities table, Adapter trait hooks in onboarding
docs/guide/streaming.md, proxying.md	Only Cloudflare preserves progressive delivery; SpinProxyClient, AxumProxyClient::try_new()?
docs/guide/routing.md, handlers.md, middleware.md, kv.md	Duplicate routes panic at build; Store Extractors (Kv, Config, Secrets, AppConfig<C>); FnMiddleware / middleware_arc; Axum KV file naming
docs/guide/configuration.md	app! argument table; adapter metadata component / host / port; auth-* command overrides; rename_all and store_ref rules; compiling secret-resolution example
docs/guide/blob-app-config-migration.md	config push --staging as the supported staging path; Axum env-var and wrangler secret put forms; canary key in examples; config.rs diff entry point
docs/guide/manifest-store-migration.md	EDGEZERO__LOGGING__* rows; drop dispatch_with_*_handle
docs/guide/cli-reference.md, cli-walkthrough.md	-C / --manifest-path serve and deploy forms; healthcheck outputs and token behaviour; Cloudflare --binding --local; pushed-key / pushed-store; EDGEZERO_MANIFEST scope; my-app.toml in the tree; lifecycle commands in the generated CLI
docs/guide/deploy-github-actions.md, docs/specs/edgezero-deploy-github-action.md	cache/restore@v6 + cache/save@v6, no checkout; cache-key components; artifact retention and job summary
docs/guide/architecture.md, what-is-edgezero.md, roadmap.md, docs/index.md	Spin in the layout, adapter list, feature table, platform table, feature cards; Spin moved to Completed; dispatch_with_config dropped from the diagram
docs/.vitepress/config.mts	KV Storage added to the sidebar
crates/edgezero-adapter-axum/src/key_value_store.rs	Module doc: .edgezero/kv-<slug>-<hash>.redb, not the removed .edgezero/kv.redb default

Closes

Closes #372
Closes #361
Closes #77

Test plan

• cargo fmt --all -- --check
• Docs build: cd docs && npm run lint && npm run format && npm run build
• Other: every behavioural claim edited was checked against the cited source line; the identifier/flag/link cross-check over docs/guide reports only placeholder app names and third-party names
• cargo test --workspace --all-targets (no Rust code changed; one //! comment)
• cargo clippy --workspace --all-targets --all-features -- -D warnings (not applicable)
• cargo check --workspace --all-targets --features "fastly cloudflare spin" (not applicable)
• WASM builds (not applicable)
• examples/app-demo workspace (not applicable)
• Manual testing via edgezero serve --adapter axum (not applicable)

Checklist

• Changes follow CLAUDE.md conventions
• No Tokio deps added to core or adapter crates
• Route params use {id} syntax (not :id)
• Types imported from edgezero_core (not http crate)
• Store wiring goes through KvRegistry / ConfigRegistry / SecretRegistry (not the legacy single-handle setters) — see spec §6.6
• New code has tests (docs only)
• No secrets or credentials committed

[ChristianPavilonis]

Summary

Reviewed the locked PR revision against its base. The documentation alignment is broadly correct, with five actionable documentation corrections noted inline.

[prk-Jr]

PR Review

Summary

A genuinely high-quality audit — the corrections I spot-checked held up against source almost without exception, and at least one of them (the Fastly streaming claim) removes a description that was never true of this codebase. Findings below are mostly the audit's own blind spot: places where a correction landed in one file but the identical stale text, or a directly adjacent claim, was left behind. One finding is a hard blocker because it would not compile.

😃 Praise

• The streaming rewrite fixes a fabricated claim. stream_to_client appears nowhere in crates/ — the old text described an API that does not exist. fastly/src/response.rs:18-25 really does drain the whole Body::Stream via executor::block_on(stream.next()) into a fastly::Body before returning. Correctly scoped, and correctly left alone for Cloudflare, which genuinely streams via CfResponse::from_stream (cloudflare/src/response.rs:30).
• The Axum bind-precedence rewrite is exact and complete, covering both paths: CLI (axum/src/cli.rs:473-540, env → edgezero.toml → axum.toml → addr::DEFAULT_*) and direct-binary (dev_server.rs:517-519, which passes None, None so only env or default apply). The old "binds to 127.0.0.1:8787 regardless of axum.toml" was stale.
• The Store Capabilities table is correct in every cell across all four adapters, including the gc_config_entries / staging-lifecycle exclusivity claim.
• The cache-key component list matches resolve-project.sh:224 term for term, workspace path and build-args hash included.

Findings

Blocking

• 🔧 Cloudflare's dispatch_with_registries is pub(crate) — inline on docs/guide/adapters/cloudflare.md:85. Would fail to compile if a reader follows the Fastly page's import pattern.

• 🔧 Fastly custom entry point omits the owns_logging guard — inline on docs/guide/adapters/fastly.md:145. Breaks the "full parity" promise the section is built on.

• 🔧 cargo install worker-builder installs nothing — the crate is worker-build. docs/guide/adapters/cloudflare.md:8 (unchanged by this PR) still says:

  - worker-builder: `cargo install worker-builder`
  

  This PR changed line 34 to command = "worker-build --release", matching cloudflare/src/templates/wrangler.toml.hbs:6 — correct, and now sitting 26 lines below a prerequisite command that fails. worker-builder appears nowhere else in the repo. Cheap to fix while in the file.

• 🔧 The same stale wrangler command survives in a file this PR edited. docs/guide/manifest-store-migration.md:182 still reads Populate the namespace via `wrangler kv:key put` . This PR fixed that exact string in cloudflare.md:201 (wrangler kv key put), and the repo's own CLI uses the space form (cloudflare/src/cli.rs:134). The colon form is the deprecated pre-3.60 spelling. Same one-word fix.

Non-blocking

• ♻️ proxying.md gained SpinProxyClient but the two bullets above it still say "Fastly and Cloudflare". The PR updated line 59; lines 56-57 were left:

  • L56 "Fastly and Cloudflare preserve streaming bodies; Axum buffers outbound bodies before sending." Spin buffers too, and harder than Axum — spin/src/proxy.rs:29 calls collect_body_bytes, which errors above 16 MiB (spin/src/response.rs:19,38-42). A reader who has just been introduced to Spin's proxy client on line 59 is left assuming it streams.
  • L57 "Fastly and Cloudflare automatically decode gzip/br responses for you." Spin does this as well — spin/src/proxy.rs:52 (decompress_body), stripping content-encoding/content-length at :66-70.

  (The Fastly/Cloudflare halves of L56 are correct: fastly/src/proxy.rs:183-193 writes chunks to a StreamingBody, cloudflare/src/proxy.rs:70-81 uses WorkerBody::from_stream. Proxy streaming and response streaming differ per adapter, which is worth not flattening.)

• ♻️ .edgezero/kv.redb still stands in core. crates/edgezero-core/src/key_value_store.rs:915, in the put_bytes_with_ttl doc comment: "Keys never accessed after expiration remain in the database until deleted, so .edgezero/kv.redb grows without bound on long-running dev servers." This is the identical stale path the PR corrects in the Axum sibling module doc — same fix, one file over.

• 🤔 [local_server.*] framing on fastly.md:41 — inline.

• ⛏ axum.md:272 "(geolocation)" names a gap that does not exist — inline.

• ⛏ key_value_store.rs:9 "each declared KV id" — keyed by resolved store name, not id — inline.

• ⛏ Redundant Ok(…?) on fastly.md:150 — inline.

Verification notes

Claims were checked against source rather than read for plausibility. Verified correct, among others: the FastlyService / CloudflareService builder surfaces (every method name, arity, and sync-vs-async — Fastly's dispatch is sync and consumes self, Cloudflare's is async and takes (req, env, ctx), and both docs get this right); RUNTIME_ENV_STORE_NAME and the EDGEZERO__SERVICES__<ID>__… → canonical-key translation; the two Fastly footguns, both backed by existing tests; manifest_version = 3 against the template; store extractors Kv / Config / Secrets / AppConfig<C> with .default() / .named(); FnMiddleware and middleware_arc (router.rs:155); the duplicate-route panic string (router.rs:105) and the per-adapter timing claim (build_app() per request in fastly/cloudflare/spin lib.rs, once at startup in dev_server.rs:352); EDGEZERO_MANIFEST scope, confirmed at all four load_manifest_optional call sites — run_build, run_deploy, run_serve, and auth.rs:30; --key/--staging exclusivity (config.rs:1389-1401); the healthcheck output shape, including status-code being emitted only when a status arrived (fastly/src/cli.rs:5468-5476); pushed-key / pushed-store; the app! argument table against the macro's own "expected state or owns_logging" error; the adapter metadata keys against the manifest's component/crate/host/manifest/port rejection message; wrangler kv bulk put … --binding … --local (cloudflare/src/cli.rs:474); cache/restore@v6 + cache/save@v6 with no actions/checkout in the composite actions; and if: always() on the job-summary step (deploy-fastly/action.yml:449).

Two caveats on coverage. The Fastly/Cloudflare and Axum/Spin areas were verified exhaustively, file by file. The CLI/config and core-guide areas were verified claim-by-claim via targeted source lookups rather than full reads, so a stale claim there is likelier to have been missed than in the first two.

CI Status

Run against fa40699 merged with main (593fc92):

• cargo fmt --all -- --check: PASS
• cargo clippy --workspace --all-targets --all-features -- -D warnings: PASS
• cargo test --workspace --all-targets: PASS — 1421 passed, 0 failed
• cd docs && npm run lint && npm run format && npm run build: PASS, no dead links

Two trybuild cases corroborate the configuration.md additions directly: secret_store_ref_optional.rs and secret_with_serde_container_rename_all.rs / nested_parent_rename_all.rs all exist as should-fail-to-compile fixtures, so the rename_all and non-Option store_ref rules the PR documents are genuinely enforced.

[aram356]

Addressed the second review in 8f55e2e. The six inline threads each have a reply. The four items that were only in the review body are also in that commit:

• cargo install worker-builder is now cargo install worker-build (cloudflare.md prerequisites).
• wrangler kv:key put in manifest-store-migration.md is now the space form.
• proxying.md's two bullets now include Spin: it buffers outbound bodies with a 16 MiB cap and decodes gzip/br.
• The .edgezero/kv.redb path in core's put_bytes_with_ttl doc comment now names the per-store kv-<slug>-<hash>.redb file.

Docs lint, format, and build pass locally; cargo fmt and the doc tests for the two touched crates pass.