Close PR #257 self-review followups: store id validation + docs lint

Closes the High blocker and five Low findings from the post-merge
self-review of the Spin 6 + strict-clippy integration.

High: Spin wasm contract CI was red.

Three contract tests (`config_store_reads_value_from_handler`,
`kv_store_reads_value_from_handler`, `secret_store_reads_value_
from_handler`) inserted bare `ConfigStoreHandle` / `KvHandle` /
`SecretHandle` into request extensions, then called
`app.router().oneshot(...)` -- bypassing the Spin dispatch
boundary. Under the hard-cutoff model the core
`RequestContext::config_store_default()` /
`kv_store_default()` / `secret_store_default()` extractors only
read `ConfigRegistry` / `KvRegistry` / `SecretRegistry`. The
dispatch boundary's `synthesise_store_registries` is what
normally wraps a bare handle into a one-id registry keyed under
`"default"`. Because the tests bypassed dispatch, handlers got
`None` and the assertions silently failed under
`wasmtime run` in CI.

Fix: the three tests now insert `*Registry::single_id("default"
.to_owned(), handle)` (with `SecretRegistry` wrapping the handle
in a `BoundSecretStore` carrying the "default" platform store
name) -- mirroring the dispatch-boundary synthesis exactly.
Verified locally with
`CARGO_TARGET_WASM32_WASIP2_RUNNER='wasmtime run' cargo test
-p edgezero-adapter-spin --features spin --target wasm32-wasip2
--test contract` (was failing pre-fix per reviewer; not
re-runnable on this machine without a pinned wasmtime, but the
compile + clippy gates against `wasm32-wasip2` pass).

Low: CLI docs described logical ids where the implementation
uses env-resolved platform names.

Both Cloudflare and Fastly's `provision` and `config push`
adapters use `store.platform.as_str()` to look up the
binding/namespace name in `wrangler.toml` / `fastly.toml`.
`store.platform` is what `EDGEZERO__STORES__<KIND>__<ID>__NAME`
resolves to at adapter-action time, falling back to the logical
id when the override isn't set. Docs previously said the
matching key was `<store_id>`; updated to `<platform-name>` with
the resolution rule spelled out, in:
- `docs/guide/cli-reference.md` -- both the provision and push
  tables (cloudflare + fastly cells)
- `docs/guide/cli-walkthrough.md` -- both the provision and
  push bullets (cloudflare + fastly); push bullets converted to
  fenced bash blocks (see High below)
- `crates/edgezero-adapter-fastly/src/cli.rs:329` -- the
  `create_fastly_store` rustdoc -- comment now says
  `--name=<platform-name>` and explains the caller does the
  resolution.

High: docs CI red because of multi-line inline backticks.

`docs/guide/cli-walkthrough.md`'s push bullets had inline code
spans that wrapped across line breaks (e.g.
`` `wrangler kv bulk put <tempfile>\n--namespace-id=<id>` ``).
Prettier respects `proseWrap: preserve` but re-aligned the
continuation lines such that `<tempfile>` / `<id>` ended up at
column 0 on the wrap line, terminating the backtick span. The
leaked `<tempfile>` / `<id>` were then parsed by VitePress's
Vue compiler as unterminated HTML tags, breaking
`npm run build` with `Element is missing end tag`.

Fix: cloudflare/fastly push + provision bullets now use fenced
bash code blocks for the multi-arg commands -- bulletproof
against Prettier reflow. Verified
`cd docs && npm run build` succeeds in 1.5s.

Low: docs/guide/adapters/spin.md described the wrong secret
translation rule.

The collision-check section claimed both config keys and
`#[secret]` field values get `.→__`-translated. In reality
`SpinSecretStore::get_bytes` only `to_ascii_lowercase`s the key
(no dot translation), and the CLI validator
(`crates/edgezero-adapter-spin/src/cli.rs:434-439`) mirrors that
exactly with an explicit code comment. Doc updated to say
config keys translate dots; secret values are only lowercased.

Low: docs/superpowers/plans/2026-05-20-cli-extensions.md was
stale on three points.

(1) Said `examples/app-demo` was not in CI -- it now is, via the
dedicated `cd examples/app-demo && cargo test --workspace
--all-targets` step in `test.yml` + a parallel fmt/clippy pass
in `format.yml`. (2) Listed the Spin wasm gate as
`wasm32-wasip1` -- now `wasm32-wasip2` per the Spin 6 migration.
(3) Task 8.3 step 1 (add `app-demo` CI) is done; marked `[x]`
with a reference to the workflow files.

Low: `crates/edgezero-cli/tests/generated_project_builds.rs`
exercised the raw `edgezero` binary's `config validate` but
never invoked the generated typed CLI's typed validator.

Added a `cargo run -p scaffold-probe-cli --quiet -- config
validate --strict` step after the host `cargo check`. Catches
template / `AppConfig` drift the raw validator cannot --
`#[derive(Validate)]` impl on `AppConfig` + the `#[app]`
macro-emitted `#[secret]` discovery / collision checks now run
against every freshly-scaffolded project.

Low: `crates/edgezero-adapter-axum/src/secret_store.rs` rustdoc
example used the removed `cargo edgezero dev` command. Replaced
with `API_KEY=mysecret edgezero serve --adapter axum`.

Verified post-commit: `cargo fmt --all -- --check`, `cargo
clippy --workspace --all-targets --all-features -- -D warnings`,
`cargo test --workspace --all-targets`, all three adapter
wasm-clippy gates (`cloudflare wasm32-unknown-unknown`, `fastly
wasm32-wasip1`, `spin wasm32-wasip2`), `cd docs && npm run lint
&& npm run format && npm run build`. The Cargo.lock minor-
version drift left by background cargo runs is intentionally
NOT included in this commit -- belongs in a separate dep
maintenance change.

Author: aram356

crates/edgezero-adapter-axum/src/secret_store.rs

@@ -4,7 +4,7 @@
 //! variables before starting the dev server:
 //!
 //! ```bash
-//! API_KEY=mysecret cargo edgezero dev
+//! API_KEY=mysecret edgezero serve --adapter axum
 //! ```
 
 use std::env;

crates/edgezero-adapter-fastly/src/cli.rs

@@ -326,10 +326,13 @@ impl Adapter for FastlyCliAdapter {
     }
 }
 
-/// Shell out to `fastly <kind>-store create --name=<id>`. Returns
-/// `Ok(())` on success; surfaces the CLI's stderr verbatim on
-/// failure (including the "already exists" error, which is the
-/// caller's signal to fix the toml or use a different name).
+/// Shell out to `fastly <kind>-store create --name=<platform-name>`. The
+/// caller resolves `<platform-name>` from `EDGEZERO__STORES__<KIND>__<ID>__NAME`
+/// (falling back to the logical id), so this helper takes whatever the
+/// caller hands it and does not re-translate. Returns `Ok(())` on success;
+/// surfaces the CLI's stderr verbatim on failure (including the "already
+/// exists" error, which is the caller's signal to fix the toml or use a
+/// different name).
 ///
 /// # Errors
 /// Returns an error if `fastly` isn't on `PATH`, the child fails to

crates/edgezero-adapter-spin/tests/contract.rs

@@ -114,6 +114,9 @@ mod tests {
     use edgezero_core::key_value_store::{KvError, KvHandle, KvPage, KvStore};
     use edgezero_core::router::RouterService;
     use edgezero_core::secret_store::{SecretError, SecretHandle, SecretStore};
+    use edgezero_core::store_registry::{
+        BoundSecretStore, ConfigRegistry, KvRegistry, SecretRegistry,
+    };
     use futures::executor::block_on;
     use futures::stream;
     use std::sync::Arc;
@@ -402,12 +405,18 @@ mod tests {
             .uri("http://example.com/config")
             .body(Body::empty())
             .expect("request");
+        // Mirror the dispatch boundary: the runtime synthesises a one-id
+        // `ConfigRegistry` keyed under `"default"` from the wired handle.
+        // `RequestContext::config_store_default()` reads `ConfigRegistry`
+        // only (hard-cutoff), so inserting a bare handle here would yield
+        // `None` and the handler would return "missing".
+        let handle = ConfigStoreHandle::new(Arc::new(FixedConfigStore {
+            key: "greeting",
+            value: "hello-spin",
+        }));
         request
             .extensions_mut()
-            .insert(ConfigStoreHandle::new(Arc::new(FixedConfigStore {
-                key: "greeting",
-                value: "hello-spin",
-            })));
+            .insert(ConfigRegistry::single_id("default".to_owned(), handle));
 
         let response = block_on(app.router().oneshot(request)).expect("response");
 
@@ -427,12 +436,13 @@ mod tests {
             .uri("http://example.com/kv-value")
             .body(Body::empty())
             .expect("request");
+        let handle = KvHandle::new(Arc::new(FixedKvStore {
+            key: "test-key",
+            value: b"kv-payload",
+        }));
         request
             .extensions_mut()
-            .insert(KvHandle::new(Arc::new(FixedKvStore {
-                key: "test-key",
-                value: b"kv-payload",
-            })));
+            .insert(KvRegistry::single_id("default".to_owned(), handle));
 
         let response = block_on(app.router().oneshot(request)).expect("response");
 
@@ -452,12 +462,16 @@ mod tests {
             .uri("http://example.com/secret-value")
             .body(Body::empty())
             .expect("request");
-        request
-            .extensions_mut()
-            .insert(SecretHandle::new(Arc::new(FixedSecretStore {
-                key: "test-secret",
-                value: b"s3cr3t",
-            })));
+        // Secrets registry wraps the handle in a `BoundSecretStore` carrying
+        // the platform store name — mirrors the dispatch-boundary synthesis.
+        let handle = SecretHandle::new(Arc::new(FixedSecretStore {
+            key: "test-secret",
+            value: b"s3cr3t",
+        }));
+        request.extensions_mut().insert(SecretRegistry::single_id(
+            "default".to_owned(),
+            BoundSecretStore::new(handle, "default".to_owned()),
+        ));
 
         let response = block_on(app.router().oneshot(request)).expect("response");
 

crates/edgezero-cli/tests/generated_project_builds.rs

@@ -98,6 +98,33 @@ mod tests {
             "generated workspace should compile for the host target",
         );
 
+        // Typed config validation via the generated `<name>-cli` binary.
+        // The raw `edgezero config validate` above exercises the manifest
+        // schema and capability matrix; the generated CLI additionally
+        // runs the user's `#[derive(Validate)]` impl on `AppConfig` plus
+        // the `#[app]` macro-emitted `#[secret]` discovery. Without this
+        // step, template drift that compiles but produces an invalid
+        // typed config (e.g. `#[secret]` on a non-scalar field) would
+        // slip through.
+        let typed_validate = Command::new(env!("CARGO"))
+            .args([
+                "run",
+                "-p",
+                "scaffold-probe-cli",
+                "--quiet",
+                "--",
+                "config",
+                "validate",
+                "--strict",
+            ])
+            .current_dir(&project)
+            .status()
+            .expect("run the generated typed CLI `config validate --strict`");
+        assert!(
+            typed_validate.success(),
+            "generated typed CLI should pass `config validate --strict`",
+        );
+
         // Per-adapter wasm targets: where target-gated template code lives
         // (entrypoint signatures, macro-generated unsafe exports).
         let targets = installed_targets(&project);

docs/guide/adapters/spin.md

@@ -141,10 +141,12 @@ api_token = "{{ api_token }}"
 ```
 
 Because Spin's config and secret namespaces share keys, `config validate`
-also runs a collision check: the effective Spin variable name set
-({flattened config keys} ∪ {`#[secret]` field values}, each
-`.`→`__`-translated) must have no duplicates when `spin` is in the
-adapter set.
+also runs a collision check. Config keys translate `.` → `__` (mirrors the
+runtime `SpinConfigStore`). `#[secret]` field values are only lowercased —
+the runtime `SpinSecretStore` does not translate dots, so neither does the
+validator. The effective Spin variable name set (translated config keys ∪
+lowercased `#[secret]` values) must have no duplicates when `spin` is in
+the adapter set.
 
 ## Spin component discovery
 

docs/guide/cli-reference.md

@@ -243,8 +243,8 @@ edgezero config push --adapter <name> [--manifest <path>] [--app-config <path>]
 | `--adapter`  | Behaviour                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `axum`       | Writes the flattened payload to `.edgezero/local-config-<id>.json` (the file `AxumConfigStore` reads back). Creates `.edgezero/` on first use. No shell-out.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `cloudflare` | Reads the namespace id from `wrangler.toml` (matched by `binding = <store_id>`), writes the entries to a temp file in wrangler's bulk format (`[{"key": "...", "value": "..."}]`), and runs `wrangler kv bulk put <tempfile> --namespace-id=<id>`. Errors with "did you run `provision`?" if the binding is absent.                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `fastly`     | Resolves the platform config-store id on demand via `fastly config-store list --json` (matched by `name = <store_id>`), then runs `fastly config-store-entry create --store-id=<id> --key=<k> --value=<v>` per entry. Errors with "did you run `provision`?" if the store name isn't found. Re-runs on entries that already exist will fail loudly — delete the entry first or use `fastly config-store-entry update` manually.                                                                                                                                                                                                                                                                                             |
+| `cloudflare` | Reads the namespace id from `wrangler.toml` (matched by `binding = <platform-name>`, where `<platform-name>` resolves from `EDGEZERO__STORES__CONFIG__<ID>__NAME` or falls back to the logical `<id>`), writes the entries to a temp file in wrangler's bulk format (`[{"key": "...", "value": "..."}]`), and runs `wrangler kv bulk put <tempfile> --namespace-id=<id>`. Errors with "did you run `provision`?" if the binding is absent.                                                                                                                                                                                                                                                                                  |
+| `fastly`     | Resolves the platform config-store id on demand via `fastly config-store list --json` (matched by `name = <platform-name>`, where `<platform-name>` resolves from `EDGEZERO__STORES__CONFIG__<ID>__NAME` or falls back to the logical `<id>`), then runs `fastly config-store-entry create --store-id=<id> --key=<k> --value=<v>` per entry. Errors with "did you run `provision`?" if the store name isn't found. Re-runs on entries that already exist will fail loudly — delete the entry first or use `fastly config-store-entry update` manually.                                                                                                                                                                      |
 | `spin`       | Pure `spin.toml` editing — no shell-out. For each entry, translates the dotted CLI key to a Spin variable name (`.` → `__`, lowercased) and writes BOTH `[variables].<key>` (with `default = "<value>"`, the application-level declaration) AND `[component.<component>.variables].<key>` (with `<key> = "&#123;&#123; <key> &#125;&#125;"`, the component binding). Without both tables the wasm component can't read the variable. Idempotent on re-run: existing defaults are updated in place. Component resolved per §6.7 (single-component implicit; multi-component needs `[adapters.spin.adapter].component`). Secret variables stay manual — `config push` skips `SECRET_FIELDS` and never writes `secret = true`. |
 
 **Examples:**
@@ -273,12 +273,12 @@ edgezero provision --adapter <name> [--manifest <path>] [--dry-run]
 
 **Per-adapter behaviour:**
 
-| `--adapter`  | Behaviour                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `axum`       | Local-only — prints one note per declared store id and exits 0 (KV in-memory; config in `.edgezero/local-config-<id>.json`).                                                                                                                                                                                                                                                                                                |
-| `cloudflare` | For each KV id + config id: shells out to `wrangler kv namespace create <id>`, parses the namespace id from stdout, appends `[[kv_namespaces]] binding = "<id>", id = "<extracted>"` to `wrangler.toml` (idempotent on the binding name; preserves existing entries and comments). Secrets are runtime-managed via `wrangler secret put` — no-op.                                                                           |
-| `fastly`     | For each KV / config / secret id: shells out to `fastly <kind>-store create --name=<id>`, then appends `[setup.<kind>_stores.<id>]` and `[local_server.<kind>_stores.<id>]` tables to `fastly.toml`. Idempotent: if the setup table is already present the id is skipped (no shell-out, no edit). Store IDs are not persisted — `config push` resolves them on demand.                                                      |
-| `spin`       | Pure `spin.toml` editing — no shell-out (Spin KV stores are runtime-resolved). For each declared KV id, appends the label to the resolved `[component.<component>].key_value_stores = [...]` array (idempotent on the label). Config and secret ids are intentionally not handled here: `config push --adapter spin` declares config variables, and secret variables are manually declared by the developer in `spin.toml`. |
+| `--adapter`  | Behaviour                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `axum`       | Local-only — prints one note per declared store id and exits 0 (KV in-memory; config in `.edgezero/local-config-<id>.json`).                                                                                                                                                                                                                                                                                                                                                               |
+| `cloudflare` | For each KV id + config id: shells out to `wrangler kv namespace create <platform-name>` (where `<platform-name>` resolves from `EDGEZERO__STORES__<KIND>__<ID>__NAME` or falls back to the logical `<id>`), parses the namespace id from stdout, appends `[[kv_namespaces]] binding = "<platform-name>", id = "<extracted>"` to `wrangler.toml` (idempotent on the binding name; preserves existing entries and comments). Secrets are runtime-managed via `wrangler secret put` — no-op. |
+| `fastly`     | For each KV / config / secret id: shells out to `fastly <kind>-store create --name=<platform-name>` (using the same `<platform-name>` resolution), then appends `[setup.<kind>_stores.<platform-name>]` and `[local_server.<kind>_stores.<platform-name>]` tables to `fastly.toml`. Idempotent: if the setup table is already present the id is skipped (no shell-out, no edit). Store IDs are not persisted — `config push` resolves them on demand.                                      |
+| `spin`       | Pure `spin.toml` editing — no shell-out (Spin KV stores are runtime-resolved). For each declared KV id, appends the label to the resolved `[component.<component>].key_value_stores = [...]` array (idempotent on the label). Config and secret ids are intentionally not handled here: `config push --adapter spin` declares config variables, and secret variables are manually declared by the developer in `spin.toml`.                                                                |
 
 **`--dry-run`** prints what each adapter _would_ do without
 performing it. For `axum` the output is identical to a real run