From 18264a5b76965d1f8076b3a211ed0ff32597adf0 Mon Sep 17 00:00:00 2001
From: Steven RYDELL <srydell@gmx.com>
Date: Sat, 1 Aug 2026 18:39:33 +0200
Subject: [PATCH] docs(dev): add troubleshooting section, fix stale "one
 command" claim

Add a Troubleshooting section to DEVELOPMENT.md covering the case that
just happened: npm run dev only reads .env.development.local at
startup, so regenerating a token or restarting the Docker container
while it's already running silently leaves the UI unable to reach the
backend until it's restarted.

README.md's "one command" claim for spinning up the test server was
stale since dev-server-init.sh became a separate one-time step.
---
 DEVELOPMENT.md | 19 +++++++++++++++++++
 README.md      |  2 +-
 2 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index 87af2a5..4ca12d4 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -122,6 +122,25 @@ npm run dev:server
 bash ./scripts/dev-server-init.sh   # re-run: fresh volume needs bootstrapping again
 ```
 
+## Troubleshooting
+
+- **UI shows a login screen instead of the admin panel, or the page fails
+  to load data**: `npm run dev` only reads `.env.development.local` at
+  startup. If you regenerate a token, or restart the Docker container,
+  while `npm run dev` is already running, stop it (Ctrl+C) and start it
+  again — it won't pick up the new token or reconnect on its own.
+- **`Failed to fetch` / connection refused in the browser console**: the
+  test server isn't running or isn't ready yet. Check with
+  `docker ps --filter name=stalwart-webui-dev` and
+  `npm run dev:server:logs`; wait for `Network listener started ...
+  localPort = 8080` before retrying.
+- **401s after everything was working**: your token expired. Re-run
+  `scripts/dev-token.sh` (or `.ps1`) and restart `npm run dev`.
+- **`scripts/dev-server-init.sh` fails with connection errors**: the
+  container needs a few seconds after `npm run dev:server` before it
+  accepts requests — the script retries for ~30s, but if your machine is
+  slow, just re-run it.
+
 ## Notes for AI agents
 
 - This whole workflow (steps 1–4) is scriptable end-to-end without a
diff --git a/README.md b/README.md
index 7137233..0d12aa1 100644
--- a/README.md
+++ b/README.md
@@ -118,7 +118,7 @@ Every tagged release of this fork publishes a `webui.zip` build via CI (see [`.g
 Prerequisites:
 
 - Node.js 18 or later
-- A running Stalwart instance (for JMAP API calls) — see [DEVELOPMENT.md](DEVELOPMENT.md) for how to spin up a disposable local test server with Docker in one command, no manual Stalwart setup required.
+- A running Stalwart instance (for JMAP API calls) — see [DEVELOPMENT.md](DEVELOPMENT.md) for how to spin up a disposable local test server with Docker, no manual Stalwart setup required.
 
 Install dependencies: