feat(bundled-binary): add a test

Cargo.toml

@@ -48,11 +48,24 @@ async-stream = "0.3.6"
 async-trait = "0.1.89"
 mime_guess = "2.0.5"
 # `rust-embed` — compile-time asset embedding for the `bundled-assets` feature.
-# Optional so default builds never pull it in. `compression` deflate-compresses
-# each embedded file at compile time; the handler decompresses lazily on first
-# read (cached per-file in a `OnceCell`). See src/interfaces/web/embedded.rs
-# for the actual embed struct + handlers.
-rust-embed = { version = "8", features = ["compression", "include-exclude"], optional = true }
+# Optional so default builds never pull it in.
+#
+# Features:
+# * `compression` — deflate-compress each embedded file at compile time; the
+#   handler decompresses lazily on first read (cached per-file in a
+#   `OnceCell`). Halves the on-disk contribution to the final binary.
+# * `include-exclude` — enables the `#[include]` / `#[exclude]` glob
+#   attributes on the derive.
+# * `debug-embed` — CRITICAL. Without this, debug builds read files from
+#   disk at runtime (dynamic mode) instead of compiling them in. The
+#   runtime read is fragile (`CARGO_MANIFEST_DIR` resolution + working
+#   directory dependency) and returned `total=0` for us on 2026-08-28.
+#   With `debug-embed`, both `cargo build` and `cargo build --release`
+#   produce a truly self-contained binary — the only sensible default
+#   for the `bundled-assets` feature.
+#
+# See src/interfaces/web/embedded.rs for the actual embed struct + handlers.
+rust-embed = { version = "8", features = ["compression", "include-exclude", "debug-embed"], optional = true }
 uuid = { version = "1.23.3", features = ["v4", "v7", "serde"] }
 thiserror = "2.0.18"
 arc-swap = "1.9"