docs: replace stale API names, line numbers and the api_v3.py path

- ADVANCED_FEATURES: StreamManager methods that exist
  (get_next_segment, take_next_group, refresh, advance_cycle, ...), and the
  real on-demand status envelope ({status, data: {state, service}})
- app.py:199 / :144 / :607-619 line citations and
  web_interface/blueprints/api_v3.py (now a package) replaced with file and
  function names in ADVANCED_FEATURES, CONFIG_DEBUGGING,
  PLUGIN_ARCHITECTURE_SPEC, PLUGIN_QUICK_REFERENCE,
  PLUGIN_CONFIGURATION_TABS, TROUBLESHOOTING and web_interface/README
- CONFIG_DEBUGGING: partial /config/main saves change only sent keys; use
  /config/raw/main to replace the file; describe where validation runs
- TROUBLESHOOTING: clear_cache.py needs --clear-all (no args only prints
  usage)

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

docs/ADVANCED_FEATURES.md

@@ -377,9 +377,16 @@ Vegas mode consists of four core components working together to provide smooth 1
 5. Compose into continuous stream with separators
 
 **Key Methods:**
-- `get_stream_content()` - Returns current stream content as PIL Image
+- `get_next_segment()` - Returns the next buffered `ContentSegment` (or `None`)
-- `advance_stream(pixels)` - Advances stream by N pixels
+- `take_next_group(count=None, offscreen_only=False)` - Hands over the next
-- `refresh_stream()` - Regenerates stream from current plugins
+  slice of the rotation as `(plugin_id, images)` groups
+- `get_grouped_content_for_composition()` - Buffered images grouped by plugin
+- `mark_plugin_updated(plugin_id)` / `process_updates()` - Refresh one
+  plugin's segment in place when its data changes
+- `refresh()` - Re-read the plugin list and config
+- `advance_cycle()` - Clear the active buffer when a scroll cycle completes
+
+(`src/vegas_mode/stream_manager.py`)
 
 #### 3. PluginAdapter
 
@@ -552,7 +559,8 @@ time when something is active.
 
 ### REST API Reference
 
-The API is mounted at `/api/v3` (`web_interface/app.py:199`).
+The API is mounted at `/api/v3` (the `api_v3` blueprint, registered in
+`web_interface/app.py`). Full details: [REST_API_REFERENCE.md](REST_API_REFERENCE.md#display-control).
 
 #### Start On-Demand Display
 
@@ -608,20 +616,30 @@ curl http://localhost:5000/api/v3/display/on-demand/status
 
 # Response:
 {
+  "status": "success",
+  "data": {
+    "state": {
       "active": true,
       "plugin_id": "weather",
       "mode": "weather",
-  "remaining": 25.5,
+      "duration": 30,
       "pinned": false,
-  "status": "active"
+      "status": "running",
+      "last_updated": 1234567890.1
+    },
+    "service": {"active": true, "returncode": 0, "stdout": "active", "stderr": ""}
+  }
 }
 ```
 
+When nothing is running on demand, `data.state` is
+`{"active": false, "status": "idle", "last_updated": null}`.
+
 > There is no public Python on-demand API. The display controller's
 > on-demand machinery is internal — drive it through the REST endpoints
 > above (or the web UI buttons). The API handlers
 > (`start_on_demand_display()` / `stop_on_demand_display()` in
-> `web_interface/blueprints/api_v3.py`) write a request into the cache
+> `web_interface/blueprints/api_v3/display.py`) write a request into the cache
 > manager under the `display_on_demand_request` key, which
 > `DisplayController._poll_on_demand_requests()`
 > (`src/display_controller.py`) picks up. A separate

docs/CONFIG_DEBUGGING.md

@@ -250,14 +250,21 @@ WARNING - Plugin ID 'Football-Scoreboard' may conflict with 'football-scoreboard
 
 ## Checking Configuration via API
 
-The API blueprint mounts at `/api/v3` (`web_interface/app.py:144`).
+The API blueprint (`web_interface/blueprints/api_v3/`) is registered at
+`/api/v3` in `web_interface/app.py`.
 
 ```bash
-# Get full main config (includes all plugin sections)
+# Get full main config (includes all plugin sections; credential-named
+# fields are blanked in the response)
 curl http://localhost:5000/api/v3/config/main
 
-# Save updated main config
+# Change some settings: only the keys you send are changed
 curl -X POST http://localhost:5000/api/v3/config/main \
+  -H "Content-Type: application/json" \
+  -d '{"timezone": "America/Chicago", "brightness": 80}'
+
+# Replace config.json wholesale (advanced)
+curl -X POST http://localhost:5000/api/v3/config/raw/main \
   -H "Content-Type: application/json" \
   -d @new-config.json
 
@@ -269,8 +276,10 @@ curl "http://localhost:5000/api/v3/plugins/config?plugin_id=football-scoreboard"
 ```
 
 > There is no dedicated `/config/plugin/<id>` or `/config/validate`
-> endpoint — config validation runs server-side automatically when you
+> endpoint. `POST /plugins/config` validates against the plugin's schema
-> POST to `/config/main` or `/plugins/config`. See
+> and rejects an invalid config with `400`; `POST /config/main` checks the
+> individual fields it knows (display hardware values, durations, Vegas
+> and sync settings). See
 > [REST_API_REFERENCE.md](REST_API_REFERENCE.md) for the full list.
 
 ## Backup and Recovery

docs/PLUGIN_ARCHITECTURE_SPEC.md

@@ -8,7 +8,8 @@
 > - Code paths reference `web_interface_v2.py`; the current web UI is
 >   `web_interface/app.py` with v3 Blueprint-based templates.
 > - The example Flask routes use `/api/plugins/*`; the real API
->   blueprint is mounted at `/api/v3` (`web_interface/app.py:199`).
+>   blueprint (`web_interface/blueprints/api_v3/`) is mounted at `/api/v3`
+>   in `web_interface/app.py`.
 > - The default plugin location is `plugin-repos/` (configurable via
 >   `plugin_system.plugins_directory`), not `./plugins/`.
 > - Example imports use `src/plugin_system/base_classes/*_plugin.py`;

docs/PLUGIN_CONFIGURATION_TABS.md

@@ -6,7 +6,8 @@
 > in the "Implementation Details" section below still reference the
 > pre-v3 file layout (`web_interface_v2.py`, `templates/index_v2.html`).
 > The current implementation lives in `web_interface/app.py`,
-> `web_interface/blueprints/api_v3.py`, and `web_interface/templates/v3/`.
+> `web_interface/blueprints/api_v3/` (plugin config handlers in
+> `plugins.py`), and `web_interface/templates/v3/`.
 > The user-facing description (Overview, Features, Form Generation
 > Process) is still accurate.
 

docs/PLUGIN_QUICK_REFERENCE.md

@@ -127,7 +127,8 @@ git push origin v1.0.0
 
 ### REST API
 
-The API is mounted at `/api/v3` (`web_interface/app.py:199`).
+The API is mounted at `/api/v3` (the `api_v3` blueprint in
+`web_interface/blueprints/api_v3/`, registered in `web_interface/app.py`).
 
 ```bash
 # Install plugin from the registry

docs/TROUBLESHOOTING.md

@@ -273,7 +273,7 @@ sudo systemctl cat ledmatrix-web | grep User
 1. **Verify file structure:**
    ```bash
    ls -l web_interface/app.py
-   ls -l web_interface/blueprints/api_v3.py
+   ls -ld web_interface/blueprints/api_v3/
    ls -l web_interface/blueprints/pages_v3.py
    ```
 
@@ -531,7 +531,7 @@ sudo systemctl cat ledmatrix-web | grep User
 
    ```bash
    # Clear the cache with the helper script
-   sudo python3 scripts/utils/clear_cache.py
+   sudo python3 scripts/utils/clear_cache.py --clear-all
 
    # Or remove files manually from the cache dir in use, e.g.:
    sudo rm -rf /var/cache/ledmatrix/*

web_interface/README.md

@@ -20,7 +20,9 @@ web_interface/
 ├── run.sh                    # Shell runner script
 ├── requirements.txt          # Python dependencies
 ├── blueprints/               # Flask blueprints
-│   ├── api_v3.py            # API endpoints
+│   ├── api_v3/              # API endpoints (package: config, display,
+│   │                        #   plugins, system, backup, fonts, misc,
+│   │                        #   wifi, starlark)
 │   └── pages_v3.py          # Page routes
 ├── templates/                # HTML templates
 │   └── v3/
@@ -75,7 +77,8 @@ The web interface reads configuration from:
 
 ## API Documentation
 
-The V3 API is mounted at `/api/v3/` (`app.py:144`). For the complete
+The V3 API is the `api_v3` blueprint, registered at `/api/v3/` in
+`app.py`. For the complete
 list and request/response formats, see
 [`docs/REST_API_REFERENCE.md`](../docs/REST_API_REFERENCE.md). Quick
 reference for the most common endpoints:
@@ -115,9 +118,9 @@ reference for the most common endpoints:
 - `POST /api/v3/plugins/store/refresh` - Refresh registry from GitHub
 
 ### Real-time Streams (SSE)
-SSE stream endpoints are defined directly on the Flask app
+SSE stream endpoints are defined directly on the Flask app in `app.py`
-(`app.py:607-619` — includes the CSRF exemption and rate-limit hookup
+(`stream_stats`, `stream_display`, `stream_logs`, followed by their CSRF
-alongside the three route definitions), not on the api_v3 blueprint:
+exemption and rate-limit hookup), not on the api_v3 blueprint:
 - `GET /api/v3/stream/stats` - System statistics stream
 - `GET /api/v3/stream/display` - Display preview stream
 - `GET /api/v3/stream/logs` - Service logs stream