From bed5419409ac8f6f6a1945acfbddf1e74384965f Mon Sep 17 00:00:00 2001
From: Pedro Gomes <pedro.gomes@wavefunctionvr.com>
Date: Sat, 16 May 2026 17:42:04 +0100
Subject: [PATCH] update readme for offline tests

---
 .claude/settings.local.json |  5 ++++-
 README.md                   | 21 +++++++++++++++++++++
 2 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/.claude/settings.local.json b/.claude/settings.local.json
index f0f0a2d..3fae1ae 100644
--- a/.claude/settings.local.json
+++ b/.claude/settings.local.json
@@ -42,7 +42,10 @@
       "Bash(pnpm --filter @repo/e2e exec tsc --noEmit)",
       "Bash(pnpm exec *)",
       "Bash(pnpm test:e2e)",
-      "Bash(pnpm -w run test:e2e)"
+      "Bash(pnpm -w run test:e2e)",
+      "Bash(netstat -ano)",
+      "Bash(findstr \"LISTENING\")",
+      "Bash(findstr -E \"3000|3001|9000|9001|5432\")"
     ]
   }
 }
diff --git a/README.md b/README.md
index 835b547..e4b9873 100644
--- a/README.md
+++ b/README.md
@@ -84,6 +84,12 @@ pnpm --filter @repo/admin-web dev
 Chrome DevTools → Network → Offline → create 3 requests → Network → Online.  
 The requests sync automatically within ~10 s; "Tudo sincronizado" appears.
 
+> ⚠️ The offline navigation test only works against a **production build** of
+> `operator-pwa`. In `pnpm dev` mode, Next.js generates page chunks on demand,
+> so the service worker has nothing to precache and navigation to
+> `/maintenance/new` fails with `Failed to fetch`. See the
+> [Troubleshooting](#troubleshooting) section for the workaround.
+
 ### As admin / maintenance supervisor (port 3001)
 
 1. Open http://localhost:3001 — it lands on the maintenance queue.
@@ -240,6 +246,21 @@ pkill -f 'next dev'
 (`docker compose ps`) and that the `fieldops` bucket exists
 (`docker logs fieldops-minio-init-1`).
 
+**Offline navigation fails with `Failed to fetch` / `NetworkOnly`** — the PWA
+service worker can only serve pages it has precached, and `pnpm dev` builds
+pages on demand (no precache). To test the full offline flow, run the
+operator PWA in production mode:
+```sh
+# Stop the running `pnpm dev` for operator-pwa first, then:
+pnpm --filter @repo/operator-pwa build
+pnpm --filter @repo/operator-pwa start
+```
+Load http://localhost:3000 once while online (so the SW precaches the shell),
+reload the tab to activate the new SW, then switch DevTools to Offline. The
+admin-web can stay in `dev` mode — only the operator PWA needs the production
+build for offline navigation. The IndexedDB sync queue itself works in both
+modes; only the page-navigation layer requires precache.
+
 ---
 
 ## License