refactor: split port diagnostics helpers

docs/concepts/agent-workspace.md

@@ -37,6 +37,19 @@ file creation:
 { agent: { skipBootstrap: true } }
 ```
 
+## Legacy workspace folders
+
+Older installs may have created `~/clawdis` or `~/clawdbot`. Keeping multiple
+workspace directories around can cause confusing auth or state drift, because
+only one workspace is active at a time.
+
+**Recommendation:** keep a single active workspace. If you no longer use the
+legacy folders, archive or move them to Trash (for example `trash ~/clawdis`).
+If you intentionally keep multiple workspaces, make sure
+`agent.workspace` points to the active one.
+
+`clawdbot doctor` warns when it detects legacy workspace directories.
+
 ## Workspace file map (what each file means)
 
 These are the standard files Clawdbot expects inside the workspace:

docs/gateway/troubleshooting.md

@@ -39,6 +39,15 @@ clawdbot daemon status
 It will show the listener(s) and likely causes (gateway already running, SSH tunnel).
 If needed, stop the service or pick a different port.
 
+### Legacy Workspace Folders Detected
+
+If you upgraded from older installs, you might still have `~/clawdis` or
+`~/clawdbot` on disk. Multiple workspace directories can cause confusing auth
+or state drift because only one workspace is active.
+
+**Fix:** keep a single active workspace and archive/remove the rest. See
+[Agent workspace](/concepts/agent-workspace#legacy-workspace-folders).
+
 ### "Agent was aborted"
 
 The agent was interrupted mid-response.