docs: enhance CLAUDE.md with maintenance table

- Add table of key docs with "When to Update" guidance
- Include TASKS.md, TODO.md, ROADMAP.md, CHANGELOG.md
- Add deployment section with node update commands
- Add Multi-scanner sync and Termux support to key files

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

CLAUDE.md

@@ -2,11 +2,23 @@
 
 RF Environment Scanner for WiFi and Bluetooth signal mapping on Linux.
 
-## Key Documentation
+## Key Documentation (Maintain These!)
+
+| File | Purpose | When to Update |
+|------|---------|----------------|
+| **[TASKS.md](TASKS.md)** | Current sprint tasks, priorities (P0-P3), status | Start/end of each work session |
+| **[TODO.md](TODO.md)** | Backlog by category, completed items | When adding/completing features |
+| **[ROADMAP.md](ROADMAP.md)** | Version milestones, long-term vision | When milestones change |
+| **[CHANGELOG.md](CHANGELOG.md)** | Version history, notable changes | Each release |
+| **[PROJECT.md](PROJECT.md)** | Goals, architecture, dependencies | Major architectural changes |
+| **[USAGE.md](USAGE.md)** | User guide, CLI, web interface, API | When adding features |
+| **[docs/CHEATSHEET.md](docs/CHEATSHEET.md)** | Quick reference commands | When adding features |
+| **[INVENTORY.md](INVENTORY.md)** | Multi-node deployment info (gitignored) | When nodes change |
+
+## Configuration
 
-- **[USAGE.md](USAGE.md)** - User guide with CLI commands, web interface, configuration, and API reference
-- **[TODO.md](TODO.md)** - Pending features and improvements
 - **[config.yaml](config.yaml)** - Current configuration (GPS, web server, scanner, building settings)
+- **[docs/HOME_ASSISTANT.md](docs/HOME_ASSISTANT.md)** - Home Assistant webhook integration
 
 ## Project Structure
 
@@ -22,6 +34,8 @@ src/rf_mapper/
 ├── bluetooth_*.py   # Bluetooth device identification and classification
 ├── visualize.py     # ASCII radar and chart generation
 ├── profiling.py     # CPU/memory profiling utilities
+├── termux.py        # Termux/Android environment detection
+├── sync.py          # Multi-scanner peer sync
 └── web/
     ├── app.py       # Flask application and API endpoints
     ├── templates/   # Jinja2 HTML templates (base.html, index.html)
@@ -38,21 +52,35 @@ src/rf_mapper/
 | Change web UI | `web/templates/index.html`, `static/js/app.js`, `static/css/style.css` |
 | Add configuration | `src/rf_mapper/config.py`, `config.yaml` |
 | Home Assistant integration | `src/rf_mapper/homeassistant.py`, `docs/HOME_ASSISTANT.md` |
+| Multi-scanner sync | `src/rf_mapper/sync.py`, `web/app.py` |
+| Termux/Android support | `src/rf_mapper/termux.py` |
 
 ## Running
 
 ```bash
 source venv/bin/activate
-rf-mapper start        # Start web server (background)
+python -m rf_mapper start        # Start web server (background)
-rf-mapper status       # Check if running
+python -m rf_mapper status       # Check if running
-rf-mapper stop         # Stop server
+python -m rf_mapper stop         # Stop server
-rf-mapper scan -l room # CLI scan
+python -m rf_mapper restart      # Restart server
-rf-mapper --help       # All commands
+python -m rf_mapper scan -l room # CLI scan
+python -m rf_mapper --help       # All commands
+```
+
+## Deployment
+
+See [INVENTORY.md](INVENTORY.md) for multi-node deployment details.
+
+```bash
+# Update and restart all nodes
+cd ~/git/rf-mapper && source venv/bin/activate && git pull && python -m rf_mapper restart
+ssh grokbox "cd ~/git/rf-mapper && source venv/bin/activate && git pull && python -m rf_mapper restart"
+ssh jellystar "cd ~/git/rf-mapper && source venv/bin/activate && git pull && python -m rf_mapper restart"
 ```
 
 ## Tech Stack
 
-- Python 3.10+, Flask, PyYAML, requests
+- Python 3.10+, Flask, PyYAML, requests, bleak
 - Leaflet.js (2D maps), MapLibre GL JS (3D maps)
 - Linux tools: `iw`, bleak (BLE via D-Bus)
 - SQLite for device history

PROJECT.md

@@ -122,14 +122,17 @@ pip install -e .
 ## Quick Start
 
 ```bash
+# Activate virtual environment
+source venv/bin/activate
+
 # Start web server (background)
-rf-mapper start
+python -m rf_mapper start
 
 # Check status
-rf-mapper status
+python -m rf_mapper status
 
 # CLI scan
-rf-mapper scan
+python -m rf_mapper scan
 
 # Open http://localhost:5000
 ```

USAGE.md

@@ -65,7 +65,7 @@ For auto-start on device boot, create `~/.termux/boot/start-rf-mapper.sh`:
 termux-wake-lock
 cd ~/git/rf-mapper
 source venv/bin/activate
-rf-mapper start
+python -m rf_mapper start
 ```
 
 Make it executable:
@@ -91,92 +91,97 @@ pip install -e .
 source venv/bin/activate
 
 # Run interactive scan
-rf-mapper
+python -m rf_mapper
 
 # Start web server
-rf-mapper start
+python -m rf_mapper start
 ```
 
 ## CLI Commands
 
+All commands require activating the virtual environment first:
+```bash
+source venv/bin/activate
+```
+
 ### Scanning
 
 ```bash
 # Basic scan (interactive mode)
-rf-mapper
+python -m rf_mapper
 
 # Scan with location label
-rf-mapper scan -l kitchen
+python -m rf_mapper scan -l kitchen
 
 # Scan WiFi only
-rf-mapper scan --no-bt
+python -m rf_mapper scan --no-bt
 
 # Scan Bluetooth only
-rf-mapper scan --no-wifi
+python -m rf_mapper scan --no-wifi
 
 # Use specific WiFi interface
-rf-mapper scan -i wlan1
+python -m rf_mapper scan -i wlan1
 ```
 
 ### Visualization (CLI)
 
 ```bash
 # Visualize latest scan (ASCII radar + charts)
-rf-mapper visualize
+python -m rf_mapper visualize
 
 # Visualize specific scan file
-rf-mapper visualize -f data/scan_20240131_120000_kitchen.json
+python -m rf_mapper visualize -f data/scan_20240131_120000_kitchen.json
 
 # Analyze RF environment
-rf-mapper analyze
+python -m rf_mapper analyze
 ```
 
 ### Scan History
 
 ```bash
 # List saved scans
-rf-mapper list
+python -m rf_mapper list
 ```
 
 ### Web Server
 
 ```bash
 # Start web server (background daemon)
-rf-mapper start
+python -m rf_mapper start
 
 # Start in foreground (for debugging)
-rf-mapper start --foreground
+python -m rf_mapper start --foreground
 
 # Custom host/port
-rf-mapper start -H 127.0.0.1 -p 8080
+python -m rf_mapper start -H 127.0.0.1 -p 8080
 
 # With debug mode
-rf-mapper start --foreground --debug
+python -m rf_mapper start --foreground --debug
 
 # With request profiling
-rf-mapper start --profile-requests
+python -m rf_mapper start --profile-requests
 
 # With request logging
-rf-mapper start --log-requests
+python -m rf_mapper start --log-requests
 
 # Stop the server
-rf-mapper stop
+python -m rf_mapper stop
 
 # Restart the server
-rf-mapper restart
+python -m rf_mapper restart
 
 # Check server status
-rf-mapper status
+python -m rf_mapper status
 ```
 
 ### Configuration
 
 ```bash
 # Show current configuration
-rf-mapper config
+python -m rf_mapper config
 
 # Set GPS coordinates
-rf-mapper config --set-gps 50.8585 4.3978 --save
+python -m rf_mapper config --set-gps 50.8585 4.3978 --save
 
 # Check Termux prerequisites (Android only)
 rf-mapper check-termux
@@ -462,7 +467,7 @@ adb shell "settings put global settings_enable_monitor_phantom_procs false"
 
 ### Master Dashboard: Node selector not appearing
 1. Verify `is_master: true` in config.yaml
-2. Restart rf-mapper: `rf-mapper restart`
+2. Restart rf-mapper: `python -m rf_mapper restart`
 3. Check peers are registered: `curl http://localhost:5000/api/peers | jq '.peers | length'`
 4. At least one peer must be registered for selector to appear
 

docs/CHEATSHEET.md

@@ -6,21 +6,26 @@ Quick reference for RF Mapper commands and configuration.
 
 ## CLI Commands
 
+All commands require activating the virtual environment first:
+```bash
+source venv/bin/activate
+```
+
 | Command | Description |
 |---------|-------------|
-| `rf-mapper` | Interactive scan mode |
+| `python -m rf_mapper` | Interactive scan mode |
-| `rf-mapper scan` | Run scan with defaults |
+| `python -m rf_mapper scan` | Run scan with defaults |
-| `rf-mapper scan -l kitchen` | Scan with location label |
+| `python -m rf_mapper scan -l kitchen` | Scan with location label |
-| `rf-mapper scan --no-bt` | WiFi only |
+| `python -m rf_mapper scan --no-bt` | WiFi only |
-| `rf-mapper scan --no-wifi` | Bluetooth only |
+| `python -m rf_mapper scan --no-wifi` | Bluetooth only |
-| `rf-mapper visualize` | ASCII radar display |
+| `python -m rf_mapper visualize` | ASCII radar display |
-| `rf-mapper analyze` | RF environment analysis |
+| `python -m rf_mapper analyze` | RF environment analysis |
-| `rf-mapper list` | List saved scans |
+| `python -m rf_mapper list` | List saved scans |
-| `rf-mapper start` | Start web server (background) |
+| `python -m rf_mapper start` | Start web server (background) |
-| `rf-mapper stop` | Stop web server |
+| `python -m rf_mapper stop` | Stop web server |
-| `rf-mapper restart` | Restart web server |
+| `python -m rf_mapper restart` | Restart web server |
-| `rf-mapper status` | Check if server is running |
+| `python -m rf_mapper status` | Check if server is running |
-| `rf-mapper config` | Show configuration |
+| `python -m rf_mapper config` | Show configuration |
 
 ---
 
@@ -28,18 +33,18 @@ Quick reference for RF Mapper commands and configuration.
 
 ```bash
 # Lifecycle
-rf-mapper start                  # Start (background daemon)
+python -m rf_mapper start                  # Start (background daemon)
-rf-mapper stop                   # Stop
+python -m rf_mapper stop                   # Stop
-rf-mapper restart                # Restart
+python -m rf_mapper restart                # Restart
-rf-mapper status                 # Check if running
+python -m rf_mapper status                 # Check if running
 
 # Start options
-rf-mapper start -f               # Foreground mode
+python -m rf_mapper start -f               # Foreground mode
-rf-mapper start -H 127.0.0.1     # Bind to localhost only
+python -m rf_mapper start -H 127.0.0.1     # Bind to localhost only
-rf-mapper start -p 8080          # Custom port
+python -m rf_mapper start -p 8080          # Custom port
-rf-mapper start --debug          # Debug mode (requires -f)
+python -m rf_mapper start --debug          # Debug mode (requires -f)
-rf-mapper start --profile-requests # Per-request profiling
+python -m rf_mapper start --profile-requests # Per-request profiling
-rf-mapper start --log-requests   # Request logging
+python -m rf_mapper start --log-requests   # Request logging
 ```
 
 ---
@@ -48,10 +53,10 @@ rf-mapper start --log-requests   # Request logging
 
 ```bash
 # Show current config
-rf-mapper config
+python -m rf_mapper config
 
 # Set GPS coordinates
-rf-mapper config --set-gps 50.8585 4.3978 --save
+python -m rf_mapper config --set-gps 50.8585 4.3978 --save
 ```
 
 ---

docs/HOME_ASSISTANT.md

@@ -258,7 +258,7 @@ template:
 
 1. **Enable integration**: Set `home_assistant.enabled: true` in config.yaml
 2. **Add HA automations**: Copy webhook automations to HA
-3. **Restart RF Mapper**: `rf-mapper restart`
+3. **Restart RF Mapper**: `source venv/bin/activate && python -m rf_mapper restart`
 4. **Run scan**: Trigger BT scan in RF Mapper web UI
 5. **Check HA**: Verify `device_tracker.rf_*` entities appear
 6. **Test new device**: Clear device from DB, re-scan, verify notification