docs(desktop): document the server log and startup diagnostic page

Refs #174

Author: ApocDev

docs/development/desktop.md

@@ -47,12 +47,40 @@ PYOPS_MIGRATIONS_DIR=<bundled drizzle directory>
 PYOPS_MOD_DIR=<bundled mod directory>
 ```
 
-The shell drains the child-process output channel and retains its handle so shutdown can
-terminate the server cleanly.
+The shell retains the child-process handle so shutdown can terminate the server cleanly,
+and passes each path through `dunce` so Windows sidecars receive plain `C:\…` paths rather
+than `\\?\`-prefixed extended-length paths.
 
 This split is why server path code must use `app/src/server/paths.server.ts`. The current
 working directory is not a reliable resource or data root in a packaged application.
 
+### Server log
+
+In a packaged build, everything the server prints — stdout and stderr — is written to
+`server.log` in the app-data directory, interleaved with launcher lifecycle lines that are
+stamped with seconds since launch (`[launcher +0.2s] server ready, opening the app`). Each
+launch starts a fresh log; the previous launch's log is kept as `server.log.old`.
+
+This file is the primary diagnostic for startup failures on user machines: it records the
+resolved server entry path, the data directory, spawn errors, server crashes with their
+exit code, and the server's own output. Ask a user to attach it before anything else.
+Logging must never take the app down: if the file cannot be created, logging is silently
+disabled and startup proceeds.
+
+Development builds do not write it — the server runs in the developer's terminal.
+
+### Startup failure page
+
+The shell waits up to 90 seconds for the server port, and bails out immediately if the
+server process exits or fails to spawn. If the server is not reachable, the window opens
+with a built-in diagnostic page instead of the webview's network-error page: it explains
+that the local server has not come up, shows the `server.log` path to attach to a bug
+report, and offers a retry button.
+
+The page is not a dead end. The launcher keeps polling the port behind it and swaps in the
+application the moment the server becomes reachable, which absorbs slow first launches
+(for example, antivirus software scanning a fresh install).
+
 ### Fixed port and single instance
 
 The webview URL uses fixed port `34115`. `tauri-plugin-single-instance` is registered before

docs/troubleshooting/faq.md

@@ -32,6 +32,24 @@ Yes. Create a separate project and sync it from the appropriate Factorio mod set
 project keeps its own reference data and plan. Confirm the active project before syncing,
 because the sync updates that project.
 
+### The app says it couldn't reach its local server. What now?
+
+The desktop app runs a local server in the background, and that page means the server has
+not come up yet. The window keeps checking and loads the app by itself as soon as the
+server is reachable — a first launch can take a while, for example while antivirus
+software scans the new installation. If nothing happens for a few minutes, close the app
+and start it again.
+
+If it keeps failing, attach `server.log` to a bug report. The page shows its full path;
+it lives in the app's data directory:
+
+- Windows: `%APPDATA%\com.apocdev.pyops\server.log`
+- macOS: `~/Library/Application Support/com.apocdev.pyops/server.log`
+- Linux: `~/.local/share/com.apocdev.pyops/server.log`
+
+The log records what the server printed while starting, so it usually identifies the
+failure directly.
+
 ## Planning behavior
 
 ### Why does PyOps leave ingredients as imports?