diff --git a/documentation/BOOTSTRAP__AI_Agent_Quickstart.md b/documentation/BOOTSTRAP__AI_Agent_Quickstart.md
index d07125fa..bd76d8ae 100644
--- a/documentation/BOOTSTRAP__AI_Agent_Quickstart.md
+++ b/documentation/BOOTSTRAP__AI_Agent_Quickstart.md
@@ -308,8 +308,10 @@ Read this section first, then open the reference doc when your task touches one
    field, SWR-await-after-write races, and stateful/conditional sync gates that desync local
    state from history rather than current config. See the Pres Mgmt Config sync overhaul
    (2026-06-16) in `PROJECT__AE_Events_PressMgmt_Config_Cleanup.md` for the full incident.
-10. **`param?: Type` in `.svelte` function/snippet parameters** — breaks `vite build` (SSR step)
-    silently: dev server is fine, Docker/production builds fail with "Expected ',', got '?'".
+10. **`param?: Type` in `.svelte` function/snippet parameters** — breaks both dev and production.
+    In dev mode, saving the file triggers HMR which produces `SyntaxError: missing ) after formal
+    parameters` and crashes the page with a 500. In production, `vite build` fails at the SSR step
+    with "Expected ',', got '?'". `npx svelte-check` does NOT catch this — it requires a full build.
     Use `param: Type | undefined = undefined` instead. See mistake #19 in the reference doc.
 
 The reference doc also includes a short archive list for older, less-relevant historical incidents.
diff --git a/documentation/REFERENCE__Common_Agent_Mistakes.md b/documentation/REFERENCE__Common_Agent_Mistakes.md
index e4f36ef8..4d1a299f 100644
--- a/documentation/REFERENCE__Common_Agent_Mistakes.md
+++ b/documentation/REFERENCE__Common_Agent_Mistakes.md
@@ -250,9 +250,11 @@ the gate is ever actually in the "off" state before assuming it needs to exist.
 
 ### 19) `param?: Type` in `.svelte` function or snippet parameter positions
 
-**Impact:** `vite build` SSR step fails with "Expected ',', got '?'" — Docker builds and
-production deploys break. Dev server is unaffected (different code path), so the error is
-invisible in local development and only surfaces in CI/CD or the first clean Docker build.
+**Impact:** Breaks both dev and production. In dev mode, Vite's HMR recompile produces
+`SyntaxError: missing ) after formal parameters` in `app.js`, which crashes the page with a
+500 error immediately after saving the file. In production, `vite build` fails at the SSR
+step with "Expected ',', got '?'" — Docker builds and deploys break. The error surfaces in
+both environments; do not assume the dev server is a safe testing ground for this.
 
 **What happened:** Source files used TypeScript optional-parameter syntax (`param?: Type`)
 inside `.svelte` `<script lang="ts">` functions and `{#snippet}` parameter lists. esbuild