docs: correct semantically stale content across the user and developer guides

A second-pass content audit checked the guides' substantive claims
against the code (the first pass only fixed mechanical drift). Fixes:

- GETTING_STARTED: described booting a prebuilt SD image and seeing
  default clock/weather plugins — neither exists. Now documents the real
  install (Pi OS Lite + one-shot installer / first_time_install.sh) and
  that displays come from the Plugin Store. Duration and ordering
  instructions moved to the Rotation tab where the controls actually
  live.
- WEB_INTERFACE_GUIDE: three whole tabs were undocumented (Rotation,
  Backup & Restore, Tools) and the Display tab's Vegas Scroll section
  was unmentioned. Fonts overrides are per display element (not per
  plugin); Logs has an Auto-scroll checkbox (not a Pause button); the
  aspirational keyboard-shortcut list and no-JS claim removed.
- TROUBLESHOOTING: the hand-written service-file template (wrong user,
  wrong ExecStart, dropped the autostart gate) replaced with the real
  systemd/ units + install scripts; recovery steps no longer copy
  placeholder units verbatim; WiFi curl endpoint corrected to /api/v3/;
  cache-clearing advice now targets the real cache locations.
- ADVANCED_FEATURES: removed a false claim that CacheManager has no
  delete(); fixed two example snippets that raise TypeError
  (BackgroundDataService and get_config_file_mode signatures); fixed
  cache paths, a 5-minute TTL that is actually 1 hour, and the vegas
  table now links the complete 26-key reference.
- EMULATOR_SETUP_GUIDE: documented run.py flags that don't exist
  (--plugin/--test-plugins) removed in favor of dev_server.py and
  check_plugin.py; shipped emulator config values corrected (browser
  adapter default on :8888, not pygame).
- PLUGIN_QUICK_REFERENCE: drag-and-drop reordering is shipped, not
  'not yet supported'; discovery-fallback and registry-repo claims
  corrected. PLUGIN_API_REFERENCE: get_vegas_segment_width returns
  panels, not pixels. CONTRIBUTING: the repo uses flake8/mypy/bandit
  pre-commit hooks, not black/ruff, and tests need requirements-test.txt.
- SKIN_SYSTEM/DEVELOPER_QUICK_REFERENCE: stale module paths.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SXb4mKcAkVaxkeTb3YnAdr

docs/TROUBLESHOOTING.md

@@ -330,8 +330,8 @@ sudo systemctl cat ledmatrix-web | grep User
 
 6. **Manually enable AP mode:**
    ```bash
-   # Via API
-   curl -X POST http://localhost:5000/api/wifi/ap/enable
+   # Via API (the WiFi blueprint is mounted under /api/v3)
+   curl -X POST http://localhost:5000/api/v3/wifi/ap/enable
 
    # Via Python
    python3 -c "
@@ -482,19 +482,19 @@ sudo systemctl cat ledmatrix-web | grep User
 
 1. **Check plugin directory exists:**
    ```bash
-   ls -ld plugins/plugin-id/
+   ls -ld plugin-repos/plugin-id/
    ```
 
 2. **Verify manifest.json:**
    ```bash
-   cat plugins/plugin-id/manifest.json
+   cat plugin-repos/plugin-id/manifest.json
    # Verify all required fields present
    ```
 
 3. **Check dependencies installed:**
    ```bash
-   if [ -f plugins/plugin-id/requirements.txt ]; then
-     pip3 install --break-system-packages -r plugins/plugin-id/requirements.txt
+   if [ -f plugin-repos/plugin-id/requirements.txt ]; then
+     pip3 install --break-system-packages -r plugin-repos/plugin-id/requirements.txt
    fi
    ```
 
@@ -507,7 +507,7 @@ sudo systemctl cat ledmatrix-web | grep User
    ```bash
    python3 -c "
    import sys
-   sys.path.insert(0, 'plugins/plugin-id')
+   sys.path.insert(0, 'plugin-repos/plugin-id')
    from manager import PluginClass
    print('Plugin imports successfully')
    "
@@ -523,12 +523,18 @@ sudo systemctl cat ledmatrix-web | grep User
 **Solutions:**
 
 1. **Manual cache clearing:**
-   ```bash
-   # Remove plugin-specific cache
-   rm -rf cache/plugin-id*
 
-   # Or remove all cache
-   rm -rf cache/*
+   The cache does not live in the project directory. The cache manager
+   uses the first writable location among `/var/cache/ledmatrix`,
+   `~/.ledmatrix_cache`, `/opt/ledmatrix/cache`, and
+   `$TMPDIR/ledmatrix_cache`. The easiest option is the helper script:
+
+   ```bash
+   # Clear the cache with the helper script
+   sudo python3 scripts/utils/clear_cache.py
+
+   # Or remove files manually from the cache dir in use, e.g.:
+   sudo rm -rf /var/cache/ledmatrix/*
 
    # Restart display
    sudo systemctl restart ledmatrix
@@ -536,8 +542,8 @@ sudo systemctl cat ledmatrix-web | grep User
 
 2. **Check cache permissions:**
    ```bash
-   ls -ld cache/
-   sudo chown -R ledpi:ledpi cache/
+   ls -ld /var/cache/ledmatrix
+   sudo ./scripts/fix_perms/fix_cache_permissions.sh
    ```
 
 ---
@@ -772,11 +778,11 @@ nmcli device status
 ```bash
 # Check file exists
 ls -l config/config.json
-ls -l plugins/plugin-id/manifest.json
+ls -l plugin-repos/plugin-id/manifest.json
 
 # Check directory structure
 ls -la web_interface/
-ls -la plugins/
+ls -la plugin-repos/
 
 # Check file permissions
 ls -l config/config_secrets.json
@@ -804,7 +810,7 @@ python3 -c "from src.wifi_manager import WiFiManager; print('OK')"
 # Test plugin import
 python3 -c "
 import sys
-sys.path.insert(0, 'plugins/plugin-id')
+sys.path.insert(0, 'plugin-repos/plugin-id')
 from manager import PluginClass
 print('Plugin imports OK')
 "
@@ -812,40 +818,29 @@ print('Plugin imports OK')
 
 ---
 
-## Service File Template
+## Reinstalling Service Files
 
-If your systemd service file is corrupted or missing, use this template:
-
-```ini
-[Unit]
-Description=LEDMatrix Web Interface
-After=network.target
-
-[Service]
-Type=simple
-User=ledpi
-Group=ledpi
-WorkingDirectory=/home/ledpi/LEDMatrix
-Environment="PYTHONUNBUFFERED=1"
-ExecStart=/usr/bin/python3 /home/ledpi/LEDMatrix/web_interface/start.py
-Restart=on-failure
-RestartSec=5s
-StandardOutput=journal
-StandardError=journal
-SyslogIdentifier=ledmatrix-web
-
-[Install]
-WantedBy=multi-user.target
-```
-
-Save to `/etc/systemd/system/ledmatrix-web.service` and run:
+If a systemd service file is corrupted or missing, do NOT hand-write
+one. The real unit files live in the repo's `systemd/` directory
+(`ledmatrix.service`, `ledmatrix-web.service`,
+`ledmatrix-wifi-monitor.service`) and contain a
+`__PROJECT_ROOT_DIR__` placeholder that the install scripts substitute
+with your actual checkout path:
 
 ```bash
-sudo systemctl daemon-reload
-sudo systemctl enable ledmatrix-web
-sudo systemctl start ledmatrix-web
+# Reinstall the display service unit
+sudo ./scripts/install/install_service.sh
+
+# Reinstall the web interface service unit
+sudo ./scripts/install/install_web_service.sh
 ```
 
+Note that `ledmatrix-web.service` runs as root via
+`scripts/utils/start_web_conditionally.py` — root is needed for
+system operations (service control, WiFi management), and the wrapper
+honors the `web_display_autostart` config flag before actually
+starting the web server.
+
 ---
 
 ## Complete Diagnostic Script
@@ -878,7 +873,7 @@ echo ""
 
 echo "5. File Structure:"
 ls -la web_interface/ | head -10
-ls -la plugins/ | head -10
+ls -la plugin-repos/ | head -10
 echo ""
 
 echo "6. Python Imports:"
@@ -954,12 +949,11 @@ sudo systemctl restart ledmatrix-web
 # Reinstall WiFi monitor
 sudo ./scripts/install/install_wifi_monitor.sh
 
-# Recreate service files from templates
-sudo cp templates/ledmatrix.service /etc/systemd/system/
-sudo cp templates/ledmatrix-web.service /etc/systemd/system/
+# Recreate service files (substitutes __PROJECT_ROOT_DIR__ in systemd/ units)
+sudo ./scripts/install/install_service.sh
+sudo ./scripts/install/install_web_service.sh
 
-# Reload and restart
-sudo systemctl daemon-reload
+# Restart
 sudo systemctl restart ledmatrix ledmatrix-web
 ```