salvage: uncommitted work from /home/jwoltje/distrobox-homes/mosaic-dev/src/stack-p5a (disk cleanup #824, 2026-11-06)

docs/webui/PHASE-P-STRUCTURE.md

@@ -78,6 +78,19 @@ Legend: `──` new SPA (keep), `══` legacy Next (removed at P5), shared `l
 At **P5** the `:vite` variants become the defaults (`dev`→vite, `build`→vite build) and the Next
 build path is retired.
 
+### Gateway serving scripts (`apps/gateway/package.json`) — P5a polarity
+
+| Script  | Mode set                       | Behavior                                                 |
+| ------- | ------------------------------ | -------------------------------------------------------- |
+| `dev`   | `GATEWAY_WEB_UI_MODE=required` | builds the Vite bundle first, then serves it same-origin |
+| `start` | `GATEWAY_WEB_UI_MODE=disabled` | API-only; compiled gateway, no Web UI routes             |
+
+The `start` polarity is deliberate and fail-closed: if a bundle is present at `apps/web/dist`
+(e.g. left over from `dev` or `build:vite`), `start` **refuses to boot** rather than serve a stale,
+unvetted bundle. That is the intended tripwire, not a bug — remove the stale bundle
+(`rm -rf apps/web/dist`) or opt in explicitly with `GATEWAY_WEB_UI_MODE=required`. The startup error
+names both remedies.
+
 ## 5. Increment map (P1–P6)
 
 | #      | Increment                                                                                                                                      | Branch                        | Status                    |