Summary

During a safe-mode recovery session, two documentation gaps caused extended debugging:

Issue 1: Token Updates - Missing habitat-parsed.env

Current state: TOOLS.md mentions /etc/habitat-parsed.env in Key Paths but doesn't explain its role.

Problem: When Discord bot tokens are regenerated, the safe-mode agent only updated ~/.openclaw/openclaw.full.json. However, recovery scripts read tokens from /etc/habitat-parsed.env, causing repeated fallback to safe mode.

Proposed fix: Add a section explaining:

• Both files must be updated when tokens change
• habitat-parsed.env is the source of truth for safe-mode-recovery.sh
• Step-by-step commands for updating both files

Issue 2: OAuth Re-auth - Hidden tmux session

Current state: TOOLS.md shows using tmux new-session -d for the OAuth wizard.

Problem: The -d flag creates a detached (hidden) session. The user couldn't see the wizard on their RDP desktop, and the callback flow failed because the terminal wasn't visible.

Proposed fix:

• Clarify that the terminal must be VISIBLE on DISPLAY=:10
• Use xfce4-terminal or xterm instead of detached tmux
• Add warning about the -d flag

Files affected

• /usr/local/bin/setup-safe-mode-workspace.sh (generates TOOLS.md)
• Or wherever safe-mode workspace templates are stored

Context

This came from a real debugging session where the safe-mode agent spent ~45 minutes troubleshooting these issues. Clear documentation would have resolved them in minutes.

Happy to provide full updated TOOLS.md content if helpful.