diff --git a/scripts/README.md b/scripts/README.md
new file mode 100644
index 0000000..bd6dce3
--- /dev/null
+++ b/scripts/README.md
@@ -0,0 +1,50 @@
+# scripts/
+
+Dev-only utility scripts. These are NOT bundled by `npm run build` — the
+production `dist/` contains zero `smoke` artifacts (verified by
+`grep -rn smoke dist/` returning empty post-build).
+
+## Smoke-isolation invariant
+
+`smoke.sh` and any future smoke-test harness live ENTIRELY in this
+directory. Vite's `rollupOptions.input` (vite.config.ts) does NOT
+reference any path under `scripts/`; the build pipeline cannot include
+smoke artifacts in `dist/`. RESEARCH §12 verifies no-op condition via
+`grep -rn 'smoke\|SMOKE\|data:text/html' src/` returning empty.
+
+A defensive `__VITE_DEV__` define-token (see `vite.config.ts:define`)
+is reserved for any future inline smoke-mode check; currently it
+defaults to `false` so even a misplaced `if (__VITE_DEV__) { ... }`
+branch is statically tree-shaken out of production by Rollup.
+
+Override per-build via env var:
+
+```bash
+VITE_DEV=1 npm run dev    # __VITE_DEV__ === true
+npm run build              # __VITE_DEV__ === false (production default)
+```
+
+## Index
+
+| Script                    | Purpose                                                              |
+|---------------------------|----------------------------------------------------------------------|
+| `subset-fonts.sh`         | One-off font subsetting (Lora + IBM Plex Sans/Mono → Latin+Cyrillic) |
+| `rasterize-icons.sh`      | One-off icon rasterization (mokosh-mark.svg → icons/icon{16,48,128}.png) |
+| `smoke.sh` (if present)   | Local smoke harness — not part of `npm run build`                    |
+
+Re-run conditions:
+
+- `subset-fonts.sh`: when upstream Lora-Cyrillic or IBM/plex releases a
+  major bump with bug fixes; or when the UNICODES range needs
+  expansion. See `src/shared/fonts/README.md` for the canonical recipe.
+- `rasterize-icons.sh`: when `src/shared/brand/mokosh-mark.svg` changes
+  (the source-of-truth for the toolbar icon).
+
+## References
+
+- `.planning/phases/01-stabilize-video-pipeline/01-12-PLAN.md` Wave 5
+  Task 1 — the smoke-isolation contract this README documents
+- `.planning/phases/01-stabilize-video-pipeline/01-12-RESEARCH.md` §12
+  — verification rationale
+- `.planning/intel/brand-decisions-v1.md` D-09 — dev-only smoke
+  shipping decision
diff --git a/vite.config.ts b/vite.config.ts
index d99ab19..76c869d 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -38,6 +38,16 @@ export default defineConfig({
   // Reference: https://vite.dev/config/shared-options.html#define
   define: {
     __MOKOSH_UAT__: 'false',
+    // Plan 01-12 Wave 5 (RESEARCH §12 + D-09 spirit-satisfaction):
+    // Defensive token reserved for any future inline smoke-mode check.
+    // Currently the smoke harness lives entirely in `smoke.sh` outside
+    // Vite's input set — verified by `grep -rn 'smoke\|SMOKE\|data:text/html' src/`
+    // returning empty. Activated by setting the env var `VITE_DEV=1`
+    // before invoking `vite` / `vite build`; defaults to `false` so the
+    // gated branch (if any future plan adds one) is statically tree-
+    // shaken out of production. See scripts/README.md for the wider
+    // dev-script isolation invariant.
+    __VITE_DEV__: JSON.stringify(process.env.VITE_DEV === '1'),
   },
   build: {
     // Plan 01-11: bump from default ES2020 to ES2022 so gated top-level