diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md
index 074cb8d..3c36495 100644
--- a/DEPLOYMENT.md
+++ b/DEPLOYMENT.md
@@ -491,6 +491,21 @@ docker compose --env-file .env.test -f docker-compose.prod.yml logs --tail=100 w
 docker compose --env-file .env.test -f docker-compose.prod.yml logs --tail=100 caddy
 ```
 
+## If localhost still looks wrong after the server is fixed
+Use this order before assuming the local checkout is missing code:
+1. hard refresh the page with `Cmd + Shift + R`
+2. clear site data for `127.0.0.1:8088` in browser devtools and sign in again
+3. restart the local web container:
+   ```bash
+   docker compose restart web
+   ```
+4. if it still survives, rebuild the local stack:
+   ```bash
+   docker compose up -d --build
+   ```
+
+This is the correct recovery path for stale browser state, shared-header fixes, page-local CSS fixes, and versioned static asset updates.
+
 ## Rollback
 This deployment path is source-upload based, not image-tag based.
 
diff --git a/backend/workflows/templates/workflows/developer_handbook.html b/backend/workflows/templates/workflows/developer_handbook.html
index 49d6389..87cf19e 100644
--- a/backend/workflows/templates/workflows/developer_handbook.html
+++ b/backend/workflows/templates/workflows/developer_handbook.html
@@ -624,6 +624,20 @@ make backup-verify BACKUP_DIR=backups/backup_YYYYmmdd_HHMMSS</code></pre>
     </div>
 
     <h2 id="troubleshooting">20) Troubleshooting</h2>
+    <div class="box">
+      <h3>Localhost still looks stale after the server is already fixed</h3>
+      <ol>
+        <li>Hard refresh the page with <code>Cmd + Shift + R</code>.</li>
+        <li>If it still looks wrong, clear site data for <code>127.0.0.1:8088</code> in the browser devtools and sign in again.</li>
+        <li>Restart the local web container:
+          <pre><code>docker compose restart web</code></pre>
+        </li>
+        <li>If the issue still survives, rebuild the local stack:
+          <pre><code>docker compose up -d --build</code></pre>
+        </li>
+      </ol>
+      <p>This is the right order when shared header fixes, page-local CSS fixes, or versioned static assets look correct on the server but localhost still shows the old UI.</p>
+    </div>
     <ul>
       <li><strong>Page looks stale:</strong> restart <code>web</code> and hard-refresh browser</li>
       <li><strong>Second request hangs:</strong> inspect web logs and verify health endpoint</li>