diff --git a/stacks/gateway-chat/README.md b/stacks/gateway-chat/README.md
index dcf0484..d2c631c 100644
--- a/stacks/gateway-chat/README.md
+++ b/stacks/gateway-chat/README.md
@@ -36,3 +36,45 @@ ssh ana-docker 'cd /opt/docker/compose/gateway-chat && docker compose up -d'
 
 Set the gateway base URL + an API key in the page's sidebar (persists in `localStorage`),
 then hit ↻ to load the model list.
+
+## ⚠️ Single-file bind mount — a `--conf` deploy is NOT enough
+
+`compose.yaml` bind-mounts **one file**:
+
+```
+/opt/docker/conf/gateway-chat/index.html -> /usr/share/nginx/html/index.html
+```
+
+A single-file bind mount binds the **inode**, not the path. `deploy-stack.sh`
+uses rsync, which writes a new file and renames it over the old one — a *new*
+inode — so the container keeps serving the **old** content indefinitely. The host
+file and the container's view silently disagree, and nothing errors.
+
+Observed 2026-08-16: host showed `value="4096"`, container and HTTP still served
+`value="1024"`.
+
+**Always follow a conf deploy of this stack with a recreate:**
+
+```bash
+scripts/deploy-stack.sh ana-docker gateway-chat --conf --yes
+ssh infra-ops@10.250.50.70 'cd /opt/docker/compose/gateway-chat && sudo docker compose up -d --force-recreate'
+```
+
+`docker restart` does **not** fix it — the stale inode is already bound. Verify
+against what the container actually sees, never the host file:
+
+```bash
+docker exec gateway-chat grep -oE 'id="max"[^>]*value="[0-9]+"' /usr/share/nginx/html/index.html
+```
+
+Applies to any stack whose mount source is a FILE rather than a directory.
+Directory mounts do not have this problem.
+
+## Max tokens default
+
+Raised 1024 → 4096 (2026-08-16). Every thinking seat on this gateway
+(`gen-reasoning`, `char-rp-reasoning`) spends part of the completion budget on
+CoT before emitting content, so a 1024 cap truncates mid-sentence with
+`finish_reason=length` — which reads as the *model* being degenerate when it is
+purely a client-side cap. Measured: `gen-reasoning` at 1024 → `finish=length`,
+cut mid-word; at 4096 → clean stop at 839 words.
diff --git a/stacks/gateway-chat/conf/index.html b/stacks/gateway-chat/conf/index.html
index e575e44..df7ae53 100644
--- a/stacks/gateway-chat/conf/index.html
+++ b/stacks/gateway-chat/conf/index.html
@@ -65,7 +65,13 @@
     <textarea id="sys" placeholder="You are a helpful assistant."></textarea>
     <div class="row">
       <div><label>Temperature</label><input id="temp" type="number" step="0.05" value="1"></div>
-      <div><label>Max tokens</label><input id="max" type="number" step="1" value="1024"></div>
+      <!-- 4096, not 1024: every thinking seat on this gateway (gen-reasoning,
+           char-rp-reasoning) spends part of the completion budget on CoT before
+           emitting any content, so a 1024 cap truncates mid-sentence with
+           finish_reason=length and reads as the MODEL being degenerate. Measured
+           2026-08-16: gen-reasoning at 1024 -> finish=length cut mid-word; at
+           4096 -> clean stop at 839 words. -->
+      <div><label>Max tokens</label><input id="max" type="number" step="1" value="4096"></div>
     </div>
     <label style="margin-top:.5rem">🔊 TTS (quoted text)</label>
     <label class="hint" style="display:flex;gap:.45rem;align-items:center;margin:.15rem 0"><input id="ttsOn" type="checkbox" style="width:auto"> Auto-play quoted dialogue</label>