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: