fix(tunnel): prefer /etc/cloudflared/ over ~/.cloudflared/ for config detection

The systemd cloudflared service reads from /etc/cloudflared/config.yml,
not ~/.cloudflared/. Flipped detection priority in leader_mode.py and
daemon_spawner.py to check /etc/ first. Updated troubleshooting docs.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: dennys246

docs/troubleshooting/remote_update.md

@@ -75,12 +75,12 @@ maxim peer restart
 
 **Causes (in order of likelihood):**
 1. **Tunnel points at port 8100** (llama-cpp-server) instead of 8099 (LeaderProxy)
-   - Check on leader: `grep service ~/.cloudflared/config.yml`
+   - Check on leader: `grep service /etc/cloudflared/config.yml`
    - Should say `service: http://localhost:8099`
    - Fix: edit config, restart cloudflared
 2. **cloudflared not restarted** after config change
    - `sudo systemctl restart cloudflared` (Linux/systemd)
-   - `pkill -f cloudflared && cloudflared --config ~/.cloudflared/config.yml tunnel run &` (WSL2/manual)
+   - `pkill -f cloudflared && cloudflared --config /etc/cloudflared/config.yml tunnel run &` (WSL2/manual)
 3. **LeaderProxy didn't start** — port 8099 held by stale process
    - Check on leader: `ss -ltnp | grep 8099`
    - Restart maxim
@@ -95,7 +95,7 @@ maxim peer restart
 
 **Fix:** Leaders in leader mode auto-enable this. If it's still disabled:
 - Leader may not be detected as leader. Check: `maxim doctor` → Role section
-- Need either `MAXIM_ROLE=leader` env var or `~/.cloudflared/config.yml` present
+- Need either `MAXIM_ROLE=leader` env var or `/etc/cloudflared/config.yml` present
 - Explicitly: `MAXIM_ALLOW_REMOTE_UPDATE=1 maxim`
 
 ### HTTP 409 — Dirty working tree

src/maxim/runtime/leader_mode.py

@@ -7,8 +7,9 @@
 
 Signals, in priority order:
   1. MAXIM_ROLE env var (explicit)            → "leader" | "client" | "solo"
-  2. ~/.cloudflared/config.yml exists          → leader (implicit)
-  3. default                                   → "solo"
+  2. /etc/cloudflared/config.yml exists        → leader (implicit, systemd)
+  3. ~/.cloudflared/config.yml exists           → leader (implicit, user-space)
+  4. default                                   → "solo"
 
 The leader distinction only changes bind semantics and peer advertising —
 the process itself is still a normal Maxim instance with its own CLI + loop.
@@ -46,11 +47,13 @@ def _env_role() -> str | None:
 def _cloudflared_config_exists() -> Path | None:
     """Return the path to cloudflared's config.yml if present.
 
-    Checks ~/.cloudflared/config.yml and /etc/cloudflared/config.yml.
+    Prefers /etc/cloudflared/ (systemd service, production) over
+    ~/.cloudflared/ (user-space, development). The systemd service
+    reads from /etc/, so that's the authoritative location.
     """
     candidates = [
-        Path.home() / ".cloudflared" / "config.yml",
         Path("/etc/cloudflared/config.yml"),
+        Path.home() / ".cloudflared" / "config.yml",
     ]
     for path in candidates:
         try:

src/maxim/tunnel/daemon_spawner.py

@@ -49,15 +49,15 @@ def cloudflared_already_running() -> bool:
 def resolve_config_path() -> Path | None:
     """Return the cloudflared config path to pass to --config.
 
-    Prefers the user-space config (~/.cloudflared/config.yml, the path
-    `maxim tunnel setup` writes) over the system-wide one, so the daemon
-    uses the same credentials file referenced by the user's config.
-    Falls through to /etc/cloudflared/config.yml if only that exists.
+    Prefers /etc/cloudflared/config.yml (system-wide, used by the
+    systemd service) over ~/.cloudflared/config.yml (user-space).
+    The systemd service is the authoritative tunnel process — its
+    config must match what we expect.
     """
-    if USER_CONFIG_PATH.is_file():
-        return USER_CONFIG_PATH
     if SYSTEM_CONFIG_PATH.is_file():
         return SYSTEM_CONFIG_PATH
+    if USER_CONFIG_PATH.is_file():
+        return USER_CONFIG_PATH
     return None